Crate honggfuzz [−] [src]

About Honggfuzz

Honggfuzz is a security oriented fuzzer with powerful analysis options. Supports evolutionary, feedback-driven fuzzing based on code coverage (software- and hardware-based).

Compatibility

  • Rust: stable, beta, nightly
  • OS: GNU/Linux, macOS, FreeBSD, Android, WSL (Windows Subsystem for Linux)
  • Arch: x86_64, x86, arm64-v8a, armeabi-v7a, armeabi
  • Sanitizer: none, address, thread, leak

How to use this crate

Install honggfuzz commands to build with instrumentation and fuzz

# installs hfuzz and honggfuzz subcommands in cargo
cargo install honggfuzz

Add to your dependencies

[dependencies]
honggfuzz = "0.5"

Create a target to fuzz

#[macro_use] extern crate honggfuzz;
 
fn main() {
    // Here you can parse `std::env::args and 
    // setup / initialize your project
 
    // You have full control over the loop but
    // you're supposed to call `fuzz` ad vitam aeternam
    loop {
        // The fuzz macro gives an arbitrary object (see `arbitrary crate`)
        // to a closure-like block of code.
        // For performance reasons, it is recommended that you use the native type
        // `&[u8]` when possible.
        // Here, this slice will contain a "random" quantity of "random" data.
        fuzz!(|data: &[u8]| {
            if data.len() != 6 {return}
            if data[0] != b'q' {return}
            if data[1] != b'w' {return}
            if data[2] != b'e' {return}
            if data[3] != b'r' {return}
            if data[4] != b't' {return}
            if data[5] != b'y' {return}
            panic!("BOOM")
        });
    }
}

Fuzz for fun and profit !

# builds with fuzzing instrumentation and then runs the "example" target
cargo hfuzz run example

Once you got a crash, replay it easily in a debug environment

# builds the target in debug mode and replays automatically the crash in gdb
cargo hfuzz run-debug example fuzzing_workspace/*.fuzz

Clean

# a wrapper on "cargo clean" which cleans the fuzzing_target directory
cargo hfuzz clean

Environment variables

RUSTFLAGS

You can use RUSTFLAGS to send additional arguments to rustc.

For instance, you can enable the use of LLVM's sanitizers. This is a recommended option if you want to test your unsafe rust code but it will have an impact on performance.

RUSTFLAGS="-Z sanitizer=address" cargo hfuzz run example

HFUZZ_BUILD_ARGS

You can use HFUZZ_BUILD_ARGS to send additional arguments to cargo build.

HFUZZ_RUN_ARGS

You can use HFUZZ_RUN_ARGS to send additional arguments to honggfuzz. See USAGE for the list of those.

For example:

# 1 second of timeout
# use 12 fuzzing thread
# be verbose
# stop after 1000000 fuzzing iteration
# exit upon crash
HFUZZ_RUN_ARGS="-t 1 -n 12 -v -N 1000000 --exit_upon_crash" cargo hfuzz run example

HFUZZ_DEBUGGER

By default we use rust-lldb but you can change it to rust-gdb, gdb, /usr/bin/lldb-7 ...

Relevant documentation about honggfuzz

About Rust fuzzing

There is other projects providing Rust fuzzing support at github.com/rust-fuzz.

You'll find support for AFL and LLVM's LibFuzzer and there is also a trophy case ;-) .

This crate was inspired by those projects!

Macros

fuzz

Fuzz a closure-like block of code by passing it an object of arbitrary type.

Functions

fuzz

Fuzz a closure by passing it a &[u8]