espilon-source/tools

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 for complete C2 documentation.

Quick start:

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:

   {
     "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:

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:

# 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:

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

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

Flash-Only Mode

Flash pre-built firmware:

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

See 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

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 - Full Epsilon setup
• Hardware Guide - Supported boards
• Module API - Available commands
• Protocol Specification - C2 protocol details
• Security - Security best practices

Contributing

See CONTRIBUTING.md for guidelines on contributing to Epsilon tools.

License

Part of the Epsilon project. See LICENSE for details.