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

Description (from upstream project)

It's multi-process and multi-threaded: no need to run multiple copies of your fuzzer, as honggfuzz can unlock potential of all your available CPU cores with one process. The file corpus is automatically shared and improved between the fuzzing threads.
It's blazingly fast when in the persistent fuzzing mode). A simple/empty LLVMFuzzerTestOneInput function can be tested with up to 1mo iterations per second on a relatively modern CPU (e.g. i7-6700K)
Has a solid track record of uncovered security bugs: the only (to the date) vulnerability in OpenSSL with the critical score mark was discovered by honggfuzz. See the Trophies paragraph for the summary of findings to the date
Uses low-level interfaces to monitor processes (e.g. ptrace under Linux). As opposed to other fuzzers, it will discover and report hijacked/ignored signals (intercepted and potentially hidden by signal handlers)
Easy-to-use, feed it a simple corpus directory (can even be empty) and it will work its way up expanding it utilizing feedback-based coverage metrics
Supports several (more than any other coverage-based feedback-driven fuzzer) hardware-based (CPU: branch/instruction counting, Intel BTS, Intel PT) and software-based feedback-driven fuzzing methods known from other fuzzers (libfuzzer, afl)
Works (at least) under GNU/Linux, FreeBSD, Mac OS X, Windows/CygWin and Android
Supports the persistent fuzzing mode (long-lived process calling a fuzzed API repeatedly) with libhfuzz/libhfuzz.a. More on that can be found here
Can fuzz remote/standalone long-lasting processes (e.g. network servers like Apache's httpd and ISC's bind), though the persistent fuzzing mode is suggested instead: as it's faster and multiple instances of a service can be fuzzed with this
It comes with the examples directory, consisting of real world fuzz setups for widely-used software (e.g. Apache and OpenSSL)

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() != 10 {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}
            if data[6] != b'u' {return}
            if data[7] != b'i' {return}
            if data[8] != b'o' {return}
            if data[9] != b'p' {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

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