A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Support for maintaining the usefulness of a corpus over time.
//!
//! Wasmtime's fuzzing strategy in general is to use `wasm-smith` to generate
//! modules which interprets fuzz input from libFuzzer as a sort of "DNA". This
//! works to generate pretty interesting modules but falls down over time
//! because the DNA to generate the same module over time can change. This
//! means that maintaining a corpus for Wasmtime is not the most useful thing
//! in the world unfortunately and any historical discoveries of coverage need
//! to be rediscovered every time the DNA changes.
//!
//! To help with this the module here implements a scheme where Wasmtime's fuzz
//! inputs are highly likely to be of the form:
//!
//! ```text
//! [ ... wasm module ... ][ .. fuzz custom section .. ]
//! ```
//!
//! The `fuzz custom section` here contains the original fuzz input used to
//! generate the `wasm module`, and if the DNA hasn't changed then it should
//! still be possible to do that as well. The benefit of this format, though,
//! is that if the DNA is changed then the interpretation of the `fuzz custom
//! section` will change but the original `wasm module` will not. This enables
//! us to populate the corpus, ideally, with a set of interesting `wasm module`
//! entries.
//!
//! Over time the `fuzz custom section` will "bitrot" and will be no longer able
//! to generate the original `wasm module`. The main consequence of this is that
//! when the original test case is mutated the generated wasm module from the
//! mutation will be nothing alike from the original test case's wasm module.
//! This means libFuzzer will have to rediscover ways to mutate into
//! interesting modules, but we're no worse off than before hopefully.
//! Additionally this more easily opens the door to integrate `wasm-mutate` one
//! day into mutation here as well.
//!
//! Currently this is all supported via two methods:
//!
//! 1. A custom mutator is registered with libfuzzer. This means that all
//! inputs generated by the mutator, so long as they fit, will be the
//! "envelope" format of this module. This means that the corpus will
//! hopefully naturally get populated with wasm files rather than random
//! inputs. Note that this is not guaranteed to succeed since sometimes the
//! buffer to store the fuzz input in the mutator is not big enough to store
//! the final wasm module, in which case a non-enveloped wasm module is
//! stored.
//!
//! 2. If the environment variable `WRITE_FUZZ_INPUT_TO is set then the fuzz
//! input, in its envelope format, will be written to the specified file.
//! This can be useful in case an input is in its binary form or if a
//! preexisting corpus is being rewritten.
use std::borrow::Cow;
use arbitrary::{Arbitrary, Result, Unstructured};
use wasm_encoder::Section;
/// Helper macro for fuzz targets that are single-module fuzzers.
///
/// This combines the features of this module into one macro invocation to
/// generate the fuzz entry point and mutator in tandem.
#[macro_export]
macro_rules! single_module_fuzzer {
($execute:ident $generate:ident) => {
libfuzzer_sys::fuzz_target!(|data: &[u8]| {
$crate::init_fuzzing();
drop($crate::single_module_fuzzer::execute(
data, $execute, $generate,
));
});
libfuzzer_sys::fuzz_mutator!(|data: &mut [u8], size: usize, max_size: usize, seed: u32| {
$crate::single_module_fuzzer::mutate(
data,
size,
max_size,
$generate,
libfuzzer_sys::fuzzer_mutate,
)
});
};
}
/// Executes a "single module fuzzer" given the raw `input` from libfuzzer.
///
/// This will use the `input` to generate `T`, some configuration, which is
/// then used by `gen_module` to generate a WebAssembly module. The module is
/// then passed to `run` along with the configuration and remaining data that
/// can be used as fuzz input.
///
/// The main purpose of this function is to handle when `input` is actually a
/// WebAssembly module "envelope". If the `input` is a valid wasm module and
/// ends with a specific trailing custom section then the module generated by
/// `gen_module` is actually discarded. The purpose of this is to handle the
/// case where the input used to generate a module may change over time but
/// we're still interested in the historical coverage of the original wasm
/// module.
pub fn execute<'a, T, U>(
input: &'a [u8],
run: fn(&[u8], KnownValid, T, &mut Unstructured<'a>) -> Result<U>,
gen_module: fn(&mut T, &mut Unstructured<'a>) -> Result<(Vec<u8>, KnownValid)>,
) -> Result<U>
where
T: Arbitrary<'a>,
{
let (fuzz_data, module_in_input) = match extract_fuzz_input(input) {
Ok(input) => {
log::debug!("fuzz input was a valid module with trailing custom section");
(input.fuzz_data, Some(input.module))
}
Err(e) => {
log::debug!("fuzz input not a valid module: {e:?}");
(input, None)
}
};
let mut u = Unstructured::new(fuzz_data);
let mut config = u.arbitrary()?;
let (generated, known_valid) = gen_module(&mut config, &mut u)?;
let module = module_in_input.unwrap_or(&generated);
if let Ok(file) = std::env::var("WRITE_FUZZ_INPUT_TO") {
std::fs::write(file, encode_module(&module, &fuzz_data)).unwrap();
}
let known_valid = if module_in_input.is_some() {
KnownValid::No
} else {
known_valid
};
run(module, known_valid, config, &mut u)
}
/// Used as part of `execute` above to determine whether a module is known to
/// be valid ahead of time.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
pub enum KnownValid {
/// This module is known to be valid so it should assert compilation
/// succeeds for example.
Yes,
/// This module is not known to be valid and it may not compile
/// successfully. Note that it's also not known to compile unsuccessfully.
No,
}
const SECTION_NAME: &str = "wasmtime-fuzz-input";
/// Implementation of a libfuzzer custom mutator for a single-module-fuzzer.
///
/// This mutator will take the seed specified in `data` and attempt to mutate
/// it with the provided `mutate` function. The `mutate` function may not
/// receive the `data` as-specified, but instead may receive only the seed
/// that was used to generate `data`.
pub fn mutate<T>(
data: &mut [u8],
mut size: usize,
max_size: usize,
gen_module: fn(&mut T, &mut Unstructured<'_>) -> Result<(Vec<u8>, KnownValid)>,
mutate: fn(&mut [u8], usize, usize) -> usize,
) -> usize
where
T: for<'a> Arbitrary<'a>,
{
// If `data` is a valid wasm module with the fuzz seed at the end, then
// discard the wasm module portion and instead shuffle the seed into the
// beginning of the `data` slice. This is the "de-envelope" part of the
// seed management here.
//
// After this the `data` array should contain the raw contents used to
// produce the module and is ripe for mutation/minimization/etc.
if let Ok(input) = extract_fuzz_input(&data[..size]) {
let start = input.fuzz_data.as_ptr() as usize - data.as_ptr() as usize;
size = input.fuzz_data.len();
data.copy_within(start..start + input.fuzz_data.len(), 0);
}
// Delegate to the provided mutation function for standard mutations to
// apply.
let new_size = mutate(data, size, max_size);
// Next the goal of this function is to produce a test case which is an
// actual wasm module. To that end this will run module generation over the
// input provided. If this is all successful then the custom section
// representing the seed is appended to the module, making it a sort of
// self-referential module.
//
// After all this it's copied into `data` if the it fits. If the module
// doesn't fit then the seed is left un-perturbed since there's not much
// that we can do about that.
let mut u = Unstructured::new(&data[..new_size]);
match u
.arbitrary()
.and_then(|mut config| gen_module(&mut config, &mut u))
{
Ok((module, _known_valid)) => {
let module = encode_module(&module, &data[..new_size]);
if module.len() < max_size {
log::debug!(
"successfully generated mutated module with \
appended input section"
);
data[..module.len()].copy_from_slice(&module);
return module.len();
} else {
log::debug!("mutated module doesn't fit in original slice");
}
}
// If our new seed can't generate a new module then that's something
// for the fuzzer to figure out later when it "officially" executes
// this fuzz input. For the purposes of this function it's not too
// useful to try to put it in an envelope otherwise so ignore it.
Err(e) => {
log::debug!("failed to generate module from mutated seed {e:?}");
}
}
new_size
}
fn encode_module(module: &[u8], fuzz_data: &[u8]) -> Vec<u8> {
let mut module = module.to_vec();
wasm_encoder::CustomSection {
name: SECTION_NAME.into(),
data: Cow::Borrowed(&fuzz_data),
}
.append_to(&mut module);
module
}
struct FuzzInput<'a> {
/// The module extracted from the input, without the fuzz input custom
/// section.
module: &'a [u8],
/// The contents of the fuzz input custom section.
fuzz_data: &'a [u8],
}
/// Attempts to extract a fuzz input from the `data` provided.
///
/// This will attempt to read `data` as a WebAssembly binary. If successful
/// and the module ends with a custom section indicating it's a fuzz input
/// then the contents of the custom section are returned along with the
/// contents of the original module.
fn extract_fuzz_input(data: &[u8]) -> wasmtime::Result<FuzzInput<'_>> {
use wasmparser::{Encoding, Parser, Payload};
let mut prev_end = 8;
for section in Parser::new(0).parse_all(data) {
let section = section?;
// Only support core wasm modules here, reject components.
if let Payload::Version {
encoding: Encoding::Component,
..
} = §ion
{
wasmtime::bail!("components are not valid fuzz inputs");
}
// If this is a custom section, the end of the section is the end of
// the entire module, and it's got the expected name, then this section
// is assumed to be the input seed to the fuzzer.
//
// The section's contents are returned through `fuzz_data` and the wasm
// binary format means that we can simply chop off the last custom
// section and still have a valid module.
if let Payload::CustomSection(s) = §ion {
if s.name() == SECTION_NAME && s.range().end == data.len() as u64 {
return Ok(FuzzInput {
module: &data[..prev_end],
fuzz_data: s.data(),
});
}
}
// Record each section's end to record what the end of the module is
// up to this point.
if let Some((_, range)) = section.as_section() {
prev_end = range.end as usize;
}
}
wasmtime::bail!("no input found")
}
#[cfg(test)]
mod tests {
use super::*;
use rand::rngs::SmallRng;
use rand::{Rng, SeedableRng};
#[test]
fn changing_configuration_does_not_change_module() {
drop(env_logger::try_init());
// This test asserts that if the static configuration associated with a
// module changes then the generated module, as sourced from the
// original fuzz input, does not change. That's the whole purpose of
// this module, to enable our fuzz inputs to be in a format that's
// resilient to changes in configuration over time (or at least the
// module part of the input).
//
// This test will execute N=200 iterations where each iteration will
// attempt to, with some fresh random data, generate a module. This
// module is then "mutated" with a noop mutation to effectively
// serialize it into the envelope where the module is preserved. The
// now-mutated input, which should be a wasm module, is then passed
// as the seed to a second execution which has a different static input.
//
// This simulates having a fuzzer one day produce an interesting test
// case through mutation, and then the next day the configuration of
// the fuzzer changes. On both days the module input to the function
// should have been the same.
let mut rng = SmallRng::seed_from_u64(0);
let max_size = 4096;
let seed_size = 128;
let mut buf = vec![0; max_size];
let mut compares = 0;
for _ in 0..200 {
rng.fill_bytes(&mut buf[..seed_size]);
let run1 = run_config::<u32>;
let mutate = mutate::<u32>;
let run2 = run_config::<(u32, u32)>;
if let Ok((module, known_valid)) = execute(&buf[..seed_size], run1, generate) {
assert_eq!(known_valid, KnownValid::Yes);
let new_size = mutate(&mut buf, seed_size, max_size, generate, noop_mutate);
if let Ok((module2, known_valid)) = execute(&buf[..new_size], run2, generate) {
assert_eq!(known_valid, KnownValid::No);
compares += 1;
if module != module2 {
panic!("modules differ");
}
}
}
}
// At least one iteration should have succeeded in the fuzz generation
// above.
assert!(compares > 0);
fn run_config<T>(
data: &[u8],
known_valid: KnownValid,
_: T,
_: &mut Unstructured<'_>,
) -> Result<(Vec<u8>, KnownValid)>
where
T: for<'a> Arbitrary<'a>,
{
Ok((data.to_vec(), known_valid))
}
fn generate<T>(_: &mut T, u: &mut Unstructured<'_>) -> Result<(Vec<u8>, KnownValid)>
where
T: for<'a> Arbitrary<'a>,
{
Ok((
u.arbitrary::<wasm_smith::Module>()?.to_bytes(),
KnownValid::Yes,
))
}
fn noop_mutate(_buf: &mut [u8], size: usize, _new_size: usize) -> usize {
size
}
}
}