diff options
| -rw-r--r-- | README.md | 10 | ||||
| -rw-r--r-- | llvm_mode/README.instrim.md | 3 | ||||
| -rw-r--r-- | llvm_mode/README.laf-intel.md | 23 | ||||
| -rw-r--r-- | llvm_mode/README.md | 7 | ||||
| -rw-r--r-- | llvm_mode/README.neverzero.md | 17 | ||||
| -rw-r--r-- | llvm_mode/README.whitelist.md | 12 | ||||
| -rw-r--r-- | qemu_mode/README.md | 22 |
7 files changed, 56 insertions, 38 deletions
diff --git a/README.md b/README.md index fd37eaac..053f5fa5 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Repository: [https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus) afl++ is maintained by Marc "van Hauser" Heuse <mh@mh-sec.de>, - Heiko "hexc0der" Eißfeldt <heiko.eissfeldt@hexco.de> and + Heiko "hexcoder-" Eißfeldt <heiko.eissfeldt@hexco.de> and Andrea Fioraldi <andreafioraldi@gmail.com>. Note that although afl now has a Google afl repository [https://github.com/Google/afl](https://github.com/Google/afl), @@ -24,8 +24,8 @@ Many improvements were made over the official afl release - which did not get any improvements since November 2017. - Among others afl++ has a more performant llvm_mode, supporting - llvm up to version 9, Qemu 3.1, more speed and crashfixes for Qemu, + Among other changes afl++ has a more performant llvm_mode, supports + llvm up to version 9, QEMU 3.1, more speed and crashfixes for QEMU, better *BSD and Android support and much, much more. Additionally the following patches have been integrated: @@ -258,8 +258,8 @@ A more comprehensive description of these and other options can be found in ## 5) Power schedules The power schedules were copied from Marcel Böhme's excellent AFLfast -implementation and expands on the ability to discover new paths and -therefore the coverage. +implementation and expand on the ability to discover new paths and +therefore may increase the code coverage. The available schedules are: diff --git a/llvm_mode/README.instrim.md b/llvm_mode/README.instrim.md index e5e3614d..b40dbb18 100644 --- a/llvm_mode/README.instrim.md +++ b/llvm_mode/README.instrim.md @@ -10,7 +10,8 @@ path discovery. ## Usage -Set the environment variable `AFL_LLVM_INSTRIM=1`. +Set the environment variable `AFL_LLVM_INSTRIM=1` during compilation of +the target. 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 diff --git a/llvm_mode/README.laf-intel.md b/llvm_mode/README.laf-intel.md index d51c7e2f..c787744b 100644 --- a/llvm_mode/README.laf-intel.md +++ b/llvm_mode/README.laf-intel.md @@ -2,7 +2,7 @@ ## Usage -By default the passes will not run when you compile programs using +By default these 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. @@ -15,11 +15,24 @@ Enables the split-switches pass. `export AFL_LLVM_LAF_TRANSFORM_COMPARES=1` -Enables the transform-compares pass (strcmp, memcmp, strncmp, strcasecmp, strncasecmp). +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>`. - +By default it will +1. simplify operators >= (and <=) into chains of > (<) and == comparisons +2. change signed integer comparisons to a chain of sign-only comparison +and unsigned comparisons +3. split all unsigned integer comparisons with bit widths of +64, 32 or 16 bits to chains of 8 bits comparisons. + +You can change the behaviour of the last step by setting +`export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>`, where +bit_width may be 64, 32 or 16. + +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_COMPARES` setting. diff --git a/llvm_mode/README.md b/llvm_mode/README.md index f196395b..fa655ed6 100644 --- a/llvm_mode/README.md +++ b/llvm_mode/README.md @@ -27,7 +27,8 @@ several interesting properties: - The instrumentation can cope a bit better with multi-threaded targets. - Because the feature relies on the internals of LLVM, it is clang-specific - and will *not* work with GCC (see ../gcc_plugin/ for an alternative). + and will *not* work with GCC (see ../gcc_plugin/ for an alternative once + it is available). Once this implementation is shown to be sufficiently robust and portable, it will probably replace afl-clang. For now, it can be built separately and @@ -86,7 +87,7 @@ Several options are present to make llvm_mode faster or help it rearrange the code to make afl-fuzz path discovery easier. If you need just to instrument specific parts of the code, you can whitelist -which C/C++ files to actually intrument. See README.whitelist +which C/C++ files to actually instrument. See README.whitelist For splitting memcmp, strncmp, etc. please see README.laf-intel @@ -98,7 +99,7 @@ See README.instrim Finally if your llvm version is 8 or lower, you can activate a mode that prevents that a counter overflow result in a 0 value. This is good for -path discovery, but the llvm implementation for intel for this functionality +path discovery, but the llvm implementation for x86 for this functionality is not optimal and was only fixed in llvm 9. You can set this with AFL_LLVM_NOT_ZERO=1 See README.neverzero diff --git a/llvm_mode/README.neverzero.md b/llvm_mode/README.neverzero.md index 5fcf7b47..1e406560 100644 --- a/llvm_mode/README.neverzero.md +++ b/llvm_mode/README.neverzero.md @@ -2,17 +2,20 @@ ## Usage -In larger, complex or reiterative programs the map that collects the edge pairs -can easily fill up and wrap. -This is not that much of an issue - unless by chance it wraps just to a 0 -when the program execution ends. -In this case afl-fuzz is not able to see that the pair has been accessed and +In larger, complex or reiterative programs the 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 behaviour. If a counter wraps, it jumps over the 0 -directly to a 1. This improves path discovery (by a very little amount) +NeverZero prevents this behaviour. If a counter wraps, it jumps over the value +0 directly to a 1. This improves path discovery (by a very little amount) at a very little 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, however for llvm_mode this is optional if the llvm version is below 9 - as there is a perfomance bug that is only fixed in version 9 and onwards. diff --git a/llvm_mode/README.whitelist.md b/llvm_mode/README.whitelist.md index 5aededba..6a5770c2 100644 --- a/llvm_mode/README.whitelist.md +++ b/llvm_mode/README.whitelist.md @@ -34,8 +34,8 @@ the compiler. The environment variable must point to a file containing all the filenames that should be instrumented. For matching, the filename that is being compiled -must end in the filename contained in this whitelist (to avoid breaking the -matching when absolute paths are used during compilation). +must end in the filename entry contained in this whitelist (to avoid breaking +the matching when absolute paths are used during compilation). For example if your source tree looks like this: @@ -47,14 +47,14 @@ project/feature_b/b1.cpp project/feature_b/b2.cpp ``` -And you only want to test feature_a, then create a whitelist file containing: +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: +However if the whitelist file contains only this, it works as well: ``` a1.cpp @@ -62,7 +62,7 @@ a2.cpp ``` but it might lead to files being unwantedly instrumented if the same filename -exists somewhere else in the project. +exists somewhere else in the project directories. The created whitelist file is then set to AFL_INST_WHITELIST when you compile your program. For each file that didn't match the whitelist, the compiler will @@ -72,4 +72,4 @@ didn't intend to instrument that file, then you can safely ignore that warning. For old LLVM versions this feature might require to be compiled with debug information (-g), however at least from llvm version 6.0 onwards this is not required anymore (and might hurt performance and crash detection, so better not -use -g) +use -g). diff --git a/qemu_mode/README.md b/qemu_mode/README.md index b994e4c6..5406371e 100644 --- a/qemu_mode/README.md +++ b/qemu_mode/README.md @@ -46,21 +46,21 @@ directory. ## 3) Bonus feature #1: deferred initialization -As for LLVM mode (referes to its README for mode details) QEMU mode support +As for LLVM mode (refer to its README for mode details) QEMU mode supports the deferred initialization. This can be enabled setting the environment variable AFL_ENTRYPOINT which allows to move the forkserver to a different part, e.g. just before the file is -opened (e.g. way after command line parsing and config file loading, etc) +opened (e.g. way after command line parsing and config file loading, etc.) which can be a huge speed improvement. Note that the specified address must be an address of a basic block. ## 4) Bonus feature #2: persistent mode -QEMU mode support also persistent mode for x86 and x86_64 targets. +QEMU mode supports also persistent mode for x86 and x86_64 targets. The environment variable to enable it is AFL_QEMU_PERSISTENT_ADDR=`start addr`. In this variable you must specify the address of the function that -have to be the body of the persistent loop. +has to be the body of the persistent loop. The code in this function must be stateless like in the LLVM persistent mode. The return address on stack is patched like in WinAFL in order to repeat the execution of such function. @@ -70,18 +70,18 @@ With this variable assigned, instead of patching the return address, the specified instruction is transformed to a jump towards `start addr`. Note that the format of the addresses in such variables is hex. -Note that the base address of PIE binaries in QEMU user is 0x4000000000. +Note that the base address of PIE binaries in QEMU user mode is 0x4000000000. With the env variable AFL_QEMU_PERSISTENT_GPR you can tell QEMU to save the -original value of general purpose registers and restore them ech cycle. -This allow to use as persistent loop functions that make use of arguments on +original value of general purpose registers and restore them in each cycle. +This allows to use as persistent loop functions that make use of arguments on x86_64. With AFL_QEMU_PERSISTENT_RETADDR_OFFSET you can specify the offset from the -stack pointer in which QEME can find the return address when `start addr` is +stack pointer in which QEMU can find the return address when `start addr` is hitted. -Use this mode with caution, problably will not work at first shot. +Use this mode with caution, probably it will not work at the first shot. ## 5) Bonus feature #3: CompareCoverage @@ -103,7 +103,7 @@ Highly recommended. AFL++ QEMU can use Wine to fuzz WIn32 PE binaries. Use the -W flag of afl-fuzz. -Note that some binaries require user interaction with GUI and must be patched. +Note that some binaries require user interaction with the GUI and must be patched. For examples look [here](https://github.com/andreafioraldi/WineAFLplusplusDEMO). @@ -176,6 +176,6 @@ The best implementation is this one: https://github.com/vanhauser-thc/afl-dyninst The issue however is Dyninst which is not rewriting the binaries so that -they run stable. a lot of crashes happen, especially in C++ programs that +they run stable. A lot of crashes happen, especially in C++ programs that use throw/catch. Try it first, and if it works for you be happy as it is 2-3x as fast as qemu_mode. |