From ca80dee5145ff9240aa6b4e342e14332bec9973b Mon Sep 17 00:00:00 2001 From: Matt Morehouse Date: Mon, 20 Mar 2023 11:36:42 -0500 Subject: [PATCH] doc: add section about improving fuzzing corpora We want to encourage contributions to the seed corpora that improve coverage. --- doc/FUZZING.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/doc/FUZZING.md b/doc/FUZZING.md index c2101d1e0..0acb710f0 100644 --- a/doc/FUZZING.md +++ b/doc/FUZZING.md @@ -60,7 +60,43 @@ The latter will run all targets two by two `12345` times. If you want to contribute new seeds, be sure to merge your corpus with the main one: ``` ./tests/fuzz/run.py my_locally_extended_fuzz_corpus -j2 --generate --runs 12345 -./tests/fuzz/run.py main_fuzz_corpus --merge_dir my_locally_extended_fuzz_corpus +./tests/fuzz/run.py tests/fuzz/corpora --merge_dir my_locally_extended_fuzz_corpus +``` + + +## Improve seed corpora + +If you find coverage increasing inputs while fuzzing, please create a pull +request to add them into `tests/fuzz/corpora`. Be sure to minimize any additions +to the corpora first. + +### Example + +Here's an example workflow to contribute new inputs for the `fuzz-addr` target. + +Create a directory for newly found corpus inputs and begin fuzzing: + +```shell +mkdir -p local_corpora/fuzz-addr +./tests/fuzz/fuzz-addr -jobs=4 local_corpora/fuzz-addr tests/fuzz/corpora/fuzz-addr/ +``` + +After some time, libFuzzer may find some potential coverage increasing inputs +and save them in `local_corpora/fuzz-addr`. We can then merge them into the seed +corpora in `tests/fuzz/corpora`: + +```shell +./tests/fuzz/run.py tests/fuzz/corpora --merge_dir local_corpora +``` + +This will copy over any inputs that improve the coverage of the existing corpus. +If any new inputs were added, create a pull request to improve the upstream seed +corpus: + +```shell +git add tests/fuzz/corpora/fuzz-addr/* +git commit +... ```