Skip to main content

Fuzz Container API

A Fuzz Container needs to adhere to the API outlined in this document so that CI Sense can execute the fuzz tests in the Fuzz Container and report relevant results.

Note: Fuzz Containers built by CI Fuzz already adhere to the API outlined in this document. The reference here is only for very advanced custom builds in scenarios where CI Fuzz can not produce the desired Fuzz Container out of the box.

Expected CLI behavior​

CI Sense always passes the fuzz test name as the first argument to the fuzz container and follows up with the following optional flags:

  1. --json-output-file - File to write progress information and findings as json messages into.
  2. --generated-corpus-dir - Directory to store the fuzzing corpus.
  3. --coverage-output-path - Output directory for coverage information.
  4. --stop-signal-file - File that is written to on exit.
  5. -v - Enable additional logging.

Fuzz container output​

The Fuzz Container may print arbirary logs on stdout and stderr. In order for CI Sense to display progress information and findings the Fuzz Container is expected to write JSON messages into the file specified via the --json-output-file flag. The exact JSON output format is intentionally not documented here and is not considered to be stable at time of writing.

Data persisted for a future execution of a fuzz test needs to be stored in the directory specified with the --generated-corpus-dir flag.