# aflplusplus/libafl architecture

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

- Interactive diagram: https://gitdiagram.com/aflplusplus/libafl
- Repository: https://github.com/aflplusplus/libafl

## Overview

Below are the main guidelines and components to include:

##### Main Components
- Core Fuzzing Libraries – Represent the primary “engine” components such as:
- libafl (the core building blocks for input handling, scheduling, feedbacks, mutators, and stages)
- libafl_targets (instrumentation backends such as SanitizerCoverage and other target-specific code)
- libafl_cc (facilitates compiler wrapping/instrumentation for source-based fuzzing)
- Additional core crates like libafl_bolts (utility functions for randomness, shmem, and system-level interactions)
- Integrations/Backends – Show separate modules/layers for each supported instrumentation framework:
- Frida support (libafl_frida)
- QEMU-based instrumentation (libafl_qemu)
- TinyInst integration (libafl_tinyinst)
- Concolic execution (libafl_concolic)
- Other targets (e.g. libafl_intelpt, libafl_unicorn).
- Fuzzer Implementations – There is a large “fuzzers” directory containing a huge variety of example fuzzers:
- In-process fuzzers (e.g. fuzzers/inprocess/*)
- Forkserver based fuzzers (e.g. fuzzers/forkserver/*)
- System and binary-only fuzzers (e.g. fuzzers/full_system/*, fuzzers/binary_only/*)
- WebAssembly fuzzers and others.
- Supporting Tools and Utilities – Other directories such as “docs”, “just”, “scripts”, and “utils” are important for building, testing, and demonstrating the overall framework.

##### Relationships and Interactions
- The core libraries form the “heart” of the system. They expose interfaces for feedback, scheduling, mutating inputs, and running target executables. These libraries are then used by the fuzzer implementations.
- Each fuzzer (found inside the fuzzers/ folder) uses one or more of the core libraries and then applies further customization, such as custom executors or instrumented harnesses.
- The integration modules (e.g., libafl_frida, libafl_qemu, libafl_tinyinst) bridge between the core fuzzing internals and external instrumentation frameworks—either through process injection, emulation, or compiler instrumentation.
- Message passing and multi-machine support (LLMP) are built into the libraries and provide data flow between fuzzers running across cores or machines.

##### Architectural Patterns and Design Principles
- Extensibility: The design intentionally allows replacing components (for example, using a different executor or mutator). Illustrate these components with “pluggable” interfaces.
- Lightweight message passing and multi-thread scalability: Emphasize the LLMP component which is used for inter-process and inter-machine communication.
- Multi-platform support: The project’s design supports multiple operating systems and architectures. Although this might be noted as a non-functional requirement, you could denote support across several platforms at a high level.

##### Additional Elements
- If space allows, include notes regarding how configuration is injected into the system (via Justfiles, Cargo build scripts, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["LibAFL Framework"]:::framework

    %% Core Libraries Subgraph
    subgraph "Core Libraries"
        %% Core Components
        subgraph "Core Components"
            B["libafl"]:::core
            C["libafl_targets"]:::core
            D["libafl_cc"]:::core
            E["libafl_bolts"]:::core
        end
        %% Integrations/Backends
        subgraph "Integrations/Backends"
            F["libafl_frida"]:::integration
            G["libafl_qemu"]:::integration
            H["libafl_tinyinst"]:::integration
            I["libafl_concolic"]:::integration
            J["libafl_intelpt"]:::integration
            K["libafl_unicorn"]:::integration
        end
    end

    %% Example Fuzzer Engines Subgraph
    subgraph "Example Fuzzer Engines"
        L["Fuzzer Implementations"]:::fuzzer
    end

    %% Supporting Tools Subgraph
    subgraph "Supporting Tools"
        M["Documentation"]:::tool
        N["Build & Test Scripts"]:::tool
        O["Utilities"]:::tool
        P["Python Bindings"]:::tool
    end

    %% Top-level Connections
    A --> B
    A --> L
    A --> M

    %% Fuzzer Implementations use Core Components
    L -->|"uses"| B
    L -->|"uses"| C
    L -->|"uses"| D
    L -->|"uses"| E

    %% Fuzzer Implementations integrate with Integration Modules
    L -->|"integrates"| F
    L -->|"integrates"| G
    L -->|"integrates"| H
    L -->|"integrates"| I
    L -->|"integrates"| J
    L -->|"integrates"| K

    %% Click Events for Core Libraries
    click B "https://github.com/aflplusplus/libafl/tree/main/libafl"
    click C "https://github.com/aflplusplus/libafl/tree/main/libafl_targets"
    click D "https://github.com/aflplusplus/libafl/tree/main/libafl_cc"
    click E "https://github.com/aflplusplus/libafl/tree/main/libafl_bolts"

    %% Click Events for Integration Modules
    click F "https://github.com/aflplusplus/libafl/tree/main/libafl_frida"
    click G "https://github.com/aflplusplus/libafl/tree/main/libafl_qemu"
    click H "https://github.com/aflplusplus/libafl/tree/main/libafl_tinyinst"
    click I "https://github.com/aflplusplus/libafl/tree/main/libafl_concolic"
    click J "https://github.com/aflplusplus/libafl/tree/main/libafl_intelpt"
    click K "https://github.com/aflplusplus/libafl/tree/main/libafl_unicorn"

    %% Click Event for Fuzzer Implementations
    click L "https://github.com/aflplusplus/libafl/tree/main/fuzzers"

    %% Click Events for Supporting Tools
    click M "https://github.com/aflplusplus/libafl/tree/main/docs"
    click N "https://github.com/aflplusplus/libafl/tree/main/scripts"
    click O "https://github.com/aflplusplus/libafl/tree/main/utils"
    click P "https://github.com/aflplusplus/libafl/tree/main/bindings/pylibafl"

    %% Style Definitions
    classDef framework fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef integration fill:#FFE082,stroke:#FFA000,stroke-width:2px;
    classDef fuzzer fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef tool fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
