diff options
| -rw-r--r-- | README.md | 78 |
1 files changed, 38 insertions, 40 deletions
diff --git a/README.md b/README.md index 8982d76a..5fc16ff7 100644 --- a/README.md +++ b/README.md @@ -23,19 +23,6 @@ Note that although afl now has a Google afl repository [https://github.com/Google/afl](https://github.com/Google/afl), it is unlikely to receive any noteable enhancements: [https://twitter.com/Dor3s/status/1154737061787660288](https://twitter.com/Dor3s/status/1154737061787660288) -## Branches - - The following branches exist: - - * [master/trunk](https://github.com/AFLplusplus/AFLplusplus/) : stable state of afl++ - it is synced from dev from time to - time when we are satisfied with it's stability - * [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev) : development state of afl++ - bleeding edge and you might catch a - checkout which does not compile or has a bug. *We only accept PRs in dev!!* - * (any other) : experimental branches to work on specific features or testing - new functionality or changes. - - For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. - ## The enhancements compared to the original stock afl Many improvements were made over the official afl release - which did not @@ -57,9 +44,9 @@ * Custom mutator by a library (instead of Python) by kyakdan - * unicorn_mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk) + * Unicron mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk) - * laf-intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode + * LAF-Intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode * NeverZero patch for afl-gcc, llvm_mode, qemu_mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage @@ -69,11 +56,11 @@ * Radamsa mutator (enable with `-R` to add or `-RR` to run it exclusivly). - * qbdi_mode: fuzz android native libraries via QBDI framework + * QBDI mode to fuzz android native libraries via QBDI framework * The new CmpLog instrumentation for LLVM and QEMU inspired by [Redqueen](https://www.syssec.ruhr-uni-bochum.de/media/emma/veroeffentlichungen/2018/12/17/NDSS19-Redqueen.pdf) - * llvm_mode ngram coverage by Adrean Herrera [https://github.com/adrianherrera/afl-ngram-pass](https://github.com/adrianherrera/afl-ngram-pass) + * LLVM mode Ngram coverage by Adrian Herrera [https://github.com/adrianherrera/afl-ngram-pass](https://github.com/adrianherrera/afl-ngram-pass) A more thorough list is available in the PATCHES file. @@ -81,18 +68,18 @@ | ----------------------- |:-------:|:---------:|:----------:|:----------------:|:------------:| | NeverZero | x | x(1) | (2) | x | x | | Persistent mode | | x | x | x86[_64]/arm[64] | x | - | laf-intel / CompCov | | x | | x86[_64]/arm[64] | x86[_64]/arm | + | LAF-Intel / CompCov | | x | | x86[_64]/arm[64] | x86[_64]/arm | | CmpLog | | x | | x86[_64]/arm[64] | | | Whitelist | | x | x | (x)(3) | | - | non-colliding coverage | | x(4) | | (x)(5) | | + | Non-colliding coverage | | x(4) | | (x)(5) | | | InsTrim | | x | | | | - | ngram prev_loc coverage | | x(6) | | | | + | Ngram prev_loc coverage | | x(6) | | | | neverZero: - (1) only in LLVM >= 9.0 due to a bug in llvm in previous versions + (1) only in LLVM >= 9.0 due to a bug in LLVM in previous versions - (2) gcc creates non-performant code, hence it is disabled in gcc_plugin + (2) GCC creates non-performant code, hence it is disabled in gcc_plugin (3) partially via AFL_CODE_START/AFL_CODE_END @@ -113,6 +100,18 @@ See [docs/QuickStartGuide.md](docs/QuickStartGuide.md) if you don't have time to read this file. +## Branches + + The following branches exist: + + * [master/trunk](https://github.com/AFLplusplus/AFLplusplus/) : stable state of afl++ - it is synced from dev from time to + time when we are satisfied with it's stability + * [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev) : development state of afl++ - bleeding edge and you might catch a + checkout which does not compile or has a bug. *We only accept PRs in dev!!* + * (any other) : experimental branches to work on specific features or testing + new functionality or changes. + + For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. ## Google Summer of Code 2020 (and any other students and enthusiast developers) @@ -130,7 +129,7 @@ We have an idea list in [docs/ideas.md](docs/ideas.md) For everyone who wants to contribute (and send pull requests) please read [CONTRIBUTING.md](CONTRIBUTING.md) before your submit. -## 0) Building and installing afl++ +## Building and installing afl++ afl++ has many build options. The easiest is to build and install everything: @@ -191,7 +190,7 @@ $ sudo docker build -t aflplusplus . ``` -## 1) Challenges of guided fuzzing +## Challenges of guided fuzzing Fuzzing is one of the most powerful and proven strategies for identifying security issues in real-world software; it is responsible for the vast @@ -218,7 +217,7 @@ to suffer from reliability and performance problems in practical uses - and currently do not offer a viable alternative to "dumb" fuzzing techniques. -## 2) The afl-fuzz approach +## The afl-fuzz approach American Fuzzy Lop is a brute-force fuzzer coupled with an exceedingly simple but rock-solid instrumentation-guided genetic algorithm. It uses a modified @@ -257,7 +256,7 @@ The fuzzer is thoroughly tested to deliver out-of-the-box performance far superior to blind fuzzing or coverage-only tools. -## 3) Instrumenting programs for use with AFL +## Instrumenting programs for use with AFL PLEASE NOTE: llvm_mode compilation with afl-clang-fast/afl-clang-fast++ instead of afl-gcc/afl-g++ is much faster and has a few cool features. @@ -313,7 +312,7 @@ PS. ASAN users are advised to review [docs/notes_for_asan.md](docs/notes_for_asa file for important caveats. -## 4) Instrumenting binary-only apps +## Instrumenting binary-only apps When source code is *NOT* available, the fuzzer offers experimental support for fast, on-the-fly instrumentation of black-box binaries. This is accomplished @@ -357,7 +356,7 @@ structure is), these two links have you covered: If you find other good ones, please send them to us :-) -## 6) Power schedules +## Power schedules The power schedules were copied from Marcel Böhme's excellent AFLfast implementation and expand on the ability to discover new paths and @@ -388,7 +387,7 @@ made the default mode). More details can be found in the paper published at the 23rd ACM Conference on Computer and Communications Security [CCS'16](https://www.sigsac.org/ccs/CCS2016/accepted-papers/) -## 7) Choosing initial test cases +## Choosing initial test cases To operate correctly, the fuzzer requires one or more starting file that contains a good example of the input data normally expected by the targeted @@ -409,7 +408,7 @@ the afl-cmin utility to identify a subset of functionally distinct files that exercise different code paths in the target binary. -## 8) Fuzzing binaries +## Fuzzing binaries The fuzzing process itself is carried out by the afl-fuzz utility. This program requires a read-only directory with initial test cases, a separate place to @@ -446,7 +445,7 @@ steps, which can take several days, but tend to produce neat test cases. If you want quick & dirty results right away - akin to zzuf and other traditional fuzzers - add the -d option to the command line. -## 9) Interpreting output +## Interpreting output See the [docs/status_screen.md](docs/status_screen.md) file for information on how to interpret the displayed stats and monitor the health of the process. Be @@ -506,7 +505,7 @@ If you have gnuplot installed, you can also generate some pretty graphs for any active fuzzing task using afl-plot. For an example of how this looks like, see [http://lcamtuf.coredump.cx/afl/plot/](http://lcamtuf.coredump.cx/afl/plot/). -## 10) Parallelized fuzzing +## Parallelized fuzzing Every instance of afl-fuzz takes up roughly one core. This means that on multi-core systems, parallelization is necessary to fully utilize the hardware. @@ -517,7 +516,7 @@ The parallel fuzzing mode also offers a simple way for interfacing AFL to other fuzzers, to symbolic or concolic execution engines, and so forth; again, see the last section of [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md) for tips. -## 12) Fuzzer dictionaries +## Fuzzer dictionaries By default, afl-fuzz mutation engine is optimized for compact data formats - say, images, multimedia, compressed data, regular expression syntax, or shell @@ -552,7 +551,7 @@ If a dictionary is really hard to come by, another option is to let AFL run for a while, and then use the token capture library that comes as a companion utility with AFL. For that, see [libtokencap/README.md](libtokencap/README.tokencap.md). -## 13) Crash triage +## Crash triage The coverage-based grouping of crashes usually produces a small data set that can be quickly triaged manually or with a very simple GDB or Valgrind script. @@ -599,8 +598,7 @@ be critical, and which are not; while not bulletproof, it can often offer quick insights into complex file formats. More info about its operation can be found near the end of [docs/technical_details.md](docs/technical_details.md). - -## 14) Going beyond crashes +## Going beyond crashes Fuzzing is a wonderful and underutilized technique for discovering non-crashing design and implementation errors, too. Quite a few interesting bugs have been @@ -623,7 +621,7 @@ if you are the maintainer of a particular package, you can make this code conditional with `#ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION` (a flag also shared with libfuzzer) or `#ifdef __AFL_COMPILER` (this one is just for AFL). -## 15) Common-sense risks +## Common-sense risks Please keep in mind that, similarly to many other computationally-intensive tasks, fuzzing may put strain on your hardware and on the OS. In particular: @@ -652,7 +650,7 @@ tasks, fuzzing may put strain on your hardware and on the OS. In particular: $ iostat -d 3 -x -k [...optional disk ID...] ``` -## 16) Known limitations & areas for improvement +## Known limitations & areas for improvement Here are some of the most important caveats for AFL: @@ -692,7 +690,7 @@ Here are some of the most important caveats for AFL: Beyond this, see INSTALL for platform-specific tips. -## 17) Special thanks +## Special thanks Many of the improvements to the original afl and afl++ wouldn't be possible without feedback, bug reports, or patches from: @@ -746,7 +744,7 @@ without feedback, bug reports, or patches from: Thank you! (For people sending pull requests - please add yourself to this list :-) -## 18) Contact +## Contact Questions? Concerns? Bug reports? The contributors can be reached via [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) |