Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
Corpus and compatibility keys

A campaign's merged corpus is its most valuable output: a compact set of inputs that together reach a lot of code. Promoting it into the app lets future local campaigns start from that coverage instead of rediscovering it every time. CI keeps its own corpus and does not depend on it (Corpus in CI).

Promoting a corpus

After a good campaign, promote its merged corpus with corpus.py promote:

"$BOLOS_SDK"/fuzzing/scripts/corpus.py promote \
  <app>/.fuzz-artifacts/<run>/targets/<target>/corpus \
  <app>/fuzzing/base-corpus.zip

This writes two tracked files next to each other:

  • base-corpus.zip — the inputs, packed with the Python standard library (no zip/unzip tool required),
  • base-corpus.compat-key — the sidecar key that ties the archive to a build.

The .compat-key is metadata, not a fuzz input, so it is stored beside the archive, never inside it.

Reusing a corpus

Reuse is automatic. On the next run the campaign stages base-corpus.zip into the starting corpus — but only when its sidecar key matches the current build. A mismatch is reported and the stale corpus is skipped, so a changed binary is never fed inputs shaped for an old one. Set BASE_CORPUS_ZIP= (empty) to skip a promoted corpus for one run.

The end-to-end loop:

  1. Run a campaign (Running a campaign).
  2. corpus.py promote its corpus to fuzzing/base-corpus.zip.
  3. Commit base-corpus.zip and base-corpus.compat-key.
  4. The next local campaign starts from it automatically.

Corpus in CI

CI does not rely on the promoted corpus. ClusterFuzzLite publishes each target's corpus as a cifuzz-corpus-<target> artifact and every run starts from the newest one, so the CI corpus grows and is pruned from run to run without any commit (see CI and maintainability).

The promoted corpus is also normally skipped in CI: the key depends on the invariant model, which depends on the toolchain, and CI builds with the OSS-Fuzz Clang. The "Build Fuzzers" step then reports the base corpus as incompatible and logs both keys (compat_key: <key> for each target). That message is expected and does not affect the CI corpus.

The compatibility key

The key is:

sha256( prefix_size || sha256(fuzz_globals.zon) || fuzzer || harness_version )

So it changes when the prefix size changes, when the invariant model changes (a new sanitizer, an SDK/toolchain change that shifts globals), or when you bump harness_version in the manifest. When the key changes, the old base corpus no longer matches: rerun a campaign and promote again to refresh it.

Warning
A refusal is easy to miss. run_single_target is invoked as if ! run_single_target ..., which disables errexit for its whole body, so the campaign continues from generated seeds alone and still reports a coverage number. Check for the warning before trusting it: bootstrapping from a few dozen seeds instead of a few thousand evolved inputs changes the result materially.

When to promote

  • After a long run that reached coverage you want to keep.
  • After a change that invalidated the key (the previous corpus is now skipped), so local campaigns do not restart from generated seeds.

One promoted corpus per target is the intended shape.