Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rust-fuzz/honggfuzz-rs
Fuzz your Rust code with Google-developed Honggfuzz !
https://github.com/rust-fuzz/honggfuzz-rs
crates fuzz fuzz-testing fuzzer fuzzing honggfuzz rust rust-fuzz sanitizer security security-testing security-tools
Last synced: 4 days ago
JSON representation
Fuzz your Rust code with Google-developed Honggfuzz !
- Host: GitHub
- URL: https://github.com/rust-fuzz/honggfuzz-rs
- Owner: rust-fuzz
- License: apache-2.0
- Created: 2018-02-06T19:23:16.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-01T05:05:19.000Z (about 2 months ago)
- Last Synced: 2024-10-06T17:16:41.049Z (about 1 month ago)
- Topics: crates, fuzz, fuzz-testing, fuzzer, fuzzing, honggfuzz, rust, rust-fuzz, sanitizer, security, security-testing, security-tools
- Language: Rust
- Homepage: https://crates.io/crates/honggfuzz
- Size: 245 KB
- Stars: 451
- Watchers: 6
- Forks: 42
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# honggfuzz-rs [![Build Status][build-img]][build] [![Crates.io][crates-img]][crates] [![Documentation][docs-img]][docs]
[build-img]: https://github.com/rust-fuzz/honggfuzz-rs/actions/workflows/rust.yml/badge.svg
[build]: https://github.com/rust-fuzz/honggfuzz-rs/actions/workflows/rust.yml
[crates-img]: https://img.shields.io/crates/v/honggfuzz.svg
[crates]: https://crates.io/crates/honggfuzz
[docs-img]: https://docs.rs/honggfuzz/badge.svg
[docs]: https://docs.rs/honggfuzz
Fuzz your Rust code with Google-developed Honggfuzz !
## [Documentation](https://docs.rs/honggfuzz)
[](https://asciinema.org/a/43MLo5Xl8ukHxgwDLArKqS9xc)
## 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](http://honggfuzz.com/)
* project repository [github.com/google/honggfuzz](https://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, NetBSD, Android, WSL (Windows Subsystem for Linux)
* __Arch__: x86_64, x86, arm64-v8a, armeabi-v7a, armeabi
* __Sanitizer__: none, address, thread, leak
## Dependencies
### Linux
* C compiler: `cc`
* GNU Make: `make`
* GNU Binutils development files for the BFD library: `libbfd.h`
* libunwind development files: `libunwind.h`
* Blocks runtime library (when compiling with clang)
* liblzma development files
For example on Debian and its derivatives:
```sh
sudo apt install build-essential binutils-dev libunwind-dev libblocksruntime-dev liblzma-dev
```
## How to use this crate
Install honggfuzz commands to build with instrumentation and fuzz
```sh
# installs hfuzz and honggfuzz subcommands in cargo
cargo install honggfuzz
```
Add to your dependencies
```toml
[dependencies]
honggfuzz = "0.5"
```
Create a target to fuzz
```rust
use honggfuzz::fuzz;
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() != 3 {return}
if data[0] != b'h' {return}
if data[1] != b'e' {return}
if data[2] != b'y' {return}
panic!("BOOM")
});
}
}
```
Fuzz for fun and profit !
```sh
# builds with fuzzing instrumentation and then fuzz the "example" target
cargo hfuzz run example
```
Once you got a crash, replay it easily in a debug environment
```sh
# builds the target in debug mode and replays automatically the crash in rust-lldb
cargo hfuzz run-debug example hfuzz_workspace/*/*.fuzz
```
You can also build and run your project without compile-time software instrumentation (LLVM's SanCov passes)
This allows you for example to try hardware-only feedback driven fuzzing:
```sh
# builds without fuzzing instrumentation and then fuzz the "example" target using hardware-based feedback
HFUZZ_RUN_ARGS="--linux_perf_ipt_block --linux_perf_instr --linux_perf_branch" cargo hfuzz run-no-instr example
```
Clean
```sh
# a wrapper on "cargo clean" which cleans the fuzzing_target directory
cargo hfuzz clean
```
Version
```sh
cargo hfuzz version
```
### Environment variables
#### `RUSTFLAGS`
You can use `RUSTFLAGS` to send additional arguments to `rustc`.
For instance, you can enable the use of LLVM's [sanitizers](https://github.com/japaric/rust-san).
This is a recommended option if you want to test your `unsafe` rust code but it will have an impact on performance.
```sh
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](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md) for the list of those.
For example:
```sh
# 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` ...
#### `CARGO_TARGET_DIR`
Target compilation directory, defaults to `hfuzz_target` to not clash with `cargo build`'s default `target` directory.
#### `HFUZZ_WORKSPACE`
Honggfuzz working directory, defaults to `hfuzz_workspace`.
#### `HFUZZ_INPUT`
Honggfuzz input files (also called "corpus"), defaults to `$HFUZZ_WORKSPACE/{TARGET}/input`.
## Conditional compilation
Sometimes, it is necessary to make some specific adaptation to your code to yield a better fuzzing efficiency.
For instance:
* Make you software behavior as much as possible deterministic on the fuzzing input
* [PRNG](https://en.wikipedia.org/wiki/Pseudorandom_number_generator)s must be seeded with a constant or the fuzzer input
* Behavior shouldn't change based on the computer's clock.
* Avoid potential undeterministic behavior from racing threads.
* ...
* Never ever call `std::process::exit()`.
* Disable logging and other unnecessary functionalities.
* Try to avoid modifying global state when possible.
* Do not set up your own panic hook when run with `cfg(fuzzing)`
When building with `cargo hfuzz`, the argument `--cfg fuzzing` is passed to `rustc` to allow you to condition the compilation of those adaptations thanks to the `cfg` macro like so:
```rust
#[cfg(fuzzing)]
let mut rng = rand_chacha::ChaCha8Rng::from_seed(&[0]);
#[cfg(not(fuzzing))]
let mut rng = rand::thread_rng();
```
Also, when building in debug mode, the `fuzzing_debug` argument is added in addition to `fuzzing`.
For more information about conditional compilation, please see the [reference](https://doc.rust-lang.org/reference/attributes.html#conditional-compilation).
## Relevant documentation about honggfuzz
* [USAGE](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md)
* [FeedbackDrivenFuzzing](https://github.com/google/honggfuzz/blob/master/docs/FeedbackDrivenFuzzing.md)
* [PersistentFuzzing](https://github.com/google/honggfuzz/blob/master/docs/PersistentFuzzing.md)
## About Rust fuzzing
There is other projects providing Rust fuzzing support at [github.com/rust-fuzz](https://github.com/rust-fuzz).
You'll find support for [AFL](https://github.com/rust-fuzz/afl.rs) and LLVM's [LibFuzzer](https://github.com/rust-fuzz/cargo-fuzz) and there is also a [trophy case](https://github.com/rust-fuzz/trophy-case) ;-) .
This crate was inspired by those projects!