From f62b2663b96d440d3b9dd50b40dc911f9e0083d3 Mon Sep 17 00:00:00 2001 From: Elliot Gorokhovsky Date: Tue, 19 Mar 2024 14:05:23 -0700 Subject: [PATCH] Add docs on how to add a new fuzzer --- tests/fuzz/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/tests/fuzz/README.md b/tests/fuzz/README.md index 2a9bd4570..e2196e832 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 + + -- 2.47.2