diff options
| author | Wladimir J. van der Laan <laanwj@gmail.com> | 2016-11-16 12:25:18 +0100 |
|---|---|---|
| committer | Wladimir J. van der Laan <laanwj@gmail.com> | 2016-12-15 13:29:03 +0100 |
| commit | 8b15434b59c6cd7368b4db680544cd77ed337bd3 (patch) | |
| tree | a223f694f718f7e244fae20c7c1bf7e6f4ad53a0 | |
| parent | a4153e20eca3f3a7bec5f0b1f13d0ae07557416b (diff) | |
doc: Add bare-bones documentation for fuzzing
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/fuzzing.md | 66 |
2 files changed, 67 insertions, 0 deletions
diff --git a/doc/README.md b/doc/README.md index 8b9c0ea262..36684e5401 100644 --- a/doc/README.md +++ b/doc/README.md @@ -68,6 +68,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th ### Miscellaneous - [Assets Attribution](assets-attribution.md) - [Files](files.md) +- [Fuzz-testing](fuzzing.md) - [Reduce Traffic](reduce-traffic.md) - [Tor Support](tor.md) - [Init Scripts (systemd/upstart/openrc)](init.md) diff --git a/doc/fuzzing.md b/doc/fuzzing.md new file mode 100644 index 0000000000..bf3ad17861 --- /dev/null +++ b/doc/fuzzing.md @@ -0,0 +1,66 @@ +Fuzz-testing Bitcoin Core +========================== + +A special test harness `test_bitcoin_fuzzy` is provided to provide an easy +entry point for fuzzers and the like. In this document we'll describe how to +use it with AFL. + +Building AFL +------------- + +It is recommended to always use the latest version of afl: +``` +wget http://lcamtuf.coredump.cx/afl/releases/afl-latest.tgz +tar -zxvf afl-latest.tgz +cd afl-<version> +make +export AFLPATH=$PWD +``` + +Instrumentation +---------------- + +To build Bitcoin Core using AFL instrumentation (this assumes that the +`AFLPATH` was set as above): +``` +./configure --disable-ccache --disable-shared --enable-tests CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ +export AFL_HARDEN=1 +cd src/ +make test/test_bitcoin_fuzzy +``` +We disable ccache because we don't want to pollute the ccache with instrumented +objects, and similarly don't want to use non-instrumented cached objects linked +in. + +Preparing fuzzing +------------------ + +AFL needs an input directory with examples, and an output directory where it +will place examples that it found. These can be anywhere in the file system, +we'll define environment variables to make it easy to reference them. + +``` +mkdir inputs +AFLIN=$PWD/inputs +mkdir outputs +AFLOUT=$PWD/outputs +``` + +Example inputs are available from: + +- https://download.visucore.com/bitcoin/bitcoin_fuzzy_in.tar.xz +- http://strateman.ninja/fuzzing.tar.xz + +Extract these (or other starting inputs) into the `inputs` directory before starting fuzzing. + +Fuzzing +-------- + +To start the actual fuzzing use: +``` +$AFLPATH/afl-fuzz -i ${AFLIN} -o ${AFLOUT} -m52 -- test/test_bitcoin_fuzzy +``` + +You may have to change a few kernel parameters to test optimally - `afl-fuzz` +will print an error and suggestion if so. + |