1--- 2layout: default 3parent: ClusterFuzzLite 4title: Running ClusterFuzzLite 5has_children: true 6nav_order: 3 7permalink: /clusterfuzzlite/running-clusterfuzzlite/ 8--- 9# Running ClusterFuzzLite 10{: .no_toc} 11 12- TOC 13{:toc} 14--- 15 16## Overview 17TODO: add a diagram. 18 19Once your project's fuzzers can be built and run by the helper script, it is 20ready to be fuzzed by ClusterFuzzLite. 21The exact method for doing this will depend on the how you are running 22ClusterFuzzLite. For guides on how to run ClusterFuzzLite in your particular 23environment (e.g. GitHub Actions) see the subguides. 24The rest of this page will explain concepts configuration options and that are 25agnostic to how ClusterFuzzLite is being run. 26 27## ClusterFuzzLite Tasks 28 29ClusterFuzzLite has the concept of tasks which instruct ClusterFuzzLite what to 30do when running. 31 32### Code Review Fuzzing 33 34TODO(metzman): Work on a generic name for CIFuzz/PR fuzzing. 35 36One of the core ways for ClusterFuzzLite to be used is for fuzzing code that is 37in review that was just commited. 38This use-case is important because it allows ClusterFuzzLite to find bugs before 39they are commited into your code and while they are easiest to fix. 40To use Code Review Fuzzing, set the configuration option `clusterfuzzlite-task` 41to `code-review`. 42If you are familiar with OSS-Fuzz's CIFuzz, this task is similar to CIFuzz. 43Running other ClusterFuzzLite tasks enhances ClusterFuzzLite's ability to do 44Code Review Fuzzing. 45 46If [Batch Fuzzing] is enabled, Code Review Fuzzing will report only newly 47introduced bugs and use the corpus developed during batch fuzzing. 48If [Code Coverage Reporting] is enabled, Code Review Fuzzing will try to only 49run the fuzzers affected by the code change. 50 51### Batch Fuzzing 52 53ClusterFuzzLite can also run in a batch fuzzing mode where all fuzzers are run 54for a long amount of time. Unlike Code Review Fuzzing, this task is not meant to 55be interactive, it is meant to be long-lasting and generally is more similar to 56fuzzing in ClusterFuzz than Code Review Fuzzing. Batch Fuzzing allows 57ClusterFuzzLite to build up a corpus for each of your fuzz targets. This corpus 58will be used in Code Coverage Reporting as well as Code Review Fuzzing. 59 60### Corpus Prune 61 62If multiple Batch Fuzzing tasks are run concurrently then we strongly recommend 63running a pruning task as well. This task is run according to some set schedule 64(once a day is probably sufficient) to prune the corpus of redundant testcases, 65which can happen if multiple Batch Fuzzing jobs are done concurrently. 66 67### Code Coverage Report 68 69The last task ClusterFuzzLite offers is Code Coverage Reports. This task will 70run your fuzzers on the corpus developed during Batch Fuzzing and will generate 71an HTML report that shows you which part of your code is covered by batch 72fuzzing. 73 74## Configuration Options 75 76Below are some configuration options that you can set when running 77ClusterFuzzLite. 78We will explain how to set these in each of the subguides. 79 80`language`: (optional) The language your target program is written in. Defaults 81to `c++`. This should be the same as the value you set in `project.yaml`. See 82[this explanation]({{ site.baseurl }}//getting-started/new-project-guide/#language) 83for more details. 84 85`fuzz-time`: Determines how long ClusterFuzzLite spends fuzzing your project in 86seconds. The default is 600 seconds. 87 88`sanitizer`: Determines a sanitizer to build and run fuzz targets with. The 89choices are `'address'`, and `'undefined'`. The default is `'address'`. 90 91`task`: The task for ClusterFuzzLite to execute. `code-review` 92by default. See [ClusterFuzzLite Tasks] for more details on how to run different 93tasks. 94TODO(metzman): change run_fuzzers_mode to this. 95 96`dry-run`: Determines if ClusterFuzzLite surfaces bugs/crashes. The default 97value is `false`. When set to `true`, ClusterFuzzLite will never report a 98failure even if it finds a crash in your project. This requires the user to 99manually check the logs for detected bugs. 100 101TODO(metzman): We probably want a TOC on this page for subguides. 102