cargo-fuzz

cargo-fuzz is the de facto choice for fuzzing Rust projects using Cargo. It uses libFuzzer as the backend and provides automatic sanitizer support including AddressSanitizer.

When to Use

Choose cargo-fuzz when:

• Your project uses Cargo (required)
• You want simple, quick setup with minimal configuration
• You need integrated sanitizer support
• You're fuzzing Rust code with or without unsafe blocks

Fuzzer	Best For	Complexity
cargo-fuzz	Cargo-based Rust projects, quick setup	Low
AFL++	Multi-core fuzzing, non-Cargo projects	Medium
LibAFL	Custom fuzzers, research, advanced use cases	High

Installation

cargo-fuzz requires the nightly Rust toolchain.

# Install nightly toolchain
rustup install nightly

# Install cargo-fuzz
cargo install cargo-fuzz

# Verify
cargo +nightly fuzz --version

Quick Start

#![no_main]
use libfuzzer_sys::fuzz_target;

fn harness(data: &[u8]) {
    your_project::check_buf(data);
}

fuzz_target!(|data: &[u8]| {
    harness(data);
});

Initialize and run:

cargo fuzz init
# Edit fuzz/fuzz_targets/fuzz_target_1.rs with your harness
cargo +nightly fuzz run fuzz_target_1

Writing a Harness

Project Structure

cargo-fuzz works best when your code is structured as a library crate:

src/
  main.rs    # Entry point (main function)
  lib.rs     # Code to fuzz (public functions)
Cargo.toml
fuzz/
  Cargo.toml
  fuzz_targets/
    fuzz_target_1.rs

Harness Structure

#![no_main]
use libfuzzer_sys::fuzz_target;

fn harness(data: &[u8]) {
    // 1. Validate input size if needed
    if data.is_empty() {
        return;
    }
    
    // 2. Call target function with fuzz data
    your_project::target_function(data);
}

fuzz_target!(|data: &[u8]| {
    harness(data);
});

Harness Rules

Do	Don't
Structure code as library crate	Keep everything in main.rs
Use fuzz_target! macro	Write custom main function
Handle Result::Err gracefully	Panic on expected errors
Keep harness deterministic	Use random number generators

Structure-Aware Fuzzing

Use the arbitrary crate for structure-aware fuzzing:

// In your library crate
use arbitrary::Arbitrary;

#[derive(Debug, Arbitrary)]
pub struct Config {
    pub timeout: u32,
    pub retries: u8,
    pub data: Vec<u8>,
}

// In your fuzz target
#![no_main]
use libfuzzer_sys::fuzz_target;

fuzz_target!(|config: your_project::Config| {
    your_project::process_config(config);
});

Add to your library's Cargo.toml:

[dependencies]
arbitrary = { version = "1", features = ["derive"] }

Running Campaigns

Basic Run

cargo +nightly fuzz run fuzz_target_1

Without Sanitizers (Safe Rust)

If your project doesn't use unsafe Rust, disable sanitizers for 2x performance:

cargo +nightly fuzz run --sanitizer none fuzz_target_1

Check if your project uses unsafe code:

cargo install cargo-geiger
cargo geiger

Using Dictionaries

cargo +nightly fuzz run fuzz_target_1 -- -dict=./dict.dict

libFuzzer Options

# See all options
cargo +nightly fuzz run fuzz_target_1 -- -help=1

# Set timeout per run
cargo +nightly fuzz run fuzz_target_1 -- -timeout=10

# Limit maximum input size
cargo +nightly fuzz run fuzz_target_1 -- -max_len=1024

Interpreting Output

Output	Meaning
NEW	New coverage-increasing input discovered
pulse	Periodic status update
INITED	Fuzzer initialized successfully
Crash with stack trace	Bug found, saved to fuzz/artifacts/

• Corpus location: fuzz/corpus/fuzz_target_1/
• Crashes location: fuzz/artifacts/fuzz_target_1/

Coverage Analysis

Prerequisites

rustup toolchain install nightly --component llvm-tools-preview
cargo install cargo-binutils
cargo install rustfilt

Generating Coverage Reports

# Generate coverage data from corpus
cargo +nightly fuzz coverage fuzz_target_1

Tips and Tricks

Tip	Why It Helps
Start with a seed corpus	Dramatically speeds up initial coverage discovery
Use --sanitizer none for safe Rust	2x performance improvement
Check coverage regularly	Identifies gaps in harness or seed corpus
Use dictionaries for parsers	Helps overcome magic value checks
Structure code as library	Required for cargo-fuzz integration

Troubleshooting

Problem	Cause	Solution
"requires nightly" error	Using stable toolchain	Use cargo +nightly fuzz
Slow fuzzing performance	ASan enabled for safe Rust	Add --sanitizer none flag
"cannot find binary"	No library crate	Move code from main.rs to lib.rs
Low coverage	Missing seed corpus	Add sample inputs to fuzz/corpus/
Magic value not found	No dictionary	Create dictionary file with magic values

Example: Parsing Library

#![no_main]
use libfuzzer_sys::fuzz_target;
use std::io::Cursor;

fuzz_target!(|data: &[u8]| {
    let mut reader = Cursor::new(data.to_vec());
    
    // Parse the data - don't panic on expected errors
    if let Ok(parsed) = my_parser::parse(&mut reader) {
        // Optionally re-serialize to check roundtrip
        let _ = my_parser::serialize(&parsed);
    }
});

Attribution

Based on trailofbits/skills cargo-fuzz skill.