| 1 |
ancient fuzz suite |
| 2 |
================== |
| 3 |
|
| 4 |
In this directory, you can find the necessary tools for fuzzing the ancient |
| 5 |
decoders with the American Fuzzy Lop fuzzer (afl++). |
| 6 |
|
| 7 |
Contents: |
| 8 |
|
| 9 |
* `all_formats.dict`: A dictionary containing magic bytes from all supported |
| 10 |
formats to make the life of the fuzzer a bit easier. |
| 11 |
* `fuzz-main.sh`: Script to launch the main fuzzing process. If you want to |
| 12 |
use just one fuzzer instance, run this one. |
| 13 |
* `fuzz-secondary.sh`: Script to launch the secondary fuzzing process. It is |
| 14 |
recommended to run at least two fuzzer instances, as the deterministic and |
| 15 |
random fuzz mode have been found to complement each other really well. |
| 16 |
* `fuzz-settings.sh`: Set up your preferences and afl settings here before the |
| 17 |
first run. |
| 18 |
* `fuzz.cpp`: A tiny C++ program that is used by the fuzzer to test ancient. |
| 19 |
* `get-afl.sh`: A simple script to obtain the latest version of the fuzzer. |
| 20 |
|
| 21 |
Prerequisites |
| 22 |
============= |
| 23 |
* [afl++](https://github.com/AFLplusplus/AFLplusplus) or |
| 24 |
[afl](https://lcamtuf.coredump.cx/afl/) - the makefile expects this to be |
| 25 |
installed in `contrib/fuzzing/afl`, as it is automatically done by the |
| 26 |
`get-afl.sh` install script. |
| 27 |
* Clang with LLVM dev headers (llvm-config needs to be installed). |
| 28 |
afl also works with gcc, but our makefile has been set up to make use of afl's |
| 29 |
faster LLVM mode. |
| 30 |
|
| 31 |
How to use |
| 32 |
========== |
| 33 |
* Run `get-afl.sh`, or manually extract afl to `contrib/fuzzing/afl`, use `make` |
| 34 |
to build afl-fuzz, `cd llvm_mode`, `make` to build afl-clang-fast. |
| 35 |
If building with either option fails because `llvm-config` cannot be found, |
| 36 |
try prepending `LLVM_CONFIG=/usr/bin/llvm-config-3.8` or similar, and read the |
| 37 |
afl manual. |
| 38 |
* Build ancient with the `build.sh` script in this directory. |
| 39 |
* Set up `fuzz-settings.sh` to your taste. Most importantly, you will have to |
| 40 |
specify the input directory for first use. |
| 41 |
The default setup mounts a tmpfs folder for all temporary files. You may |
| 42 |
change this behaviour if you do not have root privileges. |
| 43 |
* Run `fuzz-main.sh` for the first (deterministic) instance of afl-fuzz. |
| 44 |
* For a secondary instance to run on another core, run `fuzz-secondary.sh`. |
| 45 |
* If you want to make use of even more cores, make a copy of `fuzz-secondary.sh` |
| 46 |
and adjust "infile02" / "fuzzer02" to "infile03" / "fuzzer03" (they need to be |
| 47 |
unique) |