From d536ddc24085bced267143b4f45102715d71693e Mon Sep 17 00:00:00 2001 From: van Hauser Date: Fri, 15 May 2020 09:27:15 +0200 Subject: change: slaves only sync from masters --- docs/parallel_fuzzing.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/parallel_fuzzing.md') diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md index 8b39df04..12aefb46 100644 --- a/docs/parallel_fuzzing.md +++ b/docs/parallel_fuzzing.md @@ -57,12 +57,14 @@ Each fuzzer will keep its state in a separate subdirectory, like so: Each instance will also periodically rescan the top-level sync directory for any test cases found by other fuzzers - and will incorporate them into its own fuzzing when they are deemed interesting enough. +For performance reasons only -M masters sync the queue with everyone, the +-S slaves will only sync from the master. The difference between the -M and -S modes is that the master instance will still perform deterministic checks; while the secondary instances will -proceed straight to random tweaks. If you don't want to do deterministic -fuzzing at all, it's OK to run all instances with -S. With very slow or complex -targets, or when running heavily parallelized jobs, this is usually a good plan. +proceed straight to random tweaks. + +Note that you must always have one -M master instance! Note that running multiple -M instances is wasteful, although there is an experimental support for parallelizing the deterministic checks. To leverage -- cgit 1.4.1 From 434ccf3df4760019cb87ceb11087d3440dc5a4ab Mon Sep 17 00:00:00 2001 From: van Hauser Date: Wed, 27 May 2020 11:24:09 +0200 Subject: allow for copy paste from documentation --- README.md | 36 ++++++++++++++++++------------------ docs/parallel_fuzzing.md | 18 +++++++++--------- examples/afl_network_proxy/README.md | 4 ++-- examples/afl_untracer/README.md | 4 ++-- llvm_mode/README.lto.md | 30 +++++++++++++++--------------- llvm_mode/README.md | 2 +- qemu_mode/README.md | 4 ++-- unicorn_mode/README.md | 6 +++--- 8 files changed, 52 insertions(+), 52 deletions(-) (limited to 'docs/parallel_fuzzing.md') diff --git a/README.md b/README.md index 5af2b0fc..1c730ec1 100644 --- a/README.md +++ b/README.md @@ -137,9 +137,9 @@ afl++ has many build options. The easiest is to build and install everything: ```shell -$ sudo apt install build-essential libtool-bin python3-dev automake flex bison libglib2.0-dev libpixman-1-dev clang python3-setuptools llvm -$ make distrib -$ sudo make install +sudo apt install build-essential libtool-bin python3-dev automake flex bison libglib2.0-dev libpixman-1-dev clang python3-setuptools llvm +make distrib +sudo make install ``` Note that "make distrib" also builds llvm_mode, qemu_mode, unicorn_mode and @@ -148,7 +148,7 @@ using at least llvm_mode is highly recommended for much better results - hence in this case ```shell -$ make source-only +make source-only ``` is what you should choose. @@ -171,7 +171,7 @@ These build targets exist: afl++ binaries by passing the STATIC=1 argument to make: ```shell -$ make all STATIC=1 +make all STATIC=1 ``` These build options exist: @@ -191,8 +191,8 @@ Hence at least gcc-9 and especially llvm-9 should be the compilers of choice. If your distribution does not have them, you can use the Dockerfile: ```shell -$ cd AFLplusplus -$ sudo docker build -t aflplusplus . +cd AFLplusplus +sudo docker build -t aflplusplus . ``` @@ -281,8 +281,8 @@ The correct way to recompile the target program may vary depending on the specifics of the build process, but a nearly-universal approach would be: ```shell -$ CC=/path/to/afl/afl-gcc ./configure -$ make clean all +CC=/path/to/afl/afl-gcc ./configure +make clean all ``` For C++ programs, you'd would also want to set `CXX=/path/to/afl/afl-g++`. @@ -306,7 +306,7 @@ runtime (usually by setting `LD_LIBRARY_PATH`). The simplest option is a static build, usually possible via: ```shell -$ CC=/path/to/afl/afl-gcc ./configure --disable-shared +CC=/path/to/afl/afl-gcc ./configure --disable-shared ``` Setting `AFL_HARDEN=1` when calling 'make' will cause the CC wrapper to @@ -328,8 +328,8 @@ QEMU is a project separate from AFL, but you can conveniently build the feature by doing: ```shell -$ cd qemu_mode -$ ./build_qemu_support.sh +cd qemu_mode +./build_qemu_support.sh ``` For additional instructions and caveats, see [qemu_mode/README.md](qemu_mode/README.md). @@ -423,7 +423,7 @@ store its findings, plus a path to the binary to test. For target binaries that accept input directly from stdin, the usual syntax is: ```shell -$ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program [...params...] +./afl-fuzz -i testcase_dir -o findings_dir /path/to/program [...params...] ``` For programs that take input from a file, use '@@' to mark the location in @@ -431,7 +431,7 @@ the target's command line where the input file name should be placed. The fuzzer will substitute this for you: ```shell -$ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@ +./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@ ``` You can also use the -f option to have the mutated data written to a specific @@ -494,8 +494,8 @@ When you can't reproduce a crash found by afl-fuzz, the most likely cause is that you are not setting the same memory limit as used by the tool. Try: ```shell -$ LIMIT_MB=50 -$ ( ulimit -Sv $[LIMIT_MB << 10]; /path/to/tested_binary ... ) +LIMIT_MB=50 +( ulimit -Sv $[LIMIT_MB << 10]; /path/to/tested_binary ... ) ``` Change LIMIT_MB to match the -m parameter passed to afl-fuzz. On OpenBSD, @@ -504,7 +504,7 @@ also change -Sv to -Sd. Any existing output directory can be also used to resume aborted jobs; try: ```shell -$ ./afl-fuzz -i- -o existing_output_dir [...etc...] +./afl-fuzz -i- -o existing_output_dir [...etc...] ``` If you have gnuplot installed, you can also generate some pretty graphs for any @@ -586,7 +586,7 @@ Oh, one more thing: for test case minimization, give afl-tmin a try. The tool can be operated in a very simple way: ```shell -$ ./afl-tmin -i test_case -o minimized_result -- /path/to/program [...] +./afl-tmin -i test_case -o minimized_result -- /path/to/program [...] ``` The tool works with crashing and non-crashing test cases alike. In the crash diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md index 12aefb46..c6e54218 100644 --- a/docs/parallel_fuzzing.md +++ b/docs/parallel_fuzzing.md @@ -40,14 +40,14 @@ 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...] +./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...] +./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: @@ -71,9 +71,9 @@ 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 [...] +./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 @@ -91,9 +91,9 @@ 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 @@ +./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 diff --git a/examples/afl_network_proxy/README.md b/examples/afl_network_proxy/README.md index 42c0b71b..a5ac3578 100644 --- a/examples/afl_network_proxy/README.md +++ b/examples/afl_network_proxy/README.md @@ -29,7 +29,7 @@ Run `afl-network-server` with your target with the -m and -t values you need. Important is the -i parameter which is the TCP port to listen on. e.g.: ``` -$ afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@ +afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@ ``` ### on the (afl-fuzz) master @@ -38,7 +38,7 @@ Just run afl-fuzz with your normal options, however the target should be `afl-network-client` with the IP and PORT of the `afl-network-server` and increase the -t value: ``` -$ afl-fuzz -i in -o out -t 2000+ -- afl-network-client TARGET-IP 1111 +afl-fuzz -i in -o out -t 2000+ -- afl-network-client TARGET-IP 1111 ``` Note the '+' on the -t parameter value. The afl-network-server will take care of proper timeouts hence afl-fuzz should not. The '+' increases the diff --git a/examples/afl_untracer/README.md b/examples/afl_untracer/README.md index 05fd8776..e59792cb 100644 --- a/examples/afl_untracer/README.md +++ b/examples/afl_untracer/README.md @@ -29,8 +29,8 @@ The patches.txt file has to be pointed to by `AFL_UNTRACER_FILE`. To easily run the scripts without needing to run the GUI with Ghidra: ``` -$ /opt/ghidra/support/analyzeHeadless /tmp/ tmp$$ -import libtestinstr.so -postscript ./ghidra_get_patchpoints.java -$ rm -rf /tmp/tmp$$ +/opt/ghidra/support/analyzeHeadless /tmp/ tmp$$ -import libtestinstr.so -postscript ./ghidra_get_patchpoints.java +rm -rf /tmp/tmp$$ ``` ### Fuzzing diff --git a/llvm_mode/README.lto.md b/llvm_mode/README.lto.md index 99bcc50d..48c587eb 100644 --- a/llvm_mode/README.lto.md +++ b/llvm_mode/README.lto.md @@ -84,21 +84,21 @@ apt-get install -y clang-11 clang-tools-11 libc++1-11 libc++-11-dev \ Building llvm from github takes quite some long time and is not painless: ``` -$ sudo apt install binutils-dev # this is *essential*! -$ git clone https://github.com/llvm/llvm-project -$ cd llvm-project -$ mkdir build -$ cd build -$ cmake -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;compiler-rt;libclc;libcxx;libcxxabi;libunwind;lld' -DCMAKE_BUILD_TYPE=Release -DLLVM_BINUTILS_INCDIR=/usr/include/ ../llvm/ -$ make -j $(nproc) -$ export PATH=`pwd`/bin:$PATH -$ export LLVM_CONFIG=`pwd`/bin/llvm-config -$ cd /path/to/AFLplusplus/ -$ make -$ cd llvm_mode -$ make -$ cd .. -$ make install +sudo apt install binutils-dev # this is *essential*! +git clone https://github.com/llvm/llvm-project +cd llvm-project +mkdir build +cd build +cmake -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;compiler-rt;libclc;libcxx;libcxxabi;libunwind;lld' -DCMAKE_BUILD_TYPE=Release -DLLVM_BINUTILS_INCDIR=/usr/include/ ../llvm/ +make -j $(nproc) +export PATH=`pwd`/bin:$PATH +export LLVM_CONFIG=`pwd`/bin/llvm-config +cd /path/to/AFLplusplus/ +make +cd llvm_mode +make +cd .. +make install ``` ## How to use afl-clang-lto diff --git a/llvm_mode/README.md b/llvm_mode/README.md index fa008cba..c24aef49 100644 --- a/llvm_mode/README.md +++ b/llvm_mode/README.md @@ -179,7 +179,7 @@ If you have not an outdated compiler and want to give it a try, build targets this way: ``` -$ AFL_LLVM_INSTRUMENT=PCGUARD make +AFL_LLVM_INSTRUMENT=PCGUARD make ``` Note that this us currently the default, as it is the best mode. diff --git a/qemu_mode/README.md b/qemu_mode/README.md index 50d451b6..3cf678e4 100644 --- a/qemu_mode/README.md +++ b/qemu_mode/README.md @@ -147,8 +147,8 @@ non-instrumented binary with the same optimization flags that are normally injected by afl-gcc, and make sure that the bits to be tested are statically linked into the binary. A common way to do this would be: -$ CFLAGS="-O3 -funroll-loops" ./configure --disable-shared -$ make clean all +CFLAGS="-O3 -funroll-loops" ./configure --disable-shared +make clean all Comparative measurements of execution speed or instrumentation coverage will be fairly meaningless if the optimization levels or instrumentation scopes don't diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index 86683839..f6bd4d12 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -29,8 +29,8 @@ Once that completes successfully you need to build and add in the Unicorn Mode features: ``` -$ cd unicorn_mode -$ ./build_unicorn_support.sh +cd unicorn_mode +./build_unicorn_support.sh ``` NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested @@ -71,7 +71,7 @@ Once you have all those things ready to go you just need to run afl-fuzz in 'unicorn-mode' by passing in the '-U' flag: ``` -$ afl-fuzz -U -m none -i /path/to/inputs -o /path/to/results -- ./test_harness @@ +afl-fuzz -U -m none -i /path/to/inputs -o /path/to/results -- ./test_harness @@ ``` The normal afl-fuzz command line format applies to everything here. Refer to -- cgit 1.4.1