aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorllzmb <46303940+llzmb@users.noreply.github.com>2021-10-17 20:29:24 +0200
committerllzmb <46303940+llzmb@users.noreply.github.com>2021-10-17 20:29:24 +0200
commit65c94d914db9930eaae50c6d36bdcb4ed16ea908 (patch)
treed93d8624bb3792bceb544ea836311b91f60c74b8
parent79d87f8544a0f67537b2169e3f6821f459659f61 (diff)
downloadafl++-65c94d914db9930eaae50c6d36bdcb4ed16ea908.tar.gz
Change line length to max. 80 characters
-rw-r--r--README.md109
1 files changed, 70 insertions, 39 deletions
diff --git a/README.md b/README.md
index 9fe1da7e..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,56 +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 [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.
+* 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:
@@ -77,42 +96,52 @@ When fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described i
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>
@@ -171,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.