README.afl
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
README.oss-fuzz
1# OVERVIEW
2
3This directory provides fuzzing targets to be run inside Google
4oss-fuzz infrastructure.
5
6See also https://github.com/google/oss-fuzz.
7
8# HOW IT WORKS
9
10We need to provide the source code and the rune to produce objects or
11archives (artefacts) from source code. These items ideally should live
12inside xen.git so that they can be kept up to date.
13
14The artefacts contain all the code we wish to fuzz and a function
15called LLVMFuzzerTestOneInput. LLVMFuzzerTestOneInput is the entry
16point to the code we wish to fuzz. Note that we don't produce
17executable programs because we don't have libFuzzEngine
18locally. libFuzzEngine is maintained by oss-fuzz.
19
20We also provide build script to oss-fuzz. The build script will
21inherit the correct compiler settings and be run in a pre-setup
22environment, which has libFuzzEngine installed. The build script is
23responsible for calling the correct Xen build rune to produce the
24artefacts, then link them against libFuzzEngine to produce
25executables, which will run in oss-fuzz infrastructure.
26
27Please refer to official oss-fuzz documents for the most up-to-date
28descriptions for all moving parts.
29
30# HOW TO IMPROVE THE FUZZING TARGETS
31
32Feel free to modify each fuzzing targets at will. Make sure they build
33by invoking make as you would build tools.
34
35To actually test the new code, you would need to run the target in
36standalone mode, please refer to oss-fuzz documents on how to do that.
37
38It is highly recommended that you run the new target for a while to
39weed out error in plumbing code to avoid false positives.
40