mirror of
https://github.com/AFLplusplus/AFLplusplus.git
synced 2025-06-10 09:11:34 +00:00
Change line length to max. 80 characters
This commit is contained in:
llzmb
parent
79d87f8544
commit
65c94d914d
109
README.md
109
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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user