Cargo Fuzz

cargo-fuzz

Contract

Inputs

• Target crate path (required): the Cargo crate to fuzz, containing a library target.
• Fuzz target name (required for run/coverage/triage; generated by init): the name under fuzz/fuzz_targets/.
• Sanitizer choice (optional, default address): one of address, thread, memory, none. Use none only for pure safe Rust with no unsafe in the dependency tree.
• Crash artifact path (optional, for triage): a file under fuzz/artifacts/<target>/.
• Source filter (optional, for coverage): one or more src/*.rs paths to scope the HTML report, loaded into the SRC_FILTER array.

Procedure

1. Install the nightly toolchain and cargo-fuzz with rustup install nightly and cargo install cargo-fuzz. Confirm both are installed with cargo +nightly --version and cargo fuzz --version. cargo-fuzz requires nightly because it relies on unstable compiler features and libFuzzer integration. Done when: nightly and cargo-fuzz are installed and confirmed.
2. Ensure the target crate exposes a library target. If the project is binary-only, move reusable code from src/main.rs into src/lib.rs so the fuzz harness can call it. Done when: the crate exposes a library target.
3. Initialize the fuzz workspace: cargo fuzz init. This creates fuzz/Cargo.toml and fuzz/fuzz_targets/fuzz_target_1.rs. Done when: the fuzz workspace is initialized.
4. Write the harness in the generated fuzz target file using the fuzz_target! macro with #![no_main]:

   #![no_main]
   use libfuzzer_sys::fuzz_target;
   
   fuzz_target!(|data: &[u8]| {
       your_project::target_function(data);
   });
   

   Handle Result::Err gracefully inside the harness, and keep the harness deterministic with no RNG. For structure-aware fuzzing, derive Arbitrary on a type in the library crate (#[derive(Debug, Arbitrary)]) and add arbitrary = { version = "1", features = ["derive"] } to the library Cargo.toml. Use that type as the fuzz_target! parameter instead of &[u8]. Done when: the harness is written with deterministic behavior and graceful error handling.
5. Run the campaign: cargo +nightly fuzz run <target>. AddressSanitizer is enabled by default. To disable it for pure safe Rust, first verify no unsafe code with cargo install cargo-geiger && cargo geiger, then run cargo +nightly fuzz run --sanitizer none <target> for approximately 2x throughput. Done when: the campaign is running or completed under the chosen sanitizer.
6. Reproduce a crash artifact: cargo +nightly fuzz run <target> fuzz/artifacts/<target>/crash-<hash>. To replay the full corpus without fuzzing: cargo +nightly fuzz run <target> fuzz/corpus/<target> -- -runs=0. Pass libFuzzer options after -- (e.g. -timeout=10, -max_len=1024, -dict=dict.dict). Done when: the artifact is reproduced or the corpus is replayed.
7. Measure coverage: install rustup toolchain install nightly --component llvm-tools-preview, cargo install cargo-binutils, and cargo install rustfilt. Run cargo +nightly fuzz coverage <target>. Generate the HTML report:

   HOST=$(rustc -vV | sed -n 's|host: ||p')
   cargo +nightly cov -- show -Xdemangler=rustfilt \
     "target/$HOST/coverage/$HOST/release/<target>" \
     -instr-profile="fuzz/coverage/<target>/coverage.profdata" \
     -show-line-counts-or-regions -show-instantiations \
     -format=html -o fuzz_html/ ${SRC_FILTER[@]+"${SRC_FILTER[@]}"}
   

   Leave SRC_FILTER unset when no source filter is supplied. Done when: the HTML coverage report is generated under fuzz_html/.

Failure and recovery

• "requires nightly" error: the stable toolchain was selected. Re-run with cargo +nightly fuzz.
• Sanitizer compilation failure: the installed nightly is incompatible. Pin a dated nightly with rustup install nightly-<YYYY-MM-DD> and re-run.
• "cannot find binary": the crate has no library target. Move code from main.rs into lib.rs and re-run cargo fuzz init.
• Low coverage: the seed corpus is empty or sparse. Add representative sample inputs to fuzz/corpus/<target>/.
• Magic value not reached: supply a dictionary file with -dict=<file>.
• Partial-result rule: a crash artifact must be reproduced by re-running the target against it before reporting it as a terminal finding. If reproduction fails, classify the artifact as nondeterministic rather than confirmed. Do not stop on an unreproduced artifact.
• Rollback: mutations cover fuzz/, target/, fuzz_html/, src/ edits to expose a library target, and toolchain installation. Remove fuzz/ to revert initialization; delete fuzz/corpus/<target>/, fuzz/artifacts/<target>/, or fuzz/coverage/ to revert a single phase. Revert src/ edits by restoring the original file layout. Uninstall the nightly toolchain or cargo-fuzz with rustup toolchain uninstall nightly or cargo uninstall cargo-fuzz if they were installed by this skill.

Output

A running or completed fuzz campaign under the chosen sanitizer, a corpus under fuzz/corpus/<target>/, any crash artifacts under fuzz/artifacts/<target>/ (each reproducible by re-running the target against the artifact path), and optionally an HTML coverage report under fuzz_html/.