1# GCC-based instrumentation for afl-fuzz 2 3For the general instruction manual, see [docs/README.md](../docs/README.md). 4 5For the LLVM-based instrumentation, see [README.llvm.md](README.llvm.md). 6 7This document describes how to build and use `afl-gcc-fast` and `afl-g++-fast`, 8which instrument the target with the help of gcc plugins. 9 10TL;DR: 11* Check the version of your gcc compiler: `gcc --version` 12* `apt-get install gcc-VERSION-plugin-dev` or similar to install headers for gcc 13 plugins. 14* `gcc` and `g++` must match the gcc-VERSION you installed headers for. You can 15 set `AFL_CC`/`AFL_CXX` to point to these! 16* `make` 17* Just use `afl-gcc-fast`/`afl-g++-fast` normally like you would do with 18 `afl-clang-fast`. 19 20## 1) Introduction 21 22The code in this directory allows to instrument programs for AFL++ using true 23compiler-level instrumentation, instead of the more crude assembly-level 24rewriting approach taken by afl-gcc and afl-clang. This has several interesting 25properties: 26 27- The compiler can make many optimizations that are hard to pull off when 28 manually inserting assembly. As a result, some slow, CPU-bound programs will 29 run up to around faster. 30 31 The gains are less pronounced for fast binaries, where the speed is limited 32 chiefly by the cost of creating new processes. In such cases, the gain will 33 probably stay within 10%. 34 35- The instrumentation is CPU-independent. At least in principle, you should be 36 able to rely on it to fuzz programs on non-x86 architectures (after building 37 `afl-fuzz` with `AFL_NOX86=1`). 38 39- Because the feature relies on the internals of GCC, it is gcc-specific and 40 will *not* work with LLVM (see [README.llvm.md](README.llvm.md) for an 41 alternative). 42 43Once this implementation is shown to be sufficiently robust and portable, it 44will probably replace afl-gcc. For now, it can be built separately and co-exists 45with the original code. 46 47The idea and much of the implementation comes from Laszlo Szekeres. 48 49## 2) How to use 50 51In order to leverage this mechanism, you need to have modern enough GCC (>= 52version 4.5.0) and the plugin development headers installed on your system. That 53should be all you need. On Debian machines, these headers can be acquired by 54installing the `gcc-VERSION-plugin-dev` packages. 55 56To build the instrumentation itself, type `make`. This will generate binaries 57called `afl-gcc-fast` and `afl-g++-fast` in the parent directory. 58 59The gcc and g++ compiler links have to point to gcc-VERSION - or set these by 60pointing the environment variables `AFL_CC`/`AFL_CXX` to them. If the `CC`/`CXX` 61environment variables have been set, those compilers will be preferred over 62those from the `AFL_CC`/`AFL_CXX` settings. 63 64Once this is done, you can instrument third-party code in a way similar to the 65standard operating mode of AFL++, e.g.: 66 67``` 68 CC=/path/to/afl/afl-gcc-fast 69 CXX=/path/to/afl/afl-g++-fast 70 export CC CXX 71 ./configure [...options...] 72 make 73``` 74 75Note: We also used `CXX` to set the C++ compiler to `afl-g++-fast` for C++ code. 76 77The tool honors roughly the same environmental variables as `afl-gcc` (see 78[docs/env_variables.md](../docs/env_variables.md). This includes 79`AFL_INST_RATIO`, `AFL_USE_ASAN`, `AFL_HARDEN`, and `AFL_DONT_OPTIMIZE`. 80 81Note: if you want the GCC plugin to be installed on your system for all users, 82you need to build it before issuing 'make install' in the parent directory. 83 84## 3) Gotchas, feedback, bugs 85 86This is an early-stage mechanism, so field reports are welcome. You can send bug 87reports to afl@aflplus.plus. 88 89## 4) Bonus feature #1: deferred initialization 90 91See 92[README.persistent_mode.md#3) Deferred initialization](README.persistent_mode.md#3-deferred-initialization). 93 94## 5) Bonus feature #2: persistent mode 95 96See 97[README.persistent_mode.md#4) Persistent mode](README.persistent_mode.md#4-persistent-mode). 98 99## 6) Bonus feature #3: selective instrumentation 100 101It can be more effective to fuzzing to only instrument parts of the code. For 102details, see [README.instrument_list.md](README.instrument_list.md).