diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Changelog.md | 3 | ||||
| -rw-r--r-- | docs/FAQ.md | 21 | ||||
| -rw-r--r-- | docs/INSTALL.md | 45 | ||||
| -rw-r--r-- | docs/env_variables.md | 21 | ||||
| -rw-r--r-- | docs/features.md | 65 | ||||
| -rw-r--r-- | docs/fuzzing_binary-only_targets.md | 23 | ||||
| -rw-r--r-- | docs/fuzzing_in_depth.md | 137 | ||||
| -rw-r--r-- | docs/ideas.md | 8 | ||||
| -rw-r--r-- | docs/important_changes.md | 13 | ||||
| -rw-r--r-- | docs/resources/grafana-afl++.json | 4 | ||||
| -rw-r--r-- | docs/resources/screenshot.png | bin | 117199 -> 144422 bytes | |||
| -rw-r--r-- | docs/tutorials.md | 5 |
12 files changed, 233 insertions, 112 deletions
diff --git a/docs/Changelog.md b/docs/Changelog.md index 1daa9a75..c4786bf3 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -14,6 +14,8 @@ sending a mail to <afl-users+subscribe@googlegroups.com>. e.g. "unique crashes" -> "saved crashes", "total paths" -> "corpus count", "current path" -> "current item". This might need changing custom scripting! + - Nyx mode (full system emulation with snapshot capability) has been + added - thanks to @schumilo and @eqv! - new binary-only fuzzing mode: coresight_mode for aarch64 CPUs :) thanks to RICSecLab submitting! - if instrumented libaries are dlopen()'ed after the forkserver you @@ -57,6 +59,7 @@ sending a mail to <afl-users+subscribe@googlegroups.com>. - added AFL_USE_TSAN thread sanitizer support - llvm and LTO mode modified to work with new llvm 14-dev (again. again.) - fix for AFL_REAL_LD + - more -z defs filtering - make -v without options work - added the very good grammar mutator "GramaTron" to the custom_mutators diff --git a/docs/FAQ.md b/docs/FAQ.md index f1cffe00..3d3dce20 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -180,6 +180,27 @@ If you find an interesting or important question missing, submit it via [best_practices.md#improving-stability](best_practices.md#improving-stability). </p></details> +<details> + <summary id="what-are-power-schedules">What are power schedules?</summary><p> + + Not every item in our queue/corpus is the same, some are more interesting, + others provide little value. + A power schedule measures how "interesting" a value is, and depending on + the calculated value spends more or less time mutating it. + + AFL++ comes with several power schedules, initially ported from [AFLFast](https://github.com/mboehme/aflfast) + however modified to be more effective and several more modes added. + + The most effective modes are '-p fast` (default) and `-p explore`. + + If you fuzz with several parallel afl-fuzz instances, then it is beneficial + to assign a different schedule to each instance, however the majority should + be `fast` and `explore`. + + It does not make sense to explain the details of the calculation and + reasoning behind all of the schedules. If you are interested, read the source + code and the AFLFast paper. + ## Troubleshooting <details> diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 906d3f8e..efec0d8b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -33,10 +33,10 @@ sudo make install It is recommended to install the newest available gcc, clang and llvm-dev possible in your distribution! -Note that "make distrib" also builds instrumentation, QEMU mode, unicorn_mode -and more. If you just want plain AFL++, then do "make all". However, compiling -and using at least instrumentation is highly recommended for much better results -- hence in this case choose: +Note that "make distrib" also builds FRIDA mode, QEMU mode, unicorn_mode +and more. If you just want plain AFL++, then do "make all". If you want +some assisting tooling compiled but are not interested in binary-only targets +then instead choose: ```shell make source-only @@ -44,11 +44,11 @@ make source-only These build targets exist: -* all: just the main AFL++ binaries -* binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, - libdislocator, libtokencap -* source-only: everything for source code fuzzing: instrumentation, - libdislocator, libtokencap +* all: the main afl++ binaries and llvm/gcc instrumentation +* binary-only: everything for binary-only fuzzing: frida_mode, nyx_mode, + qemu_mode, frida_mode, unicorn_mode, coresight_mode, libdislocator, libtokencap +* source-only: everything for source code fuzzing: nyx_mode, libdislocator, + libtokencap * distrib: everything (for both binary-only and source code fuzzing) * man: creates simple man pages from the help option of the programs * install: installs everything you have compiled with the build options above @@ -86,32 +86,35 @@ e.g.: `make ASAN_BUILD=1` ## MacOS X on x86 and arm64 (M1) -MacOS X should work, but there are some gotchas due to the idiosyncrasies of the -platform. On top of this, we have limited release testing capabilities and -depend mostly on user feedback. +MacOS has some gotchas due to the idiosyncrasies of the platform. To build AFL, install llvm (and perhaps gcc) from brew and follow the general instructions for Linux. If possible, avoid Xcode at all cost. -`brew install wget git make cmake llvm gdb` +```shell +brew install wget git make cmake llvm gdb coreutils +``` Be sure to setup `PATH` to point to the correct clang binaries and use the -freshly installed clang, clang++ and gmake, e.g.: +freshly installed clang, clang++, gmake and coreutils, e.g.: -``` -export PATH="/usr/local/Cellar/llvm/12.0.1/bin/:$PATH" +```shell +export +PATH="/usr/local/Cellar/llvm/13.0.0_2/bin/:/usr/local/opt/coreutils/libexec/gnubin:/usr/local/bin:$PATH" export CC=clang export CXX=clang++ gmake cd frida_mode gmake cd .. -gmake install +sudo gmake install ``` `afl-gcc` will fail unless you have GCC installed, but that is using outdated -instrumentation anyway. You don't want that. Note that `afl-clang-lto`, -`afl-gcc-fast` and `qemu_mode` are not working on MacOS. +instrumentation anyway. `afl-clang` might fail too depending on your PATH +setup. But you don't want neither, you want `afl-clang-fast` anyway :) +Note that `afl-clang-lto`, `afl-gcc-fast` and `qemu_mode` are not working on +MacOS. The crash reporting daemon that comes by default with MacOS X will cause problems with fuzzing. You need to turn it off: @@ -133,7 +136,7 @@ and definitely don't look POSIX-compliant. This means two things: User emulation mode of QEMU does not appear to be supported on MacOS X, so black-box instrumentation mode (`-Q`) will not work. However, Frida mode (`-O`) -should work on x86 and arm64 MacOS boxes. +works on both x86 and arm64 MacOS boxes. MacOS X supports SYSV shared memory used by AFL's instrumentation, but the default settings aren't usable with AFL++. The default settings on 10.14 seem to @@ -169,4 +172,4 @@ sysctl kern.sysv.shmall=98304 See [http://www.spy-hill.com/help/apple/SharedMemory.html](http://www.spy-hill.com/help/apple/SharedMemory.html) -for documentation for these settings and how to make them permanent. \ No newline at end of file +for documentation for these settings and how to make them permanent. diff --git a/docs/env_variables.md b/docs/env_variables.md index dc79bf9e..76a64bd2 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -105,7 +105,8 @@ fairly broad use of environment variables instead: within your program at a certain point (such as at the end of an `__AFL_LOOP()`), you can run the macro `__AFL_LEAK_CHECK();` which will cause an abort if any memory is leaked (you can combine this with the - `LSAN_OPTIONS=...` suppression option to suppress some known leaks). + `__AFL_LSAN_OFF();` and `__AFL_LSAN_ON();` macros to avoid checking for + memory leaks from memory allocated between these two calls. - `AFL_USE_MSAN=1` - activates the memory sanitizer (uninitialized memory) - `AFL_USE_TSAN=1` - activates the thread sanitizer to find thread race conditions @@ -283,12 +284,24 @@ mode. TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all ``` - - GCC_PLUGIN mode only: Setting `AFL_GCC_INSTRUMENT_FILE` with a filename will - only instrument those files that match the names listed in this file (one - filename per line). See + - GCC_PLUGIN mode only: Setting `AFL_GCC_INSTRUMENT_FILE` or + `AFL_GCC_ALLOWLIST` with a filename will only instrument those files + that match the names listed in this file (one filename per line). + + Setting `AFL_GCC_DENYLIST` or `AFL_GCC_BLOCKLIST` + with a file name and/or function will only skip those files that match + the names listed in the specified file. See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) for more information. + Setting `AFL_GCC_OUT_OF_LINE=1` will instruct afl-gcc-fast to instrument the + code with calls to an injected subroutine instead of the much more efficient + inline instrumentation. + + Setting `AFL_GCC_SKIP_NEVERZERO=1` will not implement the skip zero test. + If the target performs only a few loops, then this will give a small + performance boost. + ## 4) Settings for afl-fuzz The main fuzzer binary accepts several options that disable a couple of sanity diff --git a/docs/features.md b/docs/features.md index 431d9eb1..628f9383 100644 --- a/docs/features.md +++ b/docs/features.md @@ -4,20 +4,56 @@ AFL++ supports llvm from 3.8 up to version 12, very fast binary fuzzing with QEMU 5.1 with laf-intel and redqueen, FRIDA mode, unicorn mode, gcc plugin, full *BSD, Mac OS, Solaris and Android support and much, much, much more. -| Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | FRIDA mode(9) | QEMU mode(10) |unicorn_mode(10) |coresight_mode(11)| -| -------------------------|:-------:|:---------:|:----------:|:----------------:|:----------------:|:----------------:|:----------------:| -| Threadsafe counters | | x(3) | | | | | | -| NeverZero | x86[_64]| x(1) | x | x | x | x | | -| Persistent Mode | | x | x | x86[_64]/arm64 | x86[_64]/arm[64] | x | | -| LAF-Intel / CompCov | | x | | | x86[_64]/arm[64] | x86[_64]/arm[64] | | -| CmpLog | | x | | x86[_64]/arm64 | x86[_64]/arm[64] | | | -| Selective Instrumentation| | x | x | x | x | | | -| Non-Colliding Coverage | | x(4) | | | (x)(5) | | | -| Ngram prev_loc Coverage | | x(6) | | | | | | -| Context Coverage | | x(6) | | | | | | -| Auto Dictionary | | x(7) | | | | | | -| Snapshot LKM Support | | (x)(8) | (x)(8) | | (x)(5) | | | -| Shared Memory Test cases | | x | x | x86[_64]/arm64 | x | x | | +| Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | FRIDA mode(9) | QEMU mode(10) |unicorn_mode(10) |nyx_mode(12)|coresight_mode(11)| +| ------------------------------|:-------:|:---------:|:----------:|:----------------:|:----------------:|:----------------:|:----------:|:----------------:| +| Threadsafe counters [A] | | x(3) | | | | | x | | +| NeverZero [B] | x86[_64]| x(1) | x | x | x | x | | | +| Persistent Mode [C] | | x | x | x86[_64]/arm64 | x86[_64]/arm[64] | x | | | +| LAF-Intel / CompCov [D] | | x | | | x86[_64]/arm[64] | x86[_64]/arm[64] | x86[_64] | | +| CmpLog [E] | | x | | x86[_64]/arm64 | x86[_64]/arm[64] | | | | +| Selective Instrumentation [F] | | x | x | x | x | | | | +| Non-Colliding Coverage [G] | | x(4) | | | (x)(5) | | | | +| Ngram prev_loc Coverage [H] | | x(6) | | | | | | | +| Context Coverage [I] | | x(6) | | | | | | | +| Auto Dictionary [J] | | x(7) | | | | | | | +| Snapshot Support (K) | | (x)(8) | (x)(8) | | (x)(5) | | x | | +| Shared Memory Test cases [L] | | x | x | x86[_64]/arm64 | x | x | x | | + +A. Default is not thread-safe coverage counter updates for better performance, + see [instrumentation/README.llvm.md](../instrumentation/README.llvm.md) +B. On wrapping coverage counters (255 + 1) skip the 0 value and jump to 1 + instead. This has shown to give better coverage data and is the default; + see [instrumentation/README.llvm.md](../instrumentation/README.llvm.md) +C. Instead of forking, reiterate the fuzz target function in a loop (like + `LLVMFuzzerTestOneInput`. Great speed increase but only work with target + functions that does not keep state, leak memory or exit; + see [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md) +D. Split any non-8-bit comparison to 8 bit comparison; + see [instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md) +E. CmpLog is our enhanced [Redqueen](https://www.ndss-symposium.org/ndss-paper/redqueen-fuzzing-with-input-to-state-correspondence/) + implementation, see see [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md) +F. Similar and compatible to clang 13+ sancov sanitize-coverage-allow/deny but + for all llvm versions and all our compile modes, only instrument what should + be instrumented, for more speed, directed fuzzing and less instability; + see [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) +G. Vanilla AFL uses coverage where edges could collide to the same coverage + bytes the larger the target is. Our default instrumentation in LTO and + afl-clang-fast (PCGUARD) uses non-colliding coverage that also makes it + faster. Vanilla AFL style is available with `AFL_LLVM_INSTRUMENT=AFL`; + see [instrumentation/README.llvm.md](../instrumentation/README.llvm.md) +H.+I. Alternative coverage based on previous edges (NGRAM) or depending on the + caller (CTX), based on + [https://www.usenix.org/system/files/raid2019-wang-jinghan.pdf](https://www.usenix.org/system/files/raid2019-wang-jinghan.pdf); + see [instrumentation/README.llvm.md](../instrumentation/README.llvm.md) +J. An LTO feature that creates a fuzzing dictionary based on comparisons found + during compilation/instrumentation. Automatic feature :) + See [instrumentation/README.lto.md](../instrumentation/README.lto.md) +K. The snapshot feature requires a kernel module that was a lot of work to get + right and maintained so it is no longer supported. We have + [nyx_mode](../nyx_mode/README.md) instead. +L. Faster fuzzing and less kernel syscall overhead by in-memory fuzz testcase + delivery, see + [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md) 1. default for LLVM >= 9.0, environment variable for older version due an efficiency bug in previous llvm versions @@ -34,6 +70,7 @@ QEMU 5.1 with laf-intel and redqueen, FRIDA mode, unicorn mode, gcc plugin, full 10. QEMU/Unicorn is only supported on Linux 11. Coresight mode is only available on AARCH64 Linux with a CPU with Coresight extension +12. Nyx mode is only supported on Linux and currently restricted to x86_x64 Among others, the following features and patches have been integrated: diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md index 5434a22c..855d7756 100644 --- a/docs/fuzzing_binary-only_targets.md +++ b/docs/fuzzing_binary-only_targets.md @@ -12,11 +12,10 @@ fuzzed with AFL++. ## TL;DR: -QEMU mode in persistent mode is the fastest - if the stability is high enough. -Otherwise, try RetroWrite, Dyninst, and if these fail, too, then try standard -QEMU mode with `AFL_ENTRYPOINT` to where you need it. - -If your target is a library, then use FRIDA mode. +FRIDA mode and QEMU mode in persistent mode are the fastest - if persistent mode +is possible and the stability is high enough. +Otherwise, try Zafl, RetroWrite, Dyninst, and if these fail, too, then try +standard FRIDA/QEMU mode with `AFL_ENTRYPOINT` to where you need it. If your target is non-linux, then use unicorn_mode. @@ -92,7 +91,7 @@ For more information, see ### FRIDA mode In FRIDA mode, you can fuzz binary-only targets as easily as with QEMU mode. -FRIDA mode is sometimes faster and sometimes slower than QEMU mode. It is also +FRIDA mode is most of the times slightly faster than QEMU mode. It is also newer, lacks COMPCOV, and has the advantage that it works on MacOS (both intel and M1). @@ -100,7 +99,7 @@ To build FRIDA mode: ```shell cd frida_mode -make +gmake ``` For additional instructions and caveats, see @@ -126,6 +125,16 @@ to check out our sister project libafl which supports Frida, too: [https://github.com/AFLplusplus/LibAFL](https://github.com/AFLplusplus/LibAFL). Working examples already exist :-) +### Nyx mode + +Nyx is a full system emulation fuzzing environment with snapshot support that +is built upon KVM and QEMU. +It is only available on Linux and currently restricted to x86_x64. + +For binary-only fuzzing a special 5.10 kernel is required. + +See [nyx_mode/README.md](../nyx_mode/README.md) + ### Unicorn Unicorn is a fork of QEMU. The instrumentation is, therefore, very similar. In diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index b280ca0a..446c4466 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -55,7 +55,7 @@ tasks, fuzzing may put a strain on your hardware and on the OS. In particular: ### a) Selecting the best AFL++ compiler for instrumenting the target AFL++ comes with a central compiler `afl-cc` that incorporates various different -kinds of compiler targets and and instrumentation options. The following +kinds of compiler targets and instrumentation options. The following evaluation flow will help you to select the best possible. It is highly recommended to have the newest llvm version possible installed, @@ -101,7 +101,7 @@ You can select the mode for the afl-cc compiler by one of the following methods: afl-clang-fast, afl-clang-fast++, afl-clang-lto, afl-clang-lto++, afl-gcc-fast, afl-g++-fast (recommended!). * Using the environment variable `AFL_CC_COMPILER` with `MODE`. -* Passing --afl-MODE command line options to the compiler via +* Passing --afl-`MODE` command line options to the compiler via `CFLAGS`/`CXXFLAGS`/`CPPFLAGS`. `MODE` can be one of the following: @@ -141,20 +141,42 @@ options are available: [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md). If you use LTO, LLVM, or GCC_PLUGIN mode -(afl-clang-fast/afl-clang-lto/afl-gcc-fast), you have the option to selectively -only instrument parts of the target that you are interested in: - -* To instrument only those parts of the target that you are interested in, - create a file with all the filenames of the source code that should be - instrumented. For afl-clang-lto and afl-gcc-fast - or afl-clang-fast if a mode - other than DEFAULT/PCGUARD is used or you have llvm > 10.0.0 - just put one - filename or function per line (no directory information necessary for - filenames), and either set `export AFL_LLVM_ALLOWLIST=allowlist.txt` **or** - `export AFL_LLVM_DENYLIST=denylist.txt` - depending on if you want per default - to instrument unless noted (DENYLIST) or not perform instrumentation unless - requested (ALLOWLIST). **NOTE:** During optimization functions might be - inlined and then would not match! See - [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md). +(afl-clang-fast/afl-clang-lto/afl-gcc-fast), you have the option to +selectively instrument _parts_ of the target that you are interested in. +For afl-clang-fast you have to use an llvm version newer than 10.0.0 or a mode +other than DEFAULT/PCGUARD. + +This step can be done either by explicitly including parts to be instrumented +or by explicitly excluding parts from instrumentation. + +* To instrument _only specified parts_ + create a file (eg `allowlist.txt`) with all the filenames and/or functions of + the source code that should be instrumented and then: + + 1. just put one filename or function (prefixing with `fun: `) per line (no + directory information necessary for filenames) in the file `allowlist.txt`. + Example: +``` +foo.cpp # will match foo/foo.cpp, bar/foo.cpp, barfoo.cpp etc. +fun: foo_func # will match the function foo_func +``` + + 2. set `export AFL_LLVM_ALLOWLIST=allowlist.txt` to enable selective positive + instrumentation. + +* Similarly to _exclude_ specified parts from instrumentation + create a file (eg `denylist.txt`) with all the filenames of the source code + that should be skipped during instrumentation and then + + 1. same as above just put one filename or function per line in the file + `denylist.txt` + + 2. set `export AFL_LLVM_DENYLIST=denylist.txt` to enable selective negative + instrumentation. + +**NOTE:** During optimization functions might be +inlined and then would not match the list! See +[instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md). There are many more options and modes available, however, these are most of the time less effective. See: @@ -173,26 +195,26 @@ allows you to find bugs that would not necessarily result in a crash. Note that sanitizers have a huge impact on CPU (= less executions per second) and RAM usage. Also, you should only run one afl-fuzz instance per sanitizer -type. This is enough because a use-after-free bug will be picked up, e.g., by -ASAN (address sanitizer) anyway when syncing to other fuzzing instances, so not -all fuzzing instances need to be instrumented with ASAN. +type. This is enough because e.g. a use-after-free bug will be picked up by +ASAN (address sanitizer) anyway after syncing test cases from other fuzzing +instances, so running more than one address sanitized target would be a waste. The following sanitizers have built-in support in AFL++: * ASAN = Address SANitizer, finds memory corruption vulnerabilities like use-after-free, NULL pointer dereference, buffer overruns, etc. Enabled with `export AFL_USE_ASAN=1` before compiling. -* MSAN = Memory SANitizer, finds read access to uninitialized memory, e.g., a +* MSAN = Memory SANitizer, finds read accesses to uninitialized memory, e.g., a local variable that is defined and read before it is even set. Enabled with `export AFL_USE_MSAN=1` before compiling. * UBSAN = Undefined Behavior SANitizer, finds instances where - by the C and C++ standards - undefined behavior happens, e.g., adding two signed integers - together where the result is larger than a signed integer can hold. Enabled + where the result is larger than what a signed integer can hold. Enabled with `export AFL_USE_UBSAN=1` before compiling. * CFISAN = Control Flow Integrity SANitizer, finds instances where the control flow is found to be illegal. Originally this was rather to prevent return - oriented programming exploit chains from functioning. In fuzzing, this is - mostly reduced to detecting type confusion vulnerabilities - which is, + oriented programming (ROP) exploit chains from functioning. In fuzzing, this + is mostly reduced to detecting type confusion vulnerabilities - which is, however, one of the most important and dangerous C++ memory corruption classes! Enabled with `export AFL_USE_CFISAN=1` before compiling. * TSAN = Thread SANitizer, finds thread race conditions. Enabled with `export @@ -201,7 +223,10 @@ The following sanitizers have built-in support in AFL++: security issue, but for developers this can be very valuable. Note that unlike the other sanitizers above this needs `__AFL_LEAK_CHECK();` added to all areas of the target source code where you find a leak check necessary! Enabled with - `export AFL_USE_LSAN=1` before compiling. + `export AFL_USE_LSAN=1` before compiling. To ignore the memory-leaking check + for certain allocations, `__AFL_LSAN_OFF();` can be used before memory is + allocated, and `__AFL_LSAN_ON();` afterwards. Memory allocated between these + two macros will not be checked for memory leaks. It is possible to further modify the behavior of the sanitizers at run-time by setting `ASAN_OPTIONS=...`, `LSAN_OPTIONS` etc. - the available parameters can @@ -261,7 +286,8 @@ Then build the target. (Usually with `make`.) 3. In case the configure/build system complains about AFL++'s compiler and aborts, then set `export AFL_NOOPT=1` which will then just behave like the - real compiler. This option has to be unset again before building the target! + real compiler and run the configure step separately. + For building the target afterwards this option has to be unset again! #### configure @@ -334,7 +360,7 @@ afl-clang-fast++ -fsanitize=fuzzer -o harness harness.cpp targetlib.a ``` You can even use advanced libfuzzer features like `FuzzedDataProvider`, -`LLVMFuzzerMutate()` etc. and they will work! +`LLVMFuzzerInitialize()` etc. and they will work! The generated binary is fuzzed with afl-fuzz like any other fuzz target. @@ -373,22 +399,23 @@ produce a new path/coverage in the target: 1. Put all files from [step a](#a-collecting-inputs) into one directory, e.g., INPUTS. 2. Run afl-cmin: - * If the target program is to be called by fuzzing as `bin/target -d - INPUTFILE`, set the INPUTFILE argument that the target program would read - from as `@@`: + * If the target program is to be called by fuzzing as `bin/target + INPUTFILE`, replace the INPUTFILE argument that the target program would read + from with `@@`: ``` - afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -d @@ + afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -someopt @@ ``` - * If the target reads from stdin instead, just omit the `@@` as this is the - default: + * If the target reads from stdin (standard input) instead, just omit the `@@` + as this is the default: ``` - afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -d + afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -someopt ``` -This step is highly recommended! +This step is highly recommended, because afterwards the testcase corpus is not +bloated with duplicates anymore, which would slow down the fuzzing progress! ### c) Minimizing all corpus files @@ -400,7 +427,7 @@ however, it is a long process as this has to be done for every file: mkdir input cd INPUTS_UNIQUE for i in *; do - afl-tmin -i "$i" -o "../input/$i" -- bin/target -d @@ + afl-tmin -i "$i" -o "../input/$i" -- bin/target -someopt @@ done ``` @@ -421,7 +448,7 @@ In this final step, fuzz the target. There are not that many important options to run the target - unless you want to use many CPU cores/threads for the fuzzing, which will make the fuzzing much more useful. -If you just use one CPU for fuzzing, then you are fuzzing just for fun and not +If you just use one instance for fuzzing, then you are fuzzing just for fun and not seriously :-) ### a) Running afl-fuzz @@ -449,13 +476,13 @@ hence all you need is to specify the seed input directory with the result of step [2a) Collecting inputs](#a-collecting-inputs): ``` -afl-fuzz -i input -o output -- bin/target -d @@ +afl-fuzz -i input -o output -- bin/target -someopt @@ ``` Note that the directory specified with `-o` will be created if it does not exist. -It can be valuable to run afl-fuzz in a screen or tmux shell so you can log off, +It can be valuable to run afl-fuzz in a `screen` or `tmux` shell so you can log off, or afl-fuzz is not aborted if you are running it in a remote ssh session where the connection fails in between. Only do that though once you have verified that your fuzzing setup works! Run it like `screen -dmS afl-main -- afl-fuzz -M @@ -469,27 +496,32 @@ If you need to stop and re-start the fuzzing, use the same command line options mode!) and switch the input directory with a dash (`-`): ``` -afl-fuzz -i - -o output -- bin/target -d @@ +afl-fuzz -i - -o output -- bin/target -someopt @@ ``` Adding a dictionary is helpful. See the directory [dictionaries/](../dictionaries/) if something is already included for your data format, and tell afl-fuzz to load that dictionary by adding `-x -dictionaries/FORMAT.dict`. With afl-clang-lto, you have an autodictionary -generation for which you need to do nothing except to use afl-clang-lto as the -compiler. You also have the option to generate a dictionary yourself, see -[utils/libtokencap/README.md](../utils/libtokencap/README.md). +dictionaries/FORMAT.dict`. +With `afl-clang-lto`, you have an autodictionary generation for which you need +to do nothing except to use afl-clang-lto as the compiler. +With `afl-clang-fast` you can set +`AFL_LLVM_DICT2FILE=/full/path/to/new/file.dic` to automatically generate a +dictionary during target compilation. +You also have the option to generate a dictionary yourself during an independant +run of the target, see [utils/libtokencap/README.md](../utils/libtokencap/README.md). +Finally you can also write a dictionary file manually, of course. afl-fuzz has a variety of options that help to workaround target quirks like -specific locations for the input file (`-f`), performing deterministic fuzzing -(`-D`) and many more. Check out `afl-fuzz -h`. +very specific locations for the input file (`-f`), performing deterministic +fuzzing (`-D`) and many more. Check out `afl-fuzz -h`. We highly recommend that you set a memory limit for running the target with `-m` which defines the maximum memory in MB. This prevents a potential out-of-memory problem for your system plus helps you detect missing `malloc()` failure handling in the target. Play around with various `-m` values until you find one that safely works for all your input seeds (if you have good ones and then -double or quadruple that. +double or quadruple that). By default, afl-fuzz never stops fuzzing. To terminate AFL++, press Control-C or send a signal SIGINT. You can limit the number of executions or approximate @@ -558,7 +590,8 @@ All other secondaries should be used like this: * a quarter to a third with the MOpt mutator enabled: `-L 0` * run with a different power schedule, recommended are: `fast (default), explore, coe, lin, quad, exploit and rare` which you can set - with, e.g., `-p explore` + with the `-p` option, e.g., `-p explore`. See the [FAQ](FAQ.md#what-are-power-schedules) + for details. * a few instances should use the old queue cycling with `-Z` Also, it is recommended to set `export AFL_IMPORT_FIRST=1` to load test cases @@ -601,7 +634,7 @@ Now there are three strategies on how you can sync between the servers: * regularly (~4h): this ensures that all fuzzing campaigns on the servers "see" the same thing. It is like fuzzing on a huge server. * in intervals of 1/10th of the overall expected runtime of the fuzzing you - sync. This tries a bit to combine both. have some individuality of the paths + sync. This tries a bit to combine both. Have some individuality of the paths each campaign on a server explores, on the other hand if one gets stuck where another found progress this is handed over making it unstuck. @@ -844,8 +877,8 @@ normal fuzzing campaigns as these are much shorter runnings. 1. Always: * LTO has a much longer compile time which is diametrical to short fuzzing - hence use afl-clang-fast instead. - * If you compile with CMPLOG, then you can save fuzzing time and reuse that - compiled target for both the `-c` option and the main fuzz target. This + * If you compile with CMPLOG, then you can save compilation time and reuse that + compiled target with the `-c` option and as the main fuzz target. This will impact the speed by ~15% though. * `AFL_FAST_CAL` - enables fast calibration, this halves the time the saturated corpus needs to be loaded. @@ -876,7 +909,7 @@ and ## The End -Check out the [FAQ](FAQ.md) if it maybe answers your question (that you might +Check out the [FAQ](FAQ.md). Maybe it answers your question (that you might not even have known you had ;-) ). This is basically all you need to know to professionally run fuzzing campaigns. @@ -885,4 +918,4 @@ covered. Note that there are also a lot of tools out there that help fuzzing with AFL++ (some might be deprecated or unsupported), see -[third_party_tools.md](third_party_tools.md). \ No newline at end of file +[third_party_tools.md](third_party_tools.md). diff --git a/docs/ideas.md b/docs/ideas.md index 52b07c26..e2360ab2 100644 --- a/docs/ideas.md +++ b/docs/ideas.md @@ -19,17 +19,17 @@ Mentor: vanhauser-thc ## WASM Instrumentation Currently, AFL++ can be used for source code fuzzing and traditional binaries. -With the rise of WASM as compile target, however, a novel way of instrumentation +With the rise of WASM as a compile target, however, a novel way of instrumentation needs to be implemented for binaries compiled to Webassembly. This can either be done by inserting instrumentation directly into the WASM AST, or by patching -feedback into a WASM VMs of choice, similar to the current Unicorn +feedback into a WASM VM of choice, similar to the current Unicorn instrumentation. Mentor: any ## Support other programming languages -Other programming languages also use llvm hence they could (easily?) supported +Other programming languages also use llvm hence they could be (easily?) supported for fuzzing, e.g., mono, swift, go, kotlin native, fortran, ... GCC also supports: Objective-C, Fortran, Ada, Go, and D (according to @@ -54,4 +54,4 @@ Mentor: domenukk ## Your idea! Finally, we are open to proposals! Create an issue at -https://github.com/AFLplusplus/AFLplusplus/issues and let's discuss :-) \ No newline at end of file +https://github.com/AFLplusplus/AFLplusplus/issues and let's discuss :-) diff --git a/docs/important_changes.md b/docs/important_changes.md index d5e67f75..040a086d 100644 --- a/docs/important_changes.md +++ b/docs/important_changes.md @@ -5,12 +5,13 @@ changes. ## From version 3.00 onwards -With AFL++ 3.13-3.20, we introduce FRIDA mode (`-O`) to have an alternative for -binary-only fuzzing. It is slower than QEMU mode but works on MacOS, Android, -iOS etc. +With AFL++ 4.00, we introduced the following changes from previous behaviors: + * the complete documentation was overhauled and restructured thanks to @llzmb! + * a new CMPLOG target format requires recompiling CMPLOG targets for use + with afl++ 4.0 onwards + * better naming for several fields in the UI With AFL++ 3.15, we introduced the following changes from previous behaviors: - * Also -M main mode does not do deterministic fuzzing by default anymore * afl-cmin and afl-showmap -Ci now descent into subdirectories like afl-fuzz -i does (but note that afl-cmin.bash does not) @@ -20,7 +21,7 @@ With AFL++ 3.14, we introduced the following changes from previous behaviors: however, does not) With AFL++ 3.10, we introduced the following changes from previous behaviors: - * The '+' feature of the '-t' option now means to auto-calculate the timeout + * The '+' feature of the '-t' option now means to auto-calculate the timeout with the value given being the maximum timeout. The original meaning of "skipping timeouts instead of abort" is now inherent to the -t option. @@ -55,4 +56,4 @@ behaviors and defaults: * -M mains do not perform trimming * examples/ got renamed to utils/ * libtokencap/ libdislocator/ and qdbi_mode/ were moved to utils/ - * afl-cmin/afl-cmin.bash now search first in PATH and last in AFL_PATH \ No newline at end of file + * afl-cmin/afl-cmin.bash now search first in PATH and last in AFL_PATH diff --git a/docs/resources/grafana-afl++.json b/docs/resources/grafana-afl++.json index 7afe89b1..910129a8 100644 --- a/docs/resources/grafana-afl++.json +++ b/docs/resources/grafana-afl++.json @@ -424,7 +424,7 @@ "steppedLine": false, "targets": [ { - "expr": "fuzzing{type=\"unique_crashes\"}", + "expr": "fuzzing{type=\"saved_crashes\"}", "interval": "", "legendFormat": "", "refId": "A" @@ -519,7 +519,7 @@ "steppedLine": false, "targets": [ { - "expr": "fuzzing{type=\"unique_hangs\"}", + "expr": "fuzzing{type=\"saved_hangs\"}", "interval": "", "legendFormat": "", "refId": "A" diff --git a/docs/resources/screenshot.png b/docs/resources/screenshot.png index 7b4dd7e4..75b88287 100644 --- a/docs/resources/screenshot.png +++ b/docs/resources/screenshot.png Binary files differdiff --git a/docs/tutorials.md b/docs/tutorials.md index ed8a7eec..0a44602d 100644 --- a/docs/tutorials.md +++ b/docs/tutorials.md @@ -9,6 +9,7 @@ Here are some good write-ups to show how to effectively use AFL++: * [https://securitylab.github.com/research/fuzzing-sockets-FTP](https://securitylab.github.com/research/fuzzing-sockets-FTP) * [https://securitylab.github.com/research/fuzzing-sockets-FreeRDP](https://securitylab.github.com/research/fuzzing-sockets-FreeRDP) * [https://securitylab.github.com/research/fuzzing-apache-1](https://securitylab.github.com/research/fuzzing-apache-1) +* [https://mmmds.pl/fuzzing-map-parser-part-1-teeworlds/](https://mmmds.pl/fuzzing-map-parser-part-1-teeworlds/) If you do not want to follow a tutorial but rather try an exercise type of training, then we can highly recommend the following: @@ -18,13 +19,13 @@ training, then we can highly recommend the following: If you are interested in fuzzing structured data (where you define what the structure is), these links have you covered: -* Superion for AFL++: - [https://github.com/adrian-rt/superion-mutator](https://github.com/adrian-rt/superion-mutator) * libprotobuf for AFL++: [https://github.com/P1umer/AFLplusplus-protobuf-mutator](https://github.com/P1umer/AFLplusplus-protobuf-mutator) * libprotobuf raw: [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator) * libprotobuf for old AFL++ API: [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator) +* Superion for AFL++: + [https://github.com/adrian-rt/superion-mutator](https://github.com/adrian-rt/superion-mutator) If you find other good ones, please send them to us :-) \ No newline at end of file |
