The fuzzbuzz.yaml

You can configure how Fuzzbuzz understands, builds and tests your code by modifying a configuration file in the root of your repository. Throughout the documentation and platform, this will be referred to as the fuzzbuzz.yaml, but you may use any one of the following filenames, placed at the root of your repository:

• fuzzbuzz.yaml
• fuzzbuzz.yml
• .fuzzbuzz.yaml
• .fuzzbuzz.yml

The fuzzbuzz.yaml can be split up into different sections that encapsulate specific configurations and languages. These sections can be named anything you want, as long as the name is a valid YAML key. For example, if you wanted to fuzz test a repository with Go and Rust code, your fuzzbuzz.yaml might look like:

go-tests:
  language: go

rust-tests:
  language: rust

Syntax Reference

{config-name}

The one type of root node, and the beginning of any Configuration. Encapsulates an entire set of fuzz tests for a certain language and configuration options. Compiled fuzz tests are namespaced by their configuration.

{config-name}.language

The programming language this section's configuration corresponds to. Supported options: c, c++, python, go, rust.

{config-name}.version

The version of the language to use. Supported programming languages: go.

Languages that don't support this flag either have in-repository overrides that tell Fuzzbuzz which version to use (such as Rust's toolchain configurations), or are configured via other means (such as C++ via the -std= flag)

Example:

base:
  language: go
  version: "1.18"

{config-name}.root

The root of this section, relative to the root of your repository. Defaults to your repository's root. This is usually the directory you would run build commands from. For example, if your go.mod file is located in the gocode subdirectory of your repository, your fuzzbuzz.yaml might look like:

base:
  language: go
  root: ./gocode

{config-name}.docker_image

Specifies the docker image to build and fuzz this configuration inside. This is an optional tag which can be used to override the default docker images that Fuzzbuzz uses, if your build has special requirements.

Example of replacing the default golang images Fuzzbuzz uses for Go:

go-tests:
  language: go
  docker_image: my-org/custom-image:1.18

{config-name}.engine

Supported programming languages: C, C++ - Fuzzbuzz will automatically detect the engine to use for other programming languages

Supported options: fuzzbuzz, libFuzzer

Use this field to specify the fuzzing engine to use when building C or C++ fuzz tests. Inside a default Fuzzbuzz environment, this will modify the fuzzing engine that the LIB_FUZZING_ENGINE variable refers to. For builds with custom Dockerfiles, this tells Fuzzbuzz which fuzzing engine the resulting tests have been built with.

Example:

base:
  language: c++
  engine: libFuzzer 
  steps:
    - run: $CXX $CXXFLAGS -c ./api.h ./api.cpp
    - run: $CXX $CXXFLAGS ./api.o ./harness.cpp $LIB_FUZZING_ENGINE -o example_fuzzer

{config-name}.environment

Specify environment variables that will be set for the duration of the build and fuzzing run.

Example:

base:
  language: rust
  environment:
    - name: RUSTFLAGS
      value: -C target-feature="avx"

{config-name}.dependencies

Used to install dependencies prior to analyzing or compiling source code. The run option is universally available, while other options and usage depend on the chosen programming language.

Usage example of run:

base:
  language: c
  dependencies:
    - run: apt install libxml

Go-specific options

Go has two more available options in addition to run: modules and vendor. By default, if no dependencies array is specified, Go projects will use modules as the sole dependency method.

Modules tells Fuzzbuzz that this project uses Go Modules to install and track dependencies. This is an example of a project that uses Go modules, and has one non-Go library as a dependency:

base:
  language: go
  dependencies:
    - run: apt install libcurl
    - modules:

Vendor tells Fuzzbuzz that this project uses vendored dependencies. If a vendor directory already exists at the root of this section, Fuzzbuzz will do nothing. If you are using Go Modules to vendor your dependencies (via, for example go mod vendor), specify vendor, not modules, in this section.

Vendor example:

base:
  language: go
  dependencies:
    - vendor:

Rust-specific options

Rust has one more available option in addition to run: auto. By default, if no dependencies array is specified, Rust sections will use auto as the sole dependency method.

Auto tells Fuzzbuzz to use the contents of the repository's Cargo.toml and Cargo.lock to install required dependencies prior to fuzzing. If a Rust section's dependencies array consists solely of run statements, auto will be applied after running all specified steps.

Auto example:

base:
  language: rust
  dependencies:
    - run: apt install libcurl
    # We don't need to specify 'auto' here since we want Rust dependencies to be
    # installed after all of the prior commands

Auto explicit example:

base:
  language: rust
  dependencies:
    - run: apt install libcurl
    # We need to specify 'auto' here since we want to run further
    # commands after all of the Rust dependencies are installed
    - auto:
    - run: ./do-something-else.sh

{config-name}.steps

Specify the steps necessary to compile your fuzz tests.

C and C++ fuzz tests are compiled based on the steps listed in the steps section. The exact nature of this execution depends on the docker_image used.

No docker_image specified

If there is no docker_image specified for C, C++ or Rust projects, Fuzzbuzz uses the default docker image fuzzbuzz/clang, which comes with a recent version of clang and related tools, in a Debian Testing environment.

Fuzzbuzz will execute all of the build steps in sequence, providing the following environment variables:

You should use these environment variables in your compile steps. For example, if you usually compile your fuzz test by running clang++ -fsanitize=address -fsanitize=fuzzer my_test.cc, my_library.so, you should provide Fuzzbuzz with the following command: $CXX $CXXFLAGS -fsanitize=fuzzer my_test.cc my_library.so.

If you specify multiple incompatible sanitizers, Fuzzbuzz will run these steps multiple times with each sanitizer partition's corresponding compiler flags.

After the compilation steps are run, Fuzzbuzz will automatically detect any fuzz test binaries present in the working directory. You may also configure your project to output fuzz binaries to the directory provided in the $OUT environment variable, but this is not necessary.

Custom docker_image specified

If a custom docker_image is specified, Fuzzbuzz will run these steps once, and run the fuzz tests produced. It is up to the developer in this case to handle sanitizer incompatibility.

After the compilation steps are run, Fuzzbuzz will automatically detect any fuzz test binaries present in the working directory. You may also configure your project to output fuzz binaries to the directory provided in the $OUT environment variable, but this is not necessary.

{config-name}.sanitizers

You can use the sanitizers section to specify which sanitizers you would like to instrument your code with. Sanitizers add checks to your code that enable discovery of difficult-to-detect bugs like memory corruption and race conditions. To learn more about the functionality of different sanitizers, check out our Sanitizer reference page.

Available options: address, leak, undefined, thread, memory.

C++ example with Address Sanitizer and Thread Sanitizer

base:
  language: c++
  steps:
    - run: $CXX $CXXFLAGS -c ./api.h ./api.cpp
    - run: $CXX $CXXFLAGS ./api.o ./harness.cpp $LIB_FUZZING_ENGINE -o example_fuzzer
  sanitizers:
    address:
      # You can use the YAML file to specify options that would
      # usually be set in the ASAN_OPTIONS environment variable
      detect_stack_use_after_return: "1"
    thread:
      ignore_noninstrumented_modules: "1"

This is a list of the partitions Fuzzbuzz currently splits sanitizers into:

Programming language-specific syntax

Go

{config-name}.checkout

Specify where to check out Go code. Only used if not in Go Modules mode. Code will be checked out into $GOPATH/src/<checkout>.

Example:

gopathmode:
  language: go
  version: "1.16"
  dependencies:
    - vendor:
  checkout: company.xyz/my/package

{config-name}.build_tags

Specify build tags to be included at analysis and compile time.

Fuzzbuzz will provide the default build tag fuzzbuzz to every project.

Example:

base:
  language: go
  version: "1.16"
  build_tags:
    - tag1
    - tag2