fuzzing/README

   1 To report security bugs, see ‘SECURITY’ in the top source directory.
   2
   3 Fuzzing nbdkit using the American Fuzzy Lop (afl) fuzzer
   4 ========================================================
   5
   6 We can fuzz nbdkit using the -s (read from stdin) option, and feeding
   7 in a file of "network" input.  The stdout from nbdkit (ie. data that
   8 would normally be sent back to the client) is ignored.
   9
  10 You will need to recompile nbdkit with afl instrumentation:
  11
  12   ./configure CC=/usr/bin/afl-gcc CXX=/usr/bin/afl-g++
  13   make clean
  14   make
  15
  16 The fuzzing/testcase_dir directory contains some initial testcases
  17 that afl can use.
  18
  19 Run multiple copies of afl-fuzz.  Usually you should run 1 master (-M)
  20 and as many slaves (-S) as you can.
  21
  22 Master:
  23
  24   mkdir -p fuzzing/sync_dir
  25   afl-fuzz -i fuzzing/testcase_dir -o fuzzing/sync_dir -m 256 -M fuzz01 \
  26       ./server/nbdkit -s ./plugins/memory/.libs/nbdkit-memory-plugin.so 1M
  27
  28 Slaves:
  29
  30   # replace fuzzNN with fuzz02, fuzz03, etc.
  31   afl-fuzz -i fuzzing/testcase_dir -o fuzzing/sync_dir -m 256 -S fuzzNN \
  32       ./server/nbdkit -s ./plugins/memory/.libs/nbdkit-memory-plugin.so 1M
  33
  34 Test Coverage
  35 -------------
  36
  37 To find out if the fuzzing is covering all of the code, I used afl-cov
  38 (https://github.com/mrash/afl-cov).  Usage is rather complex, so
  39 consult the README of that project, but in brief:
  40
  41 (1) Create a second copy of the nbdkit source, and compile it with
  42 profiling:
  43
  44   ./configure CFLAGS="-O2 -g -pg -fprofile-arcs -ftest-coverage"
  45   make clean
  46   make
  47
  48 (2) Assuming ../nbdkit-afl is the nbdkit source compiled with afl, and
  49 the current directory is nbdkit compiled with profiling, then run the
  50 command below.  You can run this even while afl-fuzz is running.
  51
  52   afl-cov -d ../nbdkit-afl/fuzzing/sync_dir \
  53       --code-dir . \
  54       --coverage-cmd "cat AFL_FILE | ./server/nbdkit -s ./plugins/memory/.libs/nbdkit-memory-plugin.so 1M"
  55
  56 This will create an HTML test coverage report in
  57 ../nbdkit-afl/fuzzing/sync_dir/cov/web/
  58
  59 Notes
  60 -----
  61
  62 We only have testcases for the newstyle fixed protocol so far, but if
  63 people report that they are exposing the oldstyle protocol to the
  64 internet / untrusted clients then we could extend the testing for
  65 that.
  66
  67 We have only fuzzed the memory plugin, which is convenient because it
  68 stores everything in memory and throws it away when nbdkit exits.
  69 Since plugins can have bugs as well as the core server, it may be
  70 productive to test other plugins and filters.
  71
  72 Fuzzing nbdkit using Clang + libFuzzer
  73 ======================================
  74
  75 Recompile nbdkit with libFuzzer enabled and build the libFuzzer test
  76 binary:
  77
  78   ./configure \
  79       CC=clang \
  80       CFLAGS="-g -O1 -fPIC" \
  81       --enable-libfuzzer \
  82       --disable-perl
  83   make clean
  84   make CFLAGS="-g -O1 -fPIC -fsanitize=fuzzer,address"
  85
  86 (The awkward CFLAGS on the make command line are necessary because
  87 ./configure attempts to test that the compiler works, but this test
  88 fails when -fsanitize=fuzzer is used as that option adds an extra
  89 main() definition.)
  90
  91 ",address" enables the Clang Address Sanitizer, and can be omitted for
  92 faster fuzzing.
  93
  94 This builds a specialized version of nbdkit which is the fuzzer test
  95 program (testing only nbdkit-memory-plugin unless you modify the
  96 source).  You can run it like this on the input corpus:
  97
  98   ./server/nbdkit fuzzing/testcase_dir
  99
 100 New test inputs are written to fuzzing/testcase_dir and will be used
 101 on subsequent runs.  If this is undesirable then delete
 102 fuzzing/testcase_dir/[0-f]* before the run.
 103
 104 There are various extra command line options supported by libFuzzer.
 105 For more details see:
 106
 107   https://llvm.org/docs/LibFuzzer.html