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* `differential`: Generate a Wasm module and check that Wasmtime returns 34 the same results when run with two different configurations. 35* `differential_spec`: Generate a Wasm module and check that Wasmtime returns 36 the same results as the Wasm spec interpreter (see the `wasm-spec-interpreter` 37 crate). 38* `differential_v8`: Generate a Wasm module and check that Wasmtime returns 39 the same results as V8. 40* `differential_wasmi`: Generate a Wasm module and check that Wasmtime returns 41 the same results as the `wasmi` interpreter. 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