# rub-syssec/nyx architecture

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

- Interactive diagram: https://gitdiagram.com/rub-syssec/nyx
- Repository: https://github.com/rub-syssec/nyx

## Overview

##### Project type and purpose
- Nyx is an open-source greybox hypervisor fuzzer for type-2 hypervisors (bhyve, QEMU).
- It builds on three main components:
- KVM-PT: a Linux kernel module that exposes Intel-PT tracing per vCPU, nested hypercalls, dirty-memory tracking, etc.
- QEMU-PT: a patched QEMU (user-space) that implements corresponding hypercall handlers, fast snapshots, and an Intel-PT decoder.
- Nyx-Fuzzer: a Rust-based fuzzing engine (cargo “rust_fuzzer” crate + fuzz_runner + helpers + hypervisor_spec) orchestrating the fuzzing loop, snapshot management, and corpus.

##### File structure
- Top‐level directories:
- KVM-PT/ – the standalone LKM source + build scripts (load.sh) + headers.
- QEMU-PT/ – QEMU patch + compile script + QEMU source archive.
- Targets/ – per-hypervisor fuzz targets (bhyve & QEMU) each containing VM setup, “agent” code (guest-side loader, req_data, set_ip_range), config templates.
- nyx_fuzzer/ – the Rust workspace:
– config/ – config crate for shared spec formats (msgpack)
– fuzz_runner/ – binary crate implementing forkserver, coverage reporting loop, affine-type harness
– helpers/ – common Rust utilities (hash_by_ref, etc.)
– hypervisor_spec/ – Python- and C-based tooling to generate custom micro-OS images (“hypertrash_os”), ISO, GRUB patches, Tesseract intermediate decompiler, etc.
– rust_fuzzer/ – the main fuzzer binary (“cargo run ‑-release”)
– structured_fuzzer/ – a separate Rust crate for generative, structured-input fuzzing (examples, interpreter, spec_lib, graph_mutator, primitive_mutator)

##### README for additional insights
- Describes dependencies, build steps, and three stages:
a) install & load KVM-PT (kernel module)
b) build & run QEMU-PT
c) build GRUB & hypertrash_os (hypervisor_spec)
d) build & run Rust fuzzer against bhyve or QEMU targets

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host Kernel Layer
    subgraph "Host Kernel (L0)"
        KVMPT["KVM-PT (LKM)"]:::kernel
    end

    %% Host User-Space Layer
    subgraph "Host User-Space (L1)"
        QEMUPT["QEMU-PT / bhyve"]:::vmm
        SharedDir["Shared Directory"]:::storage
        subgraph "Nyx-Fuzzer Workspace"
            ConfigCrate["config crate"]:::rust
            FuzzRunner["fuzz_runner"]:::rust
            Helpers["helpers"]:::rust
            RustFuzzer["rust_fuzzer"]:::rust
            StructuredFuzzer["structured_fuzzer"]:::rust
        end
        HypervisorSpec["hypervisor_spec tooling"]:::spec
    end

    %% Guest VM Layer
    subgraph "Target VMs (L2)"
        BhyveTarget["bhyve target VM"]:::guest
        QemuTarget["QEMU target VM"]:::guest
        subgraph "Guest VM Contents"
            GuestOS["Guest OS (FreeBSD/Ubuntu/hypertrash_os)"]:::guest
            GuestAgent["guest-agent"]:::ccomp
        end
    end

    %% Offline Spec Generation
    HypervisorSpec -->|"builds ISO"| GuestOS

    %% Fuzzer spawning VMM
    FuzzRunner -->|"spawn VMM with config.ron"| QEMUPT

    %% VMM to Kernel hypercalls
    QEMUPT -->|"ioctl/hypercall\n(snapshot+coverage)"| KVMPT
    KVMPT -->|"coverage data via\nioctl/hypercall"| QEMUPT

    %% Shared directory sync
    GuestAgent -->|"reads/writes"| SharedDir
    RustFuzzer -->|"reads crashes & corpus\nwrites inputs/logs"| SharedDir

    %% Fuzzer components interactions
    RustFuzzer -->|uses| ConfigCrate
    RustFuzzer -->|uses| Helpers
    RustFuzzer -->|launches| FuzzRunner
    RustFuzzer -->|optionally uses| StructuredFuzzer

    %% Guest relationship to VM targets
    GuestOS -->|runs on| BhyveTarget
    GuestOS -->|runs on| QemuTarget
    GuestAgent -->|deployed in| GuestOS

    %% Click Events
    click KVMPT "https://github.com/rub-syssec/nyx/tree/main/KVM-PT/"
    click QEMUPT "https://github.com/rub-syssec/nyx/tree/main/QEMU-PT/"
    click BhyveTarget "https://github.com/rub-syssec/nyx/tree/main/Targets/bhyve/"
    click QemuTarget "https://github.com/rub-syssec/nyx/tree/main/Targets/qemu/"
    click ConfigCrate "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/config/"
    click FuzzRunner "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/fuzz_runner/"
    click Helpers "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/helpers/"
    click SpecTooling "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/hypervisor_spec/"
    click RustFuzzer "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/rust_fuzzer/"
    click StructuredFuzzer "https://github.com/rub-syssec/nyx/tree/main/nyx_fuzzer/structured_fuzzer/"

    %% Styles
    classDef kernel fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef vmm fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef rust fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef spec fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef guest fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef ccomp fill:#FFEBEE,stroke:#C62828,color:#B71C1C
    classDef storage fill:#FFFDE7,stroke:#F9A825,color:#F57F17
```
