# seemoo-lab/virtfuzz architecture

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

- Interactive diagram: https://gitdiagram.com/seemoo-lab/virtfuzz
- Repository: https://github.com/seemoo-lab/virtfuzz

## Overview

##### Project Type and Purpose
- Type: A specialized fuzzing framework for the Linux kernel’s wireless subsystems
- Purpose: Drive VirtIO devices in a QEMU VM, inject fuzzed I/O, collect coverage via KCOV, analyze crashes, and support replay and minimization.

##### File Structure
Top-level crates and directories:
- src/            – Core library (coverage handling, feedback loops, input gen, observer abstractions, QEMU executor, UI)
- fuzz/           – Fuzzer binary (virtfuzz-fuzz)
- proxy/          – Proxy binary (virtfuzz-proxy) for device I/O forwarding
- replay/         – Replayer/minimizer binary (virtfuzz-replay)
- device-definitions/ – JSON specs for various VirtIO devices
- guestimage/     – Scripts and configs to build the VM image
- kernel-patches/ – Patches to instrument Linux kernel (KCOV, VirtIO drivers)
- kernel-config/  – Kernel config fragments for KASAN, UBSAN, etc.
- resources/      – Sample PCAP init sequences and test logs
- setup-scripts/  – Helpers for building QEMU, guest image, and kernel

##### README Insights
- Core workflows: build patched QEMU, build guest image, patch & compile kernel, run fuzzer with JSON device definitions
- Dependencies: Rust & Cargo, QEMU, Linux kernel source
- Components: virtfuzz-fuzz, virtfuzz-proxy, virtfuzz-replay

##### Core Components
a. Fuzzer Engine (Rust, LibAFL)
b. QEMU VM (patched system-emulator binary)
c. Guest VM image (Debian-based, contains virtfuzz agents)
d. Patched Linux Kernel (KCOV-instrumented, VirtIO drivers)
e. VirtIO Device Definitions (JSON files)
f. Proxy Service (network/bluetooth forwarding)
g. Coverage Collector (KCOV via IVSHMEM backchannel)
h. Replay/Minimization Suite (crash reproducers, metadata handlers)
i. External Resources (PCAP init scripts, device definitions)

##### Relationships & Interactions
- The Fuzzer Engine launches one or more QEMU instances via the QEMU Executor module
- Each VM boots the Guest Image with the patched kernel
- VirtIO devices inside the VM are driven by fuzzed packets generated by the Fuzzer Engine according to JSON specs
- The Proxy (virtfuzz-proxy) sits between the Fuzzer Engine and the VM’s VirtIO ports for I/O forwarding or command fake-complete
- Observers in the fuzzer engine listen on the IVSHMEM channel for KCOV coverage data and on QEMU’s stdio/dmesg outputs
- Feedback loops in the fuzzer use coverage statistics to guide mutation of inputs
- Crashes or hangs trigger the Replay component, which reads saved inputs and metadata to reproduce and minimize

##### Architectural Patterns & Principles
- Modular Rust crates: separation of core library, binaries, and utilities
- Feedback-driven fuzzing loop (LibAFL)
- Virtualization boundary: host tool vs. guest VM
- Extensibility via JSON device definitions and PCAP initialization sequences
- Coverage collection out-of-band using KCOV→IVSHMEM

##### Technology Stack Highlights
- Rust + Cargo for all core logic
- LibAFL for mutation and scheduling
- QEMU (patched via qemu-patch.patch) for virtualization
- Linux Kernel (patched and configured) with KCOV instrumentation
- JSON for device definitions
- PCAP files for initialization sequences
- Bash scripts for image/kernel setup

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Side"
        FB["Fuzzer Binary (virtfuzz-fuzz)"]:::host
        FE["Fuzzer Engine"]:::host
        Proxy["Proxy Service (virtfuzz-proxy)"]:::host
        Replay["Replay & Minimization Suite"]:::host
        ExtRes["Device Definitions & PCAP Resources"]:::external
        QP["QEMU Patch"]:::external
        KCfg["Kernel Configuration Fragments"]:::external
        Setup["Setup Scripts"]:::external
    end

    subgraph "Fuzzer Engine Modules"
        IG["Input Generator"]:::control
        Mut["Mutator"]:::control
        Sch["Scheduler"]:::control
        QE["QEMU Executor"]:::control
        Obs["Observers"]:::control
        KCOV["KCOV Reader"]:::control
        DM["dmesg Monitor"]:::control
    end

    subgraph "Guest Side"
        VM["QEMU VM Instance"]:::guest
        GI["Guest VM Image"]:::guest
        PK["Patched Linux Kernel"]:::guest
        VD["VirtIO Devices"]:::guest
    end

    FB -->|"uses core lib"| FE
    FE -->|"initialize"| IG
    FE -->|"initialize"| Mut
    FE -->|"initialize"| Sch
    FE -->|"launch VM"| QE
    FE -->|"monitor"| Obs
    Obs -->|"reads"| KCOV
    Obs -->|"reads"| DM
    FE -->|"on crash"| Replay
    FE -->|"use definitions"| ExtRes
    FE -->|"fuzz packets"| Proxy
    Proxy -->|"forward I/O"| VM
    QE -->|"start VM"| VM
    VM -->|"coverage data"| KCOV
    VM -->|"logs"| DM
    VM -->|"contains"| GI
    VM -->|"runs"| PK
    VM -->|"drives"| VD

    classDef host fill:#eef,stroke:#339,stroke-width:2px
    classDef guest fill:#efe,stroke:#393,stroke-width:2px
    classDef control fill:#ccf,stroke:#228,stroke-width:2px
    classDef external fill:#fec,stroke:#e64,stroke-width:2px

    class FB,FE,Proxy,Replay host
    class IG,Mut,Sch,QE,Obs,KCOV,DM control
    class VM,GI,PK,VD guest
    class ExtRes,QP,KCfg,Setup external

    click FE "https://github.com/seemoo-lab/virtfuzz/blob/main/src/lib.rs"
    click IG "https://github.com/seemoo-lab/virtfuzz/tree/main/src/input/"
    click Mut "https://github.com/seemoo-lab/virtfuzz/tree/main/src/feedback/"
    click Sch "https://github.com/seemoo-lab/virtfuzz/tree/main/src/feedback/"
    click QE "https://github.com/seemoo-lab/virtfuzz/blob/main/src/qemu/executor.rs"
    click Proxy "https://github.com/seemoo-lab/virtfuzz/blob/main/proxy/src/main.rs"
    click Replay "https://github.com/seemoo-lab/virtfuzz/blob/main/replay/src/main.rs"
    click ExtRes "https://github.com/seemoo-lab/virtfuzz/tree/main/device-definitions/"
    click ExtRes "https://github.com/seemoo-lab/virtfuzz/tree/main/resources/"
    click VM "https://github.com/seemoo-lab/virtfuzz/tree/main/guestimage/"
    click GI "https://github.com/seemoo-lab/virtfuzz/tree/main/guestimage/"
    click PK "https://github.com/seemoo-lab/virtfuzz/tree/main/kernel-patches/"
    click KCOV "https://github.com/seemoo-lab/virtfuzz/blob/main/kcovreader/src/lib.rs"
    click DM "https://github.com/seemoo-lab/virtfuzz/blob/main/src/observer/kcov.rs"
    click FB "https://github.com/seemoo-lab/virtfuzz/blob/main/fuzz/src/main.rs"
    click QP "https://github.com/seemoo-lab/virtfuzz/blob/main/qemu-patch.patch"
    click KCfg "https://github.com/seemoo-lab/virtfuzz/tree/main/kernel-config/"
    click Setup "https://github.com/seemoo-lab/virtfuzz/tree/main/setup-scripts/"
```
