1# `cargo fuzz` Targets for Wasmtime 2 3This crate defines various [libFuzzer](https://www.llvm.org/docs/LibFuzzer.html) 4fuzzing targets for Wasmtime, which can be run via [`cargo 5fuzz`](https://rust-fuzz.github.io/book/cargo-fuzz.html). 6 7These fuzz targets just glue together pre-defined test case generators with 8oracles and pass libFuzzer-provided inputs to them. The test case generators and 9oracles themselves are independent from the fuzzing engine that is driving the 10fuzzing process and are defined in `wasmtime/crates/fuzzing`. 11 12## Example 13 14To start fuzzing run the following command, where `$MY_FUZZ_TARGET` is one of 15the [available fuzz targets](#available-fuzz-targets): 16 17```shell 18cargo fuzz run $MY_FUZZ_TARGET 19``` 20 21## Available Fuzz Targets 22 23At the time of writing, we have the following fuzz targets: 24 25* `api_calls`: stress the Wasmtime API by executing sequences of API calls; only 26 the subset of the API is currently supported. 27* `compile`: Attempt to compile libFuzzer's raw input bytes with Wasmtime. 28* `compile-maybe-invalid`: Attempt to compile a wasm-smith-generated Wasm module 29 with code sequences that may be invalid. 30* `cranelift-fuzzgen`: Generate a Cranelift function and check that it returns 31 the same results when compiled to the host and when using the Cranelift 32 interpreter; only a subset of Cranelift IR is currently supported. 33* `cranelift-icache`: Generate a Cranelift function A, applies a small mutation 34 to its source, yielding a function A', and checks that A compiled + 35 incremental compilation generates the same machine code as if A' was compiled 36 from scratch. 37* `differential`: Generate a Wasm module, evaluate each exported function 38 with random inputs, and check that Wasmtime returns the same results as a 39 choice of another engine: the Wasm spec interpreter (see the 40 `wasm-spec-interpreter` crate), the `wasmi` interpreter, V8 (through the `v8` 41 crate), or Wasmtime itself run with a different configuration. 42* `instantiate`: Generate a Wasm module and Wasmtime configuration and attempt 43 to compile and instantiate with them. 44* `instantiate-many`: Generate many Wasm modules and attempt to compile and 45 instantiate them concurrently. 46* `spectests`: Pick a random spec test and run it with a generated 47 configuration. 48* `table_ops`: Generate a sequence of `externref` table operations and run them 49 in a GC environment. 50 51The canonical list of fuzz targets is the `.rs` files in the `fuzz_targets` 52directory: 53 54```shell 55ls wasmtime/fuzz/fuzz_targets/ 56``` 57 58## Corpora 59 60While you *can* start from scratch, libFuzzer will work better if it is given a 61[corpus](https://www.llvm.org/docs/LibFuzzer.html#corpus) of seed inputs to kick 62start the fuzzing process. We maintain a corpus for each of these fuzz targets 63in [a dedicated repo on 64github](https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus). 65 66You can use our corpora by cloning it and placing it at `wasmtime/fuzz/corpus`: 67 68```shell 69git clone \ 70 https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus.git \ 71 wasmtime/fuzz/corpus 72``` 73 74## Reproducing a Fuzz Bug 75 76When investigating a fuzz bug (especially one found by OSS-Fuzz), use the 77following steps to reproduce it locally: 78 791. Download the test case (either the "Minimized Testcase" or "Unminimized 80 Testcase" from OSS-Fuzz will do). 812. Run the test case in the correct fuzz target: 82 ```shell 83 cargo +nightly fuzz run <target> <test case> 84 ``` 85 If all goes well, the bug should reproduce and libFuzzer will dump the 86 failure stack trace to stdout 873. For more debugging information, run the command above with `RUST_LOG=debug` 88 to print the configuration and WebAssembly input used by the test case (see 89 uses of `log_wasm` in the `wasmtime-fuzzing` crate). 90 91## Target specific options 92 93### `cranelift-fuzzgen` 94 95Fuzzgen supports passing the `FUZZGEN_ALLOWED_OPS` environment variable, which when available restricts the instructions that it will generate. 96 97Running `FUZZGEN_ALLOWED_OPS=ineg,ishl cargo fuzz run cranelift-fuzzgen` will run fuzzgen but only generate `ineg` or `ishl` opcodes. 98 99### `cranelift-icache` 100 101The icache target also uses the fuzzgen library, thus also supports the `FUZZGEN_ALLOWED_OPS` enviornment variable as described in the `cranelift-fuzzgen` section above. 102 103