diff options
| -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 |
6 files changed, 61 insertions, 57 deletions
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. |