sys/contrib/zstd/tests/fuzz/README.md

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