Target Configuration (fuzz.yaml)

Every repository needs a fuzz.yaml, which tells Fuzzbuzz how to set up and configure your fuzz targets.

The following sections describe each field allowed in a fuzz.yaml configuration file and how to use them.

base

Type: string

Required: yes

Valid values: ubuntu:16.04

The name of the operating system to use as the base of the Docker image the target is set up and fuzzed in. As of now, ubuntu:16.04 is the only option.

Usage:

base: ubuntu:16.04

environment

Type: Array

Required: no

Environment variables that will be accessible to each target.

Usage:

environment:
    - ENV_VAR=value
    - ENV_VAR2=value2

setup

Type: Array

Required: no

A list of commands to run prior to each target's specific setup commands.

Usage:

setup:
    - sudo apt-get update
    - sudo apt-get install my-dependency

language

Type: string

Required: yes

Valid values: c, c++, go

The name of the language the target was written in. This must be specified either here, or in target.language. If it is specified in both, the value in target.language overrides the one here.

Usage:

language: c++

version

Type: string

Required: yes (all languages except C/C++)

The version of the target's language to use. This must be specified either here, or in target.version. If it is specified in both, the value in target.version overrides the one here.

Usage:

language: go
version: "1.11"

checkout

Type: string

Required: yes (Golang only)

Specifies where in the Gopath to place your code. This must be specified either here, or in target.harness.checkout. If it is specified in both, the value in target.harness.checkout overrides the one here.

Usage:

# checkout specifies where to check your code out
# this repository will be placed in the directory:
# ~/go/src/github.com/x/y/
checkout: github.com/x/y

targets

Type: Array

Required: yes

An array of target configurations.

Usage:

targets:
    - name: target-name
    # --- Other target configuration options omitted

target.name

Type: string

Required: yes

The name of the target. Must be unique within the fuzz.yaml. Can only contain letters, numbers, dashes and underscores.

Usage:

targets:
    - name: my-target

target.language

Type: string

Required: yes

Valid values: c, c++, go

The name of the language the target was written in.

Usage:

targets:
    - name: my-target
      language: c

target.version

Type: string

Required: yes (all languages except C/C++)

The version of the target's language to use.

Usage:

targets:
    - name: my-target
      language: go
      version: "1.11"

target.environment

Type: Array

Required: no

Environment variables that will be accessible to this specific target.

Usage:

targets:
    - name: my-target
      environment:
        - ENV_VAR=value
        - ENV_VAR2=value2

target.setup

Type: Array

Required: no

A list of commands to run that set up or compile the target.

Usage:

targets:
    - name: my-target
      setup:
        - sudo apt-get install my-lib
        - CC=$FUZZ_CC CXX=$FUZZ_CXX make my-target

target.corpus

Type: string

Required: yes

The location of the target's test corpus. This should point to a directory of files, each of which should be a separate test case that can be fed to the target and runs a test that passes. The directory can be left empty, but this will result in a more inefficient start to fuzzing.

Usage:

targets:
    - name: my-target
      corpus: ./my-target/corpus

target.harness

Type: Map

Required: yes

Configuration that tells Fuzzbuzz how to find & run the target. Configuration differs depending on the language

targets:
    - name: my-target
      harness:
        binary: ./target

targets:
    - name: my-target
      harness:
        binary: ./target

targets:
    - name: my-target
      harness:
        # the name of your method
        function: FuzzMe
        # build tags are optional
        build_tags: tag1 tag2 tag3
        # package specifies the package to import the
        # desired function from 
        package: github.com/x/y/z/a/b/c
        # checkout specifies where to check your code out
        # this repository will be placed in the directory:
        # ~/go/src/github.com/x/y/
        checkout: github.com/x/y

targets:
    - name: my-target
      harness:
        binary: ./target @@
        input: file # either stdin, socket or file

target.memory_limit

Type: integer

Required: no

The maximum memory usage in megabytes to allow when processing a test case. Any tests that use more memory than this will be reported as bugs.

Usage:

targets:
    - name: my-target
      memory_limit: 1000 # 1 GB

target.timeout

Type: integer

Required: no

The maximum amount of time in milliseconds the target should take to process any one test case.

Usage:

targets:
    - name: my-target
      timeout: 500 # 500 milliseconds

target.sanitizers

Type: Map

Required: no

Valid values: address

Sanitizers to use with this target. Sanitizers are analyzers that are compiled along with the target, and alert on specific issues.

Supported sanitizers:

• ​Address Sanitizer: finds bugs including Use After Free, Buffer Over/Underflows, Use After Returns, Memory Leaks, etc

  • Fuzzbuzz sets the following defaults for ASAN_OPTIONS (these will override your settings): abort_on_error=1:print_scariness=1

  • symbolize=0 is set during runtime, and symbolize=1 is set when reproducing crashes to gather stacktraces

Usage:

targets:
    - name: my-target
      sanitizers:
        # sanitizer options can be specified as a string
        address: detect_stack_use_after_return=1:debug=1
        # the field can also be left blank, e.g.:
        address: