diff options
| -rw-r--r-- | README.md | 110 | ||||
| -rw-r--r-- | docs/branches.md | 3 | ||||
| -rw-r--r-- | docs/fuzzing_binary-only_targets.md | 2 | ||||
| -rw-r--r-- | docs/fuzzing_expert.md | 2 | ||||
| -rw-r--r-- | docs/triaging_crashes.md | 2 |
5 files changed, 75 insertions, 44 deletions
diff --git a/README.md b/README.md index 1a22dd12..575a6a1a 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ Release version: [3.14c](https://github.com/AFLplusplus/AFLplusplus/releases) GitHub version: 3.15a -Repository: [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) +Repository: +[https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) AFL++ is maintained by: @@ -17,57 +18,74 @@ AFL++ is maintained by: Originally developed by Michał "lcamtuf" Zalewski. -AFL++ is a superior fork to Google's AFL - more speed, more and better mutations, more and better instrumentation, custom module support, etc. +AFL++ is a superior fork to Google's AFL - more speed, more and better +mutations, more and better instrumentation, custom module support, etc. -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. +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. ## Getting started Here is some information to get you started: -* 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 changes in AFL++](docs/important_changes.md). -* If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website. +* 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 + [important changes in AFL++](docs/important_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). -* To get you started with tutorials, go to [docs/tutorials.md](docs/tutorials.md). +* 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). +* To get you started with tutorials, go to + [docs/tutorials.md](docs/tutorials.md). ## Building and installing AFL++ -To have AFL++ easily available with everything compiled, pull the image directly from the Docker Hub: +To have AFL++ easily available 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 ``` -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/INSTALL.md](docs/INSTALL.md). ## Quick start: Fuzzing with AFL++ -*NOTE: Before you start, please read about the [common sense risks of fuzzing](docs/common_sense_risks.md).* +*NOTE: Before you start, please read about the [common sense risks of +fuzzing](docs/common_sense_risks.md).* -This is a quick start for fuzzing targets with the source code available. -To read about the process in detail, see [docs/fuzzing_expert.md](docs/fuzzing_expert.md). +This is a quick start for fuzzing targets with the source code available. To +read about the process in detail, see +[docs/fuzzing_expert.md](docs/fuzzing_expert.md). 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) +* 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 quick start: -1. Compile the program or library to be fuzzed using `afl-cc`. -A common way to do this would be: +1. Compile the program or 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 -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. +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. 3. If the program reads from stdin, run `afl-fuzz` like so: @@ -78,42 +96,52 @@ in [dictionaries/README.md](dictionaries/README.md), too. To add a dictionary, add `-x /path/to/dictionary.txt` to afl-fuzz. - If the program takes input from a file, you can put `@@` in the program's + 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). +4. Investigate anything shown in red in the fuzzer UI by promptly consulting + [docs/status_screen.md](docs/status_screen.md). -5. You will find found crashes and hangs in the subdirectories `crashes/` and - `hangs/` in the `-o output_dir` directory. You can replay the crashes by - feeding them to the target, e.g.: - `cat output_dir/crashes/id:000000,* | /path/to/tested/program [...program's cmdline...]` - You can generate cores or use gdb directly to follow up the crashes. +5. You will find found crashes and hangs in the subdirectories `crashes/` and + `hangs/` in the `-o output_dir` directory. You can replay the crashes by + feeding them to the target, e.g.: `cat output_dir/crashes/id:000000,* | + /path/to/tested/program [...program's cmdline...]` You can generate cores or + use gdb directly to follow up the crashes. ## 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>. +* 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. ## 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. +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. +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. +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. +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 :-) +Thank you! (For people sending pull requests - please add yourself to this list +:-) <details> @@ -172,7 +200,9 @@ Thank you! ## Cite -If you use AFL++ in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) presented at WOOT'20: +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. diff --git a/docs/branches.md b/docs/branches.md index 98fd6827..ae147b08 100644 --- a/docs/branches.md +++ b/docs/branches.md @@ -7,4 +7,5 @@ The following branches exist: * [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. Also take a look at the list of [major changes in AFL++](important_changes.md). +For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. +Also take a look at the list of [important changes in AFL++](important_changes.md). \ No newline at end of file diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md index 8b3bbeff..ea262f6e 100644 --- a/docs/fuzzing_binary-only_targets.md +++ b/docs/fuzzing_binary-only_targets.md @@ -72,7 +72,7 @@ cd unicorn_mode If the goal is to fuzz a dynamic library then there are two options available. For both you need to write a small harness that loads and calls the library. Then you fuzz this with either frida_mode or qemu_mode, and either use -`AFL_INST_LIBS=1` or `AFL_QEMU/FRIDA_INST_RANGES` +`AFL_INST_LIBS=1` or `AFL_QEMU/FRIDA_INST_RANGES`. Another, less precise and slower option is using ptrace with debugger interrupt instrumentation: [utils/afl_untracer/README.md](../utils/afl_untracer/README.md). diff --git a/docs/fuzzing_expert.md b/docs/fuzzing_expert.md index ef3f8a4e..96193f88 100644 --- a/docs/fuzzing_expert.md +++ b/docs/fuzzing_expert.md @@ -625,4 +625,4 @@ This is basically all you need to know to professionally run fuzzing campaigns. If you want to know more, the tons of texts in [docs/](./) will have you covered. Note that there are also a lot of tools out there that help fuzzing with AFL++ -(some might be deprecated or unsupported), see [tools.md](tools.md). +(some might be deprecated or unsupported), see [tools.md](tools.md). \ No newline at end of file diff --git a/docs/triaging_crashes.md b/docs/triaging_crashes.md index b0015c90..21ccecaa 100644 --- a/docs/triaging_crashes.md +++ b/docs/triaging_crashes.md @@ -43,4 +43,4 @@ file, attempts to sequentially flip bytes, and observes the behavior of the tested program. It then color-codes the input based on which sections appear to 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 [technical_details.md](technical_details.md). +near the end of [technical_details.md](technical_details.md). \ No newline at end of file |