From e1e155022f58c0790800ba59657a0fcfa9536554 Mon Sep 17 00:00:00 2001 From: hexcoder- Date: Sun, 17 May 2020 21:35:10 +0200 Subject: adjust documentation for new minimum llvm version 3.4 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 253275e2..5af2b0fc 100644 --- a/README.md +++ b/README.md @@ -267,7 +267,7 @@ superior to blind fuzzing or coverage-only tools. PLEASE NOTE: llvm_mode compilation with afl-clang-fast/afl-clang-fast++ instead of afl-gcc/afl-g++ is much faster and has many cool features. See llvm_mode/ - however few code does not compile with llvm. -We support llvm versions 3.8.0 to 11. +We support llvm versions 3.4 to 11. When source code is available, instrumentation can be injected by a companion tool that works as a drop-in replacement for gcc or clang in any standard build @@ -290,7 +290,7 @@ For C++ programs, you'd would also want to set `CXX=/path/to/afl/afl-g++`. The clang wrappers (afl-clang and afl-clang++) can be used in the same way; clang users may also opt to leverage a higher-performance instrumentation mode, as described in [llvm_mode/README.md](llvm_mode/README.md). -Clang/LLVM has a much better performance and works with LLVM version 3.8.0 to 11. +Clang/LLVM has a much better performance and works with LLVM version 3.4 to 11. Using the LAF Intel performance enhancements are also recommended, see [llvm_mode/README.laf-intel.md](llvm_mode/README.laf-intel.md) -- 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 'README.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 From b87d97aa2b664f1a5ea90612ba7543b38bc6d24f Mon Sep 17 00:00:00 2001 From: van Hauser Date: Thu, 28 May 2020 14:34:50 +0200 Subject: make dockerfile better --- Dockerfile | 16 ++++++++++------ README.md | 10 +++++++++- 2 files changed, 19 insertions(+), 7 deletions(-) (limited to 'README.md') diff --git a/Dockerfile b/Dockerfile index 5835d205..905e8265 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,8 +11,8 @@ LABEL "about"="AFLplusplus docker image" ARG DEBIAN_FRONTEND=noninteractive -RUN apt-get update && apt-get -y install \ - --no-install-suggests --no-install-recommends \ +RUN apt-get update && apt-get upgrade -y && \ + apt-get -y install --no-install-suggests --no-install-recommends \ automake \ bison flex \ build-essential \ @@ -21,7 +21,7 @@ RUN apt-get update && apt-get -y install \ libtool libtool-bin \ libglib2.0-dev \ wget vim jupp nano \ - apt-utils apt-transport-https ca-certificates gnupg \ + apt-utils apt-transport-https ca-certificates gnupg dialog \ libpixman-1-dev RUN echo deb http://apt.llvm.org/focal/ llvm-toolchain-focal main >> /etc/apt/sources.list && \ @@ -33,7 +33,7 @@ RUN echo deb http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu focal main RUN apt-get update && apt-get upgrade -y RUN apt-get install -y gcc-10 g++-10 gcc-10-plugin-dev gcc-10-multilib \ - libc++-10-dev gdb + libc++-10-dev gdb lcov RUN apt-get install -y clang-11 clang-tools-11 libc++1-11 libc++-11-dev \ libc++abi1-11 libc++abi-11-dev libclang1-11 libclang-11-dev \ @@ -44,15 +44,19 @@ RUN apt-get install -y clang-11 clang-tools-11 libc++1-11 libc++-11-dev \ RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 0 RUN update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 0 -RUN rm -rf /var/lib/apt/lists/* +RUN rm -rf /var/cache/apt/archives/* ARG CC=gcc-10 ARG CXX=g++-10 ARG LLVM_CONFIG=llvm-config-11 RUN git clone https://github.com/AFLplusplus/AFLplusplus - RUN cd AFLplusplus && export REAL_CXX=g++-10 && make distrib && \ make install && make clean +RUN git clone https://github.com/vanhauser-thc/afl-cov afl-cov +RUN cd afl-cov && make install + +RUN echo 'alias joe="jupp --wordwrap"' >> ~/.bashrc + ENV AFL_SKIP_CPUFREQ=1 diff --git a/README.md b/README.md index 1c730ec1..a906a2c0 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,15 @@ For everyone who wants to contribute (and send pull requests) please read ## Building and installing afl++ -afl++ has many build options. +An easy way to install afl++ with everything compiled is available via docker: +```shell +docker pull aflplusplus/aflplusplus +docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus +``` +This container is automatically generated when a push to master happens. +You will find your target source code in /src in the container. + +If you want to build afl++ yourself you have many options. The easiest is to build and install everything: ```shell -- cgit 1.4.1