docs/devel/fuzzing.txt

   1 = Fuzzing =
   2
   3 == Introduction ==
   4
   5 This document describes the virtual-device fuzzing infrastructure in QEMU and
   6 how to use it to implement additional fuzzers.
   7
   8 == Basics ==
   9
  10 Fuzzing operates by passing inputs to an entry point/target function. The
  11 fuzzer tracks the code coverage triggered by the input. Based on these
  12 findings, the fuzzer mutates the input and repeats the fuzzing.
  13
  14 To fuzz QEMU, we rely on libfuzzer. Unlike other fuzzers such as AFL, libfuzzer
  15 is an _in-process_ fuzzer. For the developer, this means that it is their
  16 responsibility to ensure that state is reset between fuzzing-runs.
  17
  18 == Building the fuzzers ==
  19
  20 NOTE: If possible, build a 32-bit binary. When forking, the 32-bit fuzzer is
  21 much faster, since the page-map has a smaller size. This is due to the fact that
  22 AddressSanitizer mmaps ~20TB of memory, as part of its detection. This results
  23 in a large page-map, and a much slower fork().
  24
  25 To build the fuzzers, install a recent version of clang:
  26 Configure with (substitute the clang binaries with the version you installed).
  27 Here, enable-sanitizers, is optional but it allows us to reliably detect bugs
  28 such as out-of-bounds accesses, use-after-frees, double-frees etc.
  29
  30     CC=clang-8 CXX=clang++-8 /path/to/configure --enable-fuzzing \
  31                                                 --enable-sanitizers
  32
  33 Fuzz targets are built similarly to system/softmmu:
  34
  35     make i386-softmmu/fuzz
  36
  37 This builds ./i386-softmmu/qemu-fuzz-i386
  38
  39 The first option to this command is: --fuzz-target=FUZZ_NAME
  40 To list all of the available fuzzers run qemu-fuzz-i386 with no arguments.
  41
  42 For example:
  43     ./i386-softmmu/qemu-fuzz-i386 --fuzz-target=virtio-scsi-fuzz
  44
  45 Internally, libfuzzer parses all arguments that do not begin with "--".
  46 Information about these is available by passing -help=1
  47
  48 Now the only thing left to do is wait for the fuzzer to trigger potential
  49 crashes.
  50
  51 == Useful libFuzzer flags ==
  52
  53 As mentioned above, libFuzzer accepts some arguments. Passing -help=1 will list
  54 the available arguments. In particular, these arguments might be helpful:
  55
  56 $CORPUS_DIR/ : Specify a directory as the last argument to libFuzzer. libFuzzer
  57 stores each "interesting" input in this corpus directory. The next time you run
  58 libFuzzer, it will read all of the inputs from the corpus, and continue fuzzing
  59 from there. You can also specify multiple directories. libFuzzer loads existing
  60 inputs from all specified directories, but will only write new ones to the
  61 first one specified.
  62
  63 -max_len=4096 : specify the maximum byte-length of the inputs libFuzzer will
  64 generate.
  65
  66 -close_fd_mask={1,2,3} : close, stderr, or both. Useful for targets that
  67 trigger many debug/error messages, or create output on the serial console.
  68
  69 -jobs=4 -workers=4 : These arguments configure libFuzzer to run 4 fuzzers in
  70 parallel (4 fuzzing jobs in 4 worker processes). Alternatively, with only
  71 -jobs=N, libFuzzer automatically spawns a number of workers less than or equal
  72 to half the available CPU cores. Replace 4 with a number appropriate for your
  73 machine. Make sure to specify a $CORPUS_DIR, which will allow the parallel
  74 fuzzers to share information about the interesting inputs they find.
  75
  76 -use_value_profile=1 : For each comparison operation, libFuzzer computes
  77 (caller_pc&4095) | (popcnt(Arg1 ^ Arg2) << 12) and places this in the coverage
  78 table. Useful for targets with "magic" constants. If Arg1 came from the fuzzer's
  79 input and Arg2 is a magic constant, then each time the Hamming distance
  80 between Arg1 and Arg2 decreases, libFuzzer adds the input to the corpus.
  81
  82 -shrink=1 : Tries to make elements of the corpus "smaller". Might lead to
  83 better coverage performance, depending on the target.
  84
  85 Note that libFuzzer's exact behavior will depend on the version of
  86 clang and libFuzzer used to build the device fuzzers.
  87
  88 == Generating Coverage Reports ==
  89 Code coverage is a crucial metric for evaluating a fuzzer's performance.
  90 libFuzzer's output provides a "cov: " column that provides a total number of
  91 unique blocks/edges covered. To examine coverage on a line-by-line basis we
  92 can use Clang coverage:
  93
  94  1. Configure libFuzzer to store a corpus of all interesting inputs (see
  95     CORPUS_DIR above)
  96  2. ./configure the QEMU build with:
  97     --enable-fuzzing \
  98     --extra-cflags="-fprofile-instr-generate -fcoverage-mapping"
  99  3. Re-run the fuzzer. Specify $CORPUS_DIR/* as an argument, telling libfuzzer
 100     to execute all of the inputs in $CORPUS_DIR and exit. Once the process
 101     exits, you should find a file, "default.profraw" in the working directory.
 102  4. Execute these commands to generate a detailed HTML coverage-report:
 103  llvm-profdata merge -output=default.profdata default.profraw
 104  llvm-cov show ./path/to/qemu-fuzz-i386 -instr-profile=default.profdata \
 105  --format html -output-dir=/path/to/output/report
 106
 107 == Adding a new fuzzer ==
 108 Coverage over virtual devices can be improved by adding additional fuzzers.
 109 Fuzzers are kept in tests/qtest/fuzz/ and should be added to
 110 tests/qtest/fuzz/Makefile.include
 111
 112 Fuzzers can rely on both qtest and libqos to communicate with virtual devices.
 113
 114 1. Create a new source file. For example ``tests/qtest/fuzz/foo-device-fuzz.c``.
 115
 116 2. Write the fuzzing code using the libqtest/libqos API. See existing fuzzers
 117 for reference.
 118
 119 3. Register the fuzzer in ``tests/fuzz/Makefile.include`` by appending the
 120 corresponding object to fuzz-obj-y
 121
 122 Fuzzers can be more-or-less thought of as special qtest programs which can
 123 modify the qtest commands and/or qtest command arguments based on inputs
 124 provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the
 125 fuzzer loops over the byte-array interpreting it as a list of qtest commands,
 126 addresses, or values.
 127
 128 = Implementation Details =
 129
 130 == The Fuzzer's Lifecycle ==
 131
 132 The fuzzer has two entrypoints that libfuzzer calls. libfuzzer provides it's
 133 own main(), which performs some setup, and calls the entrypoints:
 134
 135 LLVMFuzzerInitialize: called prior to fuzzing. Used to initialize all of the
 136 necessary state
 137
 138 LLVMFuzzerTestOneInput: called for each fuzzing run. Processes the input and
 139 resets the state at the end of each run.
 140
 141 In more detail:
 142
 143 LLVMFuzzerInitialize parses the arguments to the fuzzer (must start with two
 144 dashes, so they are ignored by libfuzzer main()). Currently, the arguments
 145 select the fuzz target. Then, the qtest client is initialized. If the target
 146 requires qos, qgraph is set up and the QOM/LIBQOS modules are initialized.
 147 Then the QGraph is walked and the QEMU cmd_line is determined and saved.
 148
 149 After this, the vl.c:qemu__main is called to set up the guest. There are
 150 target-specific hooks that can be called before and after qemu_main, for
 151 additional setup(e.g. PCI setup, or VM snapshotting).
 152
 153 LLVMFuzzerTestOneInput: Uses qtest/qos functions to act based on the fuzz
 154 input. It is also responsible for manually calling the main loop/main_loop_wait
 155 to ensure that bottom halves are executed and any cleanup required before the
 156 next input.
 157
 158 Since the same process is reused for many fuzzing runs, QEMU state needs to
 159 be reset at the end of each run. There are currently two implemented
 160 options for resetting state:
 161 1. Reboot the guest between runs.
 162    Pros: Straightforward and fast for simple fuzz targets.
 163    Cons: Depending on the device, does not reset all device state. If the
 164    device requires some initialization prior to being ready for fuzzing
 165    (common for QOS-based targets), this initialization needs to be done after
 166    each reboot.
 167    Example target: i440fx-qtest-reboot-fuzz
 168 2. Run each test case in a separate forked process and copy the coverage
 169    information back to the parent. This is fairly similar to AFL's "deferred"
 170    fork-server mode [3]
 171    Pros: Relatively fast. Devices only need to be initialized once. No need
 172    to do slow reboots or vmloads.
 173    Cons: Not officially supported by libfuzzer. Does not work well for devices
 174    that rely on dedicated threads.
 175    Example target: virtio-net-fork-fuzz