NexusC2 - Command & Control Framework

A modern, distributed Command & Control (C2) framework designed for secure remote administration and red team operations. Built with Go for the backend services and Python for the operator interface.

Documentation: nexusc2.io

Overview

This C2 framework provides a robust platform for managing remote agents through a scalable, microservices-based architecture. It features real-time bidirectional communication, dynamic payload generation, and comprehensive operational security features.

Architecture

📊 Interactive Diagram: For a detailed interactive version of this architecture diagram with comprehensive documentation, download and open docs/c2-architecture.html in your browser.

Core Components

• WebSocket Service - Real-time communication hub for operator clients
• Agent Handler - Manages agent connections and HTTP/HTTPS listeners
• REST API Service - Programmatic access to all C2 operations via HTTP/JSON
• PostgreSQL Database - Persistent storage for all operational data
• Docker Builder - On-demand payload generation for multiple platforms (local or remote)
• Python GUI Client - Feature-rich operator interface

Communication Flow

1. Operators connect to the WebSocket service via TLS-encrypted connections
2. Commands are routed through a gRPC bidirectional stream to the Agent Handler
3. Agents callback to HTTP/HTTPS listeners managed by the Agent Handler
4. Results flow back through the system to operators in real-time

System Architecture Diagram

graph TB
    subgraph External["🌐 External Network"]
        direction LR
        Agent["💻 Compromised Agent<br/>(Implant on Target)"]
        Spacer[" "]
        Client["👤 Operator Client<br/>(GUI / API)"]
    end

    subgraph HostSystem[" "]
        direction TB
        HostLabel["🖥️ Host System - Docker Host"]

        subgraph FirewallLayer[" "]
            FW_Label["🛡️ Firewall Layer"]
            FW_Allow["✅ Allow: 127.0.0.1<br/>✅ Allow: 172.28.0.0/16<br/>❌ Block: External → :50051"]
        end

        subgraph HostNetwork[" "]
            HN_Label["🔴 Host Network Mode"]
            AgentHandler["⚡ Agent-Handler<br/>network_mode: host<br/>gRPC: 0.0.0.0:50051<br/>Listeners: Any Port"]
        end

        subgraph DockerBridge[" "]
            DB_Label["🔵 Docker Bridge Network<br/>172.28.0.0/16"]
            Database["🗄️ PostgreSQL<br/>172.28.0.2:5432"]
            Websocket["🌐 WebSocket Server<br/>172.28.0.3:3131"]
            RestAPI["🔌 REST API<br/>172.28.0.6:8443"]
            Builder["🔨 Builder Service<br/>172.28.0.5<br/>(Local/Remote)"]
        end
    end

    RemoteBuilder["🔨 Remote Builder<br/>(Optional)<br/>mTLS :9443"]

    %% External Connections
    Agent <-->|"HTTPS/HTTP"| AgentHandler
    Client <-->|"WSS :3131"| Websocket
    Client <-->|"HTTPS :8443"| RestAPI

    %% Internal connections
    Websocket <-->|"gRPC :50051"| AgentHandler
    RestAPI <-->|"gRPC :50051"| AgentHandler
    Websocket -->|":5432"| Database
    RestAPI -->|":5432"| Database
    AgentHandler -->|":5432"| Database
    Websocket -.->|"Docker API"| Builder
    RestAPI -.->|"Docker API"| Builder
    Websocket -.->|"mTLS"| RemoteBuilder
    RestAPI -.->|"mTLS"| RemoteBuilder
    FW_Allow -.->|"Protects"| AgentHandler

    %% Styling
    classDef hostNet fill:#e74c3c,stroke:#c0392b,stroke-width:3px,color:#fff
    classDef bridgeNet fill:#4a90e2,stroke:#2980b9,stroke-width:2px,color:#fff
    classDef external fill:#95a5a6,stroke:#7f8c8d,stroke-width:2px,color:#fff
    classDef firewall fill:#f39c12,stroke:#e67e22,stroke-width:3px,color:#000
    classDef spacer fill:none,stroke:none,color:transparent
    classDef label fill:none,stroke:none,color:#fff,font-weight:bold

    class AgentHandler hostNet
    class Database,Websocket,RestAPI,Builder bridgeNet
    class Agent,Client,RemoteBuilder external
    class FW_Allow firewall
    class Spacer spacer
    class HostLabel,FW_Label,HN_Label,DB_Label label

Message Flow:

1. Operator Client → WebSocket: WSS connection on port 3131 (GUI)
2. Operator Client → REST API: HTTPS connection on port 8443 (programmatic access)
3. WebSocket ↔ Agent Handler: gRPC bidirectional stream via host.docker.internal:50051
4. REST API ↔ Agent Handler: gRPC bidirectional stream via host.docker.internal:50051
5. Agent ↔ Agent Handler: HTTPS/HTTP callbacks on dynamic ports
6. Agent Handler → Database: Agent state and results via 172.28.0.2:5432
7. WebSocket/REST API → Database: Session management and task storage
8. WebSocket/REST API → Builder: Docker API (local) or mTLS (remote) for payload compilation

Network Architecture:

• Host Network Mode: Agent-handler runs with network_mode: host for dynamic port binding
• Firewall Protection: iptables rules secure gRPC port 50051 from external access
• Bridge Network: Database, WebSocket, REST API, and Builder on isolated Docker network (172.28.0.0/16); in remote mode, the builder runs on a separate machine via mTLS
• Dynamic Listeners: Agent-handler can bind to any port (80, 443, 8080, etc.) without container restart

Network Ports:

• PostgreSQL: 5432 (Internal bridge network only - 172.28.0.2)
• WebSocket: 3131 (Public - WSS/TLS)
• REST API: 8443 (Public - HTTPS/TLS)
• gRPC: 50051 (Secured by firewall - localhost and Docker containers only)
• HTTP/HTTPS Listeners: Dynamic (managed by agent-handler on host network)

Key Features

Agent Capabilities

• Cross-platform support (Windows, Linux, macOS)
• Multiple persistence mechanisms
• File transfer (upload/download with chunking)
• Process manipulation and injection
• Network pivoting and SOCKS proxy
• Screenshot capture
• Keylogging capabilities
• Anti-forensics and evasion techniques

This is the beginning of the README. Read the rest at the original. Read the full README ↗