How google/afl works
Project Type and Purpose
• american fuzzy lop (AFL) is an open-source, command-line guided fuzzing framework written in C.
• It provides a core fuzzing engine (afl-fuzz), compiler wrappers for compile-time instrumentation (afl-gcc, afl-clang, afl-as), and support for binary-only instrumentation via QEMU.
• Supplementary tools include testcase minimizers (afl-cmin, afl-tmin), analyzers (afl-analyze, afl-showmap), plot generators (afl-plot), and helper libraries (libdislocator, libtokencap).
a. User Interface / CLI
• afl-fuzz (driver)
• Compiler wrappers: afl-gcc, afl-g++, afl-clang, afl-clang++
• QEMU build script and qemu_mode patch set
• Auxiliary utilities: afl-cmin, afl-tmin, afl-analyze, afl-showmap, afl-plot, afl-whatsup
b. Fuzzing Engine Core
• Genetic algorithm & mutation engine (afl-fuzz.c)
• Shared memory coverage instrumentation (config.h, alloc-inl.h, debug.h)
• Fork server mechanism
c. Instrumentation Layers
• Compile-time instrumentation (wrapper front-ends + afl-as assembler)
• QEMU user-mode instrumentation layer
• LLVM mode instrumentation (llvm_mode directory)
d. Helper Libraries
• libdislocator: heap-corruption detection support
• libtokencap: token-capture for dictionary generation
e. Data Stores / File System
• Input corpus directory (–i)
• Output directory (–o) containing queue/, crashes/, hangs/
• dictionaries/ (language-specific token lists)
• testcases/ (sample files for coverage of various formats)
f. External Dependencies
• System toolchain: gcc/clang, make
• QEMU user-mode emulator
• Gnuplot (optional, for afl-plot)
• POSIX OS services (fork, shared memory, file I/O)
Relationships and Data Flow
• The user invokes afl-fuzz, pointing to an input corpus and an output directory.
• afl-fuzz initializes the queue from the input corpus and spawns the target process under instrumentation.
• Shared memory is mapped between afl-fuzz and the instrumented target to report edge coverage.
• The fuzzing engine reads coverage feedback, applies mutation strategies (optionally seeded by dictionaries/), and writes mutated test cases to queue/.
• Crashing or hanging inputs are copied to crashes/ and hangs/.
• Compiler wrappers inject instrumentation code at compile time; QEMU mode rewrites binaries on the fly.
• Utilities (afl-cmin, afl-tmin) operate on the queue or crash corpus to minimize test cases.
• Visualization and analysis tools read coverage logs or output directories to produce plots or reports.
Architectural Patterns and Design Principles
• Modular CLI-tool architecture: each utility is a standalone C binary.
• Plugin-like instrumentation: multiple modes (gcc wrapper, llvm, QEMU) share a common coverage protocol.
• Fork-server design: low-overhead repeated execution of target processes.
• File-centric dataflow: test cases are plain files in well-defined directories.
• Shared memory for IPC: efficient feedback channel between fuzzer and target.
Essential Details Not to Overlook
• The shared memory coverage map is a central IPC mechanism.
• The fork-server drastically reduces process startup overhead.
• Wrappers (afl-gcc/afl-clang) are drop-in replacements for standard compilers.
• Output directory is partitioned into queue/, crashes/, hangs/—key for understanding results storage.
• Experimental subdirectories illustrate how new fuzzing strategies or target modifications can be integrated.