# C3PO (C2) - Full Documentation

C3PO is the Command & Control (C2) server for ESPILON agents. It manages device connections, command dispatch, device state tracking, and provides a CLI, a multi-device TUI (Textual), a web dashboard, and a UDP camera receiver with recording.

---

## Summary

Main features:
- TCP server for ESP agents (Base64 + ChaCha20-Poly1305 AEAD + Protobuf)
- Device registry and group management
- Interactive CLI + multi-device TUI
- Web dashboard (Flask) with Dashboard, Cameras, and MLAT pages
- UDP camera receiver with recording
- MLAT (multilateration) engine for RSSI-based positioning

---

## Prerequisites

- Python 3.10+ (tested with 3.11)
- pip (package manager)
- Virtual environment (recommended)

---

## Installation

### 1. Créer un environnement virtuel

```bash
cd tools/c2
python3 -m venv .venv
```

Ceci crée un dossier `.venv/` isolé pour les dépendances Python.

### 2. Activer l'environnement

**Linux / macOS :**

```bash
source .venv/bin/activate
```

**Windows (PowerShell) :**

```powershell
.\.venv\Scripts\Activate.ps1
```

**Windows (CMD) :**

```cmd
.\.venv\Scripts\activate.bat
```

Le prompt devrait afficher `(.venv)` pour confirmer l'activation.

### 3. Installer les dépendances

```bash
pip install -r requirements.txt
```

Ceci installe toutes les dépendances nécessaires :

| Package | Version | Usage |
| --- | --- | --- |
| `pycryptodome` | >=3.15.0 | ChaCha20-Poly1305 AEAD + HKDF key derivation |
| `protobuf` | >=4.21.0 | Sérialisation Protocol Buffers |
| `flask` | >=2.0.0 | Serveur web (dashboard, API) |
| `python-dotenv` | >=1.0.0 | Chargement config `.env` |
| `textual` | >=0.40.0 | Interface TUI multi-pane |
| `opencv-python` | >=4.8.0 | Traitement vidéo/images caméra |
| `numpy` | >=1.24.0 | Calculs matriciels (opencv, scipy) |
| `scipy` | >=1.10.0 | Algorithme MLAT (optimisation) |

### 4. Vérifier l'installation

```bash
python -c "from web.server import UnifiedWebServer; print('OK')"
```

### Désactiver l'environnement

```bash
deactivate
```

---

## Configuration

### C2 (TCP)

The core C2 server uses constants defined in `utils/constant.py`:
- `HOST` (default `0.0.0.0`)
- `PORT` (default `2626`)

### Web + Camera + MLAT

Copy `.env.example` to `.env` and adjust as needed:

```bash
cp .env.example .env
```

Key variables:
- `WEB_HOST`, `WEB_PORT` (dashboard web server, default `0.0.0.0:8000`)
- `UDP_HOST`, `UDP_PORT` (camera UDP, default `0.0.0.0:5000`)
- `CAMERA_SECRET_TOKEN` (must match firmware)
- `WEB_USERNAME`, `WEB_PASSWORD` (dashboard login)
- `FLASK_SECRET_KEY` (sessions)
- `MULTILAT_AUTH_TOKEN` (Bearer token for MLAT API)
- `IMAGE_DIR` (JPEG frames)
- `VIDEO_ENABLED`, `VIDEO_PATH`, `VIDEO_FPS`, `VIDEO_CODEC`

---

## Launch

Classic CLI mode:

```bash
python3 c3po.py
```

TUI (Textual) mode:

```bash
python3 c3po.py --tui
```

---

## C2 Commands (CLI/TUI)

Main commands:

| Command | Description |
| --- | --- |
| `help [command]` | General help or per-command help |
| `list` | List connected devices |
| `modules` | List ESP commands by module |
| `send <target> <cmd> [args...]` | Send a command |
| `group <action>` | Manage groups |
| `active_commands` | List running commands |
| `web start\|stop\|status` | Web dashboard |
| `camera start\|stop\|status` | Camera UDP receiver |
| `clear` | Clear screen |
| `exit` | Quit |

Examples:

```bash
list
send ce4f626b system_reboot
send all fakeap_status
send group scanners mlat start AA:BB:CC:DD:EE:FF
web start
camera start
active_commands
```

### Groups

```bash
group add bots ce4f626b a91dd021
group list
group show bots
group remove bots ce4f626b
```

---

## ESP Commands (Modules)

ESP commands are organized by module (use `modules`). Summary:

| Module | Command | Description |
| --- | --- | --- |
| system | `system_reboot` | Reboot ESP32 |
| system | `system_mem` | Memory info |
| system | `system_uptime` | Device uptime |
| system | `system_info` | Auto-query on connect |
| network | `ping <host>` | Ping |
| network | `arp_scan` | ARP scan |
| network | `proxy_start <ip> <port>` | TCP proxy |
| network | `proxy_stop` | Stop proxy |
| network | `dos_tcp <ip> <port> <count>` | TCP flood |
| fakeap | `fakeap_start <ssid> [open\|wpa2] [pass]` | Start Fake AP |
| fakeap | `fakeap_stop` | Stop Fake AP |
| fakeap | `fakeap_status` | Fake AP status |
| fakeap | `fakeap_clients` | List clients |
| fakeap | `fakeap_portal_start` | Captive portal |
| fakeap | `fakeap_portal_stop` | Stop portal |
| fakeap | `fakeap_sniffer_on` | Sniffer on |
| fakeap | `fakeap_sniffer_off` | Sniffer off |
| recon | `cam_start <ip> <port>` | Start camera stream |
| recon | `cam_stop` | Stop camera stream |
| recon | `mlat config [gps\|local] <c1> <c2>` | Set scanner position |
| recon | `mlat mode <ble\|wifi>` | Scan mode |
| recon | `mlat start <mac>` | Start MLAT |
| recon | `mlat stop` | Stop MLAT |
| recon | `mlat status` | MLAT status |

Notes:
- `DEV_MODE = True` in `tools/c2/cli/cli.py` allows raw text: `send <target> <any text>`
- `system_info` is automatically sent on new connections.

---

## TUI (Textual)

The TUI shows:
- Left panel: all connected devices
- Right panel: global logs
- Bottom input bar with autocomplete

Key bindings:
- `Alt+G`: toggle global logs
- `Ctrl+L`: clear global logs
- `Ctrl+Q`: quit
- `Esc`: focus input
- `Tab`: completion

---

## Screenshots

Replace the placeholders below with your own captures:

![C3PO CLI Placeholder](docs/screenshots/c3po-cli.png)
![C3PO TUI Placeholder](docs/screenshots/c3po-tui.png)
![C3PO Web Dashboard Placeholder](docs/screenshots/c3po-web-dashboard.png)
![C3PO Cameras Placeholder](docs/screenshots/c3po-cameras.png)
![C3PO MLAT Placeholder](docs/screenshots/c3po-mlat.png)

---

## Web Dashboard

Start from the CLI:

```bash
web start
```

Default local URL:

```text
http://127.0.0.1:8000
```

Default credentials: `admin` / `admin` (defined in `.env`).

Pages:
- `/dashboard` (devices)
- `/cameras` (streams)
- `/mlat` (MLAT view)

### API (Bearer token)

Authenticate with:

```text
Authorization: Bearer <MULTILAT_AUTH_TOKEN>
```

Endpoints:
- `GET /api/devices`
- `GET /api/cameras`
- `POST /api/recording/start/<camera_id>`
- `POST /api/recording/stop/<camera_id>`
- `GET /api/recording/status?camera_id=<id>`
- `GET /api/recordings`
- `POST /api/mlat/collect`
- `GET /api/mlat/state`
- `GET|POST /api/mlat/config`
- `POST /api/mlat/clear`
- `GET /api/stats`

Example:

```bash
curl -H "Authorization: Bearer multilat_secret_token" http://127.0.0.1:8000/api/devices
```

---

## Camera UDP

The UDP receiver assembles JPEG frames and stores them in `IMAGE_DIR`. Expected protocol:
- Each packet starts with `CAMERA_SECRET_TOKEN`
- `START`: begin frame
- `END`: end frame
- Other packets are JPEG chunks

C2 commands:
- `camera start`
- `camera stop`
- `camera status`

Quick test:

```bash
python3 test_udp.py 5000
```

Recording:
- Triggered via Web API (recording endpoints)
- Files stored in `static/recordings`

---

## MLAT (Multilateration)

Supported formats (from ESP):
- `MLAT:G;<lat>;<lon>;<rssi>`
- `MLAT:L;<x>;<y>;<rssi>`
- Legacy: `MLAT:<lat>;<lon>;<rssi>`

Requirements:
- At least 3 active scanners
- Calibration via `rssi_at_1m` and `path_loss_n` (`/api/mlat/config`)

---

## Architecture (Summary)

```
tools/C3PO/
├── c3po.py              # C2 entrypoint (CLI / TUI)
├── cli/                 # CLI + help
├── commands/            # Registry + internal commands
├── core/                # Registry, transport, crypto, keystore
│   ├── crypto.py        # ChaCha20-Poly1305 AEAD + HKDF
│   ├── keystore.py      # Per-device master key management (keys.json)
│   ├── transport.py     # TCP transport with per-device crypto
│   └── registry.py      # Device registry
├── log/                 # Log manager
├── streams/             # Camera UDP + config
├── tui/                 # Textual UI
├── web/                 # Flask server + MLAT
├── templates/           # HTML
├── static/              # CSS/JS/streams/recordings
├── utils/               # Display, constants
├── keys.json            # Per-device master key store
└── requirements.txt
```

---

## Troubleshooting

- `Base64 decode failed` or `Decrypt failed`: verify the device was provisioned with `tools/deploy.py` and that `keys.json` contains the correct master key for the device ID
- `TUI not available`: install `textual`
- No camera frames: check `CAMERA_SECRET_TOKEN` and `UDP_PORT`
- Web not reachable: check `WEB_HOST`, `WEB_PORT`, firewall
- MLAT not resolving: needs at least 3 scanners

---

## Security Notes

- Each device must be provisioned with a unique master key via `tools/deploy.py`
- Master keys are stored in `keys.json` — keep this file secure and never commit it to version control
- The C2 derives per-device encryption keys using HKDF-SHA256 (master_key + device_id salt)
- All C2 communications use ChaCha20-Poly1305 AEAD with random 12-byte nonces
- Change `WEB_USERNAME` / `WEB_PASSWORD` and `FLASK_SECRET_KEY`
- Change `MULTILAT_AUTH_TOKEN` for the API