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.
Compared to Bitcoin Core, this test harness has been updated to both remove some redundant code as well as to provide entry points for fuzzing single data structures.
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
cd llvm_mode
make
cd ..
<optionally edit Makefile to install locally>
[sudo] make install
For fast fuzzing (see below), the afl-clang-fast and
afl-clang-fast++ AFL drivers should be build and used. They are in
the llvm_mode subdirectory of AFL.
To build Bitcoin 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
Disabling ccache should be optional here, and is added above solely to save some HDD space.
The fuzzer is a lot faster now when run in LLVM persistent mode. To
enable LLVM persistent mode, bitcoin_test_fuzzy has to be built with
clang/clang++. For this replace the above mentions of afl-gcc and
afl-g++ with afl-clang-fast and afl-clang-fast++`.
Note that fuzzing in fast mode (llvm_mode) might introduce some inaccuracies that might lead the fuzzer astray. For details on this, consult the documentation of AFL. It is expected however (and some simple experiments show so as well), that AFL still is a lot quicker to discover input structure this way.
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
For the old fuzzing code that fuzzes everything at once, example inputs might still be available from:
Extract these (or other starting inputs) into the inputs directory before starting fuzzing.
To start the actual fuzzing and to fuzz all fuzz cases at once:
$AFLPATH/afl-fuzz -i ${AFLIN} -o ${AFLOUT} -m 200 -- test/test_bitcoin_fuzzy
And to fuzz using just a single fuzzing entrypoint, specify a corresponding command line argument to test_bitcoin_fuzzy on what to fuzz. A list of all possible arguments can be printed like this:
test/test_bitcoin_fuzzy list_tests
So, for example, to fuzz the CBlock de-/serialization, you can use this:
$AFLPATH/afl-fuzz -i ${AFLIN} -o ${AFLOUT} -m 200 -- test/test_bitcoin_fuzzy cblock_deser
You may have to change a few kernel parameters to test optimally -
afl-fuzz will print an error and suggestion if so.
The memory limit of 200MB above (-m 200) might be generous. If you
suspect that code might have some memory leaks and you want to test
for that specifically, try lowering the limit until about just before
fuzzing breaks every time. Further information can be found in the
AFL documentation.
Important note: Fuzzing does not work by simply calling
test_bitcoin_fuzzy. This will just call the instrumented program and
it will (pretty much) behave like it would have been compiled without
fuzzer options. It can, however, be used this way to retest test cases
from the fuzzer.
The code has been updated to be more easily extensible. In test_bitcoin_fuzzy.cpp,
simply derive a class from FuzzTest or, alternatively, FuzzTestNet (in case you want
to read from a network-like CDataStream). Override the run() method and either use
the buffer object or the ds object to retrieve the data for your test.