Edit README.md and related content
Changes:
- Fix links.
- Add links.
- Restructure content.
diff --git a/README.md b/README.md
index 7fb8874..f855c5b 100644
--- a/README.md
+++ b/README.md
@@ -19,129 +19,163 @@
AFL++ is a superior fork to Google's AFL - more speed, more and better mutations, more and better instrumentation, custom module support, etc.
-For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. Also take a look at the list of [major behaviour changes in AFL++](docs/behaviour_changes.md).
-
-If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website.
-To cite our work, look at [Cite.md](docs/cite.md).
-For comparisons, use the fuzzbench `aflplusplus` setup, or use `afl-clang-fast` with `AFL_LLVM_CMPLOG=1`.
-
You are free to copy, modify, and distribute AFL++ with attribution under the terms of the Apache-2.0 License. See the [LICENSE](LICENSE) for details.
-## Help wanted
+## Getting started
-We have several [to dos](TODO.md) and [ideas](docs/ideas.md) we would like to see in AFL++ to make it even better.
-However, we already work on so many things that we do not have the time for all the big ideas.
+Here is some information to get you started:
-This can be your way to support and contribute to AFL++ - extend it to do something cool.
-
-For everyone who wants to contribute (and send pull requests), please read our [contributing guidelines](CONTRIBUTING.md) before your submit.
-
-Thank you to [everyone who contributed](#special-thanks).
+* For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab and [branches](docs/branches.md). Also take a look at the list of [major behaviour changes in AFL++](docs/behaviour_changes.md).
+* If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website.
+* To cite our work, look at the [Cite](#cite) section.
+* For comparisons, use the fuzzbench `aflplusplus` setup, or use `afl-clang-fast` with `AFL_LLVM_CMPLOG=1`. You can find the `aflplusplus` default configuration on Google's [fuzzbench](https://github.com/google/fuzzbench/tree/master/fuzzers/aflplusplus).
## Building and installing AFL++
-To install AFL++ with everything compiled, use Docker:
-* You can either use the [Dockerfile](Dockerfile) (which has gcc-10 and clang-11 - hence afl-clang-lto is available!)
-* Or just pull directly from the Docker Hub:
+To install AFL++ with everything compiled, pull the image directly from the Docker Hub:
- ```shell
- docker pull aflplusplus/aflplusplus
- docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus
- ```
+```shell
+docker pull aflplusplus/aflplusplus
+docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus
+```
- This image is automatically generated when a push to the stable repo happens (see [docs/branches.md](docs/branches.md)).
- You will find your target source code in `/src` in the container.
+This image is automatically generated when a push to the stable repo happens (see [docs/branches.md](docs/branches.md)).
+You will find your target source code in `/src` in the container.
To build AFL++ yourself, continue at [docs/building_installing.md](docs/building_installing.md).
-## Quickstart: Fuzzing with AFL++
+## Quick start: Fuzzing with AFL++
*NOTE: Before you start, please read about the [common sense risks of fuzzing](docs/common_sense_risks.md).*
-This is a quickstart for fuzzing targets with the source code available.
+This is a quick start for fuzzing targets with the source code available.
To read about the process in detail, see [docs/fuzzing.md](docs/fuzzing.md).
-To learn about fuzzing other target, see:
+To learn about fuzzing other targets, see:
* Binary-only targets: [docs/fuzzing_binary-only_targets.md](docs/fuzzing_binary-only_targets.md)
* Network services: [docs/best_practices.md#fuzzing-a-network-service](docs/best_practices.md#fuzzing-a-network-service)
* GUI programs: [docs/best_practices.md#fuzzing-a-gui-program](docs/best_practices.md#fuzzing-a-gui-program)
-Step-by-step quickstart:
+Step-by-step quick start:
-*THIS SECTION IS WIP*
+1. Compile the program or library to be fuzzed using `afl-cc`.
+A common way to do this would be:
-1. Instrumenting the target:
- 1. Selecting a compiler.
- 2. Instrumenting the target.
-2. Preparing the fuzzing campaign.
-3. Fuzzing the target:
- 1. Running afl-fuzz.
- 2. Stopping or restarting afl-fuzz or adding new seeds.
-4. Monitoring.
- 1. Checking the status.
- 2. Checking the coverage.
-5. Triaging crashes.
+ CC=/path/to/afl-cc CXX=/path/to/afl-c++ ./configure --disable-shared
+ make clean all
-## Special thanks
+2. Get a small but valid input file that makes sense to the program.
+When fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in [dictionaries/README.md](../dictionaries/README.md), too.
-Many of the improvements to the original AFL and AFL++ wouldn't be possible without feedback, bug reports, or patches from:
+3. If the program reads from stdin, run `afl-fuzz` like so:
-```
- Jann Horn Hanno Boeck
- Felix Groebert Jakub Wilk
- Richard W. M. Jones Alexander Cherepanov
- Tom Ritter Hovik Manucharyan
- Sebastian Roschke Eberhard Mattes
- Padraig Brady Ben Laurie
- @dronesec Luca Barbato
- Tobias Ospelt Thomas Jarosch
- Martin Carpenter Mudge Zatko
- Joe Zbiciak Ryan Govostes
- Michael Rash William Robinet
- Jonathan Gray Filipe Cabecinhas
- Nico Weber Jodie Cunningham
- Andrew Griffiths Parker Thompson
- Jonathan Neuschaefer Tyler Nighswander
- Ben Nagy Samir Aguiar
- Aidan Thornton Aleksandar Nikolich
- Sam Hakim Laszlo Szekeres
- David A. Wheeler Turo Lamminen
- Andreas Stieger Richard Godbee
- Louis Dassy teor2345
- Alex Moneger Dmitry Vyukov
- Keegan McAllister Kostya Serebryany
- Richo Healey Martijn Bogaard
- rc0r Jonathan Foote
- Christian Holler Dominique Pelle
- Jacek Wielemborek Leo Barnes
- Jeremy Barnes Jeff Trull
- Guillaume Endignoux ilovezfs
- Daniel Godas-Lopez Franjo Ivancic
- Austin Seipp Daniel Komaromy
- Daniel Binderman Jonathan Metzman
- Vegard Nossum Jan Kneschke
- Kurt Roeckx Marcel Boehme
- Van-Thuan Pham Abhik Roychoudhury
- Joshua J. Drake Toby Hutton
- Rene Freingruber Sergey Davidoff
- Sami Liedes Craig Young
- Andrzej Jackowski Daniel Hodson
- Nathan Voss Dominik Maier
- Andrea Biondo Vincent Le Garrec
- Khaled Yakdan Kuang-che Wu
- Josephine Calliotte Konrad Welc
- Thomas Rooijakkers David Carlier
- Ruben ten Hove Joey Jiao
- fuzzah
-```
+ ./afl-fuzz -i testcase_dir -o findings_dir -- \
+ /path/to/tested/program [...program's cmdline...]
-Thank you!
-(For people sending pull requests - please add yourself to this list :-)
+ If the program takes input from a file, you can put `@@` in the program's command line; AFL will put an auto-generated file name in there for you.
+
+4. Investigate anything shown in red in the fuzzer UI by promptly consulting [docs/status_screen.md](docs/status_screen.md).
## Contact
Questions? Concerns? Bug reports?
* The contributors can be reached via [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus).
+* Take a look at our [FAQ](docs/faq.md). If you find an interesting or important question missing, submit it via
+[https://github.com/AFLplusplus/AFLplusplus/discussions](https://github.com/AFLplusplus/AFLplusplus/discussions).
* There is a mailing list for the AFL/AFL++ project ([browse archive](https://groups.google.com/group/afl-users)). To compare notes with other users or to get notified about major new features, send an email to <afl-users+subscribe@googlegroups.com>.
-* Or join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server.
\ No newline at end of file
+* Or join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server.
+
+## Help wanted
+
+We have several [ideas](docs/ideas.md) we would like to see in AFL++ to make it even better.
+However, we already work on so many things that we do not have the time for all the big ideas.
+
+This can be your way to support and contribute to AFL++ - extend it to do something cool.
+
+For everyone who wants to contribute (and send pull requests), please read our [contributing guidelines](CONTRIBUTING.md) before your submit.
+
+## Special thanks
+
+Many of the improvements to the original AFL and AFL++ wouldn't be possible without feedback, bug reports, or patches from our contributors.
+
+Thank you!
+(For people sending pull requests - please add yourself to this list :-)
+
+<details>
+
+ <summary>List of contributors</summary>
+
+ ```
+ Jann Horn Hanno Boeck
+ Felix Groebert Jakub Wilk
+ Richard W. M. Jones Alexander Cherepanov
+ Tom Ritter Hovik Manucharyan
+ Sebastian Roschke Eberhard Mattes
+ Padraig Brady Ben Laurie
+ @dronesec Luca Barbato
+ Tobias Ospelt Thomas Jarosch
+ Martin Carpenter Mudge Zatko
+ Joe Zbiciak Ryan Govostes
+ Michael Rash William Robinet
+ Jonathan Gray Filipe Cabecinhas
+ Nico Weber Jodie Cunningham
+ Andrew Griffiths Parker Thompson
+ Jonathan Neuschaefer Tyler Nighswander
+ Ben Nagy Samir Aguiar
+ Aidan Thornton Aleksandar Nikolich
+ Sam Hakim Laszlo Szekeres
+ David A. Wheeler Turo Lamminen
+ Andreas Stieger Richard Godbee
+ Louis Dassy teor2345
+ Alex Moneger Dmitry Vyukov
+ Keegan McAllister Kostya Serebryany
+ Richo Healey Martijn Bogaard
+ rc0r Jonathan Foote
+ Christian Holler Dominique Pelle
+ Jacek Wielemborek Leo Barnes
+ Jeremy Barnes Jeff Trull
+ Guillaume Endignoux ilovezfs
+ Daniel Godas-Lopez Franjo Ivancic
+ Austin Seipp Daniel Komaromy
+ Daniel Binderman Jonathan Metzman
+ Vegard Nossum Jan Kneschke
+ Kurt Roeckx Marcel Boehme
+ Van-Thuan Pham Abhik Roychoudhury
+ Joshua J. Drake Toby Hutton
+ Rene Freingruber Sergey Davidoff
+ Sami Liedes Craig Young
+ Andrzej Jackowski Daniel Hodson
+ Nathan Voss Dominik Maier
+ Andrea Biondo Vincent Le Garrec
+ Khaled Yakdan Kuang-che Wu
+ Josephine Calliotte Konrad Welc
+ Thomas Rooijakkers David Carlier
+ Ruben ten Hove Joey Jiao
+ fuzzah
+ ```
+
+</details>
+
+## Cite
+
+If you use AFL++ in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) presented at WOOT'20:
+
+ Andrea Fioraldi, Dominik Maier, Heiko Eißfeldt, and Marc Heuse. “AFL++: Combining incremental steps of fuzzing research”. In 14th USENIX Workshop on Offensive Technologies (WOOT 20). USENIX Association, Aug. 2020.
+
+<details>
+
+<summary>BibTeX</summary>
+
+ ```bibtex
+ @inproceedings {AFLplusplus-Woot20,
+ author = {Andrea Fioraldi and Dominik Maier and Heiko Ei{\ss}feldt and Marc Heuse},
+ title = {{AFL++}: Combining Incremental Steps of Fuzzing Research},
+ booktitle = {14th {USENIX} Workshop on Offensive Technologies ({WOOT} 20)},
+ year = {2020},
+ publisher = {{USENIX} Association},
+ month = aug,
+ }
+ ```
+
+</details>
\ No newline at end of file
diff --git a/docs/QuickStartGuide.md b/docs/QuickStartGuide.md
deleted file mode 100644
index 2d056ec..0000000
--- a/docs/QuickStartGuide.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# AFL quick start guide
-
-You should read [README.md](../README.md) - it's pretty short. If you really can't, here's
-how to hit the ground running:
-
-1) Compile AFL with 'make'. If build fails, see [INSTALL.md](INSTALL.md) for tips.
-
-2) Find or write a reasonably fast and simple program that takes data from
- a file or stdin, processes it in a test-worthy way, then exits cleanly.
- If testing a network service, modify it to run in the foreground and read
- from stdin. When fuzzing a format that uses checksums, comment out the
- checksum verification code, too.
-
- If this is not possible (e.g. in -Q(emu) mode) then use
- AFL_CUSTOM_MUTATOR_LIBRARY to calculate the values with your own library.
-
- The program must crash properly when a fault is encountered. Watch out for
- custom SIGSEGV or SIGABRT handlers and background processes. For tips on
- detecting non-crashing flaws, see section 11 in [README.md](README.md) .
-
-3) Compile the program / library to be fuzzed using afl-cc. A common way to
- do this would be:
-
- CC=/path/to/afl-cc CXX=/path/to/afl-c++ ./configure --disable-shared
- make clean all
-
-4) Get a small but valid input file that makes sense to the program. When
- fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in
- dictionaries/README.md, too.
-
-5) If the program reads from stdin, run 'afl-fuzz' like so:
-
- ./afl-fuzz -i testcase_dir -o findings_dir -- \
- /path/to/tested/program [...program's cmdline...]
-
- If the program takes input from a file, you can put @@ in the program's
- command line; AFL will put an auto-generated file name in there for you.
-
-6) Investigate anything shown in red in the fuzzer UI by promptly consulting
- [status_screen.md](status_screen.md).
-
-8) There is a basic docker build with 'docker build -t aflplusplus .'
-
-That's it. Sit back, relax, and - time permitting - try to skim through the
-following files:
-
- - README.md - A general introduction to AFL,
- - docs/perf_tips.md - Simple tips on how to fuzz more quickly,
- - docs/status_screen.md - An explanation of the tidbits shown in the UI,
- - docs/parallel_fuzzing.md - Advice on running AFL on multiple cores.
diff --git a/docs/cite.md b/docs/cite.md
deleted file mode 100644
index 603616e..0000000
--- a/docs/cite.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Cite
-
-If you use AFLpluplus to compare to your work, please use either `afl-clang-lto`
-or `afl-clang-fast` with `AFL_LLVM_CMPLOG=1` for building targets and
-`afl-fuzz` with the command line option `-l 2` for fuzzing.
-The most effective setup is the `aflplusplus` default configuration on Google's [fuzzbench](https://github.com/google/fuzzbench/tree/master/fuzzers/aflplusplus).
-
-If you use AFLplusplus in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) presented at WOOT'20:
-
-+ Andrea Fioraldi, Dominik Maier, Heiko Eißfeldt, and Marc Heuse. “AFL++: Combining incremental steps of fuzzing research”. In 14th USENIX Workshop on Offensive Technologies (WOOT 20). USENIX Association, Aug. 2020.
-
-Bibtex:
-
-```bibtex
-@inproceedings {AFLplusplus-Woot20,
- author = {Andrea Fioraldi and Dominik Maier and Heiko Ei{\ss}feldt and Marc Heuse},
- title = {{AFL++}: Combining Incremental Steps of Fuzzing Research},
- booktitle = {14th {USENIX} Workshop on Offensive Technologies ({WOOT} 20)},
- year = {2020},
- publisher = {{USENIX} Association},
- month = aug,
-}
-```
\ No newline at end of file
diff --git a/docs/fuzzing.md b/docs/fuzzing.md
index b173847..23b24ad 100644
--- a/docs/fuzzing.md
+++ b/docs/fuzzing.md
@@ -51,9 +51,9 @@
Clickable README links for the chosen compiler:
- * [LTO mode - afl-clang-lto](instrumentation/README.lto.md)
- * [LLVM mode - afl-clang-fast](instrumentation/README.llvm.md)
- * [GCC_PLUGIN mode - afl-gcc-fast](instrumentation/README.gcc_plugin.md)
+ * [LTO mode - afl-clang-lto](../instrumentation/README.lto.md)
+ * [LLVM mode - afl-clang-fast](../instrumentation/README.llvm.md)
+ * [GCC_PLUGIN mode - afl-gcc-fast](../instrumentation/README.gcc_plugin.md)
* GCC/CLANG modes (afl-gcc/afl-clang) have no README as they have no own features
You can select the mode for the afl-cc compiler by:
@@ -79,7 +79,7 @@
and large input corpus. This technique is called laf-intel or COMPCOV.
To use this set the following environment variable before compiling the
target: `export AFL_LLVM_LAF_ALL=1`
- You can read more about this in [instrumentation/README.laf-intel.md](instrumentation/README.laf-intel.md)
+ You can read more about this in [instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md)
* A different technique (and usually a better one than laf-intel) is to
instrument the target so that any compare values in the target are sent to
AFL++ which then tries to put these values into the fuzzing data at different
@@ -91,7 +91,7 @@
via the `-c` parameter.
Note that you can compile also just a cmplog binary and use that for both
however there will be a performance penality.
- You can read more about this in [instrumentation/README.cmplog.md](instrumentation/README.cmplog.md)
+ You can read more about this in [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
@@ -108,16 +108,16 @@
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)
+ 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:
- * [instrumentation/README.ctx.md](instrumentation/README.ctx.md)
- * [instrumentation/README.ngram.md](instrumentation/README.ngram.md)
+ * [instrumentation/README.ctx.md](../instrumentation/README.ctx.md)
+ * [instrumentation/README.ngram.md](../instrumentation/README.ngram.md)
AFL++ performs "never zero" counting in its bitmap. You can read more about this
here:
- * [instrumentation/README.neverzero.md](instrumentation/README.neverzero.md)
+ * [instrumentation/README.neverzero.md](../instrumentation/README.neverzero.md)
#### c) Sanitizers
@@ -225,7 +225,7 @@
Note that if you are using the (better) afl-clang-lto compiler you also have to
set AR to llvm-ar[-VERSION] and RANLIB to llvm-ranlib[-VERSION] - as is
-described in [instrumentation/README.lto.md](instrumentation/README.lto.md).
+described in [instrumentation/README.lto.md](../instrumentation/README.lto.md).
##### cmake
@@ -234,7 +234,7 @@
Note that if you are using the (better) afl-clang-lto compiler you also have to
set AR to llvm-ar[-VERSION] and RANLIB to llvm-ranlib[-VERSION] - as is
-described in [instrumentation/README.lto.md](instrumentation/README.lto.md).
+described in [instrumentation/README.lto.md](../instrumentation/README.lto.md).
##### meson
@@ -260,7 +260,7 @@
It is the so-called `persistent mode`, which is much, much faster but
requires that you code a source file that is specifically calling the target
functions that you want to fuzz, plus a few specific AFL++ functions around
-it. See [instrumentation/README.persistent_mode.md](instrumentation/README.persistent_mode.md) for details.
+it. See [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md) for details.
Basically if you do not fuzz a target in persistent mode then you are just
doing it for a hobby and not professionally :-).
@@ -281,7 +281,7 @@
Bonus: the target is already optimized for fuzzing due to persistent mode and
shared-memory testcases and hence gives you the fastest speed possible.
-For more information see [utils/aflpp_driver/README.md](utils/aflpp_driver/README.md)
+For more information see [utils/aflpp_driver/README.md](../utils/aflpp_driver/README.md)
### 2. Preparing the fuzzing campaign
@@ -394,12 +394,12 @@
in MB. If this is too small for the target, you can usually see this by
afl-fuzz bailing with the message that it could not connect to the forkserver.
-Adding a dictionary is helpful. See the directory [dictionaries/](dictionaries/) if
+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).
+a dictionary yourself, see [utils/libtokencap/README.md](../utils/libtokencap/README.md).
afl-fuzz has a variety of options that help to workaround target quirks like
specific locations for the input file (`-f`), performing deterministic
@@ -604,7 +604,7 @@
#### h) Improve the speed!
- * Use [persistent mode](instrumentation/README.persistent_mode.md) (x2-x20 speed increase)
+ * Use [persistent mode](../instrumentation/README.persistent_mode.md) (x2-x20 speed increase)
* If you do not use shmem persistent mode, use `AFL_TMPDIR` to point the input file on a tempfs location, see [env_variables.md](env_variables.md)
* Linux: 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) - you can also just run `sudo afl-persistent-config`
* Linux: Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem
diff --git a/docs/links_tools.md b/docs/tools.md
similarity index 98%
rename from docs/links_tools.md
rename to docs/tools.md
index c544e18..ba96d0c 100644
--- a/docs/links_tools.md
+++ b/docs/tools.md
@@ -1,4 +1,4 @@
-# Links: tools that help fuzzing with AFL++
+# Tools that help fuzzing with AFL++
Speeding up fuzzing:
* [libfiowrapper](https://github.com/marekzmyslowski/libfiowrapper) - if the function you want to fuzz requires loading a file, this allows using the shared memory testcase feature :-) - recommended.
diff --git a/docs/links_examples_writeups.md b/docs/tutorials.md
similarity index 98%
rename from docs/links_examples_writeups.md
rename to docs/tutorials.md
index 8f70045..cc7ed13 100644
--- a/docs/links_examples_writeups.md
+++ b/docs/tutorials.md
@@ -1,4 +1,4 @@
-# Links: examples and writeups
+# Tutorials
Here are some good writeups to show how to effectively use AFL++:
