diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Changelog.md | 12 | ||||
| -rw-r--r-- | docs/FAQ.md | 124 | ||||
| -rw-r--r-- | docs/binaryonly_fuzzing.md | 19 | ||||
| -rw-r--r-- | docs/parallel_fuzzing.md | 14 | ||||
| -rw-r--r-- | docs/screenshot.png | bin | 0 -> 117199 bytes |
5 files changed, 165 insertions, 4 deletions
diff --git a/docs/Changelog.md b/docs/Changelog.md index a25cc43c..1e7a1c1d 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -10,18 +10,28 @@ sending a mail to <afl-users+subscribe@googlegroups.com>. ### Version ++2.66d (devel) + - Support for improved afl++ snapshot module: + https://github.com/AFLplusplus/AFL-Snapshot-LKM - afl-fuzz: + - added -F option to allow -M main fuzzers to sync to foreign fuzzers, + e.g. honggfuzz or libfuzzer - eliminated CPU affinity race condition for -S/-M runs + - expanded havoc mode added, on no cycle finds add extra splicing and + MOpt into the mix - llvm_mode: + - now supports llvm 12! - fixes for laf-intel float splitting (thanks to mark-griffin for reporting) - LTO: autodictionary mode is a default - LTO: instrim instrumentation disabled, only classic support used as it is always better - - added honggfuzz mangle as a custom mutator in custom_mutators/honggfuzz :) + - setting AFL_LLVM_LAF_SPLIT_FLOATS now activates + AFL_LLVM_LAF_SPLIT_COMPARES + - added honggfuzz mangle as a custom mutator in custom_mutators/honggfuzz - added afl-frida gum solution to examples/afl_frida (mostly imported from https://github.com/meme/hotwax/) - small fixes to afl-plot, afl-whatsup and man page creation + - new README, added FAQ ### Version ++2.66c (release) diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 00000000..e09385a8 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,124 @@ +# Frequently asked questions about afl++ + +## Contents + + 1. [How to improve the fuzzing speed?](#how-to-improve-the-fuzzing-speed) + 2. [What is an edge?](#what-is-an-edge) + 3. [Why is my stability below 100%?](#why-is-my-stability-below-100) + 4. [How can I improve the stability value](#how-can-i-improve-the-stability-value) + +If you find an interesting or important question missing, submit it via +[https://github.com/AFLplusplus/AFLplusplus/issues](https://github.com/AFLplusplus/AFLplusplus/issues) + +## How to improve the fuzzing speed + + 1. use [llvm_mode](docs/llvm_mode/README.md): afl-clang-lto (llvm >= 11) or afl-clang-fast (llvm >= 9 recommended) + 2. Use [persistent mode](llvm_mode/README.persistent_mode.md) (x2-x20 speed increase) + 3. Use the [afl++ snapshot module](https://github.com/AFLplusplus/AFL-Snapshot-LKM) (x2 speed increase) + 4. If you do not use shmem persistent mode, use `AFL_TMPDIR` to point the input file on a tempfs location, see [docs/env_variables.md](docs/env_variables.md) + 5. Improve kernel performance: modify `/etc/default/grub`, set `GRUB_CMDLINE_LINUX_DEFAULT="ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off spectre_v2=off stf_barrier=off"`; then `update-grub` and `reboot` (warning: makes the system more insecure) + 6. Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem + 7. Use your cores! [README.md:3.b) Using multiple cores/threads](../README.md#b-using-multiple-coresthreads) + +## What is an "edge" + +A program contains `functions`, `functions` contain the compiled machine code. +The compiled machine code in a `function` can be in a single or many `basic blocks`. +A `basic block` is the largest possible number of subsequent machine code +instructions that runs independent, meaning it does not split up to different +locations nor is it jumped into it from a different location: +``` +function() { + A: + some + code + B: + if (x) goto C; else goto D; + C: + some code + goto D + D: + some code + goto B + E: + return +} +``` +Every code block between two jump locations is a `basic block`. + +An `edge` is then the unique relationship between two `basic blocks` (from the +code example above): +``` + Block A + | + v + Block B <------+ + / \ | + v v | + Block C Block D --+ + \ + v + Block E +``` +Every line between two blocks is an `edge`. + +## Why is my stability below 100 + +Stability is measured by how many percent of the edges in the target are +"stable". Sending the same input again and again should take the exact same +path through the target every time. If that is the case, the stability is 100%. + +If however randomness happens, e.g. a thread reading from shared memory, +reaction to timing, etc. then in some of the re-executions with the same data +will result in the edge information being different accross runs. +Those edges that change are then flagged "unstable". + +The more "unstable" edges, the more difficult for afl++ to identify valid new +paths. + +A value above 90% is usually fine and a value above 80% is also still ok, and +even above 20% can still result in successful finds of bugs. +However, it is recommended that below 90% or 80% you should take measures to +improve the stability. + +## How can I improve the stability value + +Four steps are required to do this and requires quite some knowledge of +coding and/or disassembly and it is only effectively possible with +afl-clang-fast PCGUARD and afl-clang-lto LTO instrumentation! + + 1. First step: Identify which edge ID numbers are unstable + + run the target with `export AFL_DEBUG=1` for a few minutes then terminate. + The out/fuzzer_stats file will then show the edge IDs that were identified + as unstable. + + 2. Second step: Find the responsible function. + + a) For LTO instrumented binaries just disassemble or decompile the target + and look which edge is writing to that edge ID. Ghidra is a good tool + for this: [https://ghidra-sre.org/](https://ghidra-sre.org/) + + b) For PCGUARD instrumented binaries it is more difficult. Here you can + either modify the __sanitizer_cov_trace_pc_guard function in + llvm_mode/afl-llvm-rt.o.c to write a backtrace to a file if the ID in + __afl_area_ptr[*guard] is one of the unstable edge IDs. Then recompile + and reinstall llvm_mode and rebuild your target. Run the recompiled + target with afl-fuzz for a while and then check the file that you + wrote with the backtrace information. + Alternatively you can use `gdb` to hook __sanitizer_cov_trace_pc_guard_init + on start, check to which memory address the edge ID value is written + and set a write breakpoint to that address (`watch 0x.....`). + + 3. Third step: create a text file with the filenames + + Identify which source code files contain the functions that you need to + remove from instrumentation. + + Simply follow this document on how to do this: [llvm_mode/README.instrument_file.md](llvm_mode/README.instrument_file.md) + If PCGUARD is used, then you need to follow this guide: [http://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation](http://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation) + + 4. Fourth step: recompile the target + + Recompile, fuzz it, be happy :) + diff --git a/docs/binaryonly_fuzzing.md b/docs/binaryonly_fuzzing.md index 7c9be418..111147e2 100644 --- a/docs/binaryonly_fuzzing.md +++ b/docs/binaryonly_fuzzing.md @@ -8,12 +8,17 @@ The following is a description of how these binaries can be fuzzed with afl++ + ## TL;DR: qemu_mode in persistent mode is the fastest - if the stability is high enough. Otherwise try retrowrite, afl-dyninst and if these fail too then standard qemu_mode with AFL_ENTRYPOINT to where you need it. + If your a target is library use examples/afl_frida/. + + If your target is non-linux then use unicorn_mode/ + ## QEMU @@ -57,6 +62,20 @@ As it is included in afl++ this needs no URL. +## AFL FRIDA + + If you want to fuzz a binary-only shared library then you can fuzz it with + frida-gum via examples/afl_frida/, you will have to write a harness to + call the target function in the library, use afl-frida.c as a template. + + +## AFL UNTRACER + + If you want to fuzz a binary-only shared library then you can fuzz it with + examples/afl_untracer/, use afl-untracer.c as a template. + It is slower than AFL FRIDA (see above). + + ## DYNINST Dyninst is a binary instrumentation framework similar to Pintool and diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md index 271f8369..2ab1466c 100644 --- a/docs/parallel_fuzzing.md +++ b/docs/parallel_fuzzing.md @@ -99,7 +99,15 @@ example may be: This is not a concern if you use @@ without -f and let afl-fuzz come up with the file name. -## 3) Multi-system parallelization +## 3) Syncing with non-afl fuzzers or independant instances + +A -M main node can be told with the `-F other_fuzzer_queue_directory` option +to sync results from other fuzzers, e.g. libfuzzer or honggfuzz. + +Only the specified directory will by synced into afl, not subdirectories. +The specified directories do not need to exist yet at the start of afl. + +## 4) Multi-system parallelization The basic operating principle for multi-system parallelization is similar to the mechanism explained in section 2. The key difference is that you need to @@ -176,7 +184,7 @@ It is *not* advisable to skip the synchronization script and run the fuzzers directly on a network filesystem; unexpected latency and unkillable processes in I/O wait state can mess things up. -## 4) Remote monitoring and data collection +## 5) Remote monitoring and data collection You can use screen, nohup, tmux, or something equivalent to run remote instances of afl-fuzz. If you redirect the program's output to a file, it will @@ -200,7 +208,7 @@ Keep in mind that crashing inputs are *not* automatically propagated to the main instance, so you may still want to monitor for crashes fleet-wide from within your synchronization or health checking scripts (see afl-whatsup). -## 5) Asymmetric setups +## 6) Asymmetric setups It is perhaps worth noting that all of the following is permitted: diff --git a/docs/screenshot.png b/docs/screenshot.png new file mode 100644 index 00000000..7b4dd7e4 --- /dev/null +++ b/docs/screenshot.png Binary files differ |
