Installation & Configuration¶

Requirements¶

Requirement	Version	Purpose
Python	3.11+	Runtime
ESP-IDF	5.x	Firmware build (optional, for build feature)
pip	latest	Package manager

Python Dependencies¶

pip install -r tools/C3PO/requirements.txt

Package	Min Version	Purpose
`pycryptodome`	3.15.0	ChaCha20-Poly1305, HKDF symmetric encryption
`protobuf`	4.21.0	Command/AgentMessage serialization
`flask`	2.0.0	Web dashboard & REST API
`flask-limiter`	3.0.0	Per-IP rate limiting
`python-dotenv`	1.0.0	`.env` file loading
`textual`	0.40.0	TUI (Terminal User Interface)
`opencv-python`	4.8.0	Camera frame processing & recording
`numpy`	1.24.0	Matrix operations for video
`scipy`	1.10.0	MLAT positioning (least squares)

Quick Setup¶

1. Clone & Install¶

cd tools/C3PO
cp .env.example .env
pip install -r requirements.txt

2. Configure `.env`¶

Edit .env with your values. At minimum, change the security defaults:

# CRITICAL — Change these before any real use
FLASK_SECRET_KEY=your_random_secret_here
WEB_USERNAME=your_username
WEB_PASSWORD=your_strong_password
CAMERA_SECRET_TOKEN=your_camera_token
MULTILAT_AUTH_TOKEN=your_api_token

3. Launch¶

# TUI mode (default)
python c3po.py

# Headless mode (web only)
python c3po.py --headless

Security Check

C3PO refuses to start if default credentials are detected. Set ESPILON_ALLOW_DEFAULTS=1 to bypass (dev only).

Environment Variables¶

C2 Server¶

Variable	Default	Description
`C2_HOST`	`0.0.0.0`	TCP listen address
`C2_PORT`	`2626`	TCP port for agent connections

Web Dashboard¶

Variable	Default	Description
`WEB_HOST`	`0.0.0.0`	Flask bind address
`WEB_PORT`	`8000`	Dashboard HTTP port

Security¶

Variable	Default	Description
`FLASK_SECRET_KEY`	`change_this_for_prod`	Flask session secret (random string)
`WEB_USERNAME`	`admin`	Dashboard login username
`WEB_PASSWORD`	`admin`	Dashboard login password
`CAMERA_SECRET_TOKEN`	`Sup3rS3cretT0k3n`	Camera UDP auth token (must match firmware)
`MULTILAT_AUTH_TOKEN`	`multilat_secret_token`	Bearer token for API authentication

Camera UDP¶

Variable	Default	Description
`UDP_HOST`	`0.0.0.0`	UDP listener address
`UDP_PORT`	`5000`	Camera frame receiver port
`UDP_BUFFER_SIZE`	`65535`	Max UDP packet size

CORS¶

Variable	Default	Description
`CORS_ALLOWED_ORIGINS`	`http://localhost:8000,...`	Comma-separated origin whitelist (empty = allow all)

Rate Limiting¶

Variable	Default	Description
`RATE_LIMIT_DEFAULT`	`200 per minute`	Global per-IP API limit
`RATE_LIMIT_LOGIN`	`5 per minute`	Login brute-force protection

Video Recording¶

Variable	Default	Description
`IMAGE_DIR`	`static/streams`	JPEG frame storage directory
`VIDEO_ENABLED`	`true`	Enable/disable recording
`VIDEO_PATH`	`static/streams/record.avi`	Output video file
`VIDEO_FPS`	`10`	Recording framerate
`VIDEO_CODEC`	`MJPG`	OpenCV video codec

Honeypot (Optional)¶

Variable	Default	Description
`HP_DASHBOARD_PATH`	(empty)	Path to honeypot dashboard module

Docker Deployment¶

Dockerfile¶

C3PO ships with a production-ready container:

FROM python:3.11-slim

WORKDIR /app

# System deps for OpenCV
RUN apt-get update && \
    apt-get install -y --no-install-recommends libgl1 libglib2.0-0

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN mkdir -p static/streams static/recordings data firmware

EXPOSE 2626 8000 5000/udp

ENTRYPOINT ["python", "c3po.py"]

docker-compose.yml¶

services:
  c3po:
    build: .
    ports:
      - "2626:2626"      # C2 TCP
      - "8000:8000"      # Web dashboard
      - "5000:5000/udp"  # Camera UDP
    volumes:
      - ./keys.json:/app/keys.json       # Device keys (persistent)
      - ./data:/app/data                 # Runtime data
      - ./firmware:/app/firmware          # Built firmware binaries
      - ./static/recordings:/app/static/recordings  # Video recordings
    env_file:
      - .env
    restart: unless-stopped

Launch with Docker¶

cd tools/C3PO

# Configure
cp .env.example .env
# Edit .env with production values...

# Build & run
docker compose up -d

# View logs
docker compose logs -f c3po

# Stop
docker compose down

Exposed Ports¶

Port	Protocol	Service
`2626`	TCP	Agent C2 channel (encrypted)
`8000`	TCP	Web dashboard + REST API
`5000`	UDP	Camera JPEG receiver

Persistent Volumes¶

Mount	Purpose
`keys.json`	Per-device master keys — do not lose
`data/`	Runtime state (logs, honeypot SQLite)
`firmware/`	Built `.bin` files for OTA
`static/recordings/`	Video recordings

Backup keys.json

If you lose keys.json, you cannot communicate with provisioned devices. The master keys are generated during deploy.py provisioning and stored here.

Network Topology¶

┌──────────────┐         ┌──────────────────────────┐
│   ESP32      │         │       C3PO Server         │
│   Agent      │         │                           │
│              ├────TCP──►  :2626  TCP C2             │
│              │  2626   │                           │
│  (camera)    ├────UDP──►  :5000  Camera UDP        │
│              │  5000   │                           │
└──────────────┘         │  :8000  Web Dashboard     │
                         │         REST API           │
┌──────────────┐         │                           │
│   Browser    ├────HTTP─►                           │
│   Operator   │  8000   └──────────────────────────┘
└──────────────┘

First Run Checklist¶

Copy .env.example → .env
Change all default secrets in .env
Install Python dependencies
Run python c3po.py — verify TUI starts
Open http://localhost:8000 — verify dashboard login
Provision a device with deploy.py — verify connection in TUI