# ovxrfl0w/erebus architecture

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

- Interactive diagram: https://gitdiagram.com/ovxrfl0w/erebus
- Repository: https://github.com/ovxrfl0w/erebus

## Overview

##### Project Type and Purpose
- The project is a Windows kernel-mode driver written in Rust. Its primary purpose is to expose two IOCTL actions that allow user-mode programs to read and write process memory via the MmCopyVirtualMemory function.
- The README confirms that this is a learning exercise using the windows-drivers-rs crate for Windows kernel driver development.

##### File Structure and Key Components
- Three major crates (or modules) comprise the project:
- km: Contains the kernel module implementation. Files such as device.rs, ffi.rs, logger.rs, memory.rs, process.rs, and utils.rs indicate its responsibilities in setting up and handling driver operations.
- um: Contains the user-mode component that interacts with the driver. The files here (driver.rs, main.rs, utils.rs) are responsible for sending IOCTLs to the kernel driver.
- shared: Houses code common to both the kernel and user-mode parts. Files like constants.rs, ioctl.rs, ipc.rs suggest it manages shared definitions (e.g., constants, data structures during IOCTL transactions).

##### Main Components
- Kernel-Mode Driver (km)
- Acts as the core module handling IOCTL requests.
- Implements functionalities for reading and writing process memory.
- Uses helper files (logger, memory, process management, FFI wrappers).
- User-Mode Interface (um)
- Implements a user-space program that issues IOCTL requests.
- Contains the logic to communicate with the kernel driver.
- Shared Library (shared)
- Defines common data structures (IOCTL commands, constants, IPC mechanisms) making it easier to maintain consistency between kernel and user spaces.
- Windows OS Environment
- Both the kernel mode and user mode boundaries. Emphasize that the IOCTL calls traverse this boundary.

##### Relationships and Interactions
- The User-Mode Application (um) communicates with the OS’s device interface to send IOCTL commands.
- The Kernel-Mode Driver (km) listens for these IOCTL requests, processes them (invoking functions from its various components like memory and process handling), and then responds accordingly.
- Both km and um rely on the shared crate for common definitions, ensuring that data structures and command codes are consistent across both modes.
- The Windows operating system mediates the interaction between user-mode and kernel-mode components.

##### Architectural Patterns and Design Principles
- Clear separation of concerns: The division into km, um, and shared reflects separation between kernel operations, user interactions, and common utilities.
- Modularity: Each component handles a distinct part of the process—from low-level hardware interactions in km to user-triggered operations in um.
- Use of IOCTL: The communication mechanism between user and kernel spaces is explicit and central to the design.
- Emphasis on safety and logging (as seen with logger utilities and tight segregation of secure memory operations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Windows OS Boundary
    subgraph "Windows OS"
        %% User Mode Subgraph
        subgraph "User Mode"
            UM["User-Mode Application (um)"]:::umStyle
            subgraph "User Files"
                UM_main["main.rs"]:::umStyle
                UM_driver["driver.rs"]:::umStyle
                UM_utils["utils.rs"]:::umStyle
            end
        end

        %% Kernel Mode Subgraph
        subgraph "Kernel Mode"
            KM["Kernel-Mode Driver (km)"]:::kmStyle
            subgraph "Kernel Files"
                KM_device["device.rs"]:::kmStyle
                KM_ffi["ffi.rs"]:::kmStyle
                KM_logger["logger.rs"]:::kmStyle
                KM_memory["memory.rs"]:::kmStyle
                KM_process["process.rs"]:::kmStyle
                KM_utils["utils.rs"]:::kmStyle
            end
            Note["Uses windows-drivers-rs crate, MmCopyVirtualMemory"]:::noteStyle
        end
    end

    %% Shared Library Subgraph (outside Windows OS boundary to emphasize shared nature)
    subgraph "Shared Library"
        SH["Shared Library (shared)"]:::sharedStyle
        subgraph "Shared Files"
            SH_constants["constants.rs"]:::sharedStyle
            SH_ioctl["ioctl.rs"]:::sharedStyle
            SH_ipc["ipc.rs"]:::sharedStyle
            SH_lib["lib.rs"]:::sharedStyle
        end
    end

    %% Relationships and Data Flow
    UM -->|"IOCTL Request (Read/Write Process Memory)"| KM
    KM -->|"Response"| UM
    UM ---|"Depends on"| SH
    KM ---|"Depends on"| SH

    %% Click Events for Kernel-Mode Driver (km)
    click KM "https://github.com/ovxrfl0w/erebus/tree/main/km/"
    click KM_device "https://github.com/ovxrfl0w/erebus/blob/main/km/src/device.rs"
    click KM_ffi "https://github.com/ovxrfl0w/erebus/blob/main/km/src/ffi.rs"
    click KM_logger "https://github.com/ovxrfl0w/erebus/blob/main/km/src/logger.rs"
    click KM_memory "https://github.com/ovxrfl0w/erebus/blob/main/km/src/memory.rs"
    click KM_process "https://github.com/ovxrfl0w/erebus/blob/main/km/src/process.rs"
    click KM_utils "https://github.com/ovxrfl0w/erebus/blob/main/km/src/utils.rs"

    %% Click Events for User-Mode Interface (um)
    click UM "https://github.com/ovxrfl0w/erebus/tree/main/um/"
    click UM_main "https://github.com/ovxrfl0w/erebus/blob/main/um/src/main.rs"
    click UM_driver "https://github.com/ovxrfl0w/erebus/blob/main/um/src/driver.rs"
    click UM_utils "https://github.com/ovxrfl0w/erebus/blob/main/um/src/utils.rs"

    %% Click Events for Shared Library (shared)
    click SH "https://github.com/ovxrfl0w/erebus/tree/main/shared/"
    click SH_constants "https://github.com/ovxrfl0w/erebus/blob/main/shared/src/constants.rs"
    click SH_ioctl "https://github.com/ovxrfl0w/erebus/blob/main/shared/src/ioctl.rs"
    click SH_ipc "https://github.com/ovxrfl0w/erebus/blob/main/shared/src/ipc.rs"
    click SH_lib "https://github.com/ovxrfl0w/erebus/blob/main/shared/src/lib.rs"

    %% Style Definitions
    classDef kmStyle fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef umStyle fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef sharedStyle fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef noteStyle fill:#ffa07a,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5;
```
