Targets

A target is a self-contained unit that receives a test case from Fuzzbuzz, runs the test, and reports any bugs. This page describes how to build a target
This page describes how to write new targets for Fuzzbuzz. If you have existing targets for AFL, Libfuzzer, Gofuzz or other open-source fuzzing frameworks, they already work on Fuzzbuzz! Click Here to learn how.
Each target consists of two parts:
1.a method within your code, that Fuzzbuzz provides test data to - similar to a unit testing framework
2.an entry in the targets list of the project's fuzzbuzz.yaml, which describes how to run the target, and defines the type of errors to look for
Test Method
C
C++
Go
Python
Binaries
To fuzz code written in C, create a new file with the following method:
target.c
1
int FuzzerEntrypoint(const uint8_t *Data, size_t Size) {
2
  // Step 1: read Data into desired format
3
  // Step 2: run your methods/code with the test data
4
  // Step 3: check for errors, and abort if errors are found
5
  // return -1 if the Data is irrelevant or invalid
6
}
Copied!
You can use assert to check for errors as you would in a unit test - Fuzzbuzz will pick up failed assertions as bugs.
To fuzz code written in C++, create a new file with the following method:
target.cpp
1
extern "C" int FuzzerEntrypoint(const uint8_t *Data, size_t Size) {
2
  // Step 1: read Data into desired format
3
  // Step 2: run your methods/code with the test data
4
  // Step 3: check for errors, and abort if errors are found
5
  // return -1 if the Data is irrelevant or invalid 
6
}
Copied!
You can use assert to check for errors as you would in a unit test - Fuzzbuzz will pick up failed assertions as bugs.
To fuzz code written in Golang, include the following method in your package:
target.go
1
func FuzzerEntrypoint(Data []byte) int {
2
  // Step 1: read Data into desired format
3
  // Step 2: run your methods/code with the test data
4
  // Step 3: check for errors, and abort if errors are found 
5
  // return -1 if the Data is irrelevant or invalid
6
}
Copied!
Use panics to alert on bugs - Fuzzbuzz will pick up these failures.
To fuzz code written in Python, include the following method in your package:
target.py
1
def FuzzerEntrypoint(Data): # Data is a buffer of bytes
2
  # Step 1: read Data into desired format
3
  # Step 2: run your methods/code with the test data
4
  # Step 3: check for errors, and abort if errors are found 
5
  # return -1 if the Data is irrelevant or invalid
Copied!
You can use Python's assert statement to check for errors as you would in a unit test - Fuzzbuzz will pick up these failures.
Fuzzbuzz can fuzz entire binaries compiled with C or C++, that read data from files, stdin, or sockets. Check the Configuration Section to learn how to fuzz these.
This method should take the test case defined in the array Data and convert it into the desired test data - for example, if the code or methods you wish to test take 2 integers as input, parse 2 integers from the array of bytes. This interface aims to be as flexible as possible - you can parse any data type from these bytes, populate structs or objects, and generate very complex test structures. If the array of bytes isn't long enough to populate your desired structures, return -1 right away. The fuzzing engine is a quick learner, and will realize more data is required!
Configuration
This section provides a descriptive overview of fuzzbuzz.yaml configuration. For full, detailed documentation check out the Configuration Reference.
Every target needs an entry in the targets list of the project's fuzzbuzz.yaml:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
language: c
3
targets:
4
    - name: my-target # this name should be unique within the project
5
      environment: # environment specific for this target
6
        - VAR=value
7
      setup: # setup steps specific for this target
8
        - make my-target
9
      corpus: my-target/corpus # a directory containing initial test cases
10
      harness: # special language-specific configuration
Copied!
The name field is compulsory, and the setup steps should be used to install needed dependencies. For languages like C and C++, the setup steps should also be used to compile the target binaries.
The corpus directory should contain a list of files, each with an input to the Test Method that does not produce in a bug. This field is optional, but examples of tests that pass gives Fuzzbuzz an idea of what a good input looks like, and can make finding new code paths more efficient.
Finally, the harness field tells Fuzzbuzz how to run the Test Method. This entry requires certain fields depending on the specific language of the target, as described below:
C
C++
Go
Python
Binaries
To fuzz C code, compile the file containing FuzzerEntrypoint along with all other required files and libraries, using the FUZZ_CC and CFLAGS environment variables.
For example, if FuzzerEntrypoint is implemented in my_target.c and calls a method in my_api.h:
1
$FUZZ_CC $CFLAGS my_api.h my_target.c -c
Copied!
Finally, to compile into a full binary, link with FUZZ_ENGINE, which provides a main method as well as the necessary feedback for Fuzzbuzz, using the C++ compiler:
1
$FUZZ_CXX $CXXFLAGS my_target.o $FUZZ_ENGINE -o ./target
Copied!
Even for code written in C, remember to link with FUZZ_ENGINE using the C++ compiler FUZZ_CXX
This is an example of all the above steps combined to fully configure a target written in C:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
language: c
3
targets:
4
    - name: my-target
5
      environment:
6
        # you can specify your own CFLAGS/CXXFLAGS, just remember to
7
        # use the fuzzbuzz-provided defaults as well
8
        - CFLAGS="$CFLAGS -g"
9
      setup:
10
        - $FUZZ_CC $CFLAGS my_api.h my_target.c -c
11
        - $FUZZ_CXX $CXXFLAGS my_target.o $FUZZ_ENGINE -o ./target
12
      corpus: ./my_target/corpus
13
      harness:
14
        binary: ./target
Copied!
To fuzz C++ code, compile the file containing FuzzerEntrypoint along with all other required files and libraries, using the FUZZ_CXX and CXXFLAGS environment variables.
For example, if FuzzerEntrypoint is implemented in my_target.cpp and calls a method in my_api.h:
1
$FUZZ_CXX $CXXFLAGS my_api.h my_target.cpp -c
Copied!
Finally, to compile into a full binary, link with FUZZ_ENGINE, which provides a main method as well as the necessary feedback for Fuzzbuzz:
1
$FUZZ_CXX $CXXFLAGS my_target.o $FUZZ_ENGINE -o ./target
Copied!
This is an example of all the above steps combined to fully configure a target written in C++:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
language: c++
3
targets:
4
    - name: my-target
5
      environment:
6
        # you can specify your own CFLAGS/CXXFLAGS, just remember to
7
        # use the fuzzbuzz-provided defaults as well
8
        - CXXFLAGS="$CXXFLAGS -g"
9
      setup:
10
        - $FUZZ_CXX $CXXFLAGS my_api.h my_target.cpp -c
11
        - $FUZZ_CXX $CXXFLAGS my_target.o $FUZZ_ENGINE -o ./target
12
      corpus: ./my_target/corpus
13
      harness:
14
        binary: ./target
Copied!
To fuzz Go code, use the setup steps to install all the needed dependencies. Use the checkout field to specify where in the Gopath your code should be placed. This can be set at the root of the fuzzbuzz.yaml and then overridden for a specific target if needed. Then, specify the package and method to fuzz in the harness field.
This is an example of the configuration of a target written in Go:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
language: go
3
version: "1.11"
4
# checkout specifies where to check your code out
5
# this repository will be placed in the directory:
6
# ~/go/src/github.com/x/y
7
checkout: github.com/x/y
8
targets:
9
    - name: my-target
10
      setup:
11
        - dep ensure # make sure all dependencies are installed
12
      corpus: ./my_target/corpus
13
      harness:
14
        # Go targets are flexible - your method doesn't need to
15
        # be named FuzzerEntrypoint
16
        function: FuzzerEntrypoint
17
        # build tags are optional
18
        build_tags: tag1 tag2 tag3
19
        # package specifies the package to import the
20
        # desired function from 
21
        package: github.com/x/y/z/a/b/c
Copied!
To fuzz Python code, use the setup steps to install all the needed dependencies. Use the file field to specify the Python file that contains the test harness. Then, specify the function to fuzz in the function field.
This is an example of the configuration of a target written in Go:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
language: python
3
version: "3.6"
4
setup:
5
  - pip3 install -r requirements.txt
6
targets:
7
    - name: my-target
8
      harness:
9
        # Python targets are flexible - your method doesn't need to
10
        # be named FuzzerEntrypoint
11
        function: FuzzerEntrypoint
12
        file: tests/fuzz_test_file.py
Copied!
To fuzz binaries written in C or C++, compile them using the following environment variables:
FUZZ_STANDALONE_CC and CFLAGS
FUZZ_STANDALONE_CXX and CXXFLAGS
These compilers ensure that Fuzzbuzz gets the feedback it needs to provide information on code coverage and more complex memory corruption bugs.
Then, in the harness field, specify whether the binary takes input via stdin, a network socket, or from a file. If the binary takes input from a file, mark the location in the binary's command line where the input file should be placed with a @@. This will be replaced automatically when fuzzing.
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
targets:
3
    - name: my-target
4
      language: c++
5
      environment:
6
        # you can specify your own CFLAGS/CXXFLAGS, just remember to
7
        # use the fuzzbuzz-provided defaults as well
8
        - CXXFLAGS="$CXXFLAGS -g"
9
      setup:
10
        - $FUZZ_STANDALONE_CXX $CXXFLAGS my_binary.cpp -o ./target
11
      corpus: ./my_target/corpus
12
      harness:
13
        binary: ./target @@
14
        # input can be one of: stdin, file, socket
15
        # currently socket is experimental, and is not available
16
        # on the main platform
17
        input: file
Copied!
You're ready to go! Push your project to Fuzzbuzz and it will detect your targets automatically. Check out the Fuzzing Jobs page to learn how to fuzz your targets on the platform, or keep reading below to learn how Advanced Configuration options can help you get the most out of your code.
Running Fuzzing Jobs
Advanced Configuration
Fuzzbuzz provides features that allow you to monitor your target for extreme memory usage, tests that take too long to run, and memory bugs (in certain languages).
Memory Limits
You can specify a memory limit (in Megabytes) in your target configuration, and Fuzzbuzz will report any test cases that cause your target to use more memory than the limit.
Usage:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
targets:
3
    # ---- rest of target config omitted
4
    memory_limit: '1000' # in megabytes
Copied!
Timeouts
You can specify a timeout (in milliseconds) in your target configuration, and Fuzzbuzz will report any test cases that take longer than the timeout threshold to process.
Usage:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
targets:
3
    # ---- rest of target config omitted
4
    timeout: '500' # in milliseconds
Copied!
Sanitizers
Fuzzbuzz exposes the use of sanitizers for C and C++ binaries - these sanitizers monitor your code for certain memory bugs, including buffer overflows and potentially dangerous memory usage.
Currently Fuzzbuzz supports Address Sanitizer. More sanitizers will be provided in the future.
Usage:
fuzzbuzz.yaml
1
# ---- base, global setup, and global environment omitted
2
targets:
3
    # ---- rest of target config omitted
4
    sanitizers:
5
        # you can specify custom sanitizer options here
6
        address: detect_stack_use_after_return=1:debug=1 # can be left blank
Copied!
You can learn more about configuring your targets in the Configuration Section.
Developer Documentation - Previous
Projects
Next - Developer Documentation
Running Fuzzing Jobs
Last modified 2yr ago
Copy link
Contents
Test Method
Configuration
Advanced Configuration
Memory Limits
Timeouts
Sanitizers