xref: /xen/tools/fuzz/

# 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.

# OVERVIEW

This directory provides fuzzing targets to be run inside Google
oss-fuzz infrastructure.

See also https://github.com/google/oss-fuzz.

# HOW IT WORKS

We need to provide the source code and the rune to produce objects or
archives (artefacts) from source code. These items ideally should live
inside xen.git so that they can be kept up to date.

The artefacts contain all the code we wish to fuzz and a function
called LLVMFuzzerTestOneInput. LLVMFuzzerTestOneInput is the entry
point to the code we wish to fuzz. Note that we don't produce
executable programs because we don't have libFuzzEngine
locally. libFuzzEngine is maintained by oss-fuzz.

We also provide build script to oss-fuzz. The build script will
inherit the correct compiler settings and be run in a pre-setup
environment, which has libFuzzEngine installed. The build script is
responsible for calling the correct Xen build rune to produce the
artefacts, then link them against libFuzzEngine to produce
executables, which will run in oss-fuzz infrastructure.

Please refer to official oss-fuzz documents for the most up-to-date
descriptions for all moving parts.

# HOW TO IMPROVE THE FUZZING TARGETS

Feel free to modify each fuzzing targets at will. Make sure they build
by invoking make as you would build tools.

To actually test the new code, you would need to run the target in
standalone mode, please refer to oss-fuzz documents on how to do that.

It is highly recommended that you run the new target for a while to
weed out error in plumbing code to avoid false positives.

Last Index update Sat Jun 03 09:59:21 CST 2023