nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-10 21:23:58 +01:00
Code Issues Packages Projects Releases Wiki Activity

Try to tweak fuzzing.md to correspond to my changes

Browse Source
This commit is contained in:
Nick Mathewson 2016-12-14 08:12:41 -05:00
parent 0fb1156e9f
commit 44fa14c0e2
2 changed files with 19 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/HACKING/Fuzzing.md
View File

@ -3,6 +3,11 @@
To run the fuzzing test cases in a deterministic fashion, use: To run the fuzzing test cases in a deterministic fashion, use:
make fuzz make fuzz
[I've turned this off for now. - NM]
To build the fuzzing harness binaries, use:
make fuzzers
== Guided Fuzzing with AFL == Guided Fuzzing with AFL
There is no HTTPS, hash, or signature for American Fuzzy Lop's source code, so There is no HTTPS, hash, or signature for American Fuzzy Lop's source code, so
@ -22,7 +27,7 @@ To Find The ASAN Memory Limit: (64-bit only)
On 64-bit platforms, afl needs to know how much memory ASAN uses. On 64-bit platforms, afl needs to know how much memory ASAN uses.
Or, you can configure tor without --enable-expensive-hardening, then use Or, you can configure tor without --enable-expensive-hardening, then use
make fuzz make fuzz
to run the generated test cases through an ASAN-enabled fuzz_dir. to run the generated test cases through an ASAN-enabled fuzz-http.
Read afl/docs/notes_for_asan.txt for more details. Read afl/docs/notes_for_asan.txt for more details.
Download recidivm from http://jwilk.net/software/recidivm Download recidivm from http://jwilk.net/software/recidivm
@ -36,10 +41,14 @@ Read afl/docs/notes_for_asan.txt for more details.
(Normally, recidivm would output a figure automatically, but in some cases, (Normally, recidivm would output a figure automatically, but in some cases,
the fuzzing harness will hang when the memory limit is too small.) the fuzzing harness will hang when the memory limit is too small.)
You could also just say "none" instead of the memory limit below, if you
don't care about memory limits.
To Run: To Run:
mkdir -p src/test/fuzz/fuzz_dir_testcase src/test/fuzz/fuzz_dir_findings mkdir -p src/test/fuzz/fuzz_http_findings
echo "dummy" > src/test/fuzz/fuzz_dir_testcase/minimal.case ../afl/afl-fuzz -i src/test/fuzz/data/http -x src/test/fuzz/dict/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz_dir
../afl/afl-fuzz -i src/test/fuzz/fuzz_dir_testcase -o src/test/fuzz/fuzz_dir_findings -m <asan-memory-limit> -- src/test/fuzz_dir
AFL has a multi-core mode, check the documentation for details. AFL has a multi-core mode, check the documentation for details.
You might find the included fuzz-multi.sh script useful for this. You might find the included fuzz-multi.sh script useful for this.
@ -48,19 +57,12 @@ macOS (OS X) requires slightly more preparation, including:
* using afl-clang (or afl-clang-fast from the llvm directory) * using afl-clang (or afl-clang-fast from the llvm directory)
* disabling external crash reporting (AFL will guide you through this step) * disabling external crash reporting (AFL will guide you through this step)
AFL may also benefit from using dictionary files for text-based inputs: these
can be placed in src/test/fuzz/fuzz_dir_dictionary/.
Multiple dictionaries can be used with AFL, you should choose a combination of
dictionaries that targets the code you are fuzzing.
== Writing Tor fuzzers == Writing Tor fuzzers
A tor fuzzing harness should: A tor fuzzing harness should have:
* read input from standard input (many fuzzing frameworks also accept file * a fuzz_init() function to set up any necessary global state.
names) * a fuzz_main() function to receive input and pass it to a parser.
* parse that input * a fuzz_cleanup() function to clear global state.
* produce results on standard output (this assists in diagnosing errors)
Most fuzzing frameworks will produce many invalid inputs - a tor fuzzing Most fuzzing frameworks will produce many invalid inputs - a tor fuzzing
harness should rejecting invalid inputs without crashing or behaving badly. harness should rejecting invalid inputs without crashing or behaving badly.
@ -78,8 +80,8 @@ Check if a hang is reproducible before reporting it. Sometimes, processing
valid inputs may take a second or so, particularly with the fuzzer and valid inputs may take a second or so, particularly with the fuzzer and
sanitizers enabled. sanitizers enabled.
To see what fuzz_dir is doing with a test case, call it like this: To see what fuzz-http is doing with a test case, call it like this:
src/test/fuzz_dir --debug < /path/to/test.case src/test/fuzz/fuzz-http --debug < /path/to/test.case
(Logging is disabled while fuzzing to increase fuzzing speed.) (Logging is disabled while fuzzing to increase fuzzing speed.)

0
src/test/fuzz_multi.sh → src/test/fuzz/fuzz_multi.sh
View File