# google/afl architecture

> Architecture diagram of the GitHub repository google/afl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/afl
- Repository: https://github.com/google/afl

## Overview

##### 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 test­case 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actor
    User["User"]:::actor

    subgraph "User Interface / CLI"
        UF["afl-fuzz"]:::cli
        AGC["afl-gcc"]:::cli
        ACF["afl-clang-fast"]:::cli
        AA["afl-as"]:::cli
        ACM["afl-cmin"]:::cli
        ATM["afl-tmin"]:::cli
        ANA["afl-analyze"]:::cli
        ASM["afl-showmap"]:::cli
        APL["afl-plot"]:::cli
        AWP["afl-whatsup"]:::cli
    end

    subgraph "Fuzzing Engine Core"
        ME["Mutation Engine & Fork Server"]:::core
        SM["Shared Memory Coverage"]:::core
    end

    subgraph "Instrumentation Layers"
        CTI["Compile-time Instrumentation"]:::instr
        LM["LLVM Mode"]:::instr
        QM["QEMU Mode"]:::instr
        TP["Instrumented Target"]:::instr
    end

    subgraph "Helper Libraries"
        LD["libdislocator"]:::lib
        LT["libtokencap"]:::lib
    end

    subgraph "Data Stores / File System"
        IN["Input Corpus (–i)"]:::ds
        QD["queue/"]:::ds
        CD["crashes/"]:::ds
        HD["hangs/"]:::ds
        DICT["dictionaries/"]:::ds
        TC["testcases/"]:::ds
    end

    subgraph "External Dependencies"
        CC["gcc/clang, make"]:::ext
        QE["QEMU emulator"]:::ext
        GN["Gnuplot"]:::ext
        OS["POSIX OS services"]:::ext
    end

    %% Data & control flow
    User -->|invokes| UF
    UF -->|reads| IN
    UF -->|initializes| ME
    DICT -->|seeds| ME
    ME -->|spawn target| TP
    TP -->|coverage data| SM
    SM -->|feedback| ME
    ME -->|writes mutated cases| QD
    QD -->|inputs| TP
    ME -->|copies crashes| CD
    ME -->|copies hangs| HD

    AGC --> CTI
    ACF --> CTI
    AA --> CTI
    CTI --> TP

    LM --> TP
    QM --> TP

    %% Utilities
    ACM -->|minimize| QD
    ATM -->|minimize| CD
    ANA -->|analyze| QD
    ASM -->|show map| QD
    APL -->|plot| QD
    AWP -->|status| QD

    %% Helpers link into target
    LD --> TP
    LT --> TP

    %% External deps
    CC --> AGC
    CC --> ACF
    QE --> QM
    GN --> APL
    OS --> SM
    OS --> ME

    %% Click events
    click UF "https://github.com/google/afl/blob/master/afl-fuzz.c"
    click AGC "https://github.com/google/afl/blob/master/afl-gcc.c"
    click ACF "https://github.com/google/afl/blob/master/llvm_mode/afl-clang-fast.c"
    click AA "https://github.com/google/afl/blob/master/afl-as.c"
    click ACM "https://github.com/google/afl/tree/master/afl-cmin"
    click ATM "https://github.com/google/afl/blob/master/afl-tmin.c"
    click ANA "https://github.com/google/afl/blob/master/afl-analyze.c"
    click ASM "https://github.com/google/afl/blob/master/afl-showmap.c"
    click APL "https://github.com/google/afl/tree/master/afl-plot"
    click AWP "https://github.com/google/afl/tree/master/afl-whatsup"
    click CTI "https://github.com/google/afl/blob/master/afl-gcc.c"
    click CTI "https://github.com/google/afl/blob/master/afl-as.c"
    click LM "https://github.com/google/afl/blob/master/llvm_mode/afl-clang-fast.c"
    click QM "https://github.com/google/afl/blob/master/qemu_mode/build_qemu_support.sh"
    click LD "https://github.com/google/afl/tree/master/libdislocator/Makefile"
    click LT "https://github.com/google/afl/tree/master/libtokencap/Makefile"
    click DICT "https://github.com/google/afl/tree/master/dictionaries/"
    click TC "https://github.com/google/afl/tree/master/testcases/"

    %% Styles
    classDef actor fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef cli fill:#d0e6f6,stroke:#333,stroke-width:1px;
    classDef core fill:#f6d0b0,stroke:#333,stroke-width:1px;
    classDef instr fill:#d0f6d8,stroke:#333,stroke-width:1px;
    classDef lib fill:#f6d0d0,stroke:#333,stroke-width:1px;
    classDef ds fill:#f6f2d0,stroke:#333,stroke-width:1px;
    classDef ext fill:#cccccc,stroke:#333,stroke-width:1px;
```
