Terminology

Fuzzing engine a.k.a. fuzzer {#fuzzer}

A program that produces an infinite stream of inputs for a target and orchestrates the execution.

Fuzz target {#target}

A binary, a library, an API, or rather anything that can consume bytes for input and produce some sort of coverage data as an output. A libFuzzer's target can be a Centipede's target. Read more here .

Input {#input}

A sequence of bytes that can be fed to a target. The input can be an arbitrary bag of bytes, or some structured data, e.g. serialized proto.

Feature

A number that represents some unique behavior of the target. E.g. a feature 1234567 may represent the fact that a basic block number 987 in the target has been executed 7 times. When executing an input with the target, the fuzzer collects the features that were observed during execution.

Feature set

A set of features associated with one specific input.

Coverage

Some information about the behaviour of the target when it executes a given input. Coverage is usually represented as feature set that the input has triggered in the target.

Mutator

A function that takes bytes as input and outputs a small random mutation of the input. See also: structure-aware fuzzing .

Executor {#executor}

A function that knows how to feed an input into a target and get coverage in return (i.e. to execute).

Centipede

A customizable fuzzing engine that allows the user to substitute the Mutator and the Executor.

Centipede runner {#runner}

A library that implements the executor interface expected by the Centipede fuzzer. The runner knows how to run a sancov-instrumented target, collect the resulting coverage, and pass it back to Centipede. Prospective Centipede fuzz targets can be linked with this library to make them runnable by Centipede.

Corpus (plural: corpora)

A set of inputs.

Distillation (creating a distilled corpus)

A process of choosing a subset of a larger corpus, such that the subset has the same coverage features as the original corpus.

Shard

A file representing a subset of the corpus and another file representing feature sets for that same subset of the corpus.

Merging shards

To merge shard B into shard A means: for every input in shard B that has features missing in shard A, add that input to A.

Job

A single fuzzer process. One job writes only to one shard, but may read multiple shards.

Workdir or WD

A local or remote directory that contains data produced or consumed by a fuzzer.

Build Centipede

What you will need for the subsequent steps:

• $BIN_DIR/centipede - the binary of the engine (the fuzzer).
• $BIN_DIR/libcentipede_runner.pic.a - the library you need to link with your fuzz target (the runner).
• $CENTIPEDE_SRC/clang-flags.txt - recommended clang compilation flags for the target.

You can keep these files where they are or copy them somewhere.

Build your fuzz target

We provide two examples of building the target: one tiny single-file target and libpng. Once you've built your target, proceed to the fuzz target running step.

The simple example

This example uses one of the simple example fuzz targets, a.k.a. puzzles, included in the Centipede repo.

Compile

NOTE: The commands below use the flags from $CENTIPEDE_SRC/clang-flags.txt. You may choose to use some other set of instrumentation flags: clang-flags.txt only provides a simple default option.

Link

This step links the just-built fuzz target with libcentipede_runner.pic.a and other required libraries.

Skip to the running step.

The libpng example

Download and compile libpng

Link libpng's own fuzz target with libcentipede_runner.pic.a

Run Centipede locally {#run-step}

Running locally will not give the full scale, but it could be useful during the fuzzer development stage. We recommend that both the fuzzer and the target are copied to a local directory before running in order to avoid stressing a network file system.

Prepare for a run

NOTE: You may need to add llvm-symbolizer to your $PATH for some of the Centipede functionality to work. The symbolizer can be installed as part of the LLVM distribution:

Run one fuzzing job

See what's in the working directory

Run 5 concurrent fuzzing jobs

WARNING: Do not exceed the number of cores on your machine for the --j flag.

See what's in the working directory:

Corpus distillation

Each Centipede shard typically does not cover all features that the entire corpus covers. In order to distill the corpus, a Centipede process will need to read all shards. Currently, distillation works like this:

• Run fuzzing as described above, so that all shards have their feature sets computed. Stop fuzzing.
• Then, run the same fuzzing jobs, but with --distill_shards=N. This will cause the first N jobs to produce N independent distilled corpus files (one per job). Each of the distilled corpora should have the same features as the full corpus, but the inputs might be very different between these distilled corpora.

If you need to also export the distilled corpus to a libFuzzer-style directory (local dir with one file per input), add --corpus_dir=DIR.

Coverage report

Centipede generates a simple coverage report in a form of a text file. The shard 123 generates a file workdir/coverage-report-BINARY.000123.txt before the actual fuzzing begins, i.e. the report reflects the coverage as observed by the shard 123 after loading the corpus.

The report shows functions that are fully covered (all control flow edges are observed at least once), not covered, or partially covered. For partially covered functions the report contains symbolic information for all covered and uncovered edges.

The report will look something like this:

Customization

TBD

Related Reading

• Centipede Design