1# Fuzzing 2 3Each fuzzing target can be built with multiple engines. 4Zstd provides a fuzz corpus for each target that can be downloaded with 5the command: 6 7``` 8make corpora 9``` 10 11It will download each corpus into `./corpora/TARGET`. 12 13## fuzz.py 14 15`fuzz.py` is a helper script for building and running fuzzers. 16Run `./fuzz.py -h` for the commands and run `./fuzz.py COMMAND -h` for 17command specific help. 18 19### Generating Data 20 21`fuzz.py` provides a utility to generate seed data for each fuzzer. 22 23``` 24make -C ../tests decodecorpus 25./fuzz.py gen TARGET 26``` 27 28By default it outputs 100 samples, each at most 8KB into `corpora/TARGET-seed`, 29but that can be configured with the `--number`, `--max-size-log` and `--seed` 30flags. 31 32### Build 33It respects the usual build environment variables `CC`, `CFLAGS`, etc. 34The environment variables can be overridden with the corresponding flags 35`--cc`, `--cflags`, etc. 36The specific fuzzing engine is selected with `LIB_FUZZING_ENGINE` or 37`--lib-fuzzing-engine`, the default is `libregression.a`. 38It has flags that can easily set up sanitizers `--enable-{a,ub,m}san`, and 39coverage instrumentation `--enable-coverage`. 40It sets sane defaults which can be overridden with flags `--debug`, 41`--enable-ubsan-pointer-overflow`, etc. 42Run `./fuzz.py build -h` for help. 43 44### Running Fuzzers 45 46`./fuzz.py` can run `libfuzzer`, `afl`, and `regression` tests. 47See the help of the relevant command for options. 48Flags not parsed by `fuzz.py` are passed to the fuzzing engine. 49The command used to run the fuzzer is printed for debugging. 50 51## LibFuzzer 52 53``` 54# Build libfuzzer if necessary 55make libFuzzer 56# Build the fuzz targets 57./fuzz.py build all --enable-coverage --enable-asan --enable-ubsan --lib-fuzzing-engine Fuzzer/libFuzzer.a --cc clang --cxx clang++ 58# OR equivalently 59CC=clang CXX=clang++ LIB_FUZZING_ENGINE=Fuzzer/libFuzzer.a ./fuzz.py build all --enable-coverage --enable-asan --enable-ubsan 60# Run the fuzzer 61./fuzz.py libfuzzer TARGET -max_len=8192 -jobs=4 62``` 63 64where `TARGET` could be `simple_decompress`, `stream_round_trip`, etc. 65 66### MSAN 67 68Fuzzing with `libFuzzer` and `MSAN` will require building a C++ standard library 69and libFuzzer with MSAN. 70`fuzz.py` respects the environment variables / flags `MSAN_EXTRA_CPPFLAGS`, 71`MSAN_EXTRA_CFLAGS`, `MSAN_EXTRA_CXXFLAGS`, `MSAN_EXTRA_LDFLAGS` to easily pass 72the extra parameters only for MSAN. 73 74## AFL 75 76The default `LIB_FUZZING_ENGINE` is `libregression.a`, which produces a binary 77that AFL can use. 78 79``` 80# Build the fuzz targets 81CC=afl-clang CXX=afl-clang++ ./fuzz.py build all --enable-asan --enable-ubsan 82# Run the fuzzer without a memory limit because of ASAN 83./fuzz.py afl TARGET -m none 84``` 85 86## Regression Testing 87 88The regression rest supports the `all` target to run all the fuzzers in one 89command. 90 91``` 92CC=clang CXX=clang++ ./fuzz.py build all --enable-asan --enable-ubsan 93./fuzz.py regression all 94CC=clang CXX=clang++ ./fuzz.py build all --enable-msan 95./fuzz.py regression all 96``` 97