# fuzzware-fuzzer/hoedur architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzware-fuzzer/hoedur
- Repository: https://github.com/fuzzware-fuzzer/hoedur

## Overview

##### Project type and purpose
- Hoedur is a Rust-based firmware fuzzing toolchain. It ties together:
- A command-line runner (“hoedur-arm”)
- A multi-stream input fuzzer
- A high-level emulator
- Low-level QEMU bindings and patches
- Corpus archive management, modeling integration, and analysis utilities
- Its goal is to fuzz embedded ARM firmware using multi-stream inputs (USENIX Security ’23).

##### File structure
Top‐level crates, each a distinct architectural component:
- common – shared utilities (config, logging, file I/O)
- archive – read/write of compressed fuzzing corpora
- emulator – high-level emulator logic, hooks, interrupt and memory models
- qemu-sys – raw FFI shims and patches against QEMU C code
- qemu-rs – safe Rust wrapper around qemu-sys, low-level CPU and board models
- qemu-build – build-time codegen for bindings
- fuzzer – input generation, mutation, multi-stream corpus management, coverage tracking
- hoedur – CLI parsing, orchestrates fuzzer ↔ emulator interactions
- modeling – optional integration with external Fuzzware models (docker, MMIO models)
- frametracer – event tracing for basic blocks / instructions
- hoedur-analyze – post-run analysis: crash reproducers, coverage reporters, plots
- scripts – glue scripts for evaluations and usability

##### README for additional insights
- The README enumerates each crate and its role.
- Describes CLI commands: fuzz, run, run-cov, run-corpus, hook injection.
- Notes integration points: “--trace” to enable hooks, “--hook example.rn” for custom hook scripts.

a. Main components
- Hoedur CLI (hoedur-arm binary)
- Fuzzer engine (fuzzer crate)
- High-level emulator (emulator crate + frametracer)
- Low-level QEMU layer (qemu-rs → qemu-sys → patched QEMU C lib)
- Corpus archive store (archive crate)
- Common utilities (common crate)
- Modeling subsystem (modeling crate)
- Analysis tools (hoedur-analyze crate + scripts)
b. Relationships and interactions
1. User invokes Hoedur CLI with config →
CLI loads config (common) →
Spawns Fuzzer or Runner.
2. Fuzzer engine requests an execution of the firmware:
- Builds multi-stream inputs
- Calls into Emulator crate, passing input streams & hook scripts.
3. Emulator crate uses qemu-rs API → qemu-sys FFI → QEMU C library to run firmware.
4. During execution:
- Coverage / trace events flow back via frametracer → fuzzer for feedback.
- Hooks (custom or built-in) intercept syscalls, interrupts, MMIO via emulator/hooks.
5. Fuzzer mutates inputs, writes new inputs to corpus archive (archive crate).
6. After or during run, CLI can invoke hoedur-analyze binaries or external Python scripts passing archive files.
7. Optional modeling: fuzzer or emulator delegates input generation or environment simulation to modeling crate (e.g., docker, MMIO models).
c. Architectural patterns & design principles
- Layered design:
– Presentation (CLI)
– Application layers (Fuzzer, Emulator)
– Abstraction/pure-Rust wrapper (qemu-rs)
– Interop layer (qemu-sys)
– Native C library (QEMU)
- Crate-per-responsibility enforces separation of concerns.
- Plug-in style hooks enable extensibility at runtime.
- Archive management decouples corpus storage from fuzzing logic.
d. Key technologies
- Rust & Cargo for modular crates
- QEMU as the execution engine
- Zstd-compressed tar archives for corpus
- RN hook scripting language for custom instrumentation
- Python scripts for post-processing and evaluation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Layer"
        User["User"]:::user
    end

    subgraph "CLI Layer"
        HoedurCLI["hoedur-arm (CLI)"]:::cli
        Runner["Runner"]:::cli
    end

    subgraph "Rust Crates"
        subgraph "Core Engine"
            Fuzzer["fuzzer"]:::core
            Emulator["emulator"]:::core
            FrameTracer["frametracer"]:::core
        end
        subgraph "Interop Layer"
            QemuRS["qemu-rs"]:::interop
            QemuSys["qemu-sys"]:::interop
            QemuBuild["qemu-build"]:::interop
        end
        subgraph "Utilities"
            Common["common"]:::util
            Archive["archive"]:::util
            Modeling["modeling"]:::util
        end
    end

    subgraph "Native QEMU"
        QEMU["QEMU C Library"]:::native
    end

    subgraph "Analysis"
        HAnalyze["hoedur-analyze"]:::analysis
        Scripts["scripts"]:::analysis
    end

    User -->|"invokes"| HoedurCLI
    HoedurCLI -->|"uses config & common"| Common
    HoedurCLI -->|"spawns"| Fuzzer
    HoedurCLI -->|"spawns"| Runner
    Runner -->|"executes firmware"| Emulator

    Fuzzer -->|"requests execution"| Emulator
    Emulator -->|"calls API"| QemuRS
    QemuRS -->|"FFI"| QemuSys
    QemuSys -->|"runs on"| QEMU

    QEMU -->|"trace events"| FrameTracer
    FrameTracer -->|"feedback"| Fuzzer

    Fuzzer -->|"writes inputs"| Archive
    Archive -->|"reads seeds"| Fuzzer

    Fuzzer -.->|"optional modeling"| Modeling
    Emulator -.->|"optional modeling"| Modeling

    Archive -->|"input"| HAnalyze
    Archive -->|"input"| Scripts

    click HoedurCLI "https://github.com/fuzzware-fuzzer/hoedur/blob/main/hoedur/src/bin/hoedur-arm.rs"
    click Runner "https://github.com/fuzzware-fuzzer/hoedur/blob/main/hoedur/src/runner.rs"
    click Fuzzer "https://github.com/fuzzware-fuzzer/hoedur/blob/main/fuzzer/Cargo.toml"
    click Emulator "https://github.com/fuzzware-fuzzer/hoedur/blob/main/emulator/Cargo.toml"
    click FrameTracer "https://github.com/fuzzware-fuzzer/hoedur/blob/main/frametracer/Cargo.toml"
    click QemuRS "https://github.com/fuzzware-fuzzer/hoedur/blob/main/qemu-rs/Cargo.toml"
    click QemuSys "https://github.com/fuzzware-fuzzer/hoedur/blob/main/qemu-sys/Cargo.toml"
    click QemuBuild "https://github.com/fuzzware-fuzzer/hoedur/blob/main/qemu-build/Cargo.toml"
    click Common "https://github.com/fuzzware-fuzzer/hoedur/blob/main/common/Cargo.toml"
    click Archive "https://github.com/fuzzware-fuzzer/hoedur/blob/main/archive/Cargo.toml"
    click Modeling "https://github.com/fuzzware-fuzzer/hoedur/blob/main/modeling/Cargo.toml"
    click HAnalyze "https://github.com/fuzzware-fuzzer/hoedur/blob/main/hoedur-analyze/Cargo.toml"
    click Scripts "https://github.com/fuzzware-fuzzer/hoedur/tree/main/scripts"

    classDef user fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cli fill:#bbf,stroke:#333,stroke-width:2px;
    classDef core fill:#bfb,stroke:#333,stroke-width:2px;
    classDef interop fill:#ffb,stroke:#333,stroke-width:2px;
    classDef util fill:#fbf,stroke:#333,stroke-width:2px;
    classDef native fill:#fbb,stroke:#333,stroke-width:2px;
    classDef analysis fill:#def,stroke:#333,stroke-width:2px;
```
