diff options
| -rw-r--r-- | include/debug.h | 12 | ||||
| -rw-r--r-- | libdislocator/README.md (renamed from libdislocator/README.dislocator) | 6 | ||||
| -rw-r--r-- | libtokencap/README.md (renamed from libtokencap/README.tokencap) | 12 | ||||
| -rw-r--r-- | llvm_mode/README.instrim.md (renamed from llvm_mode/README.instrim) | 8 | ||||
| -rw-r--r-- | llvm_mode/README.laf-intel | 20 | ||||
| -rw-r--r-- | llvm_mode/README.laf-intel.md | 25 | ||||
| -rw-r--r-- | llvm_mode/README.md (renamed from llvm_mode/README.llvm) | 37 | ||||
| -rw-r--r-- | llvm_mode/README.neverzero.md (renamed from llvm_mode/README.neverzero) | 8 | ||||
| -rw-r--r-- | llvm_mode/README.whitelist.md (renamed from llvm_mode/README.whitelist) | 20 | ||||
| -rw-r--r-- | qemu_mode/libcompcov/README.md (renamed from qemu_mode/libcompcov/README.compcov) | 8 |
10 files changed, 81 insertions, 75 deletions
diff --git a/include/debug.h b/include/debug.h index 349aa650..c0044280 100644 --- a/include/debug.h +++ b/include/debug.h @@ -198,8 +198,8 @@ #define FATAL(x...) do { \ SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \ - cBRI x); \ - SAYF(cLRD "\n Location : " cRST "%s(), %s:%d\n\n", \ + cRST x); \ + SAYF(cLRD "\n Location : " cRST "%s(), %s:%u\n\n", \ __FUNCTION__, __FILE__, __LINE__); \ exit(1); \ } while (0) @@ -208,8 +208,8 @@ #define ABORT(x...) do { \ SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \ - cBRI x); \ - SAYF(cLRD "\n Stop location : " cRST "%s(), %s:%d\n\n", \ + cRST x); \ + SAYF(cLRD "\n Stop location : " cRST "%s(), %s:%u\n\n", \ __FUNCTION__, __FILE__, __LINE__); \ abort(); \ } while (0) @@ -219,8 +219,8 @@ #define PFATAL(x...) do { \ fflush(stdout); \ SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] SYSTEM ERROR : " \ - cBRI x); \ - SAYF(cLRD "\n Stop location : " cRST "%s(), %s:%d\n", \ + cRST x); \ + SAYF(cLRD "\n Stop location : " cRST "%s(), %s:%u\n", \ __FUNCTION__, __FILE__, __LINE__); \ SAYF(cLRD " OS message : " cRST "%s\n", strerror(errno)); \ exit(1); \ diff --git a/libdislocator/README.dislocator b/libdislocator/README.md index 837e7466..5d5a1464 100644 --- a/libdislocator/README.dislocator +++ b/libdislocator/README.md @@ -1,6 +1,4 @@ -=================================== -libdislocator, an abusive allocator -=================================== +# libdislocator, an abusive allocator (See ../docs/README for the general instruction manual.) @@ -45,7 +43,9 @@ when fuzzing small, self-contained binaries. To use this library, run AFL like so: +``` AFL_PRELOAD=/path/to/libdislocator.so ./afl-fuzz [...other params...] +``` You *have* to specify path, even if it's just ./libdislocator.so or $PWD/libdislocator.so. diff --git a/libtokencap/README.tokencap b/libtokencap/README.md index 650739f2..baf69da1 100644 --- a/libtokencap/README.tokencap +++ b/libtokencap/README.md @@ -1,10 +1,8 @@ -========================================= -strcmp() / memcmp() token capture library -========================================= +# strcmp() / memcmp() token capture library (See ../docs/README for the general instruction manual.) -This Linux-only companion library allows you to instrument strcmp(), memcmp(), +This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`, and related functions to automatically extract syntax tokens passed to any of these libcalls. The resulting list of tokens may be then given as a starting dictionary to afl-fuzz (the -x option) to improve coverage on subsequent @@ -31,15 +29,18 @@ with -fno-builtin and is linked dynamically. If you wish to automate the first part without mucking with CFLAGS in Makefiles, you can set AFL_NO_BUILTIN=1 when using afl-gcc. This setting specifically adds the following flags: +``` -fno-builtin-strcmp -fno-builtin-strncmp -fno-builtin-strcasecmp -fno-builtin-strcasencmp -fno-builtin-memcmp -fno-builtin-strstr -fno-builtin-strcasestr +``` The next step is simply loading this library via LD_PRELOAD. The optimal usage pattern is to allow afl-fuzz to fuzz normally for a while and build up a corpus, and then fire off the target binary, with libtokencap.so loaded, on every file found by AFL in that earlier run. This demonstrates the basic principle: +``` export AFL_TOKEN_FILE=$PWD/temp_output.txt for i in <out_dir>/queue/id*; do @@ -48,6 +49,7 @@ found by AFL in that earlier run. This demonstrates the basic principle: done sort -u temp_output.txt >afl_dictionary.txt +``` If you don't get any results, the target library is probably not using strcmp() and memcmp() to parse input; or you haven't compiled it with -fno-builtin; or @@ -55,7 +57,7 @@ the whole thing isn't dynamically linked, and LD_PRELOAD is having no effect. PS. The library is Linux-only because there is probably no particularly portable and non-invasive way to distinguish between read-only and read-write memory -mappings. The __tokencap_load_mappings() function is the only thing that would +mappings. The `__tokencap_load_mappings()` function is the only thing that would need to be changed for other OSes. Porting to platforms with /proc/<pid>/maps (e.g., FreeBSD) should be trivial. diff --git a/llvm_mode/README.instrim b/llvm_mode/README.instrim.md index 956a9856..e5e3614d 100644 --- a/llvm_mode/README.instrim +++ b/llvm_mode/README.instrim.md @@ -1,6 +1,6 @@ # InsTrim -InsTrim: Lightweight Instrumentation for Coverage-guided Fuzzing +InsTrim: Lightweight Instrumentation for Coverage-guided Fuzzing ## Introduction @@ -8,17 +8,15 @@ InsTrim uses CFG and markers to instrument just what is necessary in the binary in llvm_mode. It is about 20-25% faster but as a cost has a lower path discovery. - ## Usage -Set the environment variable AFL_LLVM_INSTRIM=1 +Set the environment variable `AFL_LLVM_INSTRIM=1`. There is also an advanced mode which instruments loops in a way so that afl-fuzz can see which loop path has been selected but not being able to see how often the loop has been rerun. This again is a tradeoff for speed for less path information. -To enable this mode set AFL_LLVM_INSTRIM_LOOPHEAD=1 - +To enable this mode set `AFL_LLVM_INSTRIM_LOOPHEAD=1`. ## Background diff --git a/llvm_mode/README.laf-intel b/llvm_mode/README.laf-intel deleted file mode 100644 index 340216c3..00000000 --- a/llvm_mode/README.laf-intel +++ /dev/null @@ -1,20 +0,0 @@ -Usage -===== - -By default the passes will not run when you compile programs using -afl-clang-fast. Hence, you can use AFL as usual. -To enable the passes you must set environment variables before you -compile the target project. - -The following options exist: - -export AFL_LLVM_LAF_SPLIT_SWITCHES=1 Enables the split-switches pass. - -export AFL_LLVM_LAF_TRANSFORM_COMPARES=1 Enables the transform-compares pass - (strcmp, memcmp, strncmp, strcasecmp, strncasecmp). - -export AFL_LLVM_LAF_SPLIT_COMPARES=1 Enables the split-compares pass. - By default it will split all compares with a bit width <= 64 bits. - You can change this behaviour by setting - export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>. - diff --git a/llvm_mode/README.laf-intel.md b/llvm_mode/README.laf-intel.md new file mode 100644 index 00000000..d51c7e2f --- /dev/null +++ b/llvm_mode/README.laf-intel.md @@ -0,0 +1,25 @@ +# laf-intel instrumentation + +## Usage + +By default the passes will not run when you compile programs using +afl-clang-fast. Hence, you can use AFL as usual. +To enable the passes you must set environment variables before you +compile the target project. + +The following options exist: + +`export AFL_LLVM_LAF_SPLIT_SWITCHES=1` + +Enables the split-switches pass. + +`export AFL_LLVM_LAF_TRANSFORM_COMPARES=1` + +Enables the transform-compares pass (strcmp, memcmp, strncmp, strcasecmp, strncasecmp). + +`export AFL_LLVM_LAF_SPLIT_COMPARES=1` + +Enables the split-compares pass. +By default it will split all compares with a bit width <= 64 bits. +You can change this behaviour by setting `export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>`. + diff --git a/llvm_mode/README.llvm b/llvm_mode/README.md index 9bb091ac..c7ef4b45 100644 --- a/llvm_mode/README.llvm +++ b/llvm_mode/README.md @@ -1,12 +1,9 @@ -============================================ -Fast LLVM-based instrumentation for afl-fuzz -============================================ +# Fast LLVM-based instrumentation for afl-fuzz (See ../docs/README for the general instruction manual.) (See ../gcc_plugin/README.gcc for the GCC-based instrumentation.) -1) Introduction ---------------- +## 1) Introduction ! llvm_mode works with llvm versions 3.8.0 up to 9 ! @@ -38,8 +35,7 @@ co-exists with the original code. The idea and much of the implementation comes from Laszlo Szekeres. -2) How to use this ------------------- +## 2) How to use this In order to leverage this mechanism, you need to have clang installed on your system. You should also make sure that the llvm-config tool is in your path @@ -63,8 +59,10 @@ called afl-clang-fast and afl-clang-fast++ in the parent directory. Once this is done, you can instrument third-party code in a way similar to the standard operating mode of AFL, e.g.: +``` CC=/path/to/afl/afl-clang-fast ./configure [...options...] make +``` Be sure to also include CXX set to afl-clang-fast++ for C++ code. @@ -78,7 +76,7 @@ Note: if you want the LLVM helper to be installed on your system for all users, you need to build it before issuing 'make install' in the parent directory. -3) Options +## 3) Options Several options are present to make llvm_mode faster or help it rearrange the code to make afl-fuzz path discovery easier. @@ -101,15 +99,12 @@ is not optimal and was only fixed in llvm 9. You can set this with AFL_LLVM_NOT_ZERO=1 See README.neverzero - -4) Gotchas, feedback, bugs --------------------------- +## 4) Gotchas, feedback, bugs This is an early-stage mechanism, so field reports are welcome. You can send bug reports to <afl-users@googlegroups.com>. -5) Bonus feature #1: deferred initialization --------------------------------------------- +## 5) Bonus feature #1: deferred initialization AFL tries to optimize performance by executing the targeted binary just once, stopping it just before main(), and then cloning this "master" process to get @@ -145,9 +140,11 @@ a location after: With the location selected, add this code in the appropriate spot: +```c #ifdef __AFL_HAVE_MANUAL_CONTROL __AFL_INIT(); #endif +``` You don't need the #ifdef guards, but including them ensures that the program will keep working normally when compiled with a tool other than afl-clang-fast. @@ -155,8 +152,7 @@ will keep working normally when compiled with a tool other than afl-clang-fast. Finally, recompile the program with afl-clang-fast (afl-gcc or afl-clang will *not* generate a deferred-initialization binary) - and you should be all set! -6) Bonus feature #2: persistent mode ------------------------------------- +## 6) Bonus feature #2: persistent mode Some libraries provide APIs that are stateless, or whose state can be reset in between processing different input files. When such a reset is performed, a @@ -165,6 +161,7 @@ eliminating the need for repeated fork() calls and the associated OS overhead. The basic structure of the program that does this would be: +```c while (__AFL_LOOP(1000)) { /* Read input data. */ @@ -174,6 +171,7 @@ The basic structure of the program that does this would be: } /* Exit normally */ +``` The numerical value specified within the loop controls the maximum number of iterations before AFL will restart the process from scratch. This minimizes @@ -182,8 +180,8 @@ and going much higher increases the likelihood of hiccups without giving you any real performance benefits. A more detailed template is shown in ../experimental/persistent_demo/. -Similarly to the previous mode, the feature works only with afl-clang-fast; -#ifdef guards can be used to suppress it when using other compilers. +Similarly to the previous mode, the feature works only with afl-clang-fast; #ifdef +guards can be used to suppress it when using other compilers. Note that as with the previous mode, the feature is easy to misuse; if you do not fully reset the critical state, you may end up with false positives or @@ -195,8 +193,7 @@ PS. Because there are task switches still involved, the mode isn't as fast as faster than the normal fork() model, and compared to in-process fuzzing, should be a lot more robust. -8) Bonus feature #3: new 'trace-pc-guard' mode ----------------------------------------------- +## 8) Bonus feature #3: new 'trace-pc-guard' mode Recent versions of LLVM are shipping with a built-in execution tracing feature that provides AFL with the necessary tracing data without the need to @@ -207,7 +204,9 @@ post-process the assembly or install any compiler plugins. See: If you have a sufficiently recent compiler and want to give it a try, build afl-clang-fast this way: +``` AFL_TRACE_PC=1 make clean all +``` Note that this mode is currently about 20% slower than "vanilla" afl-clang-fast, and about 5-10% slower than afl-clang. This is likely because the diff --git a/llvm_mode/README.neverzero b/llvm_mode/README.neverzero.md index ef873acb..5fcf7b47 100644 --- a/llvm_mode/README.neverzero +++ b/llvm_mode/README.neverzero.md @@ -1,5 +1,6 @@ -Usage -===== +# NeverZero counters for LLVM instrumentation + +## Usage In larger, complex or reiterative programs the map that collects the edge pairs can easily fill up and wrap. @@ -18,5 +19,6 @@ in version 9 and onwards. If you want to enable this for llvm < 9 then set +``` export AFL_LLVM_NOT_ZERO=1 - +``` diff --git a/llvm_mode/README.whitelist b/llvm_mode/README.whitelist.md index ae044749..5aededba 100644 --- a/llvm_mode/README.whitelist +++ b/llvm_mode/README.whitelist.md @@ -1,6 +1,4 @@ -======================================== -Using afl++ with partial instrumentation -======================================== +# Using afl++ with partial instrumentation This file describes how you can selectively instrument only the source files that are interesting to you using the LLVM instrumentation provided by @@ -8,9 +6,7 @@ Using afl++ with partial instrumentation Originally developed by Christian Holler (:decoder) <choller@mozilla.com>. - -1) Description and purpose --------------------------- +## 1) Description and purpose When building and testing complex programs where only a part of the program is the fuzzing target, it often helps to only instrument the necessary parts of @@ -23,15 +19,13 @@ mode of AFLFuzz that allows you to specify on a source file level which files should be compiled with or without instrumentation. -2) Building the LLVM module ---------------------------- +## 2) Building the LLVM module The new code is part of the existing afl++ LLVM module in the llvm_mode/ subdirectory. There is nothing specifically to do :) -3) How to use the partial instrumentation mode ----------------------------------------------- +## 3) How to use the partial instrumentation mode In order to build with partial instrumentation, you need to build with afl-clang-fast and afl-clang-fast++ respectively. The only required change is @@ -45,21 +39,27 @@ matching when absolute paths are used during compilation). For example if your source tree looks like this: +``` project/ project/feature_a/a1.cpp project/feature_a/a2.cpp project/feature_b/b1.cpp project/feature_b/b2.cpp +``` And you only want to test feature_a, then create a whitelist file containing: +``` feature_a/a1.cpp feature_a/a2.cpp +``` However if the whitelist file contains this, it works as well: +``` a1.cpp a2.cpp +``` but it might lead to files being unwantedly instrumented if the same filename exists somewhere else in the project. diff --git a/qemu_mode/libcompcov/README.compcov b/qemu_mode/libcompcov/README.md index 9be13d88..5aaa3dd8 100644 --- a/qemu_mode/libcompcov/README.compcov +++ b/qemu_mode/libcompcov/README.md @@ -1,10 +1,8 @@ -================================================================ -strcmp() / memcmp() CompareCoverage library for AFLplusplus-QEMU -================================================================ +# strcmp() / memcmp() CompareCoverage library for afl++ QEMU Written by Andrea Fioraldi <andreafioraldi@gmail.com> -This Linux-only companion library allows you to instrument strcmp(), memcmp(), +This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`, and related functions to log the CompareCoverage of these libcalls. Use this with caution. While this can speedup a lot the bypass of hard @@ -22,10 +20,12 @@ library and QEMU but build it with afl-clang-fast and the laf-intel options. To use this library make sure to preload it with AFL_PRELOAD. +``` export AFL_PRELOAD=/path/to/libcompcov.so export AFL_COMPCOV_LEVEL=1 afl-fuzz -Q -i input -o output <your options> -- <target args> +``` The AFL_COMPCOV_LEVEL tells to QEMU and libcompcov how to log comaprisons. Level 1 logs just comparison with immediates / read-only memory and level 2 |