Cargo Fuzz

---
name: cargo-fuzz
description: 'Use when initializing, running, measuring coverage, or triaging a cargo-fuzz target in a Rust crate. Installs the nightly toolchain, writes the fuzz_target! harness, runs under the chosen sanitizer, and reproduces crash artifacts. Not for remote, credential, publish, deploy, or irreversible changes.'
---

# cargo-fuzz

## Contract

| Field | Bound contract |
|---|---|
| Trigger | User needs to initialize, run, measure, or triage a cargo-fuzz target in a Rust crate. |
| Authority | Reversible local writes to the `fuzz/` workspace, corpus, artifact, and coverage output directories under the target crate, plus `src/` edits needed to expose a library target (e.g., moving code from `src/main.rs` to `src/lib.rs`) and nightly toolchain and cargo-fuzz installation via `rustup` and `cargo install`. Rollback by removing `fuzz/`, reverting `src/` edits, and uninstalling the added toolchain or tool. |
| Side effect | Creates and mutates Rust fuzz targets, corpus files, crash artifacts, coverage reports, and `src/` layout on the local filesystem. Installs nightly Rust and cargo-fuzz if absent. No remote, credential, or VCS mutation. |
| Done | The named cargo-fuzz target runs under the intended sanitizer and reproduces any selected artifact. |

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

## 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]`:
   ```rust
   #![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:
   ```bash
   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/ <source filter>
   ```
   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/`.