This page walks you through setting up your first blackbox fuzzer.
In order to begin fuzzing, you need to build your target with a sanitizer. The most commonly used sanitizer for fuzzing is AddressSanitizer, which instruments your code with checks for memory safety issues. Clang is the supported compiler, but GCC may also work.
This is dependent on the build system of your project. At a very high level,
this will mean adding the
-fsanitize=address flag to your C/C++ compiler and
Creating a job type
A job type is a specification for how to run a particular target program for fuzzing. It consists of environment variables values.
A basic job type for a binary called “app” might look like:
APP_NAME = app APP_ARGS = --some_interesting_option --some_very_important_option REQUIRED_APP_ARGS = --some_very_important_option CUSTOM_BINARY = True TEST_TIMEOUT = 30
Breaking this down,
APP_NAMEdenotes the name of the target program.
APP_ARGSare arguments to be passed to the target application. This variable should include both optional and required arguments you want to pass.
REQUIRED_APP_ARGSare arguments that must be passed to the target application. These arguments will be always used, while the others specified in
APP_ARGSand not specified here can be removed by ClusterFuzz during testcase minimization if they aren’t needed to reproduce a crash.
CUSTOM_BINARYindicates whether or not to use a user uploaded archive, rather than pulling from a GCS bucket.
TEST_TIMEOUTis the maximum timeout in seconds per individual testcase.
To create a job:
- Navigate to the Jobs page.
- Go to the “ADD NEW JOB” form.
- Fill out the “Name” and “Platform”.
- Select your build (your zip containing the fuzz target binary) to upload as a “Custom Build”.
- Use the “ADD” button to add the job to ClusterFuzz.
Uploading a fuzzer
A blackbox fuzzer on ClusterFuzz is a program which accepts a corpus as input, and outputs mutated or generated testcases to an output directory. This program must take the following named arguments:
--input_dir <directory>. This is the input directory which contains the corpus for the given fuzzer.
--output_dir <directory>. This is the output directory which the fuzzer should write to.
--no_of_files <n>. This is the number of testcases which the fuzzer should write to the output directory.
The testcases generated by the fuzzer must have the filename prefix
This helps ClusterFuzz to know which files to fuzz. The output directory
must also include all the dependencies needed to execute the testcase.
The main entry point for this fuzzer should be a filename which starts with
run. For example, a fuzzer in Python may be named
To upload this to ClusterFuzz, package this into a zip archive along with its dependencies and:
- Navigate to the Fuzzers page.
- Click the “CREATE NEW” button.
- Fill out the “Name” of the fuzzer.
- Select the fuzzer archive for upload.
- Click “Select/modify jobs”.
- Mark the job(s) created above.
- Click “SUBMIT”.
Give the bots some time to start running your uploaded fuzzers. You can check which bots are running your fuzzers by checking the Bots page. Once a bot has finished running your fuzzer, you can see a sample console output from the run and a sample testcase by visiting the Fuzzers page (see the second column). You may check bot logs as well.