diff options
Diffstat (limited to 'instrumentation')
| -rw-r--r-- | instrumentation/README.gcc_plugin.md | 4 | ||||
| -rw-r--r-- | instrumentation/README.instrument_list.md | 2 | ||||
| -rw-r--r-- | instrumentation/README.laf-intel.md | 6 | ||||
| -rw-r--r-- | instrumentation/README.llvm.md | 70 | ||||
| -rw-r--r-- | instrumentation/README.lto.md | 6 |
5 files changed, 65 insertions, 23 deletions
diff --git a/instrumentation/README.gcc_plugin.md b/instrumentation/README.gcc_plugin.md index f251415b..ef38662b 100644 --- a/instrumentation/README.gcc_plugin.md +++ b/instrumentation/README.gcc_plugin.md @@ -1,7 +1,7 @@ # GCC-based instrumentation for afl-fuzz -For the general instruction manual, see [../README.md](../README.md). -For the LLVM-based instrumentation, see [README.llvm.md](README.llvm.md). +For the general instruction manual, see [../README.md](../README.md). For the +LLVM-based instrumentation, see [README.llvm.md](README.llvm.md). This document describes how to build and use `afl-gcc-fast` and `afl-g++-fast`, which instrument the target with the help of gcc plugins. diff --git a/instrumentation/README.instrument_list.md b/instrumentation/README.instrument_list.md index b412b600..3ed64807 100644 --- a/instrumentation/README.instrument_list.md +++ b/instrumentation/README.instrument_list.md @@ -128,4 +128,4 @@ Note that whitespace is ignored and comments (`# foo`) are supported. ### 3b) UNIX-style pattern matching You can add UNIX-style pattern matching in the "instrument file list" entries. -See `man fnmatch` for the syntax. We do not set any of the `fnmatch` flags. \ No newline at end of file +See `man fnmatch` for the syntax. Do not set any of the `fnmatch` flags. \ No newline at end of file diff --git a/instrumentation/README.laf-intel.md b/instrumentation/README.laf-intel.md index 3cde10c3..06e653ea 100644 --- a/instrumentation/README.laf-intel.md +++ b/instrumentation/README.laf-intel.md @@ -42,9 +42,9 @@ comparisons. A new experimental feature is splitting floating point comparisons into a series of sign, exponent and mantissa comparisons followed by splitting each of them into 8 bit comparisons when necessary. It is activated with the -`AFL_LLVM_LAF_SPLIT_FLOATS` setting. Please note that full IEEE 754 -functionality is not preserved, that is values of nan and infinity will probably -behave differently. +`AFL_LLVM_LAF_SPLIT_FLOATS` setting. Note that full IEEE 754 functionality is +not preserved, that is values of nan and infinity will probably behave +differently. Note that setting this automatically activates `AFL_LLVM_LAF_SPLIT_COMPARES`. diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md index 88ea0127..d220e52c 100644 --- a/instrumentation/README.llvm.md +++ b/instrumentation/README.llvm.md @@ -40,7 +40,7 @@ The idea and much of the initial implementation came from Laszlo Szekeres. ## 2a) How to use this - short -Set the `LLVM_CONFIG` variable to the clang version you want to use, e.g. +Set the `LLVM_CONFIG` variable to the clang version you want to use, e.g.: ``` LLVM_CONFIG=llvm-config-9 make @@ -106,9 +106,10 @@ either setting `AFL_CC_COMPILER=LLVM` or pass the parameter `--afl-llvm` via CFLAGS/CXXFLAGS/CPPFLAGS. The tool honors roughly the same environmental variables as afl-gcc (see -[docs/env_variables.md](../docs/env_variables.md)). This includes AFL_USE_ASAN, -AFL_HARDEN, and AFL_DONT_OPTIMIZE. However AFL_INST_RATIO is not honored as it -does not serve a good purpose with the more effective PCGUARD analysis. +[docs/env_variables.md](../docs/env_variables.md)). This includes +`AFL_USE_ASAN`, `AFL_HARDEN`, and `AFL_DONT_OPTIMIZE`. However, `AFL_INST_RATIO` +is not honored as it does not serve a good purpose with the more effective +PCGUARD analysis. ## 3) Options @@ -119,15 +120,15 @@ If you need just to instrument specific parts of the code, you can the instrument file list which C/C++ files to actually instrument. See [README.instrument_list.md](README.instrument_list.md) -For splitting memcmp, strncmp, etc. please see -[README.laf-intel.md](README.laf-intel.md) +For splitting memcmp, strncmp, etc., see +[README.laf-intel.md](README.laf-intel.md). Then there are different ways of instrumenting the target: -1. An better instrumentation strategy uses LTO and link time instrumentation. - Note that not all targets can compile in this mode, however if it works it is - the best option you can use. Simply use afl-clang-lto/afl-clang-lto++ to use - this option. See [README.lto.md](README.lto.md). +1. A better instrumentation strategy uses LTO and link time instrumentation. + Note that not all targets can compile in this mode, however, if it works it + is the best option you can use. To go with this option, use + afl-clang-lto/afl-clang-lto++. See [README.lto.md](README.lto.md). 2. Alternatively you can choose a completely different coverage method: @@ -157,8 +158,8 @@ nozero counter default for performance reasons. ## 4) deferred initialization, persistent mode, shared memory fuzzing -This is the most powerful and effective fuzzing you can do. Please see -[README.persistent_mode.md](README.persistent_mode.md) for a full explanation. +This is the most powerful and effective fuzzing you can do. For a full +explanation, see [README.persistent_mode.md](README.persistent_mode.md). ## 5) Bonus feature: 'dict2file' pass @@ -217,7 +218,7 @@ by Jinghan Wang, et. al. Note that the original implementation (available [here](https://github.com/bitsecurerlab/afl-sensitive)) is built on top of AFL's -qemu_mode. This is essentially a port that uses LLVM vectorized instructions +QEMU mode. This is essentially a port that uses LLVM vectorized instructions (available from llvm versions 4.0.1 and higher) to achieve the same results when compiling source code. @@ -233,4 +234,45 @@ are 2-16. It is highly recommended to increase the MAP_SIZE_POW2 definition in config.h to at least 18 and maybe up to 20 for this as otherwise too many map collisions -occur. \ No newline at end of file +occur. + +## 8) NeverZero counters + +In larger, complex, or reiterative programs, the byte sized counters that +collect the edge coverage can easily fill up and wrap around. This is not that +much of an issue - unless, by chance, it wraps just to a value of zero when the +program execution ends. In this case, afl-fuzz is not able to see that the edge +has been accessed and will ignore it. + +NeverZero prevents this behavior. If a counter wraps, it jumps over the value 0 +directly to a 1. This improves path discovery (by a very small amount) at a very +low cost (one instruction per edge). + +(The alternative of saturated counters has been tested also and proved to be +inferior in terms of path discovery.) + +This is implemented in afl-gcc and afl-gcc-fast, however, for llvm_mode this is +optional if multithread safe counters are selected or the llvm version is below +9 - as there are severe performance costs in these cases. + +If you want to enable this for llvm versions below 9 or thread safe counters, +then set + +``` +export AFL_LLVM_NOT_ZERO=1 +``` + +In case you are on llvm 9 or greater and you do not want this behavior, then you +can set: + +``` +AFL_LLVM_SKIP_NEVERZERO=1 +``` + +If the target does not have extensive loops or functions that are called a lot, +then this can give a small performance boost. + +Please note that the default counter implementations are not thread safe! + +Support for thread safe counters in mode LLVM CLASSIC can be activated with +setting `AFL_LLVM_THREADSAFE_INST=1`. \ No newline at end of file diff --git a/instrumentation/README.lto.md b/instrumentation/README.lto.md index a74425dc..a20175b1 100644 --- a/instrumentation/README.lto.md +++ b/instrumentation/README.lto.md @@ -71,7 +71,7 @@ use an outdated Linux distribution, read the next section. Installing the llvm snapshot builds is easy and mostly painless: In the following line, change `NAME` for your Debian or Ubuntu release name -(e.g. buster, focal, eon, etc.): +(e.g., buster, focal, eon, etc.): ``` echo deb http://apt.llvm.org/NAME/ llvm-toolchain-NAME NAME >> /etc/apt/sources.list @@ -202,7 +202,7 @@ bytes or which functions were touched by an input. ## Solving difficult targets Some targets are difficult because the configure script does unusual stuff that -is unexpected for afl. See the next chapter `Potential issues` for how to solve +is unexpected for afl. See the next section `Potential issues` for how to solve these. ### Example: ffmpeg @@ -328,7 +328,7 @@ and `CXXFLAGS=-flto=full`). If this succeeds, then there is an issue with afl-clang-lto. Please report at [https://github.com/AFLplusplus/AFLplusplus/issues/226](https://github.com/AFLplusplus/AFLplusplus/issues/226). -Even some targets where clang-12 fails can be build if the fail is just in +Even some targets where clang-12 fails can be built if the fail is just in `./configure`, see `Solving difficult targets` above. ## History |