At a high-level, test-fuzz is a convenient front end for afl.rs. In more concrete terms, test-fuzz is a collection of Rust macros and a Cargo subcommand that automate certain fuzzing-related tasks, most notably:
test-fuzz accomplishes these (in part) using Rust's testing facilities. For example, to generate a fuzzing corpus, test-fuzz records a target's arguments each time it is called during an invocation of cargo test. Similarly, test-fuzz implements a fuzzing harness as an additional test in a cargo-test-generated binary. This tight integration with Rust's testing facilities is what motivates the name test-fuzz.
Contents
sh
cargo install cargo-test-fuzz
Fuzzing with test-fuzz is essentially three steps:*
Identify a fuzz target:
dependencies to the target crate's Cargo.toml file:
toml
serde = "1.0"
test-fuzz = "0.1.0"
test_fuzz macro:
rust
#[test_fuzz::test_fuzz]
fn foo(...) {
...
}
Generate a corpus by running cargo test:
$ cargo test
Fuzz your target by running cargo test-fuzz:
$ cargo test-fuzz --target foo
* Some additional steps may be necessary following a reboot. AFL requires the following commands to be run as root:
Linux
sh
echo core >/proc/sys/kernel/core_pattern
cd /sys/devices/system/cpu
echo performance | tee cpu*/cpufreq/scaling_governor
OSX
sh
SL=/System/Library; PL=com.apple.ReportCrash
launchctl unload -w ${SL}/LaunchAgents/${PL}.plist
sudo launchctl unload -w ${SL}/LaunchDaemons/${PL}.Root.plist
test_fuzz macroPreceding a function with the test_fuzz macro indicates that the function is a fuzz target.
The primary effects of the test_fuzz macro are:
#[cfg(test)] so that corpus files are generated only when running tests (however, see enable_in_production below).cargo test-fuzz, so that the test does not block trying to read from standard input during a normal invocation of cargo test. The test is enclosed in a module to reduce the likelihood of a name collision. Currently, the name of the module is target_fuzz, where target is the name of the target (however, see rename below).bounds = "where_predicates" - Impose where_predicates (e.g., trait bounds) on the struct used to serialize/deserialize arguments. This may be necessary, e.g., if a target's argument type is an associated type. For an example, see associated_type.rs in this repository.
concretize = "parameters" - Use parameters as the target's type parameters when fuzzing. Example:
```rust
fn foo
Note: The target's arguments must be serializable for every instantiation of its type parameters. But the target's arguments are required to be deserializable only when the target is instantiated with parameters.
concretize_impl = "parameters" - Use parameters as the target's Self type parameters when fuzzing. Example:
```rust
impl
Note: The target's arguments must be serializable for every instantiation of its Self type parameters. But the target's arguments are required to be deserializable only when the target's Self is instantiated with parameters.
enable_in_production - Generate corpus files when not running tests, provided the environment variable TEST_FUZZ_WRITE is set. The default is to generate corpus files only when running tests, regardless of whether TEST_FUZZ_WRITE is set. When running a target from outside its package directory, set TEST_FUZZ_MANIFEST_PATH to the path of the package's Cargo.toml file.
WARNING: Setting enable_in_production could introduce a denial-of-service vector. For example, setting this option for a function that is called many times with different arguments could fill up the disk. The check of TEST_FUZZ_WRITE is meant to provide some defense against this possibility. Nonetheless, consider this option carefully before using it.
no_auto - Do not try to auto-generate corpus files for the target.
only_concretizations - Record the target's concretizations when running tests, but do not generate corpus files and do not implement a fuzzing harness. This can be useful when the target is a generic function, but it is unclear what type parameters should be used for fuzzing.
The intended workflow is: enable only_concretizations, then run cargo test followed by cargo test-fuzz --display-concretizations. One of the resulting concretizations might be usable as concretize's parameters. Similarly, a concretization resulting from cargo test-fuzz --display-imply-concretizations might be usable as concretize_impl's parameters.
Note, however, that just because a target was concretized with certain parameters during tests, it does not imply the target's arguments are serializable/deserializable when so concretized. The results of --display-concretizations/--display-impl-concretizations are merely suggestive.
rename = "name" - Treat the target as though its name is name when adding a module to the enclosing scope. Expansion of the test_fuzz macro adds a module definition to the enclosing scope. Currently, the module is named target_fuzz, where target is the name of the target. Use of this option causes the module to instead be be named name_fuzz. Example:
```rust
fn foo() {}
// Without the use of rename, a name collision and compile error would result.
mod foo_fuzz {}
```
test_fuzz_impl macroWhenever the test_fuzz macro is used in an impl block,
the impl must be preceded with the test_fuzz_impl macro. Example:
```rust
impl Foo { #[test_fuzz] fn bar(&self, x: &str) { ... } } ```
The reason for this requirement is as follows. Expansion of the test_fuzz macro adds a module definition to the enclosing scope. However, a module definition cannot appear inside an impl block. Preceding the impl with the test_fuzz_impl macro causes the module to be added outside the impl block.
If you see an error like the following, it likely means a use of the test_fuzz_impl macro is missing:
error: module is not supported in `trait`s or `impl`s
test_fuzz_impl currently has no options.
cargo test-fuzz commandThe cargo test-fuzz command is used to interact with fuzz targets, and to manipulate their corpora, crashes, hangs, and work queues. Example invocations include:
List fuzz targets
cargo test-fuzz --list
Display target foo's corpus
cargo test-fuzz --target foo --display-corpus
Fuzz target foo
cargo test-fuzz --target foo
Replay crashes found for target foo
cargo test-fuzz --target foo --replay-crashes
--backtrace - Display backtraces
--consolidate - Move one target's crashes and work queue to its corpus; to consolidate all targets, use --consolidate-all
--display-concretizations - Display concretizations
--display-corpus - Display corpus using uninstrumented fuzz target; to display with instrumentation, use --display-corpus-instrumented
--display-crashes - Display crashes
--display-hangs - Display hangs
--display-impl-concretizations - Display impl concretizations
--display-queue - Display work queue
--exact - Target name is an exact name rather than a substring
--list - List fuzz targets
--no-default-features - Do not activate the default feature
--no-instrumentation - Compile without instrumentation (for testing build process)
--no-run - Compile, but don't fuzz
--no-ui - Disable user interface
--persistent - Enable persistent mode fuzzing
--pretty-print - Pretty-print debug output when displaying/replaying
--replay-corpus - Replay corpus using uninstrumented fuzz target; to replay with instrumentation, use --replay-corpus-instrumented
--replay-crashes - Replay crashes
--replay-queue - Replay work queue
--reset - Clear fuzzing data for one target, but leave corpus intact; to reset all targets, use --reset-all
--resume - Resume target's last fuzzing session
--run-until-crash - Stop fuzzing once a crash is found
-- <args>... - Arguments for the fuzzer
--features <features> - Space or comma separated list of features to activate
-p, --package <package> - Package containing fuzz target
--target <target> - String that fuzz target's name must contain
--timeout <timeout> - Number of milliseconds to consider a hang when fuzzing or replaying (equivalent to -- -t <timeout> when fuzzing)
cargo-test-fuzz can auto-generate values for types that implement certain traits. If all of a target's argument types implement such traits, cargo-test-fuzz can auto-generate corpus files for the target.
The traits that cargo-test-fuzz currently supports and the values generated for them are as follows:
| Trait(s) | Value(s) |
| --------------------------------- | ------------------------------------------------------------------ |
| Bounded | T::min_value(), T::max_value() |
| Bounded + Add + One | T::min_value() + T::one() |
| Bounded + Add + Div + Two | T::min_value() / T::two() + T::max_value() / T::two() |
| Bounded + Add + Div + Two + One | T::min_value() / T::two() + T::max_value() / T::two() + T::one() |
| Bounded + Sub + One | T::max_value() - T::one() |
| Default | T::default() |
Key
Add - core::ops::AddBounded - num_traits::bounds::BoundedDefault - std::default::DefaultDiv - core::ops::DivOne - num_traits::OneSub - core::ops::SubTwo - test_fuzz::runtime::traits::Two (essentially Add + One)TEST_FUZZ_LOG - During macro expansion, write instrumented fuzz targets and their associated module definitions to standard output. This can be useful for debugging.
TEST_FUZZ_MANIFEST_PATH - When running a target from outside its package directory, find the package's Cargo.toml file at this location. One may need to set this environment variable when enable_in_production is used.
TEST_FUZZ_WRITE - Generate corpus files when not running tests for those targets for which enable_in_production is set.
Clonable arguments - A target's arguments must implement the Clone trait. The reason for this requirement is that the arguments are needed in two places: in a test-fuzz-internal function that writes corpus files, and in the body of the target function. To resolve this conflict, the arguments are cloned before being passed to the former.
Serializable / deserializable arguments - In general, a target's arguments must implement the serde::Serialize and serde::Deserialize traits, e.g., by deriving them. We say "in general" because test-fuzz knows how to handle certain special cases that wouldn't normally be serializable/deserializable. For example, an argument of type &str is converted to String when serializing, and back to a &str when deserializing. See also concretize and concretize_impl above.
Global variables - The fuzzing harnesses that test-fuzz implements do not initialize global variables. No general purpose solution for this problem currently exists. So, to fuzz a function that relies on global variables using test-fuzz, ad-hoc methods must be used.
#[cfg(test)] is not enabled for integration tests. If your target is tested only by integration tests, then consider using enable_in_production and TEST_FUZZ_WRITE to generate a corpus. (Note the warning accompanying enable_in_production, however.)
If you know the package in which your target resides, passing -p <package> to cargo test/cargo test-fuzz can significantly reduce build times.
Rust won't allow you to implement serde::Serialize for other repositories' types. But you may be able to patch other repositories to make their types serializeble. Also, cargo-clone can be useful for grabbing dependencies' repositories.
If a type Foo is easy to construct (say by calling Foo::new()), and if you don't care to record Foo values, then you may be able to implement serde::Serialize/serde::Deserialize for Foo like this:
```rust
impl serde::Serialize for Foo {
fn serialize(&self, serializer: S) -> Result
impl<'de> serde::Deserialize<'de> for Foo {
fn deserialize