Skip to content

commands.md

Latest commit

 

History

History
245 lines (161 loc) · 5.37 KB

commands.md

File metadata and controls

245 lines (161 loc) · 5.37 KB

Commands

Complete reference for all CosmFuzz commands.

cargo cosmfuzz init

Initialize CosmFuzz configuration in the current directory.

cargo cosmfuzz init --contracts <CONTRACT1> [CONTRACT2...]

Options

  • --contracts: List of contract names to fuzz (can specify multiple or none)
  • --name: Custom name for the fuzzing project (optional, defaults to directory name)
  • --fuzz-dir: Custom path for fuzz directory (optional, default: /tmp/cosmfuzz)

Examples

# Single contract in current directory
cargo cosmfuzz init --contracts my-contract

# Multiple contracts
cargo cosmfuzz init --contracts cw20-base cw20-staking

# With custom name and directory
cargo cosmfuzz init --contracts token --name my-token-fuzzer --fuzz-dir ./fuzz

# No contracts (will prompt or use current directory)
cargo cosmfuzz init

Creates a cosmfuzz-config.toml file in the current directory.

Notes:

  • init runs cargo afl system-config.
  • build patches cosmwasm-std's MockApi::addr_validate to return Ok(Addr::unchecked(input)) for fuzzing.

cargo cosmfuzz build

Generate and build the fuzzing harness template.

cargo cosmfuzz build [-- <ZIGGY_ARGS>...]

What it does

  1. Scans contract source code for invariant functions
  2. Generates fuzzing harness template at {fuzz_dir}/{project_name}/src/main.rs
  3. Preserves any InstantiateMsg customizations from previous builds
  4. Builds the fuzzer using cargo ziggy build

Note: After first build, you must edit the generated harness to configure InstantiateMsg for your contracts. See the TODO comments in the generated main.rs.

Examples

# Basic build (uses AFL++ only by default)
cargo cosmfuzz build

# Build with specific fuzzer
cargo cosmfuzz build -- --no-afl

# Build with Honggfuzz (may have build issues)
cargo cosmfuzz build -- --honggfuzz

Notes

  • Uses --no-honggfuzz by default (AFL++ only) to avoid Honggfuzz build issues
  • Preserves InstantiateMsg customizations across rebuilds
  • Automatically discovers new invariants when you rebuild

cargo cosmfuzz fuzz

Run the fuzzer.

cargo cosmfuzz fuzz [-- <ZIGGY_ARGS>...]

Examples

# Basic fuzzing (uses config timeout/jobs if set)
cargo cosmfuzz fuzz

# Override timeout and jobs
cargo cosmfuzz fuzz -- -t 120 -j 8

# Use specific fuzzer
cargo cosmfuzz fuzz -- --no-afl

Config Integration

If you set timeout and jobs in cosmfuzz-config.toml, they're automatically used:

[fuzzing]
timeout = 60  # seconds
jobs = 4      # parallel jobs

Command-line args override config values.

cargo cosmfuzz run

Run the fuzzer with a single input file (for debugging).

cargo cosmfuzz run <INPUT_FILE> [-- <ZIGGY_ARGS>...]

Examples

# Run with a crash file
cargo cosmfuzz run /tmp/cosmfuzz/my-project/output/cosmfuzz/crashes/1760454353603/id:000000...

# Run with custom test input
cargo cosmfuzz run ./test_input.bin

# Run with directory of inputs
cargo cosmfuzz run ./crash_samples/

Use Cases

  • Reproducing crashes found during fuzzing
  • Debugging specific inputs
  • Validating fixes before re-running the full fuzzer
  • Testing with custom inputs

Output

Shows full backtrace and panic messages for crashes.

cargo cosmfuzz coverage

Generate code coverage information.

cargo cosmfuzz coverage [-- <ZIGGY_ARGS>...]

Examples

# Generate coverage from existing corpus
cargo cosmfuzz coverage

# Pass additional args to ziggy
cargo cosmfuzz coverage -- <args>

Coverage reports are generated in the fuzzer output directory.

cargo cosmfuzz add-seeds

Add seeds to the fuzzer corpus.

cargo cosmfuzz add-seeds <PATH> [-- <ZIGGY_ARGS>...]

Examples

# Add seeds from directory
cargo cosmfuzz add-seeds ./seeds

# Add single seed file
cargo cosmfuzz add-seeds ./interesting_input.bin

Seeds are copied to the fuzzer's corpus for use in future fuzzing runs.

cargo cosmfuzz minimize

Minimize the corpus.

cargo cosmfuzz minimize [-- <ZIGGY_ARGS>...]

Examples

# Minimize corpus
cargo cosmfuzz minimize

Reduces the corpus to the smallest set of inputs that achieve the same coverage.

cargo cosmfuzz clean

Clean the fuzz directory (removes generated harness and all fuzzing artifacts).

cargo cosmfuzz clean

Examples

# Remove the entire fuzz directory
cargo cosmfuzz clean

What it does

  • Deletes the entire fuzz directory: {fuzz_dir}/{project_name}/
  • Removes generated harness, build artifacts, corpus, crashes, and coverage data
  • After cleaning, run cargo cosmfuzz build to regenerate the harness

Use cases

  • Start fresh after major changes to contracts
  • Clean up disk space
  • Reset fuzzing state completely
  • Force regeneration of harness without InstantiateMsg preservation

General Notes

Passing Arguments to Ziggy

All commands support passing additional arguments to the underlying cargo ziggy command using --:

cargo cosmfuzz <command> -- <ziggy_args>

Working Directory

Most commands need to be run from a directory containing (or parent of) cosmfuzz-config.toml. The config file is searched upward from the current directory.

Environment

CosmFuzz automatically sets:

  • RUSTFLAGS="--cfg cosmfuzz" - Enables the cosmfuzz modules in your contracts
  • CARGO_HOME={fuzz_dir}/cargo_home - Isolates cargo cache