fuzzbinder

README

Fuzzing Claims for revisions of a source code

The goal of FuzzBinder is to generate, sign and publish (in a transparency log) fuzzing claims for revisions of the source code of a given project.

By following the steps described below, you will be able to generate fuzzing claims for your open-source project using the fuzzing reports generated by OSS-Fuzz and ClusterFuzz for your project, and the command line tool cmd/fuzzbinder that we have provided to generate fuzzing claims.

Generating fuzzing claims using the cmd/fuzzbinder tool

If you have not already done so, consult the development guidelines to find out what you need to install before following the steps below.

Step 1: Establish access to Google Cloud Storage

To get the fuzzing statistics, you need access to the fuzzing metadata generated by OSS-Fuzz and ClusterFuzz for your project, and stored in Google Cloud Storage.

Step 1.1: Get access to ClusterFuzz and OSS-Fuzz fuzzing reports

To get access to the fuzzing metadata used by FuzzBinder, you need to get access to two Google Cloud Storage buckets: gs://oss-fuzz-coverage and gs://${PROJECT_NAME}-logs.clusterfuzz-external.appspot.com.

Note that the coverage reports in gs://oss-fuzz-coverage are public. However, you need to be a primary_contact or an auto_cc for the project for which you want to generate fuzzing claims to have access to the fuzzing logs in gs://${PROJECT_NAME}-logs.clusterfuzz-external.appspot.com.

If you are not sure whether you are a primary_contact or an auto_cc for the project, see this OSS-Fuzz documentation for more details.

Step 1.2: Install google cloud sdk

Set up gsutil by doing the following:

• Install the gsutil tool.

Step 1.3: Authenticate to google cloud

Check whether you have access to the coverage reports and the fuzzing logs of your project:

$ gsutil ls gs://oss-fuzz-coverage/${PROJECT_NAME}

$ gsutil ls gs://${PROJECT_NAME}-logs.clusterfuzz-external.appspot.com

If you are a primary_contact or an auto_cc and you get an authorization error from the commands above, run the following command:

$ gcloud auth application-default login

If you still have authentication problems look at this authentication guide and try again. Once gsutil works, you can run the fuzzing claim generation command as explained below.

Step 2: Generate fuzzing claim

To generate a fuzzing claim run:

$ go run cmd/fuzzbinder/main.go -project_name <project-name> \
  -git_repo <project-git-repo>  \
  -fuzzengine <fuzzing-engine> -sanitizer <fuzzing-sanitizer>  \
  -date <fuzzing-date> -fuzzclaim_path <fuzzclaim-path> \
  -not_before <not-before-date> -not_after <not-after-date>

As you may have noticed, you will need <fuzzing-engine> and <fuzzing-sanitizer> that you used in your OSS-Fuzz project configuration.

For more information about the fuzzing engines and sanitizers that can be used in OSS-Fuzz, see this OSS-Fuzz documentation.

For instance, if you used libfuzzer as a fuzzing engine and an address sanitizer for your project, and you want to generate a fuzzing claim using the fuzzing reports of the date YYYYMMDD you have to run:

$ go run cmd/fuzzbinder/main.go -project_name <project-name> \
  -git_repo <project-git-repo>  \
  -fuzzengine libFuzzer -sanitizer asan  \
  -date YYYYMMDD -fuzzclaim_path <fuzzclaim-path>  \
  -not_before <not-before-date> -not_after <not-after-date>

The generated fuzzing claim will be saved in <fuzzclaim-path>.

Note that <not-before-date> is the date from which the generated fuzzing claim is effective and <not-after-date> is the date of when the generated fuzzing claim is no longer endorsed for use. For both of them, the expected format is YYYYMMDD.

Documentation

Overview

Package main contains a command-line tool for generating fuzzing claims for a revision of a source code.