• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

MakefileH A D29-Sep-20195.1 KiB153109

README.mdH A D29-Sep-20192.9 KiB9773

block_decompress.cH A D29-Sep-20191.3 KiB5230

block_round_trip.cH A D29-Sep-20192.6 KiB9368

dictionary_decompress.cH A D29-Sep-20191.9 KiB6444

dictionary_round_trip.cH A D29-Sep-20193.3 KiB10778

fuzz.hH A D29-Sep-20192.2 KiB6315

fuzz.pyH A D29-Sep-201926 KiB840707

fuzz_helpers.hH A D29-Sep-20192.6 KiB9359

regression_driver.cH A D29-Sep-20192.1 KiB7754

simple_compress.cH A D29-Sep-20191.3 KiB4828

simple_decompress.cH A D29-Sep-20191.2 KiB4626

simple_round_trip.cH A D29-Sep-20192.5 KiB8860

stream_decompress.cH A D29-Sep-20192 KiB8454

stream_round_trip.cH A D29-Sep-20194.9 KiB163128

zstd_frame_info.cH A D29-Sep-20191.4 KiB4421

zstd_helpers.cH A D29-Sep-20195 KiB138109

zstd_helpers.hH A D29-Sep-20191.2 KiB4921

README.md

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