1# American Fuzzy Lop plus plus (AFL++) 2 3<img align="right" src="https://raw.githubusercontent.com/AFLplusplus/Website/main/static/aflpp_bg.svg" alt="AFL++ logo" width="250" heigh="250"> 4 5Release version: [4.10c](https://github.com/AFLplusplus/AFLplusplus/releases) 6 7GitHub version: 4.10c 8 9Repository: 10[https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) 11 12AFL++ is maintained by: 13 14* Marc "van Hauser" Heuse <[email protected]> 15* Dominik Maier <[email protected]> 16* Andrea Fioraldi <[email protected]> 17* Heiko "hexcoder-" Eissfeldt <[email protected]> 18* frida_mode is maintained by @Worksbutnottested 19* Documentation: Jana Aydinbas <[email protected]> 20 21Originally developed by Michal "lcamtuf" Zalewski. 22 23AFL++ is a superior fork to Google's AFL - more speed, more and better 24mutations, more and better instrumentation, custom module support, etc. 25 26You are free to copy, modify, and distribute AFL++ with attribution under the 27terms of the Apache-2.0 License. See the [LICENSE](LICENSE) for details. 28 29## Getting started 30 31Here is some information to get you started: 32 33* For an overview of the AFL++ documentation and a very helpful graphical guide, 34 please visit [docs/README.md](docs/README.md). 35* To get you started with tutorials, go to 36 [docs/tutorials.md](docs/tutorials.md). 37* For releases, see the 38 [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases) and 39 [branches](#branches). The best branches to use are, however, `stable` or 40 `dev` - depending on your risk appetite. Also take a look at the list of 41 [important changes in AFL++](docs/important_changes.md) and the list of 42 [features](docs/features.md). 43* If you want to use AFL++ for your academic work, check the 44 [papers page](https://aflplus.plus/papers/) on the website. 45* To cite our work, look at the [Cite](#cite) section. 46* For comparisons, use the fuzzbench `aflplusplus` setup, or use 47 `afl-clang-fast` with `AFL_LLVM_CMPLOG=1`. You can find the `aflplusplus` 48 default configuration on Google's 49 [fuzzbench](https://github.com/google/fuzzbench/tree/master/fuzzers/aflplusplus). 50 51## Building and installing AFL++ 52 53To have AFL++ easily available with everything compiled, pull the image directly 54from the Docker Hub (available for both x86_64 and arm64): 55 56```shell 57docker pull aflplusplus/aflplusplus 58docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus 59``` 60 61This image is automatically published when a push to the stable branch happens 62(see [branches](#branches)). If you use the command above, you will find your 63target source code in `/src` in the container. 64 65Note: you can also pull `aflplusplus/aflplusplus:dev` which is the most current 66development state of AFL++. 67 68To build AFL++ yourself - *which we recommend* - continue at 69[docs/INSTALL.md](docs/INSTALL.md). 70 71## Quick start: Fuzzing with AFL++ 72 73*NOTE: Before you start, please read about the 74[common sense risks of fuzzing](docs/fuzzing_in_depth.md#0-common-sense-risks).* 75 76This is a quick start for fuzzing targets with the source code available. To 77read about the process in detail, see 78[docs/fuzzing_in_depth.md](docs/fuzzing_in_depth.md). 79 80To learn about fuzzing other targets, see: 81* Binary-only targets: 82 [docs/fuzzing_binary-only_targets.md](docs/fuzzing_binary-only_targets.md) 83* Network services: 84 [docs/best_practices.md#fuzzing-a-network-service](docs/best_practices.md#fuzzing-a-network-service) 85* GUI programs: 86 [docs/best_practices.md#fuzzing-a-gui-program](docs/best_practices.md#fuzzing-a-gui-program) 87 88Step-by-step quick start: 89 901. Compile the program or library to be fuzzed using `afl-cc`. A common way to 91 do this would be: 92 93 ``` 94 CC=/path/to/afl-cc CXX=/path/to/afl-c++ ./configure --disable-shared 95 make clean all 96 ``` 97 982. Get a small but valid input file that makes sense to the program. When 99 fuzzing verbose syntax (SQL, HTTP, etc.), create a dictionary as described in 100 [dictionaries/README.md](dictionaries/README.md), too. 101 1023. If the program reads from stdin, run `afl-fuzz` like so: 103 104 ``` 105 ./afl-fuzz -i seeds_dir -o output_dir -- \ 106 /path/to/tested/program [...program's cmdline...] 107 ``` 108 109 To add a dictionary, add `-x /path/to/dictionary.txt` to afl-fuzz. 110 111 If the program takes input from a file, you can put `@@` in the program's 112 command line; AFL++ will put an auto-generated file name in there for you. 113 1144. Investigate anything shown in red in the fuzzer UI by promptly consulting 115 [docs/afl-fuzz_approach.md#understanding-the-status-screen](docs/afl-fuzz_approach.md#understanding-the-status-screen). 116 1175. You will find found crashes and hangs in the subdirectories `crashes/` and 118 `hangs/` in the `-o output_dir` directory. You can replay the crashes by 119 feeding them to the target, e.g. if your target is using stdin: 120 121 ``` 122 cat output_dir/crashes/id:000000,* | /path/to/tested/program [...program's cmdline...] 123 ``` 124 125 You can generate cores or use gdb directly to follow up the crashes. 126 1276. We cannot stress this enough - if you want to fuzz effectively, read the 128 [docs/fuzzing_in_depth.md](docs/fuzzing_in_depth.md) document! 129 130## Contact 131 132Questions? Concerns? Bug reports? 133 134* The contributors can be reached via (e.g., by creating an issue): 135 [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus). 136* Take a look at our [FAQ](docs/FAQ.md). If you find an interesting or important 137 question missing, submit it via 138 [https://github.com/AFLplusplus/AFLplusplus/discussions](https://github.com/AFLplusplus/AFLplusplus/discussions). 139* Best: join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server. 140* There is a (not really used) mailing list for the AFL/AFL++ project 141 ([browse archive](https://groups.google.com/group/afl-users)). To compare 142 notes with other users or to get notified about major new features, send an 143 email to <[email protected]>, but note that this is not 144 managed by us. 145 146## Branches 147 148The following branches exist: 149 150* [release](https://github.com/AFLplusplus/AFLplusplus/tree/release): the latest 151 release 152* [stable/trunk](https://github.com/AFLplusplus/AFLplusplus/): stable state of 153 AFL++ - it is synced from dev from time to time when we are satisfied with its 154 stability 155* [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev): development state 156 of AFL++ - bleeding edge and you might catch a checkout which does not compile 157 or has a bug. **We only accept PRs (pull requests) for the 'dev' branch!** 158* (any other): experimental branches to work on specific features or testing new 159 functionality or changes. 160 161## Help wanted 162 163We have several [ideas](docs/ideas.md) we would like to see in AFL++ to make it 164even better. However, we already work on so many things that we do not have the 165time for all the big ideas. 166 167This can be your way to support and contribute to AFL++ - extend it to do 168something cool. 169 170For everyone who wants to contribute (and send pull requests), please read our 171[contributing guidelines](CONTRIBUTING.md) before you submit. 172 173## Special thanks 174 175Many of the improvements to the original AFL and AFL++ wouldn't be possible 176without feedback, bug reports, or patches from our contributors. 177 178Thank you! (For people sending pull requests - please add yourself to this list 179:-) 180 181<details> 182 183 <summary>List of contributors</summary> 184 185 ``` 186 Jann Horn Hanno Boeck 187 Felix Groebert Jakub Wilk 188 Richard W. M. Jones Alexander Cherepanov 189 Tom Ritter Hovik Manucharyan 190 Sebastian Roschke Eberhard Mattes 191 Padraig Brady Ben Laurie 192 @dronesec Luca Barbato 193 Tobias Ospelt Thomas Jarosch 194 Martin Carpenter Mudge Zatko 195 Joe Zbiciak Ryan Govostes 196 Michael Rash William Robinet 197 Jonathan Gray Filipe Cabecinhas 198 Nico Weber Jodie Cunningham 199 Andrew Griffiths Parker Thompson 200 Jonathan Neuschaefer Tyler Nighswander 201 Ben Nagy Samir Aguiar 202 Aidan Thornton Aleksandar Nikolich 203 Sam Hakim Laszlo Szekeres 204 David A. Wheeler Turo Lamminen 205 Andreas Stieger Richard Godbee 206 Louis Dassy teor2345 207 Alex Moneger Dmitry Vyukov 208 Keegan McAllister Kostya Serebryany 209 Richo Healey Martijn Bogaard 210 rc0r Jonathan Foote 211 Christian Holler Dominique Pelle 212 Jacek Wielemborek Leo Barnes 213 Jeremy Barnes Jeff Trull 214 Guillaume Endignoux ilovezfs 215 Daniel Godas-Lopez Franjo Ivancic 216 Austin Seipp Daniel Komaromy 217 Daniel Binderman Jonathan Metzman 218 Vegard Nossum Jan Kneschke 219 Kurt Roeckx Marcel Boehme 220 Van-Thuan Pham Abhik Roychoudhury 221 Joshua J. Drake Toby Hutton 222 Rene Freingruber Sergey Davidoff 223 Sami Liedes Craig Young 224 Andrzej Jackowski Daniel Hodson 225 Nathan Voss Dominik Maier 226 Andrea Biondo Vincent Le Garrec 227 Khaled Yakdan Kuang-che Wu 228 Josephine Calliotte Konrad Welc 229 Thomas Rooijakkers David Carlier 230 Ruben ten Hove Joey Jiao 231 fuzzah @intrigus-lgtm 232 Yaakov Saxon Sergej Schumilo 233 ``` 234 235</details> 236 237## Cite 238 239If you use AFL++ in scientific work, consider citing 240[our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) 241presented at WOOT'20: 242 243 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. 244 245<details> 246 247<summary>BibTeX</summary> 248 249 ```bibtex 250 @inproceedings {AFLplusplus-Woot20, 251 author = {Andrea Fioraldi and Dominik Maier and Heiko Ei{\ss}feldt and Marc Heuse}, 252 title = {{AFL++}: Combining Incremental Steps of Fuzzing Research}, 253 booktitle = {14th {USENIX} Workshop on Offensive Technologies ({WOOT} 20)}, 254 year = {2020}, 255 publisher = {{USENIX} Association}, 256 month = aug, 257 } 258 ``` 259 260</details> 261
