Add instructions for building the fuzzing corpus

- Inform devs how to build an organized and useful corpora based on the
results of fuzz testing.
- Modify .gitignore to allow corpus/ tracking. Note: files in corpus/
  should not be blindly committed but selectively added based on
  usefulness
- Add emptyfile to zkas-decoder corpus because it caused a panic
This commit is contained in:
y
2023-08-24 13:54:56 -04:00
committed by parazyd
parent 382205ad81
commit bc16b6c475
3 changed files with 38 additions and 1 deletions

1
fuzz/.gitignore vendored
View File

@@ -1,5 +1,4 @@
target
corpus
artifacts
coverage
Cargo.lock

38
fuzz/README.md Normal file
View File

@@ -0,0 +1,38 @@
# DarkFi Fuzzing
This directory contains our fuzz tests. It is a WIP and likley to be
re-organized as we expand the complexity of the tests
## Building the corpora
### Motivation
If you discover a crash while fuzzing, add it to the relevant
subdirectory in `corpus/` and give it a meaningful name.
Files in the corpora will be used as default inputs in subsequent
runs in the fuzzer. The fuzzer will then "mutate" or modify these
inputs using various algorithms to create new yet similar inputs.
This is a way to get more value from fuzzing as we'll be able to
test using inputs similar to ones that have been problematic in the
past and therefore more likely to find bugs.
Another benefit is that we will be able to detect regressions
in the codebase by simply running our known corpora against the fuzzer
and making sure the code doesn't crash.
Finally, the corpora make for good building blocks for unit tests
as they represent known error cases that the code has had at some point.
### Example
e.g. scenario: while testing ZkBinary's decode() function, you find
that an empty input causes a panic.
* Identify your fuzz target (`cargo fuzz list` or whatever you used
for `cargo fuzz run TARGET`
* `ls artifacts/TARGET/crash-*`
* `cat` the crash file and check that it matches the error message from
the fuzzer
* Choose a `NAME` for the crash file, e.g. `corpus_emptyfile`
* `cp artifacts/TARGET/CRASH-FILE corpus/TARGET/NAME`
Then add the new `corpus/TARGET/NAME` file to git.