# OVERVIEW

Some fuzzing targets have American Fuzzy Lop (AFL) support.

See also http://lcamtuf.coredump.cx/afl/

# HOW IT WORKS

AFL provides a customised toolchain to build an executable, which in
turn is launched by the fuzzer.

# HOW TO USE IT

Use the x86 instruction emulator fuzzer as an example.

1. download and compile AFL in $AFLPATH.

2. run the following commands to build:
   $ cd tools/fuzz/x86_instruction_emulator
   $ make distclean

   If you have a new enough version of Clang/LLVM and have configured AFL's
   llvm_mode, make use of afl-clang-fast:

     $ make CC=$AFLPATH/afl-clang-fast afl # produces afl-harness

   If not, use the default afl-gcc:

     $ make CC=$AFLPATH/afl-gcc afl # produces afl-harness

3. provide initial test case (fuzzer dependent, see afl-*.c):
   $ mkdir testcase_dir
   $ dd if=/dev/urandom of=testcase_dir/rand.bin \
       bs=`./afl-harness --min-input-size` count=1

3a. use a tmpfs for findings_dir (Perf improvement and reduced disk load)
   $ mkdir findings_dir
   $ mount -t tmpfs -o size=512M tmpfs findings_dir

4. run the fuzzer with AFL:
   $ $AFLPATH/afl-fuzz -t 1000 -i testcase_dir -o findings_dir -- ./afl-harness

Please see AFL documentation for more information.

# GENERATING COVERAGE INFORMATION

To use afl-cov or gcov, you need a separate binary instrumented to
generate coverage data.  To do this, use the target `afl-cov`:

    $ make afl-cov #produces afl-harness-cov

In order to speed up the process of checking total coverage,
`afl-harness-cov` can take several test inputs on its command-line;
the speed-up effect should be similar to that of using afl-clang-fast.
You can use xargs to do this most efficiently, like so:

    $ ls queue/id* | xargs $path/afl-harness-cov

NOTE: Please also note that the coverage instrumentation hard-codes
the absolute path for the instrumentation read and write files in the
binary; so coverage data will always show up in the build directory no
matter where you run the binary from.

Please see afl-cov and/or gcov documentation for more information.