diff options
Diffstat (limited to 'doc/HACKING/Fuzzing.md')
| -rw-r--r-- | doc/HACKING/Fuzzing.md | 60 |
1 files changed, 35 insertions, 25 deletions
diff --git a/doc/HACKING/Fuzzing.md b/doc/HACKING/Fuzzing.md index 2039d6a4c0..1a9185aebf 100644 --- a/doc/HACKING/Fuzzing.md +++ b/doc/HACKING/Fuzzing.md @@ -1,18 +1,20 @@ -= Fuzzing Tor +# Fuzzing Tor -== The simple version (no fuzzing, only tests) +## The simple version (no fuzzing, only tests) Check out fuzzing-corpora, and set TOR_FUZZ_CORPORA to point to the place where you checked it out. To run the fuzzing test cases in a deterministic fashion, use: - make test-fuzz-corpora + +```console +$ make test-fuzz-corpora +``` This won't actually fuzz Tor! It will just run all the fuzz binaries on our existing set of testcases for the fuzzer. - -== Different kinds of fuzzing +## Different kinds of fuzzing Right now we support three different kinds of fuzzer. @@ -26,7 +28,7 @@ have a reasonably recent clang and libfuzzer installed. At that point, you just build with --enable-expensive-hardening and --enable-libfuzzer. That will produce a set of binaries in src/test/fuzz/lf-fuzz-* . These programs take as input a series of directories full of fuzzing examples. For more -information on libfuzzer, see http://llvm.org/docs/LibFuzzer.html +information on libfuzzer, see https://llvm.org/docs/LibFuzzer.html Third, there's Google's OSS-Fuzz infrastructure, which expects to get all of its. For more on this, see https://github.com/google/oss-fuzz and the @@ -37,7 +39,7 @@ In all cases, you'll need some starting examples to give the fuzzer when it starts out. There's a set in the "fuzzing-corpora" git repository. Try setting TOR_FUZZ_CORPORA to point to a checkout of that repository -== Writing Tor fuzzers +## Writing Tor fuzzers A tor fuzzing harness should have: * a fuzz_init() function to set up any necessary global state. @@ -51,8 +53,7 @@ But the fuzzing harness should crash if tor fails an assertion, triggers a bug, or accesses memory it shouldn't. This helps fuzzing frameworks detect "interesting" cases. - -== Guided Fuzzing with AFL +## Guided Fuzzing with AFL There is no HTTPS, hash, or signature for American Fuzzy Lop's source code, so its integrity can't be verified. That said, you really shouldn't fuzz on a @@ -60,11 +61,13 @@ machine you care about, anyway. To Build: Get AFL from http://lcamtuf.coredump.cx/afl/ and unpack it - cd afl - make - cd ../tor - PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening - AFL_HARDEN=1 make clean fuzzers + ```console + $ cd afl + $ make + $ cd ../tor + $ PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening + $ AFL_HARDEN=1 make clean fuzzers + ``` To Find The ASAN Memory Limit: (64-bit only) @@ -74,13 +77,15 @@ and then not actually use it. Read afl/docs/notes_for_asan.txt for more details. - Download recidivm from http://jwilk.net/software/recidivm + Download recidivm from https://jwilk.net/software/recidivm Download the signature Check the signature - tar xvzf recidivm*.tar.gz - cd recidivm* - make - /path/to/recidivm -v src/test/fuzz/fuzz-http + ```console + $ tar xvzf recidivm*.tar.gz + $ cd recidivm* + $ make + $ /path/to/recidivm -v src/test/fuzz/fuzz-http + ``` Use the final "ok" figure as the input to -m when calling afl-fuzz (Normally, recidivm would output a figure automatically, but in some cases, the fuzzing harness will hang when the memory limit is too small.) @@ -90,9 +95,11 @@ don't care about memory limits. To Run: - mkdir -p src/test/fuzz/fuzz_http_findings - ../afl/afl-fuzz -i ${TOR_FUZZ_CORPORA}/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz/fuzz-http +```console +$ mkdir -p src/test/fuzz/fuzz_http_findings +$ ../afl/afl-fuzz -i ${TOR_FUZZ_CORPORA}/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz/fuzz-http +``` AFL has a multi-core mode, check the documentation for details. You might find the included fuzz-multi.sh script useful for this. @@ -101,7 +108,7 @@ macOS (OS X) requires slightly more preparation, including: * using afl-clang (or afl-clang-fast from the llvm directory) * disabling external crash reporting (AFL will guide you through this step) -== Triaging Issues +## Triaging Issues Crashes are usually interesting, particularly if using AFL_HARDEN=1 and --enable-expensive-hardening. Sometimes crashes are due to bugs in the harness code. @@ -111,13 +118,16 @@ valid inputs may take a second or so, particularly with the fuzzer and sanitizers enabled. To see what fuzz-http is doing with a test case, call it like this: - src/test/fuzz/fuzz-http --debug < /path/to/test.case + +```console +$ src/test/fuzz/fuzz-http --debug < /path/to/test.case +``` (Logging is disabled while fuzzing to increase fuzzing speed.) -== Reporting Issues +## Reporting Issues Please report any issues discovered using the process in Tor's security issue policy: -https://trac.torproject.org/projects/tor/wiki/org/meetings/2016SummerDevMeeting/Notes/SecurityIssuePolicy +https://gitlab.torproject.org/tpo/core/team/-/wikis/NetworkTeam/SecurityPolicy |