diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 104 |
1 files changed, 64 insertions, 40 deletions
diff --git a/README.md b/README.md index 084971f3..ba612edb 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ <img align="right" src="https://raw.githubusercontent.com/andreafioraldi/AFLplusplus-website/master/static/logo_256x256.png" alt="AFL++ Logo"> - Release Version: [3.12c](https://github.com/AFLplusplus/AFLplusplus/releases) + Release Version: [3.13c](https://github.com/AFLplusplus/AFLplusplus/releases) - Github Version: 3.13a + Github Version: 3.14a Repository: [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) @@ -25,7 +25,11 @@ For comparisons use the fuzzbench `aflplusplus` setup, or use `afl-clang-fast` with `AFL_LLVM_CMPLOG=1`. -## Major changes in afl++ 3.00 + 3.10 +## Major changes in afl++ 3.00 onwards: + +With afl++ 3.13-3.20 we introduce frida_mode (-O) to have an alternative for +binary-only fuzzing. It is slower than Qemu mode but works on MacOS, Android, +iOS etc. With afl++ 3.10 we introduced the following changes from previous behaviours: * The '+' feature of the '-t' option now means to auto-calculate the timeout @@ -80,30 +84,32 @@ behaviours and defaults: ## Important features of afl++ - afl++ supports llvm up to version 12, very fast binary fuzzing with QEMU 5.1 - with laf-intel and redqueen, unicorn mode, gcc plugin, full *BSD, Solaris and - Android support and much, much, much more. - - | Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | qemu_mode | unicorn_mode | - | -------------------------|:-------:|:---------:|:----------:|:----------------:|:------------:| - | NeverZero | x86[_64]| x(1) | x | x | x | - | Persistent Mode | | x | x | x86[_64]/arm[64] | x | - | LAF-Intel / CompCov | | x | | x86[_64]/arm[64] | x86[_64]/arm | - | CmpLog | | x | | x86[_64]/arm[64] | | - | Selective Instrumentation| | x | x | x | | - | Non-Colliding Coverage | | x(4) | | (x)(5) | | - | Ngram prev_loc Coverage | | x(6) | | | | - | Context Coverage | | x(6) | | | | - | Auto Dictionary | | x(7) | | | | - | Snapshot LKM Support | | x(8) | x(8) | (x)(5) | | - - 1. default for LLVM >= 9.0, env var for older version due an efficiency bug in llvm <= 8 + afl++ supports llvm from 6.0 up to version 12, very fast binary fuzzing with QEMU 5.1 + with laf-intel and redqueen, frida mode, unicorn mode, gcc plugin, full *BSD, + Mac OS, Solaris and Android support and much, much, much more. + + | Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | frida_mode | qemu_mode |unicorn_mode | + | -------------------------|:-------:|:---------:|:----------:|:----------:|:----------------:|:------------:| + | Threadsafe counters | | x(3) | | | | | + | NeverZero | x86[_64]| x(1) | x | x | x | x | + | Persistent Mode | | x | x | x86[_64] | x86[_64]/arm[64] | x | + | LAF-Intel / CompCov | | x | | | x86[_64]/arm[64] | x86[_64]/arm | + | CmpLog | | x | | x86[_64] | x86[_64]/arm[64] | | + | Selective Instrumentation| | x | x | x | x | | + | Non-Colliding Coverage | | x(4) | | | (x)(5) | | + | Ngram prev_loc Coverage | | x(6) | | | | | + | Context Coverage | | x(6) | | | | | + | Auto Dictionary | | x(7) | | | | | + | Snapshot LKM Support | | (x)(8) | (x)(8) | | (x)(5) | | + | Shared Memory Testcases | | x | x | x | x | x | + + 1. default for LLVM >= 9.0, env var for older version due an efficiency bug in previous llvm versions 2. GCC creates non-performant code, hence it is disabled in gcc_plugin - 3. (currently unassigned) - 4. with pcguard mode and LTO mode for LLVM >= 11 + 3. with `AFL_LLVM_THREADSAFE_INST`, disables NeverZero + 4. with pcguard mode and LTO mode for LLVM 11 and newer 5. upcoming, development in the branch - 6. not compatible with LTO instrumentation and needs at least LLVM >= 4.1 - 7. automatic in LTO mode with LLVM >= 11, an extra pass for all LLVM version that writes to a file to use with afl-fuzz' `-x` + 6. not compatible with LTO instrumentation and needs at least LLVM v4.1 + 7. automatic in LTO mode with LLVM 11 and newer, an extra pass for all LLVM version that writes to a file to use with afl-fuzz' `-x` 8. the snapshot LKM is currently unmaintained due to too many kernel changes coming too fast :-( Among others, the following features and patches have been integrated: @@ -140,6 +146,7 @@ behaviours and defaults: time when we are satisfied with its stability * [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev) : development state of afl++ - bleeding edge and you might catch a checkout which does not compile or has a bug. *We only accept PRs in dev!!* + * [release](https://github.com/AFLplusplus/AFLplusplus/tree/release) : the latest release * (any other) : experimental branches to work on specific features or testing new functionality or changes. @@ -180,7 +187,7 @@ sudo apt-get install -y build-essential python3-dev automake git flex bison libg # try to install llvm 11 and install the distro default if that fails sudo apt-get install -y lld-11 llvm-11 llvm-11-dev clang-11 || sudo apt-get install -y lld llvm llvm-dev clang sudo apt-get install -y gcc-$(gcc --version|head -n1|sed 's/.* //'|sed 's/\..*//')-plugin-dev libstdc++-$(gcc --version|head -n1|sed 's/.* //'|sed 's/\..*//')-dev -git clone https://github.com/AFLplusplus/AFLplusplus && cd AFLplusplus +git clone https://github.com/AFLplusplus/AFLplusplus cd AFLplusplus make distrib sudo make install @@ -249,6 +256,7 @@ Here are some good writeups to show how to effectively use AFL++: If you are interested in fuzzing structured data (where you define what the structure is), these links have you covered: * Superion for afl++: [https://github.com/adrian-rt/superion-mutator](https://github.com/adrian-rt/superion-mutator) + * libprotobuf for afl++: [https://github.com/P1umer/AFLplusplus-protobuf-mutator](https://github.com/P1umer/AFLplusplus-protobuf-mutator) * libprotobuf raw: [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator) * libprotobuf for old afl++ API: [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator) @@ -288,7 +296,7 @@ anything below 9 is not recommended. | v +---------------------------------+ -| clang/clang++ 3.3+ is available | --> use LLVM mode (afl-clang-fast/afl-clang-fast++) +| clang/clang++ 6.0+ is available | --> use LLVM mode (afl-clang-fast/afl-clang-fast++) +---------------------------------+ see [instrumentation/README.llvm.md](instrumentation/README.llvm.md) | | if not, or if the target fails with LLVM afl-clang-fast/++ @@ -370,7 +378,6 @@ There are many more options and modes available however these are most of the time less effective. See: * [instrumentation/README.ctx.md](instrumentation/README.ctx.md) * [instrumentation/README.ngram.md](instrumentation/README.ngram.md) - * [instrumentation/README.instrim.md](instrumentation/README.instrim.md) afl++ performs "never zero" counting in its bitmap. You can read more about this here: @@ -431,7 +438,7 @@ described in [instrumentation/README.lto.md](instrumentation/README.lto.md). ##### cmake For `cmake` build systems this is usually done by: -`mkdir build; cmake -DCMAKE_C_COMPILERC=afl-cc -DCMAKE_CXX_COMPILER=afl-c++ ..` +`mkdir build; cd build; cmake -DCMAKE_C_COMPILER=afl-cc -DCMAKE_CXX_COMPILER=afl-c++ ..` Note that if you are using the (better) afl-clang-lto compiler you also have to set AR to llvm-ar[-VERSION] and RANLIB to llvm-ranlib[-VERSION] - as is @@ -601,8 +608,9 @@ Every -M/-S entry needs a unique name (that can be whatever), however the same For every secondary fuzzer there should be a variation, e.g.: * one should fuzz the target that was compiled differently: with sanitizers activated (`export AFL_USE_ASAN=1 ; export AFL_USE_UBSAN=1 ; - export AFL_USE_CFISAN=1 ; ` - * one should fuzz the target with CMPLOG/redqueen (see above) + export AFL_USE_CFISAN=1 ; export AFL_USE_LSAN=1`) + * one or two should fuzz the target with CMPLOG/redqueen (see above), at + least one cmplog instance should follow transformations (`-l AT`) * one to three fuzzers should fuzz a target compiled with laf-intel/COMPCOV (see above). Important note: If you run more than one laf-intel/COMPCOV fuzzer and you want them to share their intermediate results, the main @@ -672,8 +680,8 @@ If you see that an important area or a feature has not been covered so far then try to find an input that is able to reach that and start a new secondary in that fuzzing campaign with that seed as input, let it run for a few minutes, then terminate it. The main node will pick it up and make it available to the -other secondary nodes over time. Set `export AFL_NO_AFFINITY=1` if you have no -free core. +other secondary nodes over time. Set `export AFL_NO_AFFINITY=1` or +`export AFL_TRY_AFFINITY=1` if you have no free core. Note that you in nearly all cases can never reach full coverage. A lot of functionality is usually behind options that were not activated or fuzz e.g. @@ -784,16 +792,19 @@ How this can look like can e.g. be seen at afl++'s setup in Google's [oss-fuzz]( When source code is *NOT* available, afl++ offers various support for fast, on-the-fly instrumentation of black-box binaries. -If you do not have to use Unicorn the following setup is recommended: +If you do not have to use Unicorn the following setup is recommended to use +qemu_mode: * run 1 afl-fuzz -Q instance with CMPLOG (`-c 0` + `AFL_COMPCOV_LEVEL=2`) * run 1 afl-fuzz -Q instance with QASAN (`AFL_USE_QASAN=1`) * run 1 afl-fuzz -Q instance with LAF (``AFL_PRELOAD=libcmpcov.so` + `AFL_COMPCOV_LEVEL=2`) +Alternatively you can use frida_mode, just switch `-Q` with `-O` and remove the +LAF instance. Then run as many instances as you have cores left with either -Q mode or - better - -use a binary rewriter like afl-dyninst, retrowrite, zipr, fibre, etc. +use a binary rewriter like afl-dyninst, retrowrite, zaflr, etc. -For Qemu mode, check out the persistent mode and snapshot features, they give -a huge speed improvement! +For Qemu and Frida mode, check out the persistent mode, it gives a huge speed +improvement if it is possible to use. ### QEMU @@ -805,18 +816,31 @@ feature by doing: cd qemu_mode ./build_qemu_support.sh ``` -For additional instructions and caveats, see [qemu_mode/README.md](qemu_mode/README.md) - -check out the snapshot feature! :-) +For additional instructions and caveats, see [qemu_mode/README.md](qemu_mode/README.md). If possible you should use the persistent mode, see [qemu_mode/README.persistent.md](qemu_mode/README.persistent.md). The mode is approximately 2-5x slower than compile-time instrumentation, and is less conducive to parallelization. If [afl-dyninst](https://github.com/vanhauser-thc/afl-dyninst) works for your binary, then you can use afl-fuzz normally and it will have twice -the speed compared to qemu_mode (but slower than persistent mode). +the speed compared to qemu_mode (but slower than qemu persistent mode). Note that several other binary rewriters exist, all with their advantages and caveats. +### Frida + +Frida mode is sometimes faster and sometimes slower than Qemu mode. +It is also newer, lacks COMPCOV, but supports MacOS. + +```shell +cd frida_mode +make +``` +For additional instructions and caveats, see [frida_mode/README.md](frida_mode/README.md). +If possible you should use the persistent mode, see [qemu_frida/README.persistent.md](qemu_frida/README.persistent.md). +The mode is approximately 2-5x slower than compile-time instrumentation, and is +less conducive to parallelization. + ### Unicorn For non-Linux binaries you can use afl++'s unicorn mode which can emulate |