diff options
Diffstat (limited to 'qemu_mode/README.md')
| -rw-r--r-- | qemu_mode/README.md | 77 |
1 files changed, 52 insertions, 25 deletions
diff --git a/qemu_mode/README.md b/qemu_mode/README.md index 3cf678e4..a14cbe64 100644 --- a/qemu_mode/README.md +++ b/qemu_mode/README.md @@ -1,6 +1,6 @@ # High-performance binary-only instrumentation for afl-fuzz - (See ../docs/README.md for the general instruction manual.) + (See ../README.md for the general instruction manual.) ## 1) Introduction @@ -14,12 +14,12 @@ The usual performance cost is 2-5x, which is considerably better than seen so far in experiments with tools such as DynamoRIO and PIN. The idea and much of the initial implementation comes from Andrew Griffiths. -The actual implementation on QEMU 3 (shipped with afl++) is from +The actual implementation on current QEMU (shipped as qemuafl) is from Andrea Fioraldi. Special thanks to abiondo that re-enabled TCG chaining. -## 2) How to use +## 2) How to use qemu_mode -The feature is implemented with a patch to QEMU 3.1.1. The simplest way +The feature is implemented with a patched QEMU. The simplest way to build it is to run ./build_qemu_support.sh. The script will download, configure, and compile the QEMU binary for you. @@ -58,7 +58,7 @@ directory. If you want to specify a different path for libraries (e.g. to run an arm64 binary on x86_64) use QEMU_LD_PREFIX. -## 3) Bonus feature #1: deferred initialization +## 3) Deferred initialization As for LLVM mode (refer to its README.md for mode details) QEMU mode supports the deferred initialization. @@ -68,7 +68,7 @@ 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.) which can be a huge speed improvement. -## 4) Bonus feature #2: persistent mode +## 4) Persistent mode AFL++'s QEMU mode now supports also persistent mode for x86, x86_64, arm and aarch64 targets. @@ -77,11 +77,40 @@ up - but worth the effort. Please see the extra documentation for it: [README.persistent.md](README.persistent.md) -## 5) Bonus feature #3: CompareCoverage +## 5) Snapshot mode + +As an extension to persistent mode, qemuafl can snapshot and restore the memory +state and brk(). Details are in the persistent mode readme. + +The env var that enables the ready to use snapshot mode is AFL_QEMU_SNAPSHOT and +takes a hex address as a value that is the snapshot entrypoint. + +Snapshot mode can work restoring all the writeable pages, that is typically slower than +fork() mode but, on the other hand, it can scale better with multicore. +If the AFL++ Snapshot kernel module is loaded, qemuafl will use it and, in this +case, the speed is better than fork() and also the scaling capabilities. + +## 6) Partial instrumentation + +You can tell QEMU to instrument only a part of the address space. + +Just set AFL_QEMU_INST_RANGES=A,B,C... + +The format of the items in the list is either a range of addresses like 0x123-0x321 +or a module name like module.so (that is matched in the mapped object filename). + +Alternatively you can tell QEMU to ignore part of an address space for instrumentation. + +Just set AFL_QEMU_EXCLUDE_RANGES=A,B,C... + +The format of the items on the list is the same as for AFL_QEMU_INST_RANGES, and excluding ranges +takes priority over any included ranges or AFL_INST_LIBS. + +## 7) CompareCoverage CompareCoverage is a sub-instrumentation with effects similar to laf-intel. -The option that enables QEMU CompareCoverage is AFL_COMPCOV_LEVEL. +The environment variable that enables QEMU CompareCoverage is AFL_COMPCOV_LEVEL. There is also ./libcompcov/ which implements CompareCoverage for *cmp functions (splitting memcmp, strncmp, etc. to make these conditions easier solvable by afl-fuzz). @@ -98,10 +127,10 @@ on the x86, x86_64, arm and aarch64 targets. Highly recommended. -## 6) CMPLOG mode +## 8) CMPLOG mode Another new feature is CMPLOG, which is based on the redqueen project. -Here all immidiates in CMP instructions are learned and put into a dynamic +Here all immediates in CMP instructions are learned and put into a dynamic dictionary and applied to all locations in the input that reached that CMP, trying to solve and pass it. This is a very effective feature and it is available for x86, x86_64, arm @@ -110,7 +139,7 @@ and aarch64. To enable it you must pass on the command line of afl-fuzz: -c /path/to/your/target -## 7) Bonus feature #4: Wine mode +## 9) Wine mode AFL++ QEMU can use Wine to fuzz WIn32 PE binaries. Use the -W flag of afl-fuzz. @@ -118,7 +147,7 @@ Note that some binaries require user interaction with the GUI and must be patche For examples look [here](https://github.com/andreafioraldi/WineAFLplusplusDEMO). -## 8) Notes on linking +## 10) Notes on linking The feature is supported only on Linux. Supporting BSD may amount to porting the changes made to linux-user/elfload.c and applying them to @@ -139,7 +168,7 @@ practice, this means two things: Setting AFL_INST_LIBS=1 can be used to circumvent the .text detection logic and instrument every basic block encountered. -## 9) Benchmarking +## 11) Benchmarking If you want to compare the performance of the QEMU instrumentation with that of afl-gcc compiled code against the same target, you need to build the @@ -154,10 +183,15 @@ Comparative measurements of execution speed or instrumentation coverage will be fairly meaningless if the optimization levels or instrumentation scopes don't match. -## 10) Gotchas, feedback, bugs +## 12) Other features + +With `AFL_QEMU_FORCE_DFL` you force QEMU to ignore the registered signal +handlers of the target. + +## 13) Gotchas, feedback, bugs If you need to fix up checksums or do other cleanup on mutated test cases, see -examples/custom_mutators/ for a viable solution. +utils/custom_mutators/ for a viable solution. Do not mix QEMU mode with ASAN, MSAN, or the likes; QEMU doesn't appreciate the "shadow VM" trick employed by the sanitizers and will probably just @@ -175,19 +209,12 @@ with -march=core2, can help. Beyond that, this is an early-stage mechanism, so fields reports are welcome. You can send them to <afl-users@googlegroups.com>. -## 11) Alternatives: static rewriting +## 14) Alternatives: static rewriting Statically rewriting binaries just once, instead of attempting to translate them at run time, can be a faster alternative. That said, static rewriting is fraught with peril, because it depends on being able to properly and fully model program control flow without actually executing each and every code path. -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 -use throw/catch. Try it first, and if it works for you be happy as it is -2-3x as fast as qemu_mode, however usually not as fast as QEMU persistent mode. - +Checkout the "Fuzzing binary-only targets" section in our main README.md and +the docs/binaryonly_fuzzing.md document for more information and hints. |