C3PO — Control Server¶

C3PO is the command & control server for ESPILON. It manages encrypted communication with ESP32 agents, provides a multi-device TUI, a full web dashboard with REST API, and integrates firmware build/deploy pipelines.

Features¶

Feature	Description
Encrypted C2	ChaCha20-Poly1305 AEAD + HKDF-SHA256 per-device keys
Multi-device	Concurrent TCP connections, device registry, group management
TUI	Textual-based interactive terminal with multi-pane layout
Web Dashboard	Flask dashboard with real-time SSE, 9 pages
REST API	40+ endpoints covering devices, commands, cameras, MLAT, OTA, CAN, honeypot
Firmware Build	Background `idf.py build` with live log streaming
OTA Deploy	Upload/serve firmware, push OTA updates to devices
Camera	UDP JPEG receiver, live gallery, MJPEG recording
MLAT	Multilateration positioning (GPS + local coordinates)
CAN Bus	Frame storage, stats, CSV export
Honeypot	Event store, session tracking, credential capture, MITRE mapping
SOCKS5 Tunnel	Encrypted proxy channel through agents (asyncio-based)
Docker	Ready-to-use Dockerfile + docker-compose

Architecture¶

graph TB
    subgraph ESP32["ESP32 Agents"]
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent N]
    end

    subgraph C3PO["C3PO Server"]
        TCP["TCP Server<br/>:2626"]
        UDP["UDP Receiver<br/>:5000"]

        subgraph Core["Core"]
            TR[Transport]
            CR[Crypto<br/>ChaCha20+HKDF]
            KS[KeyStore<br/>keys.json]
            DR[Device Registry]
            GR[Group Registry]
            SE[Session]
        end

        subgraph Interfaces["Interfaces"]
            TUI["TUI<br/>Textual"]
            WEB["Web Dashboard<br/>Flask :8000"]
            API["REST API<br/>40+ endpoints"]
        end

        subgraph Services["Services"]
            BM[Build Manager]
            OTA[OTA Deploy]
            MLAT[MLAT Engine]
            CAN[CAN Store]
            HP[Honeypot Store]
            CAM[Camera Receiver]
        end
    end

    A1 & A2 & A3 -->|"ChaCha20-Poly1305<br/>Protobuf"| TCP
    A1 -->|"JPEG frames<br/>UDP"| UDP

    TCP --> TR
    TR <--> CR
    CR <--> KS
    TR --> DR
    TR --> SE
    SE --> DR & GR

    TUI --> SE
    WEB --> SE
    API --> SE

    API --> BM & OTA & MLAT & CAN & HP
    UDP --> CAM

Startup Sequence¶

c3po.py
├─ validate_config()                 # Enforce non-default secrets
├─ DeviceRegistry()                  # In-memory device store
├─ LogManager()                      # Per-device logging
├─ KeyStore("keys.json")             # Master key store (hot-reload)
├─ Transport(registry, logger, ks)   # Encrypted C2 channel
├─ Session(registry, cmds, groups)   # Runtime state
│
├─ TCP Server (bind HOST:PORT)
│  ├─ ThreadPoolExecutor(50)         # Up to 50 concurrent agents
│  └─ 300s idle timeout per socket
│
├─ device_status_checker (thread)
│  ├─ Check every 10 seconds
│  ├─ Probe at 240s inactivity
│  └─ Mark inactive at 300s
│
├─ TunnelServer (asyncio thread)     # SOCKS5 proxy through agents
│
└─ Mode selection:
   ├─ --headless → Web + background C2
   └─ default    → Textual TUI

Modes¶

TUI Mode (default)¶

Interactive multi-pane terminal with device tabs, command input, auto-completion, and live log streaming.

python c3po.py

Headless Mode¶

Web dashboard + C2 server only, no TUI. Ideal for servers and Docker.

python c3po.py --headless

Supported Modules¶

C3PO manages and communicates with 8 ESP32 firmware modules. Each module is independently enabled at build time.

Module	Kconfig	Commands	Description
System	(always on)	3	Reboot, memory, uptime
Network	`CONFIG_MODULE_NETWORK`	5	Ping, ARP scan, proxy, DoS
FakeAP	`CONFIG_MODULE_FAKEAP`	8	Captive portal, sniffer, client tracking
Recon	`CONFIG_MODULE_RECON`	6	Camera streaming, MLAT positioning
Red Team	`CONFIG_MODULE_REDTEAM`	7	WiFi hunting, mesh, persistence
Honeypot	`CONFIG_MODULE_HONEYPOT`	8	TCP services, credential capture, event logging
CAN Bus	`CONFIG_MODULE_CANBUS`	27	MCP2515 sniffing, UDS, OBD-II, fuzzing
OTA	`CONFIG_ESPILON_OTA_ENABLED`	2	Over-the-air firmware updates

C3PO auto-detects which modules a device has via the status command sent automatically on connection. Module tags are displayed in the dashboard and TUI.

Quick Links¶

Page	Content
Installation	Setup, Docker, `.env` configuration
Architecture	Wire protocol, crypto, protobuf, device lifecycle
TUI	Commands, shortcuts, workflows
Dashboard	Web pages, navigation, features
API Reference	All 40+ REST endpoints with examples
Deploy	Firmware build & flash pipeline, `deploy.json`
Security	Crypto model, auth, rate limiting, best practices

Directory Structure¶

tools/C3PO/
├── c3po.py                    # Entry point
├── .env.example               # Environment template
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Container image
├── docker-compose.yml         # Compose stack
├── keys.json                  # Per-device master keys (generated)
│
├── core/
│   ├── crypto.py              # ChaCha20-Poly1305 + HKDF
│   ├── device.py              # Device dataclass
│   ├── registry.py            # Thread-safe device registry
│   ├── groups.py              # Device groups
│   ├── keystore.py            # Key persistence (keys.json)
│   ├── session.py             # Runtime state aggregator
│   ├── transport.py           # Encrypted RX/TX + dispatch
│   └── can_store.py           # CAN frame ring buffer
│
├── tui/
│   ├── app.py                 # Textual application
│   ├── commander.py           # Command router
│   ├── help.py                # Help system
│   └── styles/c2.tcss         # TUI stylesheet
│
├── web/
│   ├── server.py              # Flask app factory
│   ├── auth.py                # Auth decorators
│   ├── mlat.py                # MLAT positioning engine
│   ├── build_manager.py       # Background firmware builder
│   └── routes/
│       ├── pages.py           # HTML page routes
│       ├── api_devices.py     # Device list + SSE
│       ├── api_commands.py    # Command dispatch
│       ├── api_cameras.py     # Camera control
│       ├── api_mlat.py        # MLAT positioning
│       ├── api_ota.py         # OTA deployment
│       ├── api_build.py       # Firmware build
│       ├── api_can.py         # CAN frames
│       ├── api_monitor.py     # Serial port monitor
│       └── api_stats.py       # Server statistics
│
├── hp_dashboard/              # Honeypot dashboard (optional)
│   ├── hp_store.py            # SQLite event store
│   ├── hp_alerts.py           # Alert engine
│   ├── hp_commander.py        # HP command dispatch
│   ├── hp_geo.py              # Geo-IP enrichment
│   └── hp_routes.py           # HP API blueprint
│
├── templates/                 # Jinja2 HTML templates
│   ├── base.html              # Layout + navigation
│   ├── login.html             # Authentication
│   ├── dashboard.html         # Device list
│   ├── device.html            # Device detail
│   ├── cameras.html           # Camera gallery
│   ├── mlat.html              # MLAT map
│   ├── ota.html               # Build + deploy
│   ├── terminal.html          # Command terminal
│   └── honeypot.html          # Honeypot events
│
├── static/
│   ├── css/main.css           # Dashboard styles
│   ├── js/utils.js            # Shared utilities
│   ├── js/mlat.js             # MLAT map renderer
│   └── favicon.svg            # Icon
│
├── streams/
│   └── config.py              # .env loader + validation
│
└── proto/
    └── c2_pb2.py              # Generated protobuf (Command, AgentMessage)

Next step

Head to Installation to set up C3PO, or jump to Architecture for the technical deep-dive.