1# afl-untracer - fast fuzzing of binary-only libraries
2
3## Introduction
4
5afl-untracer is an example skeleton file which can easily be used to fuzz
6a closed source library.
7
8It requires less memory and is x3-5 faster than qemu_mode however it is way
9more course grained and does not provide interesting features like compcov
10or cmplog.
11
12Supported is so far Intel (i386/x86_64) and AARCH64.
13
14## How-to
15
16### Modify afl-untracer.c
17
18Read and modify afl-untracer.c then `make`.
19To adapt afl-untracer.c to your needs, read the header of the file and then
20search and edit the `STEP 1`, `STEP 2` and `STEP 3` locations.
21
22### Generate patches.txt file
23
24To generate the `patches.txt` file for your target library use the
25`ida_get_patchpoints.py` script for IDA Pro or
26`ghidra_get_patchpoints.java` for Ghidra.
27
28The patches.txt file has to be pointed to by `AFL_UNTRACER_FILE`.
29
30To easily run the scripts without needing to run the GUI with Ghidra:
31```
32/opt/ghidra/support/analyzeHeadless /tmp/ tmp$$ -import libtestinstr.so -postscript ./ghidra_get_patchpoints.java
33rm -rf /tmp/tmp$$
34```
35The file is created at `~/Desktop/patches.txt`
36
37### Fuzzing
38
39Example (after modifying afl-untracer.c to your needs, compiling and creating
40patches.txt):
41```
42LD_LIBRARY_PATH=/path/to/target/library AFL_UNTRACER_FILE=./patches.txt afl-fuzz -i in -o out -- ./afl-untracer
43```
44(or even remote via afl-network-proxy).
45
46### Testing and debugging
47
48For testing/debugging you can try:
49```
50make DEBUG=1
51AFL_UNTRACER_FILE=./patches.txt AFL_DEBUG=1 gdb ./afl-untracer
52```
53and then you can easily set breakpoints to "breakpoint" and "fuzz".
54
55# Background
56
57This idea is based on [UnTracer](https://github.com/FoRTE-Research/UnTracer-AFL)
58and modified by [Trapfuzz](https://github.com/googleprojectzero/p0tools/tree/master/TrapFuzz).
59This implementation is slower because the traps are not patched out with each
60run, but on the other hand gives much better coverage information.
61