How hdbreaker/nimhawk works
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