# ntu-ssl/rr-artifact architecture

> Architecture diagram of the GitHub repository ntu-ssl/rr-artifact, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ntu-ssl/rr-artifact
- Repository: https://github.com/ntu-ssl/rr-artifact

## Overview

##### Project Type and Purpose
- This is not a typical web app but a research artifact for reproducing side‐channel attacks (Reload+Reload) on AMD SEV‐SNP. It integrates host‐side and guest‐side components, automation scripts, custom kernel modules, and cryptographic workloads to demonstrate AES and Spectre attacks.

##### Key Top-Level Directories (Architectural Clues)
- setup/              – environment‐creation scripts, VM image builder, kernel patch
- host-module/        – hyperattacker.ko (host kernel module for side‐channel probing)
- guest-module/       – guest kernel modules loaded inside the VM
- aes-attack/, spectre/ – attacker binaries and victim binaries for AES and Spectre attacks
- aes-profile/        – profiling and analysis utilities for AES traces
- scripts/            – orchestration (evaluate–aes.sh, evaluate–spectre.sh)
- openssl-1.1.0l/     – OpenSSL source build used inside the guest VM
- host-utils/, guest-utils/ – helper libraries (e.g., cJSON, user-utils)

##### Main Components
a. Hardware Layer
- AMD EPYC SEV-SNP server (CPU, DRAM)
b. Virtualization Layer on Host
- Host OS kernel (Linux 22.04) with KVM
- QEMU + OVMF firmware for SEV-SNP VM
- Host kernel module “hyperattacker.ko” (host-module/)
c. Host Attack Orchestration
- setup/*.sh, launch-and-setup-vm.exp scripts (setup/)
- Attack driver binaries (aes-attack/attacker/attacker.c, spectre/attacker/attacker.c)
- Analysis utilities (aes-profile/analysis-utils/)
- Automation scripts (scripts/evaluate-*.sh)
- Data store: results/, gpas/, keys/, ciphertexts/
d. Guest VM Environment
- Guest OS (Ubuntu 20.04) with custom kernel & guest‐module/ inserted on boot
- Victim binaries (aes-attack/victim/victim.c, spectre/victim/victim.c)
- OpenSSL library (openssl-1.1.0l/) for cryptographic workloads
- Victim side-channel targets: AES encryption loops, Spectre gadget

##### Relationships and Data Flows
- Host setup scripts → build and load host kernel module → launch SEV-SNP VM (via QEMU/OVMF).
- Guest boot → loads guest module → victim code runs periodically (AES or Spectre victim)
- Host attacker binary communicates with hyperattacker.ko via ioctl/traps → issues reload probes on guest page-table addresses
- Timing/memory contention data flows back to host attacker → stores raw traces in host workspace
- Post-processing with aes-profile tools generates statistical profiles and recovers keys/secrets → writes into result/

##### Architectural Patterns & Design Principles
- Strong separation between Host (attacker) and Guest (victim) domains
- Layered approach: Hardware → Hypervisor → Host kernel module → Guest kernel module → Userland apps
- Automation pipeline: setup → build → launch → attack → analysis
- Data‐centric storage: organize raw traces, ciphertexts/plaintexts, GPAS models, recovered secrets, accuracy metrics

##### Essential Elements
- Clear component names (e.g., “hyperattacker.ko”, “guest-module/victim.c”)
- Data stores (ciphertexts/, plaintexts/, gpas/, result/) as persistent volumes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        EPYC["AMD EPYC SEV-SNP Server"]:::hardware
    end

    %% Virtualization Layer
    subgraph "Host Virtualization Layer"
        direction TB
        HostOS["Host OS (Linux 22.04) + KVM"]:::virtual
        QEMU["QEMU"]:::virtual
        OVMF["OVMF Firmware"]:::virtual
    end

    EPYC -->|"runs"| HostOS
    HostOS -->|"launch VM →"| QEMU
    QEMU -->|"uses"| OVMF

    %% Host Attack Layer
    subgraph "Host Attack Layer"
        direction TB
        subgraph "Setup & VM Provisioning" 
            direction TB
            SetupSH["setup/setup.sh"]:::host
            VMCreate["setup/vm-create.sh"]:::host
            LaunchExp["setup/launch-and-setup-vm.exp"]:::host
            GenConfig["setup/gen-config.sh"]:::host
            InstallMods["setup/install-guest-modules.sh"]:::host
        end
        subgraph "Host Kernel Module"
            direction TB
            HyperMod["hyperattacker.ko"]:::host
        end
        subgraph "Host Utils"
            direction TB
            CJSON["cJSON.c/.h"]:::host
            UUtilsHost["user-utils.h"]:::host
        end
        subgraph "Attack Binaries"
            direction TB
            AESAtt["aes-attack/attacker/attacker.c"]:::host
            SpectreAtt["spectre/attacker/attacker.c"]:::host
        end
        subgraph "AES Profiling & Analysis"
            direction TB
            GenTpl["generate-template.py"]:::host
            ProfileAtt["aes-profile/attacker/attacker.c"]:::host
            ProfileSh["aes-profile/profile.sh"]:::host
        end
        subgraph "Automation Scripts"
            direction TB
            EvalAES["scripts/evaluate-aes.sh"]:::host
            EvalAESBoth["scripts/evaluate-aes-both.sh"]:::host
            EvalAESNoCache["scripts/evaluate-aes-nocache.sh"]:::host
            EvalSpectre["scripts/evaluate-spectre.sh"]:::host
        end
        subgraph "Host Data Stores"
            direction TB
            Cylinder1(("plaintexts/")):::data
            Cylinder2(("ciphertexts/")):::data
            Cylinder3(("gpas/")):::data
            Cylinder4(("keys/")):::data
            Cylinder5(("aes-result/")):::data
            Cylinder6(("spectre/results/")):::data
            Cylinder7(("spectre/secrets/")):::data
        end
    end

    QEMU -->|"launch→"| SetupSH
    SetupSH -->|"gen config→"| GenConfig
    GenConfig -->|"install modules→"| InstallMods
    InstallMods -->|"insmod→"| HyperMod
    HyperMod -->|"ioctl/probe→"| AESAtt
    HyperMod -->|"ioctl/probe→"| SpectreAtt
    AESAtt -->|"collect traces→"| Cylinder1
    AESAtt -->|"collect traces→"| Cylinder2
    AESAtt -->|"collect traces→"| Cylinder3
    AESAtt -->|"collect traces→"| Cylinder4
    AESAtt -->|"store results→"| Cylinder5
    SpectreAtt -->|"store results→"| Cylinder6
    SpectreAtt -->|"store results→"| Cylinder7
    Cylinder1 -->|"run profiling→"| GenTpl
    GenTpl --> ProfileAtt
    ProfileAtt --> ProfileSh
    ProfileSh --> Cylinder5

    %% Guest VM Layer
    subgraph "Guest VM Layer"
        direction TB
        GuestOS["Guest OS (Ubuntu 20.04)"]:::guest
        subgraph "Guest Kernel Module"
            direction TB
            HyperVictim["hypervictim.ko"]:::guest
        end
        subgraph "Guest Utils"
            direction TB
            UUtilsGuest["guest-utils/user-utils.h"]:::guest
        end
        OpenSSL["openssl-1.1.0l/"]:::guest
    end

    QEMU -->|"boot VM→"| GuestOS
    GuestOS -->|"insmod→"| HyperVictim
    GuestOS --> UUtilsGuest
    GuestOS --> OpenSSL

    %% Victim Workloads
    subgraph "Victim Workloads"
        direction TB
        AESVictim["aes-attack/victim/victim.c"]:::guest
        AESBlock["aes-attack/victim/block.sh"]:::guest
        AESWait["aes-attack/victim/wait.sh"]:::guest
        SpectreVictim["spectre/victim/victim.c"]:::guest
        SpecBlock["spectre/victim/block.sh"]:::guest
        SpecWait["spectre/victim/wait.sh"]:::guest
    end

    GuestOS -->|"exec→"| AESVictim
    AESVictim --> AESBlock
    AESBlock --> AESWait
    GuestOS -->|"exec→"| SpectreVictim
    SpectreVictim --> SpecBlock
    SpecBlock --> SpecWait

    %% Click Events
    click SetupSH "https://github.com/ntu-ssl/rr-artifact/blob/main/setup/setup.sh"
    click VMCreate "https://github.com/ntu-ssl/rr-artifact/blob/main/setup/vm-create.sh"
    click LaunchExp "https://github.com/ntu-ssl/rr-artifact/blob/main/setup/launch-and-setup-vm.exp"
    click GenConfig "https://github.com/ntu-ssl/rr-artifact/blob/main/setup/gen-config.sh"
    click InstallMods "https://github.com/ntu-ssl/rr-artifact/blob/main/setup/install-guest-modules.sh"
    click HyperMod "https://github.com/ntu-ssl/rr-artifact/blob/main/host-module/main.c"
    click CJSON "https://github.com/ntu-ssl/rr-artifact/blob/main/host-utils/cJSON.c"
    click UUtilsHost "https://github.com/ntu-ssl/rr-artifact/blob/main/host-utils/user-utils.h"
    click AESAtt "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-attack/attacker/attacker.c"
    click SpectreAtt "https://github.com/ntu-ssl/rr-artifact/blob/main/spectre/attacker/attacker.c"
    click GenTpl "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-profile/analysis-utils/generate-template.py"
    click ProfileAtt "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-profile/attacker/attacker.c"
    click ProfileSh "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-profile/profile.sh"
    click EvalAES "https://github.com/ntu-ssl/rr-artifact/blob/main/scripts/evaluate-aes.sh"
    click EvalAESBoth "https://github.com/ntu-ssl/rr-artifact/blob/main/scripts/evaluate-aes-both.sh"
    click EvalAESNoCache "https://github.com/ntu-ssl/rr-artifact/blob/main/scripts/evaluate-aes-nocache.sh"
    click EvalSpectre "https://github.com/ntu-ssl/rr-artifact/blob/main/scripts/evaluate-spectre.sh"
    click HyperVictim "https://github.com/ntu-ssl/rr-artifact/blob/main/guest-module/guest-module.c"
    click UUtilsGuest "https://github.com/ntu-ssl/rr-artifact/blob/main/guest-utils/user-utils.h"
    click AESVictim "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-attack/victim/victim.c"
    click AESBlock "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-attack/victim/block.sh"
    click AESWait "https://github.com/ntu-ssl/rr-artifact/blob/main/aes-attack/victim/wait.sh"
    click SpectreVictim "https://github.com/ntu-ssl/rr-artifact/blob/main/spectre/victim/victim.c"
    click SpecBlock "https://github.com/ntu-ssl/rr-artifact/blob/main/spectre/victim/block.sh"
    click SpecWait "https://github.com/ntu-ssl/rr-artifact/blob/main/spectre/victim/wait.sh"

    %% Styles
    classDef hardware fill:#dddddd,stroke:#999,stroke-width:1px
    classDef virtual fill:#bbbbbb,stroke:#888,stroke-width:1px
    classDef host fill:#cce5ff,stroke:#4d7ea8,stroke-width:2px
    classDef guest fill:#d5f5dd,stroke:#2e7d32,stroke-width:2px
    classDef data fill:#ffe6cc,stroke:#cc5200,stroke-width:2px
```
