git:20260902.1fe14a3 to git:20260905.1f63894

---

name: cargo-fuzz

---

# cargo-fuzz

## Contract

| Field | Bound contract |

|---|---|

| Trigger | User needs to initialize, run, measure, or triage a cargo-fuzz target in a Rust crate. |

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

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

```

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