# hdbreaker/nimhawk architecture

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

- Interactive diagram: https://gitdiagram.com/hdbreaker/nimhawk
- Repository: https://github.com/hdbreaker/nimhawk

## Overview

##### Project type and purpose
- Nimhawk is a full-stack Command & Control (C2) framework for red-team operations.
- It consists of:
- A Nim-based implant (“agent”) that runs on Windows x64 targets.
- A Python backend that implements two REST APIs (Admin API and Implant API).
- A React/Next.js web interface (Admin Web UI) for operators.
- A SQLite database for persistence.
- Docker support, dev utilities, and YARA rules for detection/testing.

##### File structure
- Top‐level directories:
- implant/        → Nim source code for the agent
- server/         → Python backend (server/src) + React frontend (admin_web_ui)
- detection/      → YARA rules for detection
- dev_utils/      → Proof-of-concept and test tools
- docs/           → Documentation and images
- Key entry points:
- nimhawk.py      → CLI launcher for “server”, “compile”, “frontend” commands
- server/main.py  → Alternative startup for Python server
- server/admin_web_ui/ → Next.js React application
- Configuration files:
- config.toml.example → sample server+implant config
- server/admin_web_ui/.env → runtime settings for UI
- nim.cfg        → Nim cross‐compile settings
- Dockerfile, .devcontainer → container setup

##### README for extra insights
- Architecture section already outlines:
- Operator machine with Web UI and CLI
- Python backend hosting Admin API and Implant API
- SQLite database
- Target machines running the Nim implant
- Technology stack: Nim, Python (Flask or FastAPI‐style), React/Next.js, SQLite

a. Main components
- Operator Machine
- Web UI (React/Next.js)
- CLI (nimhawk.py)
- Backend Server
- Admin API Server (manages operators, workspaces, compilation tasks)
- Implant API Server (handles implant check-ins, task dispatch, result ingestion)
- Task queue / command history module
- Database (SQLite)
- Target Machine(s)
- Nimhawk Implant (agent)
- External/Infrastructure
- Docker container (optional deployment)
- YARA detection engine (offline)
b. Relationships & data-flow
1. Operator → Web UI → Admin API → Database
2. Operator → CLI compile → Admin API → triggers Nim build (calls Nim tooling) → artifacts
3. Implant ↔ Implant API:
– Register (initial check-in)
– Poll for tasks (GET)
– Post results (POST)
4. Implant API writes commands/results to Database
5. Web UI polls Admin API for real-time status and displays data
c. Architectural patterns
- Layered architecture: UI layer, API layer, Data layer, Agent layer
- Modular design: Implant functionality split into modules (filesystem, network, risky, etc.)
- Microservice‐like separation within backend: two distinct APIs
d. Key technologies/frameworks
- Nim (implant modules), Nimble, MinGW (cross‐compile)
- Python (Flask/FastAPI‐style backend), pip, virtualenv
- Next.js (React), Node.js, npm
- SQLite (nimhawk.db)
- Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Operator Layer
    subgraph "Operator Layer"
        style Operator_Layer fill:#e0f7fa,stroke:#006064,stroke-width:2px
        CLI["CLI Launcher\n(nimhawk.py)"]:::cli
        WebUI["Admin Web UI\n(Next.js)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        style Backend_Layer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
        ServerEntry["Server Entry Point\n(server/main.py)"]:::backend
        AdminAPI["Admin API Server\n(Python)"]:::backend
        ImplantAPI["Implant API Server\n(Python)"]:::backend
        TaskQueue["Task Dispatcher\n& Command History"]:::backend
        DB["nimhawk.db\n(SQLite)"]:::database
        GlobalModels["Global Models\n(c2_server_models.py)"]:::backend
        BackendUtils["Shared Utilities\n(server/src/util/)"]:::backend
    end

    %% Target Layer
    subgraph "Target Layer"
        style Target_Layer fill:#ffebee,stroke:#b71c1c,stroke-width:2px
        NimhawkImplant["Nimhawk Implant\n(Nim agent)"]:::agent
    end

    %% External Tools
    subgraph "External/Dev Tools"
        style External_Tools fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px
        Detection["YARA Detection Rules\n(detection/)"]:::tools
        DevUtils["Development Utilities\n(dev_utils/)"]:::tools
        DockerfileNode["Docker & Container\n(Dockerfile, .devcontainer/)"]:::tools
    end

    %% Connections
    CLI -->|"compile & build"| AdminAPI
    WebUI -->|"HTTP(S) Admin API"| AdminAPI
    AdminAPI -->|"read/write"| DB
    AdminAPI -->|calls| TaskQueue
    AdminAPI -->|uses| GlobalModels
    AdminAPI -->|uses| BackendUtils

    NimhawkImplant -->|"check-in/poll/results"| ImplantAPI
    ImplantAPI -->|"read/write"| DB
    ImplantAPI -->|calls| TaskQueue
    ImplantAPI -->|uses| BackendUtils

    CLI -->|start server| ServerEntry
    ServerEntry -->|initializes| AdminAPI
    ServerEntry -->|initializes| ImplantAPI

    WebUI -->|poll status| AdminAPI

    Detection -.->|offline analysis| NimhawkImplant
    DevUtils -.->|testing| AdminAPI
    DevUtils -.->|testing| ImplantAPI
    DockerfileNode -.->|containerize| ServerEntry

    %% Click Events
    click NimhawkImplant "https://github.com/hdbreaker/nimhawk/tree/main/implant/"
    click CLI "https://github.com/hdbreaker/nimhawk/blob/main/nimhawk.py"
    click ServerEntry "https://github.com/hdbreaker/nimhawk/blob/main/server/main.py"
    click AdminAPI "https://github.com/hdbreaker/nimhawk/tree/main/server/src/servers/admin_api/"
    click ImplantAPI "https://github.com/hdbreaker/nimhawk/tree/main/server/src/servers/implants_api/"
    click GlobalModels "https://github.com/hdbreaker/nimhawk/blob/main/server/src/global_models/c2_server_models.py"
    click BackendUtils "https://github.com/hdbreaker/nimhawk/tree/main/server/src/util/"
    click Detection "https://github.com/hdbreaker/nimhawk/tree/main/detection/"
    click DevUtils "https://github.com/hdbreaker/nimhawk/tree/main/dev_utils/"
    click DockerfileNode "https://github.com/hdbreaker/nimhawk/tree/main/Dockerfile"
    click WebUI "https://github.com/hdbreaker/nimhawk/tree/main/server/admin_web_ui/"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef cli fill:#b3e5fc,stroke:#01579b,color:#01579b
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef database fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef agent fill:#ffcdd2,stroke:#b71c1c,color:#b71c1c
    classDef tools fill:#eeeeee,stroke:#424242,color:#424242
```
