aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrea Fioraldi <andreafioraldi@gmail.com>2020-03-23 09:50:12 +0100
committerAndrea Fioraldi <andreafioraldi@gmail.com>2020-03-23 09:50:12 +0100
commite65e723e03e379d3a6871045fa64e8d949de4006 (patch)
treea179afb38c5221cef2331cd17c735679d33fe96a
parent94e30002e7bc41f46208c61aa477f3d07133fd01 (diff)
downloadafl++-e65e723e03e379d3a6871045fa64e8d949de4006.tar.gz
update readme
-rw-r--r--README.md78
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)