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/.