diff options
| author | Yann Collet <Cyan4973@users.noreply.github.com> | 2024-03-21 11:10:03 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-03-21 11:10:03 -0700 |
| commit | 6679d0ca7b9eb9a6ed90997006d5086ce89a7e18 (patch) | |
| tree | 9b4fdfff72acdd293488f286166f34e6a68007fc | |
| parent | 76fbb5f3d4a72decf621efe47b83b931618d82b7 (diff) | |
| parent | f62b2663b96d440d3b9dd50b40dc911f9e0083d3 (diff) | |
| download | zstd-6679d0ca7b9eb9a6ed90997006d5086ce89a7e18.tar.gz | |
Merge pull request #3982 from embg/fuzzer_readme
Document the process for adding a new fuzzer
| -rw-r--r-- | tests/fuzz/README.md | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/tests/fuzz/README.md b/tests/fuzz/README.md index 2a9bd457..e2196e83 100644 --- a/tests/fuzz/README.md +++ b/tests/fuzz/README.md @@ -117,3 +117,45 @@ CC=clang CXX=clang++ ./fuzz.py build all --enable-msan ## Fuzzing a custom sequence producer plugin Sequence producer plugin authors can use the zstd fuzzers to stress-test their code. See the documentation in `fuzz_third_party_seq_prod.h` for details. + +## Adding a new fuzzer +There are several steps involved in adding a new fuzzer harness. + +### Build your harness +1. Create a new your fuzzer harness `tests/fuzz/your_harness.c`. + +2. Add your harness to the Makefile + + 2.1 Follow [this example](https://github.com/facebook/zstd/blob/e124e39301381de8f323436a3e4c46539747ba24/tests/fuzz/Makefile#L216) if your fuzzer requires both compression and decompression symbols (prefix `rt_`). If your fuzzer only requires decompression symbols, follow [this example](https://github.com/facebook/zstd/blob/6a0052a409e2604bd40354b76b86272b712edd7d/tests/fuzz/Makefile#L194) (prefix `d_`). + + 2.2 Add your target to [`FUZZ_TARGETS`](https://github.com/facebook/zstd/blob/6a0052a409e2604bd40354b76b86272b712edd7d/tests/fuzz/Makefile#L108). + +3. Add your harness to [`fuzz.py`](https://github.com/facebook/zstd/blob/6a0052a409e2604bd40354b76b86272b712edd7d/tests/fuzz/fuzz.py#L48). + +### Generate seed data +Follow the instructions above to generate seed data: +``` +make -C ../tests decodecorpus +./fuzz.py gen your_harness +``` + +### Run the harness +Follow the instructions above to run your harness and fix any crashes: +``` +./fuzz.py build your_harness --enable-fuzzer --enable-asan --enable-ubsan --cc clang --cxx clang++ +./fuzz.py libfuzzer your_harness +``` + +### Minimize and zip the corpus +After running the fuzzer for a while, you will have a large corpus at `tests/fuzz/corpora/your_harness*`. +This corpus must be minimized and zipped before uploading to GitHub for regression testing: +``` +./fuzz.py minimize your_harness +./fuzz.py zip your_harness +``` + +### Upload the zip file to GitHub +The previous step should produce a `.zip` file containing the corpus for your new harness. +This corpus must be uploaded to GitHub here: https://github.com/facebook/zstd/releases/tag/fuzz-corpora + + |