diff --git a/QuickStartGuide.md b/QuickStartGuide.md new file mode 120000 index 00000000..8136d85e --- /dev/null +++ b/QuickStartGuide.md @@ -0,0 +1 @@ +docs/QuickStartGuide.md \ No newline at end of file diff --git a/QuickStartGuide.txt b/QuickStartGuide.txt deleted file mode 120000 index e1687eb5..00000000 --- a/QuickStartGuide.txt +++ /dev/null @@ -1 +0,0 @@ -docs/QuickStartGuide.txt \ No newline at end of file diff --git a/README.md b/README.md index e2e073ac..00ae599c 100644 --- a/README.md +++ b/README.md @@ -433,11 +433,11 @@ see [http://lcamtuf.coredump.cx/afl/plot/](http://lcamtuf.coredump.cx/afl/plot/) Every instance of afl-fuzz takes up roughly one core. This means that on multi-core systems, parallelization is necessary to fully utilize the hardware. For tips on how to fuzz a common target on multiple cores or multiple networked -machines, please refer to [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt). +machines, please refer to [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md). The parallel fuzzing mode also offers a simple way for interfacing AFL to other fuzzers, to symbolic or concolic execution engines, and so forth; again, see the -last section of [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt) for tips. +last section of [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md) for tips. ## 10) Fuzzer dictionaries diff --git a/afl-whatsup b/afl-whatsup index 6a8c5669..6156ba11 100755 --- a/afl-whatsup +++ b/afl-whatsup @@ -45,7 +45,7 @@ if [ "$DIR" = "" ]; then echo "Usage: $0 [ -s ] afl_sync_dir" 1>&2 echo 1>&2 echo "The -s option causes the tool to skip all the per-fuzzer trivia and show" 1>&2 - echo "just the summary results. See docs/parallel_fuzzing.txt for additional tips." 1>&2 + echo "just the summary results. See docs/parallel_fuzzing.md for additional tips." 1>&2 echo 1>&2 exit 1 diff --git a/docs/QuickStartGuide.md b/docs/QuickStartGuide.md index 1e89a6ad..d5ad303e 100644 --- a/docs/QuickStartGuide.md +++ b/docs/QuickStartGuide.md @@ -51,4 +51,4 @@ following files: - README.md - A general introduction to AFL, - docs/perf_tips.txt - Simple tips on how to fuzz more quickly, - docs/status_screen.txt - An explanation of the tidbits shown in the UI, - - docs/parallel_fuzzing.txt - Advice on running AFL on multiple cores. + - docs/parallel_fuzzing.md - Advice on running AFL on multiple cores. diff --git a/docs/life_pro_tips.txt b/docs/life_pro_tips.txt index c8c47636..27c70592 100644 --- a/docs/life_pro_tips.txt +++ b/docs/life_pro_tips.txt @@ -14,7 +14,7 @@ See dictionaries/README.dictionaries to learn how. % You can get the most out of your hardware by parallelizing AFL jobs. -See docs/parallel_fuzzing.txt for step-by-step tips. +See docs/parallel_fuzzing.md for step-by-step tips. % diff --git a/docs/parallel_fuzzing.txt b/docs/parallel_fuzzing.md similarity index 96% rename from docs/parallel_fuzzing.txt rename to docs/parallel_fuzzing.md index 1e65c01f..51fa3986 100644 --- a/docs/parallel_fuzzing.txt +++ b/docs/parallel_fuzzing.md @@ -1,12 +1,9 @@ -========================= -Tips for parallel fuzzing -========================= +# Tips for parallel fuzzing This document talks about synchronizing afl-fuzz jobs on a single machine or across a fleet of systems. See README for the general instruction manual. -1) Introduction ---------------- +## 1) Introduction Every copy of afl-fuzz will take up one CPU core. This means that on an n-core system, you can almost always run around n concurrent fuzzing jobs with @@ -33,8 +30,7 @@ several instances in parallel. See docs/power_schedules.txt Alternatively running other AFL spinoffs in parallel can be of value, e.g. Angora (https://github.com/AngoraFuzzer/Angora/) -2) Single-system parallelization --------------------------------- +## 2) Single-system parallelization If you wish to parallelize a single job across multiple cores on a local system, simply create a new, empty output directory ("sync dir") that will be @@ -43,12 +39,16 @@ for every instance - say, "fuzzer01", "fuzzer02", etc. Run the first one ("master", -M) like this: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -M fuzzer01 [...other stuff...] +``` ...and then, start up secondary (-S) instances like this: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer02 [...other stuff...] $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer03 [...other stuff...] +``` Each fuzzer will keep its state in a separate subdirectory, like so: @@ -68,9 +68,11 @@ Note that running multiple -M instances is wasteful, although there is an experimental support for parallelizing the deterministic checks. To leverage that, you need to create -M instances like so: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterA:1/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterB:2/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterC:3/3 [...] +``` ...where the first value after ':' is the sequential ID of a particular master instance (starting at 1), and the second value is the total number of fuzzers to @@ -86,15 +88,16 @@ WARNING: Exercise caution when explicitly specifying the -f option. Each fuzzer must use a separate temporary file; otherwise, things will go south. One safe example may be: +``` $ ./afl-fuzz [...] -S fuzzer10 -f file10.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer11 -f file11.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer12 -f file12.txt ./fuzzed/binary @@ +``` This is not a concern if you use @@ without -f and let afl-fuzz come up with the file name. -3) Multi-system parallelization -------------------------------- +## 3) Multi-system parallelization The basic operating principle for multi-system parallelization is similar to the mechanism explained in section 2. The key difference is that you need to @@ -106,18 +109,22 @@ write a simple script that performs two actions: that includes host name in the fuzzer ID, so that you can do something like: + ```sh for s in {1..10}; do ssh user@host${s} "tar -czf - sync/host${s}_fuzzid*/[qf]*" >host${s}.tgz done + ``` - Distributes and unpacks these files on all the remaining machines, e.g.: + ```sh for s in {1..10}; do for d in {1..10}; do test "$s" = "$d" && continue ssh user@host${d} 'tar -kxzf -'