# dualhorizon/blackpill architecture

> Architecture diagram of the GitHub repository dualhorizon/blackpill, 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/dualhorizon/blackpill
- Repository: https://github.com/dualhorizon/blackpill

## Overview

##### Project Overview and Components
- Project Type: BlackPill is a Linux rootkit combining kernel module techniques (hooking, persistence, defense evasion), an internal hypervisor for executing malicious code, and integration with eBPF programs for network packet interception. It also includes a separate C2 (command and control) component written in Python.
- Main Components to Represent:
- Kernel Space Rootkit: Composed of multiple Rust modules (e.g., “hiding”, “hooking”, “persistence”, “hypervisor”, “utils”, “xdp”).
- Hypervisor Module: Implements VM entry/exit and guest management (includes C components and Rust module wrappers).
- Defense Evasion & Hooking: Using kprobes for syscall interception (e.g., modifying filldir64, hiding the module) plus IDT hooking.
- eBPF Programs: Located in the “stealthbpf” directory that include a common library, eBPF-based “stealthbpf-ebpf”, and additional components for filtering incoming (XDP) and outgoing (TC) network traffic.
- C2 Client: Found under “blackpill-c2”, a Python script that sends crafted x86-64 opcodes over UDP and communicates via TCP with the rootkit.
- Auxiliary Components: Build scripts (Makefile, shell scripts in “scripts”) and configuration files (Cargo.toml, rust-toolchain.toml) which support compilation and VM setup.

##### Relationships and Data Flows
- Within the kernel, the rootkit code intercepts system calls via registered hooks (depicting “hooking” and “defense evasion” modules) and modifies behaviors to hide files, processes, and connections.
- Packets arriving from the network are filtered by an eBPF XDP program before being passed to the Linux kernel module. Outgoing packets are similarly intercepted and modified by eBPF TC programs.
- Persistence functionality (triggered by the rootkit) ensures that critical operations (e.g., test file creation, future persistence methods) continue across reboots.

##### Architectural Patterns & Design Principles
- Layered Approach: Differentiate between kernel space (the rootkit and its modules) and user space (the C2 client). Clearly indicate the network stack interactions.
- Extensibility: Point out that additional functionalities (later evolutions of persistence or hooking techniques) can be expanded in the same modular format.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% C2 Client
    C2["C2 Client (Python)"]:::client

    %% Build & Environment Setup Components
    Build["Build Scripts"]:::build
    Config["Configuration Files"]:::build

    %% Kernel Rootkit Subgraph and its Modules
    subgraph "Kernel Rootkit"
        Hiding["Hiding Module"]:::kernel
        Hooking["Hooking &DefenseEvasion"]:::kernel
        Persistence["Persistence"]:::kernel
        Hypervisor["Hypervisor Module"]:::kernel
        Utils["Utility Functions"]:::kernel
        KernelEBPF["Kernel eBPF (XDP Filtering)"]:::kernel
    end

    %% eBPF Programs Subgraph
    subgraph "eBPF Programs"
        EBPFCommon["eBPF Common Library"]:::ebpf
        EBPFProgram["eBPF Programs (XDP/TC)"]:::ebpf
    end

    %% Virtual Machine Guest
    VMGuest["Virtual Machine Guest"]:::vm

    %% Data Flows
    C2 -->|"UDP_Opcodes"| Hooking
    C2 -->|"VM_Control"| Hypervisor
    EBPFProgram -->|"PacketFiltering"| KernelEBPF
    Hooking -->|"SyscallIntercept"| Hiding
    Hooking -->|"TriggersPersistence"| Persistence
    Hypervisor -->|"Creates/EntersVM"| VMGuest
    Build -->|"compiles"| Hooking
    Config -->|"configures"| Hooking
    Build -->|"compiles"| EBPFProgram
    Config -->|"configures"| EBPFProgram

    %% Click Events for Kernel Rootkit Components
    click Hiding "https://github.com/dualhorizon/blackpill/blob/main/src/hiding/mod.rs"
    click Hooking "https://github.com/dualhorizon/blackpill/tree/main/src/hooking/"
    click Persistence "https://github.com/dualhorizon/blackpill/blob/main/src/persistence/mod.rs"
    click Hypervisor "https://github.com/dualhorizon/blackpill/tree/main/src/hypervisor/"
    click Utils "https://github.com/dualhorizon/blackpill/tree/main/src/utils/"
    click KernelEBPF "https://github.com/dualhorizon/blackpill/blob/main/src/xdp/mod.rs"

    %% Click Events for eBPF Programs
    click EBPFCommon "https://github.com/dualhorizon/blackpill/tree/main/stealthbpf/stealthbpf-common"
    click EBPFProgram "https://github.com/dualhorizon/blackpill/tree/main/stealthbpf/stealthbpf-ebpf"

    %% Click Event for C2 Client
    click C2 "https://github.com/dualhorizon/blackpill/blob/main/blackpill-c2/client.py"

    %% Click Events for Build & Configuration Components
    click Build "https://github.com/dualhorizon/blackpill/tree/main/Makefile and scripts/"
    click Config "https://github.com/dualhorizon/blackpill/blob/main/Cargo.toml and rust-toolchain.toml"

    %% Styles
    classDef kernel fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef client fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef ebpf fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef build fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef vm fill:#d1f0d1,stroke:#333,stroke-width:2px;
```
