3.9 KiB
| layout | parent | title | has_children | nav_order | permalink |
|---|---|---|---|---|---|
| default | ClusterFuzzLite | Running ClusterFuzzLite | true | 3 | /clusterfuzzlite/running-clusterfuzzlite/ |
Running ClusterFuzzLite
{: .no_toc}
- TOC {:toc}
Overview
TODO: add a diagram.
Once your project's fuzzers can be built and run by the helper script, it is ready to be fuzzed by ClusterFuzzLite. The exact method for doing this will depend on the how you are running ClusterFuzzLite. For guides on how to run ClusterFuzzLite in your particular environment (e.g. GitHub Actions) see the subguides. The rest of this page will explain concepts configuration options and that are agnostic to how ClusterFuzzLite is being run.
ClusterFuzzLite Tasks
ClusterFuzzLite has the concept of tasks which instruct ClusterFuzzLite what to do when running.
Code Review Fuzzing
TODO(metzman): Work on a generic name for CIFuzz/PR fuzzing.
One of the core ways for ClusterFuzzLite to be used is for fuzzing code that is
in review that was just commited.
This use-case is important because it allows ClusterFuzzLite to find bugs before
they are commited into your code and while they are easiest to fix.
To use Code Review Fuzzing, set the configuration option clusterfuzzlite-task
to code-review.
If you are familiar with OSS-Fuzz's CIFuzz, this task is similar to CIFuzz.
Running other ClusterFuzzLite tasks enhances ClusterFuzzLite's ability to do
Code Review Fuzzing.
If [Batch Fuzzing] is enabled, Code Review Fuzzing will report only newly introduced bugs and use the corpus developed during batch fuzzing. If [Code Coverage Reporting] is enabled, Code Review Fuzzing will try to only run the fuzzers affected by the code change.
Batch Fuzzing
ClusterFuzzLite can also run in a batch fuzzing mode where all fuzzers are run for a long amount of time. Unlike Code Review Fuzzing, this task is not meant to be interactive, it is meant to be long-lasting and generally is more similar to fuzzing in ClusterFuzz than Code Review Fuzzing. Batch Fuzzing allows ClusterFuzzLite to build up a corpus for each of your fuzz targets. This corpus will be used in Code Coverage Reporting as well as Code Review Fuzzing.
Corpus Prune
If multiple Batch Fuzzing tasks are run concurrently then we strongly recommend running a pruning task as well. This task is run according to some set schedule (once a day is probably sufficient) to prune the corpus of redundant testcases, which can happen if multiple Batch Fuzzing jobs are done concurrently.
Code Coverage Report
The last task ClusterFuzzLite offers is Code Coverage Reports. This task will run your fuzzers on the corpus developed during Batch Fuzzing and will generate an HTML report that shows you which part of your code is covered by batch fuzzing.
Configuration Options
Below are some configuration options that you can set when running ClusterFuzzLite. We will explain how to set these in each of the subguides.
language: (optional) The language your target program is written in. Defaults
to c++. This should be the same as the value you set in project.yaml. See
[this explanation]({{ site.baseurl }}//getting-started/new-project-guide/#language)
for more details.
fuzz-time: Determines how long ClusterFuzzLite spends fuzzing your project in
seconds. The default is 600 seconds.
sanitizer: Determines a sanitizer to build and run fuzz targets with. The
choices are 'address', and 'undefined'. The default is 'address'.
task: The task for ClusterFuzzLite to execute. code-review
by default. See [ClusterFuzzLite Tasks] for more details on how to run different
tasks.
TODO(metzman): change run_fuzzers_mode to this.
dry-run: Determines if ClusterFuzzLite surfaces bugs/crashes. The default
value is false. When set to true, ClusterFuzzLite 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.
TODO(metzman): We probably want a TOC on this page for subguides.