espilon-source/tools/README.md

# Epsilon Tools

This directory contains tools for managing and deploying Epsilon ESP32 agents.

## C2 Server (C3PO/)

The C2 (Command & Control) server manages communication with deployed ESP32 agents.

### C3PO - Main C2 Server

**C3PO** is the primary C2 server used to control Epsilon bots.

Features:

- Threaded TCP server (sockets + threads)
- Device registry and management with per-device crypto
- Group-based device organization
- Encrypted communications (ChaCha20-Poly1305 AEAD + HKDF key derivation)
- Per-device master key keystore (`keys.json`)
- Interactive CLI interface
- Optional TUI (Textual) and Web dashboard
- Camera UDP receiver + MLAT support
- Command dispatching to individual devices, groups, or all

See [C3PO/README.md](C3PO/README.md) for complete C2 documentation.

Quick start:

```bash
cd C3PO
python3 c3po.py
```

Authors: **@off-path**, **@eun0us**

## Multi-Device Flasher (flasher/)

The **flasher** tool automates building and flashing multiple ESP32 devices with custom configurations.

### Features

- Batch processing of multiple devices
- Support for WiFi and GPRS modes
- Per-device configuration (ID, network, modules)
- Automatic hostname randomization
- Build-only and flash-only modes
- Full module configuration (Network, Recon, FakeAP)

### Quick Start

1. Edit [flasher/devices.json](flasher/devices.json):

```json
   {
     "project": "/home/user/epsilon/espilon_bot",
     "devices": [
       {
         "device_id": "ce4f626b",
         "port": "/dev/ttyUSB0",
         "srv_ip": "192.168.1.13",
         "srv_port": 2626,
         "network_mode": "wifi",
         "wifi_ssid": "YourWiFi",
         "wifi_pass": "YourPassword",
         "module_network": true,
         "module_recon": false,
         "module_fakeap": false
       }
     ]
   }
```

2. Flash all devices:

```bash
cd flasher
python3 flash.py --config devices.json
```

### Configuration Options

Each device supports:

| Field | Description |
|-------|-------------|
| `device_id` | Unique device identifier (8 hex chars) |
| `port` | Serial port (e.g., `/dev/ttyUSB0`) |
| `srv_ip` | C2 server IP address |
| `srv_port` | C2 server port (default: 2626) |
| `network_mode` | `"wifi"` or `"gprs"` |
| `wifi_ssid` | WiFi SSID (WiFi mode) |
| `wifi_pass` | WiFi password (WiFi mode) |
| `gprs_apn` | GPRS APN (GPRS mode, default: "sl2sfr") |
| `hostname` | Network hostname (random if not set) |
| `module_network` | Enable network commands (default: true) |
| `module_recon` | Enable reconnaissance module |
| `module_fakeap` | Enable fake AP module |
| `recon_camera` | Enable camera reconnaissance (ESP32-CAM) |
| `recon_ble_trilat` | Enable BLE trilateration |

> **Note**: Crypto keys are no longer configured here. Each device must be provisioned with a unique master key using `tools/provisioning/provision.py`.

### Hostname Randomization

The flasher automatically randomizes device hostnames to blend in on networks:

- iPhone models (iPhone-15-pro-max, iPhone-14, etc.)
- Android devices (galaxy-s24-ultra, pixel-8-pro, xiaomi-14, etc.)
- Windows PCs (DESKTOP-XXXXXXX)

This helps devices appear as legitimate consumer electronics during authorized security testing.

### Manual Mode

Flash a single device without a config file:

```bash
# WiFi mode
python3 flash.py --manual \
  --project /home/user/epsilon/espilon_bot \
  --device-id abc12345 \
  --port /dev/ttyUSB0 \
  --srv-ip 192.168.1.100 \
  --wifi-ssid MyWiFi \
  --wifi-pass MyPassword

# GPRS mode
python3 flash.py --manual \
  --project /home/user/epsilon/espilon_bot \
  --device-id def67890 \
  --port /dev/ttyUSB1 \
  --srv-ip 203.0.113.10 \
  --network-mode gprs \
  --gprs-apn sl2sfr
```

### Build-Only Mode

Generate firmware without flashing:

```bash
python3 flash.py --config devices.json --build-only
```

Firmware saved to: `espilon_bot/firmware/<device_id>.bin`

### Flash-Only Mode

Flash pre-built firmware:

```bash
python3 flash.py --config devices.json --flash-only
```

See [flasher/README.md](flasher/README.md) for complete documentation.

## Device Provisioning (provisioning/)

The **provisioning** tool generates and flashes unique per-device master keys into factory NVS partitions.

### Features

- Generates 32-byte random master keys (cryptographically secure)
- Creates NVS binary for factory partition (`fctry` at offset 0x10000)
- Saves keys to C2 keystore (`keys.json`) for automatic lookup
- Supports flashing directly to connected ESP32

### Quick Start

```bash
cd provisioning
python3 provision.py --device-id my-device --port /dev/ttyUSB0
```

The master key is used by the firmware with HKDF-SHA256 to derive encryption keys for ChaCha20-Poly1305 AEAD.

## NanoPB Tools (nan/)

Tools for Protocol Buffers (nanoPB) code generation for the embedded communication protocol.

Used during development to regenerate Protocol Buffer bindings for ESP32 and Python.

## Additional Resources

- [Installation Guide](../docs/INSTALL.md) - Full Epsilon setup
- [Hardware Guide](../docs/HARDWARE.md) - Supported boards
- [Module API](../docs/MODULES.md) - Available commands
- [Protocol Specification](../docs/PROTOCOL.md) - C2 protocol details
- [Security](../docs/SECURITY.md) - Security best practices

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on contributing to Epsilon tools.

## License

Part of the Epsilon project. See [LICENSE](../LICENSE) for details.