# 0vercl0k/wtf architecture

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

- Interactive diagram: https://gitdiagram.com/0vercl0k/wtf
- Repository: https://github.com/0vercl0k/wtf

## Overview

##### Project Type and Purpose
- **Type**: A command-line, distributed master-worker (server/client) application written in C++.
- **Purpose**: “what the fuzz” (wtf) is a cross-platform, snapshot-based, coverage-guided fuzzer. It drives targets (user-mode or kernel-mode on Windows, experimental Linux mode) inside emulators or hypervisors, collects coverage and crash data, and orchestrates fuzzing in a distributed fashion.

##### High-Level Components
a. **CLI Layer**
- Entry point: `wtf.exe` managed by CLI11 (src/libs/CLI11).
- Subcommands:
– `master` (server)
– `fuzz` (client)
– `run`, `minset`, `trace`
b. **Core Engine**
- Command dispatcher & option parsing
- Master node logic (corpus management, aggregated coverage, test-case scheduling)
- Client node logic (fetch test-case, execute, report results)
- Common abstractions:
– `Target_t` (harness modules)
– `Mutator_t` interface (libfuzzer, honggfuzz, custom)
– `Backend_t` interface (bochscpu, WHV, KVM)
c. **Execution Backends** (`src/wtf/*_backend.*`)
- bochscpu_backend (emulator)
- whv_backend (Windows Hypervisor Platform)
- kvm_backend (Linux KVM)
d. **Fuzzer Modules** (`src/wtf/fuzzer_*.cc`)
- Init(), InsertTestcase(), Restore(), Crash detection, End-of-test conditions
- Provide: custom generators or mutators
e. **Communication Layer**
- Socket abstraction (`src/wtf/socket.{cc,h}`) for TCP/UDP between master and clients
f. **File-System State**
- `targets/<name>/` – subfolders: `inputs/`, `outputs/`, `coverage/`, `crashes/`, `state/`
- Master stores aggregated coverage in `coverage.cov`
- Clients read/write per-target directories
g. **External Libraries & Tools**
- BLAKE3 for hashing (src/libs/BLAKE3)
- JSON (nlohmann/json) – coverage file, symbol store
- fmt, robin-map, yas, kdmp-parser, libfuzzer, honggfuzz, CLI11, etc.
- Python scripts in `scripts/` for generating coverage breakpoints
h. **Build System**
- CMakeLists.txt in `src/`
- Cross-platform build scripts in `src/build/`

##### Component Interactions and Data Flow
- **Startup**: User runs `wtf.exe <subcommand> [options]`.
- **Master**:
1. Loads target state (snapshot, symbol-store.json).
2. Scans current corpus (`inputs`, `outputs`).
3. Opens listening socket.
4. Schedules test-cases to clients.
5. Aggregates coverage updates & new inputs.
- **Client**:
1. Connects to master over network.
2. Requests and receives a test-case.
3. Invokes `InsertTestcase()` in the fuzzer module to feed input into the target.
4. Chooses a backend: emulator (bochscpu) or hypervisor (WHV/KVM).
5. Executes the target snapshot until completion/timeout/crash.
6. Captures coverage (`.cov` file), crash info, optionally trace data.
7. Sends results back to master.
- **Mutator**: Generates or mutates raw input bytes, invoked by client prior to execution.
- **State Storage**: All intermediate files (mem.dmp, regs.json, coverage fragments, crashes) live on disk under the target directory.

##### Architectural Patterns & Principles
- **Master-Worker Pattern**: Central server delegates work to multiple fuzzing clients.
- **Plugin-style Interfaces**: Abstract `Mutator_t` and `Backend_t` allow easy addition of new fuzzers/backends.
- **Layered Architecture**:
– CLI layer
– Core engine (orchestration)
– Backend/Mutator modules
– OS/emulator

##### Relevant Technologies & Frameworks
- C++17, CMake, Ninja / MSVC solution
- CLI parsing: CLI11
- Hashing: BLAKE3
- JSON: nlohmann/json
- Coverage & breakpoint generation: Python scripts (`gen_coveragefile_*.py`)
- Emulation & virtualization: bochscpu, Windows Hypervisor Platform (WHV), Linux KVM
- Fuzzing primitives: libfuzzer, honggfuzz (via `Mutator_t`)

##### Essential Details to Capture
- Master’s role in scheduling and aggregating coverage.
- Client’s plugin points: fuzzer modules, mutators, backends.
- Shared file-system state under `targets/`.
- Key external dependencies and build system.
- Data flows: test-cases, coverage, crash reports, traces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["wtf.exe (Entry Point)"]:::cli
        Subcmd["Subcommands (master, fuzz, run, minset, trace)"]:::cli
        CLI --> Subcmd
    end
    click CLI "https://github.com/0vercl0k/wtf/blob/main/src/wtf/wtf.cc"
    click Subcmd "https://github.com/0vercl0k/wtf/blob/main/src/wtf/subcommands.cc"
    click Subcmd "https://github.com/0vercl0k/wtf/blob/main/src/wtf/subcommands.h"

    %% Master (Server)
    subgraph "Server (Master)"
        direction TB
        subgraph "Core Engine"
            Dispatcher["Command Dispatcher & Option Parsing"]:::core
            MasterLogic["Master Node Logic"]:::core
            CorpusMgmt_S["Corpus Management"]:::core
            Socket_S["Socket (TCP/UDP)"]:::comm
            Dispatcher --> MasterLogic
            MasterLogic --> CorpusMgmt_S
            MasterLogic --> Socket_S
        end
    end
    click Dispatcher "https://github.com/0vercl0k/wtf/blob/main/src/wtf/utils.cc"
    click Dispatcher "https://github.com/0vercl0k/wtf/blob/main/src/wtf/utils.h"
    click MasterLogic "https://github.com/0vercl0k/wtf/blob/main/src/wtf/server.h"
    click CorpusMgmt_S "https://github.com/0vercl0k/wtf/blob/main/src/wtf/corpus.h"
    click Socket_S "https://github.com/0vercl0k/wtf/blob/main/src/wtf/socket.cc"
    click Socket_S "https://github.com/0vercl0k/wtf/blob/main/src/wtf/socket.h"

    %% Client (Fuzz/Run)
    subgraph "Client (Fuzz/Run)"
        direction TB
        subgraph "Core Engine"
            ClientLogic["Client Node Logic"]:::core
            CorpusMgmt_C["Corpus Management"]:::core
            CrashDetect["Crash Detection (User-Mode)"]:::core
            Socket_C["Socket (TCP/UDP)"]:::comm
            MutatorIF["Mutator_t Interface"]:::backend
            BackendIF["Backend_t Interface"]:::backend

            ClientLogic --> CorpusMgmt_C
            ClientLogic --> CrashDetect
            ClientLogic --> Socket_C
            ClientLogic --> MutatorIF
            ClientLogic --> BackendIF
        end
        subgraph "Backends & Mutators"
            direction TB
            subgraph "Backends"
                Boch["bochscpu_backend"]:::backend
                WHV["whv_backend"]:::backend
                KVM["kvm_backend"]:::backend
                MutatorIF --> Boch
                MutatorIF --> WHV
                MutatorIF --> KVM
            end
            subgraph "Fuzzer Modules"
                Dummy["fuzzer_dummy.cc"]:::backend
                HEVD["fuzzer_hevd.cc"]:::backend
                IOCTL["fuzzer_ioctl.cc"]:::backend
                LinuxCrash["fuzzer_linux_crash_test.cc"]:::backend
                LinuxPF["fuzzer_linux_page_fault_test.cc"]:::backend
                TLV["fuzzer_tlv_server.cc"]:::backend
                HGF["honggfuzz Integration"]:::backend
                MutatorIF --> Dummy
                MutatorIF --> HEVD
                MutatorIF --> IOCTL
                MutatorIF --> LinuxCrash
                MutatorIF --> LinuxPF
                MutatorIF --> TLV
                MutatorIF --> HGF
            end
        end
    end
    click ClientLogic "https://github.com/0vercl0k/wtf/blob/main/src/wtf/client.cc"
    click ClientLogic "https://github.com/0vercl0k/wtf/blob/main/src/wtf/client.h"
    click CorpusMgmt_C "https://github.com/0vercl0k/wtf/blob/main/src/wtf/corpus.h"
    click CrashDetect "https://github.com/0vercl0k/wtf/blob/main/src/wtf/crash_detection_umode.cc"
    click CrashDetect "https://github.com/0vercl0k/wtf/blob/main/src/wtf/crash_detection_umode.h"
    click Socket_C "https://github.com/0vercl0k/wtf/blob/main/src/wtf/socket.cc"
    click Socket_C "https://github.com/0vercl0k/wtf/blob/main/src/wtf/socket.h"
    click MutatorIF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/mutator.cc"
    click MutatorIF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/mutator.h"
    click BackendIF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/backend.cc"
    click BackendIF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/backend.h"
    click Boch "https://github.com/0vercl0k/wtf/blob/main/src/wtf/bochscpu_backend.cc"
    click Boch "https://github.com/0vercl0k/wtf/blob/main/src/wtf/bochscpu_backend.h"
    click WHV "https://github.com/0vercl0k/wtf/blob/main/src/wtf/whv_backend.cc"
    click WHV "https://github.com/0vercl0k/wtf/blob/main/src/wtf/whv_backend.h"
    click KVM "https://github.com/0vercl0k/wtf/blob/main/src/wtf/kvm_backend.cc"
    click KVM "https://github.com/0vercl0k/wtf/blob/main/src/wtf/kvm_backend.h"
    click Dummy "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_dummy.cc"
    click HEVD "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_hevd.cc"
    click IOCTL "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_ioctl.cc"
    click LinuxCrash "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_linux_crash_test.cc"
    click LinuxPF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_linux_page_fault_test.cc"
    click TLV "https://github.com/0vercl0k/wtf/blob/main/src/wtf/fuzzer_tlv_server.cc"
    click HGF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/honggfuzz.cc"
    click HGF "https://github.com/0vercl0k/wtf/blob/main/src/wtf/honggfuzz.h"

    %% Network
    subgraph "Network" 
        direction TB
        MasterLogic -->|"test-case"| ClientLogic
        ClientLogic -->|"results (coverage, crashes)"| MasterLogic
    end

    %% File-System State
    FS["targets/ (inputs/, outputs/, coverage/, crashes/, state/)"]:::fs
    MasterLogic --> FS
    ClientLogic --> FS
    click FS "https://github.com/0vercl0k/wtf/tree/main/targets/"

    %% Scripts
    subgraph "Scripts"
        genBinja["gen_coveragefile_binja.py"]:::ext
        genGhidra["gen_coveragefile_ghidra.py"]:::ext
        genIda["gen_coveragefile_ida.py"]:::ext
        genBinja -->|generate breakpoints| Dispatcher
        genGhidra -->|generate breakpoints| Dispatcher
        genIda -->|generate breakpoints| Dispatcher
    end
    click genBinja "https://github.com/0vercl0k/wtf/blob/main/scripts/gen_coveragefile_binja.py"
    click genGhidra "https://github.com/0vercl0k/wtf/blob/main/scripts/gen_coveragefile_ghidra.py"
    click genIda "https://github.com/0vercl0k/wtf/blob/main/scripts/gen_coveragefile_ida.py"

    %% External Libraries
    subgraph "External Libraries & Build"
        direction TB
        CLI11["CLI11"]:::ext
        BLAKE3["BLAKE3"]:::ext
        JSONLib["nlohmann/json"]:::ext
        FMT["fmt"]:::ext
        Robin["robin-map"]:::ext
        YAS["yas"]:::ext
        KDMP["kdmp-parser"]:::ext
        LibFuzz["libfuzzer"]:::ext
        CMake["CMakeLists.txt & build/"]:::ext

        CLI11 --> CLI
        BLAKE3 --> Dispatcher
        JSONLib --> Dispatcher
        FMT --> Dispatcher
        Robin --> Dispatcher
        YAS --> Dispatcher
        KDMP --> Dispatcher
        LibFuzz --> Dummy
        CMake --> Dispatcher
    end
    click CLI11 "https://github.com/0vercl0k/wtf/tree/main/src/libs/CLI11/"
    click BLAKE3 "https://github.com/0vercl0k/wtf/tree/main/src/libs/BLAKE3/"
    click JSONLib "https://github.com/0vercl0k/wtf/tree/main/src/libs/json/"
    click FMT "https://github.com/0vercl0k/wtf/tree/main/src/libs/fmt/"
    click Robin "https://github.com/0vercl0k/wtf/tree/main/src/libs/robin-map/"
    click YAS "https://github.com/0vercl0k/wtf/tree/main/src/libs/yas/"
    click KDMP "https://github.com/0vercl0k/wtf/tree/main/src/libs/kdmp-parser/"
    click LibFuzz "https://github.com/0vercl0k/wtf/tree/main/src/libs/libfuzzer/"
    click CMake "https://github.com/0vercl0k/wtf/blob/main/src/CMakeLists.txt"
    click CMake "https://github.com/0vercl0k/wtf/tree/main/src/build/"

    %% Styling
    classDef cli fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef comm fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef fs fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef ext fill:#e2e3e5,stroke:#333,stroke-width:1px
```
