Skip to content

Fuzz Testing

Sipi uses libFuzzer to fuzz-test the IIIF URI parser (parse_iiif_uri). The fuzzer feeds random and mutated inputs to the parser, looking for crashes, memory safety issues, and undefined behavior via AddressSanitizer.

Architecture

fuzz/
├── CMakeLists.txt              # Top-level fuzz build (adds subdirectories)
└── handlers/
    ├── CMakeLists.txt           # Fuzz target build config (requires Clang)
    ├── iiif_handler_uri_parser_target.cpp  # Fuzz harness
    └── corpus/                  # Seed corpus (checked into git)
        ├── iiif_basic           # /prefix/image.jp2/full/max/0/default.jpg
        ├── info_json            # /unit/lena512.jp2/info.json
        ├── knora_json           # /unit/lena512.jp2/knora.json
        └── ...                  # 52 seed inputs total

The fuzz harness is minimal — it converts the fuzzer's byte input to a std::string and calls parse_iiif_uri():

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
  std::string input(reinterpret_cast<const char *>(Data), Size);
  auto result = handlers::iiif_handler::parse_iiif_uri(input);
  if (result.has_value()) {
    volatile auto type = result->request_type;
    (void)type;
  }
  return 0;
}

Requirements

libFuzzer is built into Clang, so the fuzz variant uses llvmPackages_19.stdenv under the hood. Nix handles the toolchain — no dev-shell dance required.

The CMake config (fuzz/handlers/CMakeLists.txt) guards the target behind a Clang check; it won't build with GCC or zig-cc, but .#fuzz pins Clang so that path never matters in practice.

Running Locally

Build the fuzz target

just nix-build-fuzz

This wraps nix build .#fuzz and emits result/bin/iiif_handler_uri_parser_fuzz.

Run with seed corpus

mkdir -p corpus-live
just nix-run-fuzz corpus-live 60 fuzz/handlers/corpus
  • First positional arg (corpus-live) — live corpus directory. New interesting inputs are written here.
  • Second positional arg (60) — duration in seconds. Without a bound the fuzzer runs indefinitely (Ctrl+C to stop).
  • Third positional arg (fuzz/handlers/corpus) — optional read-only seed corpus. These 52 inputs give the fuzzer a head start with known-good IIIF URIs.

The recipe forwards libFuzzer's exit code so a crash propagates through just. It also appends -print_final_stats=1 automatically.

Understanding the output

INFO: Loaded 52 files from ../../../fuzz/handlers/corpus/
#52    INITED cov: 623 ft: 1439 corp: 35/1066b
#55    NEW    cov: 625 ft: 1441 corp: 36/1104b
#96    REDUCE cov: 670 ft: 1589 corp: 46/1461b
Field Meaning
cov Code coverage edges discovered — should grow initially, then plateau
ft Feature targets — finer-grained coverage metric
corp Corpus size / total bytes — grows as new interesting inputs are found
NEW Found an input that triggers new coverage
REDUCE Found a smaller input that triggers the same coverage
pulse Periodic heartbeat — the fuzzer is still running

Useful flags

For anything beyond duration + seed corpus, invoke the fuzzer binary directly (the just recipe is a thin convenience wrapper, not a full passthrough):

# Limit input size (parser inputs are short URIs, not megabytes)
./result/bin/iiif_handler_uri_parser_fuzz corpus-live/ -max_len=256

# Run a fixed number of iterations
./result/bin/iiif_handler_uri_parser_fuzz corpus-live/ -runs=100000

# Reproduce a crash (run a single input)
./result/bin/iiif_handler_uri_parser_fuzz /path/to/crash-abc123

CI Integration

The fuzz workflow (.github/workflows/fuzz.yml) runs:

  • Nightly at 02:00 UTC
  • On demand via the Actions tab → "fuzz" → "Run workflow" (with configurable duration)

What it does

  1. Builds the fuzz target via just nix-build-fuzz (→ nix build .#fuzz)
  2. Downloads the corpus from the previous night's run (if available)
  3. Runs just nix-run-fuzz fuzz-corpus-live $FUZZ_DURATION fuzz/handlers/corpus (default 10 minutes), merging new findings into the live corpus
  4. Uploads the updated corpus as an artifact (fuzz-corpus, retained 30 days)
  5. On crash (libFuzzer exits non-zero; set -o pipefail propagates it):
    • Uploads crash reproducers as artifacts (fuzz-crashes, retained 90 days)
    • Opens a GitHub issue with crash details, hex dump, and reproduction instructions

Corpus accumulation

Each nightly run picks up where the last one left off. The corpus grows over time, so the fuzzer spends its time exploring new territory rather than rediscovering known paths.

Night 1: 52 seeds → 10 min → ~200 inputs (uploaded)
Night 2: ~200 inputs → 10 min → ~300 inputs (uploaded)
Night N: corpus keeps growing, coverage accumulates

Updating the Seed Corpus

Periodically, you should pull the CI corpus back into the repo so that:

  • Local fuzzing starts with the best available coverage
  • The CI corpus survives artifact expiration (30-day retention)
  • New contributors get a rich starting corpus

Download and merge

just fuzz-corpus-update

This downloads the latest fuzz-corpus artifact from CI, deduplicates by content hash, and merges into fuzz/handlers/corpus/. It reports how many new inputs were added.

Then commit the result:

git add fuzz/handlers/corpus/
git commit -m "test: update fuzz seed corpus from CI"

When to update

  • After the fuzzer has been running for a few weeks and coverage has grown significantly
  • Before a release, to lock in the best available corpus
  • After fixing a bug found by the fuzzer (the crash input is automatically in the CI corpus)

Adding New Fuzz Targets

To fuzz a different component:

  1. Create a new directory under fuzz/ (e.g., fuzz/image_processing/)
  2. Write a harness implementing LLVMFuzzerTestOneInput
  3. Add a CMakeLists.txt with -fsanitize=fuzzer,address flags (copy from fuzz/handlers/CMakeLists.txt)
  4. Register the subdirectory in fuzz/CMakeLists.txt
  5. Create a corpus/ directory with seed inputs
  6. Add a step to .github/workflows/fuzz.yml for the new target