# 3mper0rr/c2link architecture

> Architecture diagram of the GitHub repository 3mper0rr/c2link, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/3mper0rr/c2link
- Repository: https://github.com/3mper0rr/c2link

## Overview

1. **Overall shape**
   - This repository is split into two major runtime components: a **Python/Flask team server** and a **Nim implant** named `c2link`.
   - It is a classic **pull-based C2 loop**: the implant repeatedly contacts the server over HTTP, instead of the server directly connecting back to the target.

2. **Team server subsystem**
   - The server lives under `c2link/server/` and is implemented in **Python with Flask**.
   - Its role is to provide the operator-facing **web dashboard/control panel**, accept command input, and collect execution results from implants.
   - It listens on **0.0.0.0:5000** per the README, making it the central coordination point for the lab.

3. **Implant / agent subsystem**
   - The implant is the single Nim source file in `c2link/c2link/c2link.nim`.
   - Its job is to be a **cross-platform beacon** that polls the configured server IP, receives a command, executes it on the local host, and posts back output.
   - The binary is intended to run on Linux, macOS, and Windows via native build or cross-compilation.

4. **Core data flow**
   - Operator uses the Flask dashboard to submit a command.
   - The server stores or exposes that command to waiting implants.
   - The implant polls every **5 seconds**, retrieves the next command, executes it locally, and sends the result back.
   - The server then surfaces the output in the web UI for the operator.

5. **Network boundary**
   - All control traffic appears to be **HTTP-based**, which is the only documented transport in the repo.
   - The implant-server boundary is the main architectural boundary: the server is the trusted control plane, while the implant is the remote execution endpoint.

6. **Execution model on the target**
   - The implant supports **system command execution** on the victim machine.
   - That means the target-side behavior is not a long-lived RPC server; it is a lightweight agent that periodically wakes up, polls, executes, and reports.

7. **Operator interface**
   - The web dashboard is the main human interface.
   - It provides two key functions: **sending commands** and **viewing command output**.
   - In diagram terms, it is the presentation layer sitting on top of the Flask app and command/result handling.

8. **Configuration and deployment**
   - The implant takes the **server IP as an argument**, with `127.0.0.1` as the default according to the README.
   - That makes the server address an external configuration input rather than a compile-time constant.
   - The server is started separately from the implant, which makes the system easy to stand up in a lab.

9. **Build/tooling boundary**
   - The implant is built with the **Nim compiler**; the README shows both compile-only and compile-and-run workflows.
   - Cross-compilation support is explicitly called out for Windows from Linux/macOS.
   - The server has a minimal Python dependency footprint: just **Flask**.

10. **Repository structure implication**
   - The repo is intentionally small and monolithic: one server file, one implant file, and no shared library layer.
   - That suggests the protocol and state handling are likely embedded directly inside each component rather than abstracted into separate modules.

11. **What to show in an architecture diagram**
   - Draw two main boxes: **Flask Team Server** and **Nim Implant**.
   - Between them, show **periodic HTTP polling** and **result reporting**.
   - From the operator to the server, show **browser/web UI input**.
   - Mark the server as the **control plane** and the implant as the **execution node**.

Main entry points: [`c2link/c2link/c2link.nim`](https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim) (HTTP Client), [`c2link/server/c2_server.py`](https://github.com/3mper0rr/c2link/blob/main/c2link/server/c2_server.py) (Flask App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator"]
  node_browser["Web UI<br/>operator UI"]
end

subgraph group_server["Team Server"]
  node_flask_app["Flask App<br/>python service<br/>[c2_server.py]"]
  node_cmd_iface["Command Input<br/>control endpoint"]
  node_cmd_store[("Command Queue<br/>server state")]
  node_result_store[("Result Log<br/>server state")]
end

subgraph group_implant["Implant"]
  node_poll_loop(("Poll Loop<br/>beacon loop<br/>[c2link.nim]"))
  node_http_client["HTTP Client<br/>network client<br/>[c2link.nim]"]
  node_executor["Command Exec<br/>local execution<br/>[c2link.nim]"]
  node_server_ip["Server IP<br/>runtime config"]
end

subgraph group_build["Build & Deploy"]
  node_nim_build["Nim Build<br/>toolchain"]
  node_python_deps["Flask Dep<br/>dependency"]
end

node_browser -->|"uses"| node_flask_app
node_flask_app -->|"accepts"| node_cmd_iface
node_cmd_iface -->|"queues"| node_cmd_store
node_poll_loop -->|"drives"| node_http_client
node_http_client -->|"polls"| node_cmd_store
node_cmd_store -->|"delivers"| node_executor
node_executor -->|"returns output"| node_http_client
node_http_client -->|"posts"| node_result_store
node_result_store -->|"surfaces"| node_flask_app
node_server_ip -->|"configures"| node_http_client
node_nim_build -.->|"produces"| node_poll_loop
node_python_deps -.->|"supports"| node_flask_app

click node_flask_app "https://github.com/3mper0rr/c2link/blob/main/c2link/server/c2_server.py"
click node_poll_loop "https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim"
click node_http_client "https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim"
click node_executor "https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser toneBlue
class node_flask_app,node_cmd_iface,node_cmd_store,node_result_store toneAmber
class node_poll_loop,node_http_client,node_executor,node_server_ip toneMint
class node_nim_build,node_python_deps toneRose
```

## Components

### Operator

Human control surface

- **Web UI**: operator UI · Operator interface for issuing commands and viewing results

### Team Server

Python Flask control plane

- [Flask App](https://github.com/3mper0rr/c2link/blob/main/c2link/server/c2_server.py): python service · Web application that handles dashboard requests and coordination · `c2link/server/c2_server.py`
- **Command Input**: control endpoint · Receives operator-entered commands for execution
- **Command Queue**: server state · Pending command exposed to polling implants
- **Result Log**: server state · Collected command output returned from implants

### Implant

Nim beacon on target

- [Poll Loop](https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim): beacon loop · Repeatedly contacts the server for work on a fixed interval · `c2link/c2link/c2link.nim`
- [HTTP Client](https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim): network client · Implements pull-based HTTP communication with the server · `c2link/c2link/c2link.nim`
- [Command Exec](https://github.com/3mper0rr/c2link/blob/main/c2link/c2link/c2link.nim): local execution · Runs received system commands on the target host · `c2link/c2link/c2link.nim`
- **Server IP**: runtime config · Configured control address passed to the implant

### Build & Deploy

Language/tooling boundary

- **Nim Build**: toolchain · Compiles the implant, including cross-compilation workflows
- **Flask Dep**: dependency · Minimal Python dependency used by the server

## Connections

- Web UI → Flask App: uses · Operator interacts with the dashboard and control panel
- Flask App → Command Input: accepts · Dashboard requests submit work for implants
- Command Input → Command Queue: queues · Commands are stored or exposed for polling clients
- Poll Loop → HTTP Client: drives · Beacon loop initiates each polling cycle
- HTTP Client → Command Queue: polls · Requests the next pending command over HTTP
- Command Queue → Command Exec: delivers · Received command is handed to local execution
- Command Exec → HTTP Client: returns output · Execution result is prepared for upload
- HTTP Client → Result Log: posts · Command output is sent back to the server
- Result Log → Flask App: surfaces · Results are displayed in the web dashboard
- Server IP → HTTP Client: configures · Server address determines where the implant polls
- Nim Build → Poll Loop: produces · Nim compiler builds the target binary
- Flask Dep → Flask App: supports · Flask provides the server runtime