There are install groups available other than "all", which allow smaller installations with only required Python dependencies:

* Performing builds, fuzz testing, corpus syncing, coverage collection, and bug reproducing.

Thus, it's possible to separate fuzz testing and working with its results to different hosts, for instance, worker and reporter:

pip install .                  # worker
pip install .[dd,reporting]    # reporter

As a result, the worker host doesn't need report generation dependencies, and the reporter host doesn't need an environment to run tested applications or fuzzers.

To uninstall BugBane use the following command:

pip uninstall bugbane

The inputs to the tool are the following:

1. The source code of a tested app
2. A build script or some build-starting command
3. The bugbane.json configuration file

The bugbane.json should define variables: builder_type, build_cmd, build_root, sanitizers.

The build_cmd script or command should respect the CC, CXX, LD, CFLAGS, CXXFLAGS, LDFLAGS environment variables and should build the tested application in fuzz testing mode (so it should enable fuzzing entrypoints / harnesses). After one execution of build_cmd there should appear one build of the tested app in the build_root directory. The sanitizers variable should contain list of sanitizers to build the app with. BugBane performs a separate build for each specified sanitizer.

bb-build sequentially performs multiple builds of the tested app (with different sanitizers + with coverage + with special instrumentation like cmplog or laf), and results of each build are then saved from build_root to the directory provided as an argument to the -o option. This updates some variables in the bugbane.json file (in particular, sanitizers is filled with the names of sanitizers for which the build was successful).

Example of a script to specify in build_cmd:

#!/bin/bash
set -x

export CXX="${CXX:-afl-clang-fast++}"

rm -rf build
mkdir -p build
test -e Makefile && make clean

make -j obj/libre2.a
$CXX $CXXFLAGS --std=c++11 -I. re2/fuzzing/re2_fuzzer.cc /AFLplusplus/libAFLDriver.a obj/libre2.a -lpthread -o build/re2_fuzzer

When using such a script, compilation flags can be controlled externally using environment variables allowing you to get builds with any sanitizers, coverage instrumentation, debug information, etc.

* This wasn't tested.

All builds are recommended to be performed by fuzzer compilers, including coverage builds.
All builds must be created with debug information containing source lines (-g for gcc, -g or -gline-tables-only for clang).
All builds must be performed with the flag -fno-omit-frame-pointer in order for binaries to provide better stack traces when reproducing bugs or when debugging the binaries manually.
If the fuzzer compilers support environment variables for enabling sanitizers (AFL_USE_ASAN, etc.), then using these variables is preferred over specifying compilation flags manually.
The builds should be placed in appropriately named folders. For example, if fuzzing starts from the /fuzz directory, then an ASAN-instrumented build should be saved under the /fuzz/asan folder. If a build is instrumented with multiple sanitizers, then it's sufficient to save this build in either sanitizer directory. For instance, a build with ASAN, UBSAN, and CFISAN can be placed in either asan, ubsan, cfisan, lsan, tsan, or msan directory - this will not reduce the effectiveness of fuzzing or bugs reproducing. Though, it is recommended to create copies or symlinks according to the sanitizers (/fuzz/asan, /fuzz/ubsan, ...).
If the build process in CI takes time comparable to the fuzz testing time, then it may be worth to just use a single build that simultaneously includes instrumentation of the fuzzer, coverage, and sanitizers. This negatively affects fuzzing performance and creates additional disk load, but it still may be preferable to doing multiple builds. To use a single build of an app, compiled with both ASAN and coverage flags, place the build in the /fuzz/asan folder and then copy (or symlink) it to the /fuzz/coverage path.

Go to the folder of a project to test and execute the following command:

go-fuzz-build

More information is available on the project page.

The following instructions are for the built-in fuzzer which was introduced with the release of go1.18.
Go to the folder of a project to test and run the following command:

go test . -fuzz=FuzzMyFunc -o fuzz -c -cover

Replace FuzzMyFunc with the name of any fuzz test present in the code base. The function name must start with "Fuzz" (see the fuzzer documentation).
The result is the fuzz executable file with an option to run any of the available fuzzing tests. For example, if the code contains the FuzzHttp and FuzzJson tests, then you can build the app with the option -fuzz=FuzzHttp, and as a result, you will be able to run fuzzing with the either option: -test.fuzz=FuzzHttp or -test.fuzz=FuzzJson.
The build option -cover has no effect yet, because fuzzing and coverage are temporarily incompatible in Go. Using the option isn't mandatory, but allows you to avoid making changes in the future when the Go developers bring back fuzzing and coverage compatibility.

Sample exporting works fine, but importing requires using of one of the following options:

• use bb-corpus manual and specify the folder of a specific fuzzing test (for example, out/FuzzXxx) as the output directory
• use bb-corpus suite, but pre-define the variable fuzz_in_dir in the config file (similarly: out/FuzzXxx)
• copy the samples by other means (rsync, cp)

The tool supports importing test cases from the storage to the fuzzer working directory and exporting them from the fuzzer working directory back to the storage.
The storage is just a mounted directory, which can in turn be some Samba share, an NFS drive, etc.

Synchronization occurs in two stages:

1. Copying samples (if importing) or moving them (if exporting) from a source directory to a temporary folder without creating duplicates (SHA1 hash sum checks are in place).
2. Minimizing the samples in the temporary folder, saving results to a destination directory using fuzzer tools (such as afl-cmin)

The variable fuzzer_type must be defined in the configuration file bugbane.json.
For afl-cmin minimization there must be builds of a tested app on disk. The most preferred build for minimizing samples is the one in the laf folder, as it "distinguishes" more execution paths, though, if this build is missing, bb-corpus uses the other builds for minimization.

The names of resulting files contain the SHA1 hash sum of their contents. If the destination directory already contains files with the matching names, no file overwriting occurs.

The tool detects builds of a tested app on disk and distributes them across different processor cores.
The distribution algorithm for C/C++ builds relies on the following rules:

• builds with sanitizers are allocated one core each;
• auxiliary builds (AFL_LLVM_LAF_ALL, AFL_USE_CMPLOG) are assigned to a certain proportion of the available cores;
• the basic build (without sanitizers) occupies the remaining cores;
• builds for source code coverage collection do not participate in fuzz testing (see bb-coverage).

When fuzzing Go applications, there's only one build (in either gofuzz or gotest folder) which is allocated to all available cores.
For the built-in Go fuzzer (go test) bb-fuzz exits on the first bug discovered. This is caused by the way the fuzzer works. If there are no detected bugs, the work continues as usual until a stop condition occurs.

The bugbane.json configuration file must define the variables fuzzer_type, tested_binary_path, fuzz_cores, src_root, run_args, run_env, and timeout. The variable timeout is specified in milliseconds.
The builds of the app to test must exist on disk in folders corresponding to the build type, just as the bb-build tool places them.
There may also be dictionary files with the ".dict" extension in the "dictionaries" folder. They are merged into one dictionary, which is provided for the fuzzer to use, subject to the support from the fuzzer.

The values available for the variable fuzzer_type: AFL++, libFuzzer, go-fuzz, go-test.
The variable tested_binary_path holds the path to the tested app's binary relative to an input directory (where builds will be searched for). Example: imagine, there's a folder named "build" with the build results, executable is named "app" and is saved as build/test/app, the bb-build tool performed several builds each time copying the "build" folder to path /fuzz, that is, now there are paths /fuzz/basic/test/app, /fuzz/coverage/test/app, etc. In this case the tested_binary_path should be "test/app".
The variable src_root is not used directly, but other BugBane tools running after bb-fuzz fail if the variable is missing.
The run_args variable holds a string containing run arguments for the tested app. The variable may include the "@@" sequence, through which the fuzzer may provide input samples for the app.
For the built-in Go fuzzer the variable run_args must contain the -test.fuzz launch option with a specific fuzz test, for instance, -test.fuzz=FuzzHttp.
The run_env contains a dictionary of environment variables, required to fuzz the tested app. The env variable LD_PRELOAD is automatically converted to a corresponding fuzzer variable (such as AFL_PRELOAD for AFL++).
Example of the run_env variable in the configuration file:

"run_env": {
    "LD_PRELOAD": "/src/mylib.so",
    "ENABLE_FUZZ_TARGETS": "1"
}

The following stop conditions are available:

• actual fuzzing duration has reached X seconds (time spent regardless of the number of cores / fuzzer instances);
• no new code execution paths have been detected for the last X seconds among all instances of a fuzzer.

The stop condition is defined using the following environment variables:

• CERT_FUZZ_DURATION=X - X specifies the number of seconds without no new execution paths detected; this variable has the highest priority if other stop condition variables are set;
• CERT_FUZZ_LEVEL=X - X specifies so called "control level", which in turn defines the number of seconds without no new execution paths, available values of X are: 2, 3, 4; this variable has medium priority;
• FUZZ_DURATION=X - X specifies fuzzing duration (number of seconds); this variable has the lowest priority.

The CERT_FUZZ_* variables are fit for software certification trials, and the FUZZ_* variables are intended to be used in CI/CD.
If none of the above variables are defined, then FUZZ_DURATION=600 is used implicitly.

The number of processor cores to use in fuzzing is determined by the minimal value of the following:

1. The number of CPU cores available in the OS.
2. The value of the fuzz_cores variable of the configuration file. If the variable is not specified, the value of 8 is used.
3. The value of the --max-cpus run argument, default is 16.

Thus, the number of processor cores is limited by both the author of the bugbane.json file (presumably, the developer of the tested application), and the end user of BugBane (presumably, an Application Security specialist).

For C/C++ apps the tool does the following:

1. Runs an app under test on samples in the sync directory of a fuzzer
2. Generates a coverage report

For Go apps, the tool works differently:

1. Generates a coverage report using the coverage profiles, generated while fuzzing with the launch option -dumpcover *
2. Changes the background color of the report from black to white

* bb-fuzz uses this option.

The configuration file bugbane.json should define the variables tested_binary_path, run_args, run_env, coverage_type, fuzzer_type, fuzz_sync_dir, and src_root.
The coverage_type variable gets set by bb-build and matches the builder type used there.
The src_root variable holds the path to the source code of the tested app, which existed during the build process; the path does not have to actually exist on the file system during coverage collection: if the directory doesn't exist, then resulting coverage report shows coverage percentages, but not the code itself.

Possible values of the coverage_type variable

The bb-reproduce tool does the following:

1. Collects the overall statistics of fuzzers' operation
2. Minimizes crashes and hangs by reproducing them
3. Records information about each unique reproducible bug
4. Generates a JSON file with the stats and the bugs data
5. Saves test cases resulting in reproducible crashes and hangs to disk

The data saved for each reproducible bug includes the issue/bug title, the location of the bug in the source code, the run command with a particular test sample, the app output (stdout+stderr), the environment variables, etc.
Targets instrumented with SharpFuzz are also supported by the tool.

The bugbane.json configuration file must define the variables src_root, fuzz_sync_dir, fuzzer_type, reproduce_specs, run_args, and run_env. The variables fuzz_sync_dir and reproduce_specs are usually set by the bb-fuzz tool.
The fuzz_sync_dir contains the path to the fuzzer synchronization directory; bb-fuzz uses the "out" directory.
The src_root is the root directory of the tested app's source code as it was at the time of build; the path does not have to exist on the file system as the variable is only used for better precision when locating the crashing/hanging line in the source code.
The reproduce_specs is a JSON dictionary, specifying the fuzzer type and mapping the builds of the tested app to the folders, on which to reproduce bugs:

"fuzz_sync_dir": "/fuzz/out",
"reproduce_specs": {
    "AFL++": {
        "/fuzz/basic/app": [
            "test1"
        ],
        "/fuzz/ubsan/app": [
            "test2",
            "test3"
        ]
    }
}

In the above example the basic build (/fuzz/basic/app) will be run with the samples matching the pattern /fuzz/out/test1/{crashes,hangs}/id*, and for the ubsan build (/fuzz/ubsan/app) the pattern will be /fuzz/out/test{2,3}/{crashes,hangs}/id*.

The output of the tested app is analyzed on each reproduce try, for example, the tool searches for sanitizer messages. Each bug sample is tried until a successful bug detection, but not more than N times. The number N is defined by the --num-reruns argument of bb-reproduce (the default value is 3). When trying a crashing sample, if the app does not produce the stack trace, then the app is ran under the gdb debugger. Hangs are always reproduced under gdb.

Hereinafter https://dojo.local is used as the address of the Defect Dojo server.
--user-id: id of the user specified in the --user-name option; may be taken from the Defect Dojo's url, while desired user is selected on the page https://dojo.local/user.
--engagement: engagement id; may also be taken from the engagement url (select one on the page https://dojo.local/engagement).
--test-type: test type id; also comes from the url (select required test type on the page https://dojo.local/test_type).
--token: API key; copied from the page https://dojo.local/api/key-v2 (you need to be authorized with the name specified in the --user-name option, you need the API key from the part, starting with "Your current API key is ....").
You are advised to use the env variables BB_DEFECT_DOJO_LOGIN and BB_DEFECT_DOJO_SECRET instead of the args --user-name and --token.

If the authenticity of the Defect Dojo server certificate cannot be verified, the --no-ssl option should be added.