# nyx-fuzz/libnyx architecture

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

- Interactive diagram: https://gitdiagram.com/nyx-fuzz/libnyx
- Repository: https://github.com/nyx-fuzz/libnyx

## Overview

##### Project Purpose and Type
- The project is centered around libnyx – a library that simplifies the construction of hypervisor-based snapshot fuzzers. It has both a C and Rust interface, meaning its intended use spans both language ecosystems.
- Along with the core library (libnyx), the project includes additional crates (for example, acat, config, and fuzz_runner) that act as either demo applications, configuration modules, or runner tools that showcase and utilize libnyx’s capabilities.

##### Analyzing the File Structure
- The top-level directories correspond to separate Cargo packages:
– libnyx: Contains the core functionality, including FFI capabilities (via ffi.rs), build scripts (build.rs), and tooling (cbindgen configuration and test files for the C interface).
– acat: Likely an executable that serves as a demo or a tool that uses the libnyx library.
– config: Provides configuration management (as seen in config.rs, loader.rs, and lib.rs), which probably supports the other components.
– fuzz_runner: Contains code to drive fuzzing tasks; notice the specialized “nyx” subdirectory that groups files handling VM snapshot interactions (e.g., aux_buffer, mem_barrier, qemu_process) and even tests.
- The presence of GitHub workflows indicates CI processes. Meanwhile, the Cargo.toml files in each directory confirm that these are distinct crates within a larger workspace.

##### Architectural Components
a. Main Components:
– Core Library (libnyx): The heart of the system, exposing both a C interface and a Rust API.
– Fuzz Runner (fuzz_runner): Implements a set of modules under “nyx” for managing hypervisor-based fuzzing tasks (snapshot management, VM interactions, and integration with tools like QEMU).
– Configuration Module (config): A shared crate that likely provides centralized configuration loading and management for other components.
– Example/Application (acat): An executable that demonstrates usage or provides a command-line interface to work with libnyx.

b. Relationships and Interactions:
– acat and fuzz_runner will both depend on libnyx for managing virtual machines and snapshots.
– The fuzz runner will interact with the hypervisor environment (e.g., through QEMU––as seen in qemu_process.rs) and will use its internal “nyx” modules to manage runtime aspects such as memory barriers, auxiliary data, and parameters.
– The config module might be used by acat, fuzz_runner, and even aspects of libnyx to load and manage runtime settings.
– The FFI interface within libnyx also exposes C bindings that could be used externally or in conjunction with C-based testing interfaces (as seen with test.c and test.sh).

c. Architectural Patterns or Emphasized Design Principles:
– Modularization: Each Cargo package (crate) is a distinct module separating concerns – core functionality, configuration, execution (runner), and demonstration/application.
– FFI and Multi-language support: libnyx explicitly supports being used from both C and Rust, so include a component showing the FFI boundary.
– Clear separation between the library (business logic for snapshot fuzzer infrastructure) and the tools/applications that use it.

d. Technologies, Frameworks, and Libraries:
– Rust and Cargo as the language and build/toolchain.
– FFI tools (cbindgen) for generating C headers.
– Integration with virtualization tools such as QEMU (indicated by qemu_process.rs).
– GitHub Actions for CI (from the .github/workflows folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for libnyx – Core Fuzzer Library
    subgraph "libnyx – Core Fuzzer Library"
        direction TB
        L1["libnyx – Core Fuzzer Library"]:::core
        L2["FFI Interface (ffi.rs)"]:::core
        L3["Rust API (lib.rs)"]:::core
        L1 --- L2
        L1 --- L3
    end

    %% Subgraph for Fuzz Runner – VM & Snapshot Management
    subgraph "Fuzz Runner – VM & Snapshot Management"
        direction TB
        FR1["Fuzz Runner – VM & Snapshot Management"]:::tool
        FR2["aux_buffer.rs"]:::tool
        FR3["mem_barrier.rs"]:::tool
        FR4["qemu_process.rs"]:::tool
        FR1 --- FR2
        FR1 --- FR3
        FR1 --- FR4
    end

    %% Other Components
    ACat["acat – Fuzzer Demo/CLI"]:::tool
    Config["Configuration Module"]:::config
    Hypervisor["Hypervisor Engine (QEMU)"]:::external
    CI["GitHub CI Integration"]:::ci

    %% Relationships
    ACat -->|"depends_on"| L1
    FR1 -->|"depends_on"| L1

    ACat -->|"uses"| Config
    FR1 -->|"uses"| Config

    FR1 -->|"interacts_with"| Hypervisor

    %% Optional: Connect CI to the overall project (indicating build process awareness)
    CI ---|"triggers"| Config

    %% Click Events
    click L1 "https://github.com/nyx-fuzz/libnyx/tree/main/libnyx/"
    click FR1 "https://github.com/nyx-fuzz/libnyx/tree/main/fuzz_runner/"
    click Config "https://github.com/nyx-fuzz/libnyx/tree/main/config/"
    click ACat "https://github.com/nyx-fuzz/libnyx/tree/main/acat/"
    click CI "https://github.com/nyx-fuzz/libnyx/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef core fill:#a3c4f3,stroke:#333,stroke-width:2px;
    classDef tool fill:#c8f7c5,stroke:#333,stroke-width:2px;
    classDef config fill:#fff7a3,stroke:#333,stroke-width:2px;
    classDef external fill:#f7a3a3,stroke:#333,stroke-width:2px;
    classDef ci fill:#a3f7f3,stroke:#333,stroke-width:2px;
```
