doc/HACKING/Fuzzing.md

   1 # Fuzzing Tor
   2
   3 ## The simple version (no fuzzing, only tests)
   4
   5 Check out fuzzing-corpora, and set TOR_FUZZ_CORPORA to point to the place
   6 where you checked it out.
   7
   8 To run the fuzzing test cases in a deterministic fashion, use:
   9
  10 ```console
  11 $ make test-fuzz-corpora
  12 ```
  13
  14 This won't actually fuzz Tor!  It will just run all the fuzz binaries
  15 on our existing set of testcases for the fuzzer.
  16
  17 ## Different kinds of fuzzing
  18
  19 Right now we support three different kinds of fuzzer.
  20
  21 First, there's American Fuzzy Lop (AFL), a fuzzer that works by forking
  22 a target binary and passing it lots of different inputs on stdin.  It's the
  23 trickiest one to set up, so I'll be describing it more below.
  24
  25 Second, there's libFuzzer, a llvm-based fuzzer that you link in as a library,
  26 and it runs a target function over and over.  To use this one, you'll need to
  27 have a reasonably recent clang and libfuzzer installed.  At that point, you
  28 just build with --enable-expensive-hardening and --enable-libfuzzer.  That
  29 will produce a set of binaries in src/test/fuzz/lf-fuzz-* .  These programs
  30 take as input a series of directories full of fuzzing examples.  For more
  31 information on libfuzzer, see https://llvm.org/docs/LibFuzzer.html
  32
  33 Third, there's Google's OSS-Fuzz infrastructure, which expects to get all of
  34 its.  For more on this, see https://github.com/google/oss-fuzz and the
  35 projects/tor subdirectory.  You'll need to mess around with Docker a bit to
  36 test this one out; it's meant to run on Google's infrastructure.
  37
  38 In all cases, you'll need some starting examples to give the fuzzer when it
  39 starts out.  There's a set in the "fuzzing-corpora" git repository.  Try
  40 setting TOR_FUZZ_CORPORA to point to a checkout of that repository
  41
  42 ## Writing Tor fuzzers
  43
  44 A tor fuzzing harness should have:
  45 * a fuzz_init() function to set up any necessary global state.
  46 * a fuzz_main() function to receive input and pass it to a parser.
  47 * a fuzz_cleanup() function to clear global state.
  48
  49 Most fuzzing frameworks will produce many invalid inputs - a tor fuzzing
  50 harness should rejecting invalid inputs without crashing or behaving badly.
  51
  52 But the fuzzing harness should crash if tor fails an assertion, triggers a
  53 bug, or accesses memory it shouldn't. This helps fuzzing frameworks detect
  54 "interesting" cases.
  55
  56 ## Guided Fuzzing with AFL
  57
  58 There is no HTTPS, hash, or signature for American Fuzzy Lop's source code, so
  59 its integrity can't be verified. That said, you really shouldn't fuzz on a
  60 machine you care about, anyway.
  61
  62 To Build:
  63   Get AFL from http://lcamtuf.coredump.cx/afl/ and unpack it
  64   ```console
  65   $ cd afl
  66   $ make
  67   $ cd ../tor
  68   $ PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening
  69   $ AFL_HARDEN=1 make clean fuzzers
  70   ```
  71
  72 To Find The ASAN Memory Limit: (64-bit only)
  73
  74 On 64-bit platforms, afl needs to know how much memory ASAN uses,
  75 because ASAN tends to allocate a ridiculous amount of virtual memory,
  76 and then not actually use it.
  77
  78 Read afl/docs/notes_for_asan.txt for more details.
  79
  80   Download recidivm from https://jwilk.net/software/recidivm
  81   Download the signature
  82   Check the signature
  83   ```console
  84   $ tar xvzf recidivm*.tar.gz
  85   $ cd recidivm*
  86   $ make
  87   $ /path/to/recidivm -v src/test/fuzz/fuzz-http
  88   ```
  89   Use the final "ok" figure as the input to -m when calling afl-fuzz
  90   (Normally, recidivm would output a figure automatically, but in some cases,
  91   the fuzzing harness will hang when the memory limit is too small.)
  92
  93 You could also just say "none" instead of the memory limit below, if you
  94 don't care about memory limits.
  95
  96
  97 To Run:
  98
  99 ```console
 100 $ mkdir -p src/test/fuzz/fuzz_http_findings
 101 $ ../afl/afl-fuzz -i ${TOR_FUZZ_CORPORA}/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz/fuzz-http
 102 ```
 103
 104 AFL has a multi-core mode, check the documentation for details.
 105 You might find the included fuzz-multi.sh script useful for this.
 106
 107 macOS (OS X) requires slightly more preparation, including:
 108 * using afl-clang (or afl-clang-fast from the llvm directory)
 109 * disabling external crash reporting (AFL will guide you through this step)
 110
 111 ## Triaging Issues
 112
 113 Crashes are usually interesting, particularly if using AFL_HARDEN=1 and --enable-expensive-hardening. Sometimes crashes are due to bugs in the harness code.
 114
 115 Hangs might be interesting, but they might also be spurious machine slowdowns.
 116 Check if a hang is reproducible before reporting it. Sometimes, processing
 117 valid inputs may take a second or so, particularly with the fuzzer and
 118 sanitizers enabled.
 119
 120 To see what fuzz-http is doing with a test case, call it like this:
 121
 122 ```console
 123 $ src/test/fuzz/fuzz-http --debug < /path/to/test.case
 124 ```
 125
 126 (Logging is disabled while fuzzing to increase fuzzing speed.)
 127
 128 ## Reporting Issues
 129
 130 Please report any issues discovered using the process in Tor's security issue
 131 policy:
 132
 133 https://gitlab.torproject.org/tpo/core/team/-/wikis/NetworkTeam/SecurityPolicy