OSS-Fuzz offers CIFuzz, which will run your fuzz targets each time a pull request is submitted, for projects hosted on GitHub. This allows you to detect and fix bugs before they make it into your codebase
CIFuzz works by checking out a repository at the head of a pull request. For projects that support code coverage, fuzzers coverage is compared with PR diffs to determine which fuzzers should be used. For projects that do not support code coverage, all fuzzers are run for an even length of time. If no bugs are found and the allotted time is up (default is 10 minutes), the CI test passes with a green check. But if a bug is found, the bug is checked for reproducability and against old OSS-Fuzz builds to prevent the reporting of pre-existing bugs. If the bug is both new and reproducible, it is reported and the stack trace as well as the test case are made available for download.
You can integrate CIFuzz into your project using the following steps:
.github
directory in the root of your project.workflows
directory inside of your .github
directory.main.yml
file over from the OSS-Fuzz repository to the workflows
directory.oss-fuzz-project-name
value in main.yml
from example
to the name of your OSS-Fuzz project. It is very important that you use your OSS-Fuzz project name which is case sensitive. This name is the name of your project's subdirectory in the projects
directory of OSS-Fuzz.fuzz-seconds
. The longest time that the project maintainers are acceptable with should be used. This value should be at minimum 600 seconds and scale with project size.Your directory structure should look like the following:
project |___ .github | |____ workflows | |____ main.yml |___ other-files
main.yml for an example project:
name: CIFuzz on: [pull_request] jobs: Fuzzing: runs-on: ubuntu-latest steps: - name: Build Fuzzers id: build uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master with: oss-fuzz-project-name: 'example' dry-run: false - name: Run Fuzzers uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@master with: oss-fuzz-project-name: 'example' fuzz-seconds: 600 dry-run: false - name: Upload Crash uses: actions/upload-artifact@v1 if: failure() && steps.build.outcome == 'success' with: name: artifacts path: ./out/artifacts
fuzz-time
: Determines how long CIFuzz spends fuzzing your project in seconds. The default is 600 seconds. The GitHub Actions max run time is 21600 seconds (6 hours).
dry-run
: Determines if CIFuzz surfaces errors. The default value is false
. When set to true
, CIFuzz will never report a failure even if it finds a crash in your project. This requires the user to manually check the logs for detected bugs. If dry run mode is desired, make sure to set the dry-run parameters in both the Build Fuzzers
and Run Fuzzers
action step.
The results of CIFuzz can be found in two different places.
actions
tab of a CIFuzz integrated repo.CIFuzz
button in the workflow selector on the left hand side.Fuzzing
workflow.Run Fuzzer
drop down. It should show the timestamps and results from each of the fuzz targets.artifacts
.artifacts
contains two files:test_case
- a test case that can be used to reproduce the crash.bug_summary
- the stack trace and summary of the crash.Create an issue in OSS-Fuzz if you have questions of any other feedback on CIFuzz.