Architecture & Testing

🐇 Fuzzers

The /fuzzers/ directory contains fuzzer definitions, consisting of code to fuzz, instructions on how to compile & fuzz it, and example inputs the fuzzer can use to generate its own new fuzz. For more details on how to create your own fuzzer, look at the Fuzzer Setup & Configuration wiki page.

⚓️ Fuzzer Base

The /fuzzer-base/ directory contains all the files used to build the base docker image that is then implemented by the fuzzers defined above.

⚠️ All commands below this line assume you are running them from within the /fuzzer-base/ directory.

Testing

Run make test to run the Go unit tests

Run make deploy to deploy a test fuzzer that runs the current files with an actual fuzzing load

Directory Structure

• ./cmd/ contains all of the scripts and code that runs alongside fuzzers to provide logging, file management, and backups.

• ./config/ contains all configuration files used when instrumenting & running fuzzers, such as Supervisord config files. You can generally leave this directory alone unless you're adding support for a new fuzzing engine entirely.

• ./fuzzer-files/ contains some lightweight sample fuzzers (test-fuzzer for C/AFL and png-fuzzer for Go), which can be spun up to test out changes in a real environment.

In addition, it contains base/start, which is run after each fuzzer's specific start file. It sets up any last-minute environment variables before passing control over to Supervisord to run the instrumentation/logging binaries, and fuzzers. Again, this should really only be changed when updating fuzzing engine support.

• ./internal/ contains helper functions used by multiple packages in ./cmd/

• ./scripts/ bash scripts to make life easier/that don't require a full on package in ./cmd/

• ./sidecar/ configuration & files for a node.js sidecar server. As of now it just returns 200 to any request sent to it, in order to pass health checks. Goal: make health checks actively reflect when a fuzzer is running appropriately.