| Jonathan Metzman | d704c04 | 2019-02-20 00:07:28 | [diff] [blame] | 1 | # AFL Integration |
| 2 | |
| 3 | This document describes AFL's integration with Chromium. This document is only |
| 4 | for the curious, developers writing Chromium fuzz targets shouldn't worry about |
| 5 | AFL, as this document will explain. Therefore, it does not explain how you |
| 6 | should use AFL locally, in most cases you should just use libFuzzer. |
| 7 | |
| 8 | ## What? |
| 9 | |
| 10 | Nearly every libFuzzer target that runs on ClusterFuzz is also fuzzed on |
| 11 | ClusterFuzz using [AFL]. AFL pioneered the technique of coverage-guided fuzzing |
| 12 | and is similar to libFuzzer. In ClusterFuzz we primarily use libFuzzer, though |
| 13 | we find using AFL also helps. If you are writing a libFuzzer target (unless it |
| 14 | uses [LPM], which AFL does not support) you don't need to do anything to get |
| 15 | fuzzing with AFL on ClusterFuzz. |
| 16 | |
| 17 | ## Why? |
| 18 | |
| 19 | Why use AFL if we already use libFuzzer? The answer is because using AFL helps |
| 20 | us find bugs that we may not find with libFuzzer. We think this is particularly |
| 21 | true for fuzz targets that are slow, memory-intensive, or frequently crash. That |
| 22 | is because AFL's architecture allows it to continue fuzzing even when a crash or |
| 23 | timeout has occurred. |
| 24 | |
| 25 | ## How? |
| 26 | |
| 27 | We use Clang's [trace-pc-guard] and [ASan] to instrument fuzz targets. We use |
| 28 | [afl_driver.cpp] to send coverage information to `afl-fuzz` from the target and |
| 29 | send inputs from `afl-fuzz` to the target. It uses both deferred forkserver mode |
| 30 | and persistent mode. On ClusterFuzz we have a [launcher] to run `afl-fuzz` on |
| 31 | fuzz targets, just like we have for libFuzzer. The launcher also reports and |
| 32 | reproduces crashes, and saves the corpus found during fuzzing. Another function |
| 33 | of the launcher is ensuring targets can be fuzzed well with AFL even if they |
| 34 | would otherwise have an issue with AFL. |
| 35 | |
| 36 | We only use AFL to fuzz ASan-instrumented release builds on ClusterFuzz, instead |
| 37 | of using it to fuzz the many different build configurations we use libFuzzer on |
| 38 | (e.g. MSan, UBSan, etc). That is because ASan builds tend to find the most |
| 39 | important bugs and doing a new build for each of the configurations would be too |
| 40 | complicated. |
| 41 | |
| 42 | ## Trophies |
| 43 | |
| 44 | * [AFL Chromium bugs] - bugs found by AFL in Chromium. |
| 45 | * [AFL OSS-Fuzz bugs] - bugs found by AFL in [OSS-Fuzz]. |
| 46 | |
| 47 | [AFL]: http://lcamtuf.coredump.cx/afl/ |
| 48 | [AFL Chromium bugs]: https://bugs.chromium.org/p/chromium/issues/list?can=1&q=afl_chrome_asan+-status%3AWontFix%2CDuplicate+label%3Aclusterfuzz |
| 49 | [AFL OSS-Fuzz bugs]: https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=label%3AEngine-afl%2CStability-AFL+label%3AClusterFuzz+-status%3AWontFix%2CDuplicate |
| 50 | [trace-pc-guard]: https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/afl/src/llvm_mode/README.llvm#169 |
| 51 | [ASan]: https://clang.llvm.org/docs/AddressSanitizer.html |
| 52 | [afl_driver.cpp]: https://chromium.googlesource.com/chromium/llvm-project/compiler-rt/lib/fuzzer.git/+/HEAD/afl/afl_driver.cpp |
| 53 | [launcher]: https://github.com/google/clusterfuzz/blob/master/src/python/bot/fuzzers/afl/launcher.py |
| 54 | [LPM]: libprotobuf-mutator.md |
| 55 | [OSS-Fuzz]: https://github.com/google/oss-fuzz/ |
