honggfuzz-rs

Fuzz your Rust code with Honggfuzz !

Documentation

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

project homepage honggfuzz.com
project repository github.com/google/honggfuzz
this upstream project is maintained by Google, but ...
this is NOT an official Google product

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!

honggfuzz 0.5.7