honggfuzz-rs

使用 Google 开发的 Honggfuzz 模糊测试你的 Rust 代码！

文档

关于 Honggfuzz

Honggfuzz 是一个以安全为导向的模糊测试工具，具有强大的分析选项。支持基于代码覆盖率的进化式、反馈驱动的模糊测试（软件和硬件基础）。

• 项目主页 honggfuzz.com
• 项目仓库 github.com/google/honggfuzz
• 此上游项目由 Google 维护，但...
• 这不是一个官方的 Google 产品

兼容性

• Rust：稳定版、beta 版、nightly 版
• 操作系统：GNU/Linux、macOS、FreeBSD、NetBSD、Android、WSL (Windows Subsystem for Linux)
• 架构：x86_64、x86、arm64-v8a、armebi-v7a、armebi
• Sanitizer：无、地址、线程、泄漏

依赖关系

Linux

• C 编译器：cc
• GNU Make: make
• 为BFD库的GNU Binutils开发文件: libbfd.h
• libunwind开发文件: libunwind.h
• 块运行时库（在用clang编译时使用）
• liblzma开发文件

例如在Debian及其衍生版本中

sudo apt install build-essential binutils-dev libunwind-dev libblocksruntime-dev liblzma-dev

如何使用此crate

安装honggfuzz命令以进行带有仪器和模糊测试的构建

# installs hfuzz and honggfuzz subcommands in cargo
cargo install honggfuzz

将其添加到您的依赖项中

[dependencies]
honggfuzz = "0.5"

创建一个用于模糊测试的目标

use ziggy_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")
        });
    }
}

为了乐趣和利润而模糊！

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

一旦您获得了一个崩溃，您就可以轻松地在调试环境中重放它

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

您还可以构建和运行您的项目，而无需在编译时进行软件仪器（LLVM的SanCov传递）

这允许您尝试仅使用硬件反馈驱动的模糊测试

# 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

清洁

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

版本

cargo hfuzz version

环境变量

RUSTFLAGS

您可以使用 RUSTFLAGS 将额外的参数发送到 rustc。

例如，您可以使用LLVM的 sanitizers。如果您想测试您的 unsafe rust代码，这是一个推荐选项，但它将对性能产生影响。

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

HFUZZ_BUILD_ARGS

您可以使用 HFUZZ_BUILD_ARGS 将额外的参数发送到 cargo build。

HFUZZ_RUN_ARGS

您可以使用 HFUZZ_RUN_ARGS 将额外的参数发送到 honggfuzz。有关参数列表，请参阅USAGE。

例如

# 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

默认情况下，我们使用 rust-lldb，但您可以将它更改为 rust-gdb、gdb、/usr/bin/lldb-7 ...

CARGO_TARGET_DIR

目标编译目录，默认为 hfuzz_target 以避免与 cargo build 的默认 target 目录冲突。

HFUZZ_WORKSPACE

Honggfuzz工作目录，默认为 hfuzz_workspace。

HFUZZ_INPUT

Honggfuzz输入文件（也称为“语料库”），默认为 $HFUZZ_WORKSPACE/{TARGET}/input。

条件编译

有时，您需要对您的代码进行一些特定的适配，以获得更好的模糊测试效率。

例如

• 尽可能使您软件的行为在模糊测试输入上尽可能确定
  • PRNG 必须使用常数或模糊测试输入进行初始化
  • 行为不应基于计算机的时钟而改变。
  • 避免潜在的竞态条件导致的非确定性行为。
  • ...
• 永远不要在运行时调用 std::process::exit()。
• 禁用日志和其他不必要的功能。
• 尽可能避免在可能的情况下修改全局状态。
• 不要在运行 cfg(fuzzing) 时设置自己的panic hook

使用 cargo hfuzz 构建时，通过将参数 --cfg fuzzing 传递给 rustc，允许您利用 cfg 宏对那些适配进行条件编译，如下所示：

#[cfg(fuzzing)]
let mut rng = rand_chacha::ChaCha8Rng::from_seed(&[0]);
#[cfg(not(fuzzing))]
let mut rng = rand::thread_rng();

此外，在调试模式下构建时，除了 fuzzing 之外，还会添加 fuzzing_debug 参数。

有关条件编译的更多信息，请参阅参考。

关于 honggfuzz 的相关文档

• 用法
• 反馈驱动模糊测试
• 持久模糊测试

关于 Rust 模糊测试

在 github.com/rust-fuzz 上有其他提供 Rust 模糊测试支持的项目。

您将找到对 AFL 和 LLVM 的 LibFuzzer 的支持，还有一个 trophy case ;-)。

这个crate受到了那些项目的启发！