AuroraMiddleware/zstd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[fuzzer] Update README.md

Browse Source
This commit is contained in:
Nick Terrell 2017-09-13 18:18:35 -07:00
parent 6b8236cf7e
commit 6c6412cef9
1 changed files with 70 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
tests/fuzz/README.md
View File

@ -2,33 +2,87 @@
Each fuzzing target can be built with multiple engines.
## fuzz.py
`fuzz.py` is a helper script for building and running fuzzers.
Run `./fuzz.py -h` for the commands and run `./fuzz.py COMMAND -h` for
command specific help.
### Generating Data
`fuzz.py` provides a utility to generate seed data for each fuzzer.
```
make -C ../tests decodecorpus
./fuzz.py gen TARGET
```
By default it outputs 100 samples, each at most 8KB into `corpora/TARGET-seed`,
but that can be configured with the `--number`, `--max-size-log` and `--seed`
flags.
### Build
It respects the usual build environment variables `CC`, `CFLAGS`, etc.
The environment variables can be overridden with the corresponding flags
`--cc`, `--cflags`, etc.
The specific fuzzing engine is selected with `LIB_FUZZING_ENGINE` or
`--lib-fuzzing-engine`, the default is `libregression.a`.
It has flags that can easily set up sanitizers `--enable-{a,ub,m}san`, and
coverage instrumentation `--enable-coverage`.
It sets sane defaults which can be overriden with flags `--debug`,
`--enable-ubsan-pointer-overlow`, etc.
Run `./fuzz.py build -h` for help.
### Running Fuzzers
`./fuzz.py` can run `libfuzzer`, `afl`, and `regression` tests.
See the help of the relevant command for options.
Flags not parsed by `fuzz.py` are passed to the fuzzing engine.
The command used to run the fuzzer is printed for debugging.
## LibFuzzer
You can install `libFuzzer` with `make libFuzzer`. Then you can make each target
with `make target LDFLAGS=-L. CC=clang CXX=clang++`.
```
# Build libfuzzer if necessary
make libFuzzer
# Build the fuzz targets
./fuzz.py build all --enable-coverage --enable-asan --enable-ubsan --lib-fuzzing-engine Fuzzer/libFuzzer.a --cc clang --cxx clang++
# OR equivalently
CC=clang CXX=clang++ LIB_FUZZING_ENGINE=Fuzzer/libFuzzer.a ./fuzz.py build all --enable-coverage --enable-asan --enable-ubsan
# Run the fuzzer
./fuzz.py libfuzzer TARGET -max_len=8192 -jobs=4
```
where `TARGET` could be `simple_decompress`, `stream_round_trip`, etc.
### MSAN
Fuzzing with `libFuzzer` and `MSAN` will require building a C++ standard library
and libFuzzer with MSAN.
`fuzz.py` respects the environment variables / flags `MSAN_EXTRA_CPPFLAGS`,
`MSAN_EXTRA_CFLAGS`, `MSAN_EXTRA_CXXFLAGS`, `MSAN_EXTRA_LDFLAGS` to easily pass
the extra parameters only for MSAN.
## AFL
The regression driver also serves as a binary for `afl-fuzz`. You can make each
target with one of these commands:
The default `LIB_FUZZING_ENGINE` is `libregression.a`, which produces a binary
that AFL can use.
```
make target-regression CC=afl-clang CXX=afl-clang++
AFL_MSAN=1 make target-regression-msan CC=afl-clang CXX=afl-clang++
AFL_ASAN=1 make target-regression-uasan CC=afl-clang CXX=afl-clang++
# Build the fuzz targets
CC=afl-clang CXX=afl-clang++ ./fuzz.py build all --enable-asan --enable-ubsan
# Run the fuzzer without a memory limit because of ASAN
./fuzz.py afl TARGET -m none
```
Then run as `./target @@`.
## Regression Testing
Each fuzz target has a corpus checked into the repo under `fuzz/corpora/`.
You can run regression tests on the corpora to ensure that inputs which
previously exposed bugs still pass. You can make these targets to run the
regression tests with different sanitizers.
The regression rest supports the `all` target to run all the fuzzers in one
command.
```
make regression-test
make regression-test-msan
make regression-test-uasan
CC=clang CXX=clang++ ./fuzz.py build all --enable-asan --enable-ubsan
./fuzz.py regression all
CC=clang CXX=clang++ ./fuzz.py build all --enable-msan
./fuzz.py regression all
```