1# OVERVIEW
2
3Some fuzzing targets have American Fuzzy Lop (AFL) support.
4
5See also http://lcamtuf.coredump.cx/afl/
6
7# HOW IT WORKS
8
9AFL provides a customised toolchain to build an executable, which in
10turn is launched by the fuzzer.
11
12# HOW TO USE IT
13
14Use the x86 instruction emulator fuzzer as an example.
15
161. download and compile AFL in $AFLPATH.
17
182. run the following commands to build:
19   $ cd tools/fuzz/x86_instruction_emulator
20   $ make distclean
21
22   If you have a new enough version of Clang/LLVM and have configured AFL's
23   llvm_mode, make use of afl-clang-fast:
24
25     $ make CC=$AFLPATH/afl-clang-fast afl # produces afl-harness
26
27   If not, use the default afl-gcc:
28
29     $ make CC=$AFLPATH/afl-gcc afl # produces afl-harness
30
313. provide initial test case (fuzzer dependent, see afl-*.c):
32   $ mkdir testcase_dir
33   $ dd if=/dev/urandom of=testcase_dir/rand.bin \
34       bs=`./afl-harness --min-input-size` count=1
35
363a. use a tmpfs for findings_dir (Perf improvement and reduced disk load)
37   $ mkdir findings_dir
38   $ mount -t tmpfs -o size=512M tmpfs findings_dir
39
404. run the fuzzer with AFL:
41   $ $AFLPATH/afl-fuzz -t 1000 -i testcase_dir -o findings_dir -- ./afl-harness
42
43Please see AFL documentation for more information.
44
45# GENERATING COVERAGE INFORMATION
46
47To use afl-cov or gcov, you need a separate binary instrumented to
48generate coverage data.  To do this, use the target `afl-cov`:
49
50    $ make afl-cov #produces afl-harness-cov
51
52In order to speed up the process of checking total coverage,
53`afl-harness-cov` can take several test inputs on its command-line;
54the speed-up effect should be similar to that of using afl-clang-fast.
55You can use xargs to do this most efficiently, like so:
56
57    $ ls queue/id* | xargs $path/afl-harness-cov
58
59NOTE: Please also note that the coverage instrumentation hard-codes
60the absolute path for the instrumentation read and write files in the
61binary; so coverage data will always show up in the build directory no
62matter where you run the binary from.
63
64Please see afl-cov and/or gcov documentation for more information.
65