# pwn3rx0/simple-c2 architecture

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

- Interactive diagram: https://gitdiagram.com/pwn3rx0/simple-c2
- Repository: https://github.com/pwn3rx0/simple-c2

## Overview

##### Project Type and Purpose
- This is a lightweight Command-and-Control (C2) tool.
- It consists of a Flask-based Python server (c2.py + templates/index.html) that provides a web UI and HTTP APIs, plus two Go agents (linux.go, windows.go) that register with the server, pull commands, execute them locally, and push back output.

##### File Structure
- Top level:
- README.md – project overview, setup & usage
- c2.py – Flask server entry point and API definitions
- templates/index.html – single-page UI for issuing commands and viewing output
- agents/ directory:
- linux.go & windows.go – Go source code for cross-platform agents
- No external database or persistent store; client state is likely held in memory within the Flask app.

##### README Insights
- Server: Python 3.8+, Flask
- Agents: Go 1.18+, compile per target OS
- Features: client registration, command dispatch (to one/all), real-time output streaming, auto cleanup
- Communication: HTTP(S) between server and agents; UI uses standard Flask rendering, possibly Server-Sent Events or polling for real-time updates.

##### Main Components
a. Web Browser (Operator UI)
b. Flask Server
- HTTP API endpoints
- In-memory data structures (client registry, command queue)
c. Agents
- Windows Agent (windows.go)
- Linux Agent (linux.go)
d. External Interfaces (optional)
- HTTP(S) network boundary
- cmd.exe on Windows / shell on Linux

##### Relationships & Data Flows
1. Operator uses Web Browser → HTTP GET/POST → Flask Server UI/API
2. Flask Server enqueues command(s) in memory, tagged by client ID or “broadcast”
3. Agent polls or opens a persistent connection (e.g., long-poll/SSE) → HTTP GET → Flask Server retrieves pending commands
4. Agent executes command locally (cmd.exe or shell) → captures stdout/stderr
5. Agent sends execution output → HTTP POST → Flask Server
6. Flask Server pushes output to the Web Browser (via HTTP long-poll, SSE or WebSocket channel)

##### Architectural Patterns & Principles
- Client–Server pattern over HTTP
- Publish/Subscribe at a basic level: agent “subscribes” to commands, operator subscribes to output streams
- In-memory state store (no persistent database) for simplicity
- Clear separation of concerns: UI layer (templates), API layer (c2.py routing), agent logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Web Browser (Operator UI)"]:::ui
    README["README.md"]:::docs

    subgraph "Flask Server"
        ServerUI["UI Rendering (templates/index.html)"]:::server
        ServerAPI["API Endpoints (c2.py)"]:::server
        InMem["In-Memory Data Store"]:::server
    end

    subgraph "Agents"
        WinAgent["Windows Agent (windows.go)"]:::agent
        LinAgent["Linux Agent (linux.go)"]:::agent
    end

    Browser -->|"HTTP GET/POST UI/API"| ServerUI
    Browser -->|"HTTP GET/POST UI/API"| ServerAPI
    ServerAPI -->|"enqueue commands"| InMem
    WinAgent -->|"HTTP GET /commands"| ServerAPI
    LinAgent -->|"HTTP GET /commands"| ServerAPI
    ServerAPI -->|"commands payload"| WinAgent
    ServerAPI -->|"commands payload"| LinAgent
    WinAgent -->|"POST /output (stdout/stderr)"| ServerAPI
    LinAgent -->|"POST /output (stdout/stderr)"| ServerAPI
    ServerAPI -->|"push output (SSE/WebSocket)"| Browser

    click Browser "https://github.com/pwn3rx0/simple-c2/blob/main/templates/index.html"
    click ServerAPI "https://github.com/pwn3rx0/simple-c2/blob/main/c2.py"
    click InMem "https://github.com/pwn3rx0/simple-c2/blob/main/c2.py"
    click LinAgent "https://github.com/pwn3rx0/simple-c2/blob/main/agents/linux.go"
    click WinAgent "https://github.com/pwn3rx0/simple-c2/blob/main/agents/windows.go"
    click README "https://github.com/pwn3rx0/simple-c2/blob/main/README.md"

    classDef server fill:#E0F7FA,stroke:#0288D1,stroke-width:2px
    classDef agent fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    classDef ui fill:#FFF9C4,stroke:#F9A825,stroke-width:2px
    classDef docs fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px

    class Browser ui
    class ServerUI,ServerAPI,InMem server
    class WinAgent,LinAgent agent
    class README docs
```
