Espilon

Embedded ESP32 Agent Framework for Security Research and IoT

IMPORTANT: Espilon is intended for security research, authorized penetration testing, and education. Unauthorized use is illegal. Always obtain written permission before any deployment.

New here? Check the Quick Start Guide — get a working C2 with a simulated device in under 5 minutes, no ESP32 required.

---

Table of Contents

• Full Documentation
• Quick Start
  • Prerequisites
  • Quick Installation
• What is Espilon?
  • Connectivity Modes
• Architecture
  • Key Components
• Available Modules
  • System Module
  • Network Module
  • FakeAP Module
  • Recon Module
  • Red Team Module
  • Honeypot Module
  • Tunnel Module
  • CAN Bus Module
  • OTA Module
• Tools
  • Deploy Tool
  • C2 Server (C3PO)
• Security
  • Encryption
  • Responsible Use
• Use Cases
• Roadmap
• License
• Contributors
• Useful Links
• Support

---

Full Documentation

View the full documentation here

---

The MkDocs documentation includes:

- Step-by-step installation guide
- Translate EN/FR
- WiFi and GPRS configuration
- Module and command reference
- Deploy tool guide
- C2 protocol specification
- Examples and use cases

---

Quick Start

Prerequisites

• ESP-IDF v5.3.2
• Python 3.8+
• ESP32 (any compatible model)
• LilyGO T-Call for GPRS mode (optional)

Quick Installation

# 1. Install ESP-IDF v5.3.2
mkdir -p ~/esp
cd ~/esp
git clone -b v5.3.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32
. ./export.sh

# 2. Clone Espilon
cd ~
git clone https://github.com/Espilon-Net/epsilon-source.git
cd Espilon-Net/espilon_bot

# 3. Configure with menuconfig or tools/deploy.py
idf.py menuconfig

# 4. Build and flash
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

Minimal configuration (menuconfig):

Espilon Bot Configuration
  |- Device ID: "your_unique_id"
  |- Network -> WiFi
  |   |- SSID: "YourWiFi"
  |   |- Password: "YourPassword"
  |- Server
      |- IP: "192.168.1.100"
      |- Port: 2626

---

What is Espilon?

Espilon transforms affordable ESP32 microcontrollers (~$5) into powerful networked agents for:

• Security research: WiFi testing, network reconnaissance, IoT pentesting
• Education: Learning embedded systems, network protocols, FreeRTOS
• IoT prototyping: Distributed communication, monitoring, sensors

Connectivity Modes

Mode	Hardware	Range	Use Case
WiFi	Standard ESP32	50-100m	Labs, buildings
GPRS	LilyGO T-Call	National (2G)	Mobile, remote

---

Architecture

+---------------------------------------------------------+
|                     ESP32 Agent                         |
|  +-----------+  +----------+  +---------------------+   |
|  |  WiFi/    |->| ChaCha20 |->|   C2 Protocol       |   |
|  |  GPRS     |<-| Poly1305 |<-|  (nanoPB/TCP)       |   |
|  +-----------+  +----------+  +---------------------+   |
|         |              |                 |              |
|  +-----------------------------------------------------+|
|  |           Module System (FreeRTOS)                  ||
|  |  [Network] [Tunnel] [FakeAP] [Recon] [RedTeam]     ||
|  |  [Honeypot] [CAN Bus] [OTA] [Custom...]             ||
|  +-----------------------------------------------------+|
+---------------------------------------------------------+
                        | Encrypted TCP
              +---------------------+
              |   C2 Server (C3PO)  |
              |  - Device Registry  |
              |  - Group Management |
              |  - TUI + Web UI     |
              +---------------------+

Key Components

• Core: Network connection, ChaCha20-Poly1305 AEAD + HKDF key derivation, nanoPB protocol
• Modules: Extensible system (Network, FakeAP, Recon, etc.)
• C2 (C3PO): Python asyncio server for multi-agent control
• Deploy: Unified build, provision & flash pipeline (tools/deploy.py)

---

Available Modules

Modules are enabled independently via idf.py menuconfig → Espilon Bot Configuration → Modules. Multiple modules can be active simultaneously (subject to flash/RAM constraints).

System Module (Built-in, always active)

Basic system commands:

• system_reboot: Reboot the ESP32
• system_mem: Display memory usage (heap free, heap min, internal free)
• system_uptime: Uptime since boot
• system_info: Chip info, SDK version, active modules

Network Module

Network reconnaissance, testing, and SOCKS5 tunnel proxy:

• ping <host> [args...]: ICMP connectivity test
• arp_scan: Discover hosts on local network via ARP
• dos_tcp <ip> <port> <count>: TCP load test (authorized use only)
• tun_start <ip> <port>: Start SOCKS5 tunnel proxy to C3PO (requires CONFIG_MODULE_TUNNEL)
• tun_stop: Stop the tunnel
• tun_status: Tunnel status (channels, bytes, encryption mode)

FakeAP Module

Simulated WiFi access points with captive portal and traffic sniffing:

• fakeap_start <ssid> [open|wpa2] [password]: Start a fake access point
• fakeap_stop: Stop the fake AP
• fakeap_status: Display status (AP, portal, sniffer, clients)
• fakeap_clients: List connected clients
• fakeap_portal_start / fakeap_portal_stop: Captive portal
• fakeap_sniffer_on / fakeap_sniffer_off: Traffic capture

Recon Module

Reconnaissance and data collection. Two modes:

Camera Mode (ESP32-CAM)

• cam_start <ip> <port>: Start UDP video streaming (~7 FPS, QQVGA)
• cam_stop: Stop streaming

BLE Trilateration Mode

• trilat start <mac> <url> <bearer>: Start BLE trilateration with HTTP POST
• trilat stop: Stop trilateration

Red Team Module

Autonomous WiFi hunting, credential attacks, and ESP-NOW mesh relay:

• hunt_start [profile]: Launch autonomous WiFi scan + attack cycle
• hunt_stop: Stop hunting
• hunt_status: Current targets, progress, captured credentials
• Stealth features: MAC randomization, passive scanning, timing jitter
• ESP-NOW mesh: multi-hop relay for out-of-range C2

Honeypot Module

Fake network services that log attacker interactions:

• Emulated services: SSH, Telnet, HTTP, FTP (configurable ports)
• WiFi monitor: detect rogue APs and deauth attacks
• Network anomaly detection: ARP spoofing, port scanning alerts
• All events streamed to C2 with attacker fingerprints

Tunnel Module (SOCKS5 Proxy)

Multiplexed SOCKS5 tunnel proxy through the ESP32. Use any network tool (curl, nmap, proxychains) to pivot through the bot onto the target network.

• SOCKS5 runs on C3PO (port 1080) — the ESP32 only handles binary frames
• Up to 8 concurrent TCP connections (configurable via Kconfig)
• DNS resolution on the ESP32 side (sees internal DNS of the target network)
• Auto-reconnect with exponential backoff if C3PO connection drops
• Optional per-frame ChaCha20-Poly1305 AEAD encryption

C3PO ports: 2626 (C2 commands) + 2627 (tunnel data) + 1080 (SOCKS5, localhost only)

# Start tunnel from C2
send <device_id> tun_start <c3po_ip> 2627

# Use any tool through the proxy
curl --socks5-hostname 127.0.0.1:1080 http://target-internal.local
nmap -sT -Pn --proxies socks4://127.0.0.1:1080 192.168.x.0/24

See TUNNEL.md for full protocol specification and testing guide.

CAN Bus Module (MCP2515)

Automotive CAN bus: sniff, inject, UDS diagnostics, OBD-II, and fuzzing via external MCP2515 SPI controller.

• can_start [bitrate] [mode]: Init bus (normal/listen/loopback)
• can_sniff [duration] / can_record / can_replay: Capture and replay
• can_send <id> <data>: Frame injection
• UDS: can_scan_ecu, can_uds_read, can_uds_dump, can_uds_auth
• OBD-II: can_obd <pid>, can_obd_vin, can_obd_dtc, can_obd_monitor
• Fuzzing: can_fuzz_id, can_fuzz_data, can_fuzz_random

See mod_canbus documentation for full details.

OTA Module

Over-the-air firmware updates from C2 server:

• Secure HTTPS firmware download (optional HTTP fallback)
• Dual partition scheme (A/B) for safe rollback
• Progress reporting to C2

---

Configuration: idf.py menuconfig → Espilon Bot Configuration → Modules

• CONFIG_MODULE_NETWORK: Network Module
• CONFIG_MODULE_FAKEAP: FakeAP Module
• CONFIG_MODULE_RECON: Recon Module (Camera or BLE Trilateration)
• CONFIG_MODULE_REDTEAM: Red Team Module
• CONFIG_MODULE_HONEYPOT: Honeypot Module
• CONFIG_MODULE_TUNNEL: SOCKS5 Tunnel Proxy (requires CONFIG_MODULE_NETWORK)
• CONFIG_MODULE_CANBUS: CAN Bus Module (requires MCP2515 hardware)
• CONFIG_ESPILON_OTA_ENABLED: OTA Updates

---

Tools

Deploy Tool

Unified pipeline to build, provision (crypto keys), and flash ESP32 devices:

cd tools

# Interactive wizard
python3 deploy.py

# Single device
python3 deploy.py -p /dev/ttyUSB0 -d my-device \
    --wifi MySSID MyPassword --srv 192.168.1.100

# Batch deploy
python3 deploy.py --config deploy.example.json

Each deploy generates a 256-bit master key per device, writes it to the factory NVS partition, and registers it in the C2 keystore (keys.json).

See tools/README.md for complete documentation (modes, batch config, OTA vs non-OTA, flash map).

C2 Server (C3PO)

Command & Control server:

cd tools/C3PO
pip3 install -r requirements.txt
python3 c3po.py

Full C2 documentation and command list: see tools/C3PO/README.md.

---

Security

Encryption

• ChaCha20-Poly1305 AEAD for authenticated encryption of all C2 communications
• HKDF-SHA256 key derivation (per-device master key + device ID salt)
• Random 12-byte nonce per message (ESP32 hardware RNG)
• Per-device master keys stored in factory NVS partition (read-only)
• Protocol Buffers (nanoPB) for serialization

Provision each device with a unique master key using tools/deploy.py. Keys are never hardcoded in firmware.

Responsible Use

Espilon should only be used for:

• Authorized penetration testing
• Ethical security research
• Education and training
• Legitimate IoT prototyping

Prohibited: Unauthorized access, malicious attacks, privacy violations.

---

Use Cases

WiFi Pentesting

• Network security auditing
• WPA2/WPA3 robustness testing
• Network mapping

IoT Security Research

• IoT device testing
• Protocol analysis
• Vulnerability detection

Education

• Cybersecurity labs
• Embedded systems courses
• CTF competitions

---

Roadmap

V2.0 (Complete)

• ChaCha20-Poly1305 AEAD + HKDF crypto upgrade
• Per-device factory NVS key provisioning
• C3PO C2 rewrite with per-device crypto
• OTA firmware updates
• Red Team module (autonomous WiFi hunting)
• Honeypot module (fake services + monitoring)
• CAN Bus module (MCP2515 — sniff, inject, UDS, OBD-II, fuzzing)
• Web dashboard with device management, camera, MLAT, OTA, CAN
• SOCKS5 tunnel proxy (multiplexed pivot through ESP32)

Future

• BLE module (scan, GATT enum, beacon spoofing)
• Sub-GHz module (CC1101 — 433/868/915 MHz)
• BadUSB module (ESP32-S2/S3 HID injection)
• Custom Espilon PCB
• ESP32-S3/C3 support
• Module SDK for third-party extensions

See MODULE_IDEAS.md for the full list of planned modules.

---

License

Espilon is licensed under MIT with a security addendum.

See LICENSE for full details.

In summary:

• Free use for research, education, development
• Modification and distribution allowed
• Obtain authorization before any deployment
• Malicious use strictly prohibited

---

Contributors

• @Eun0us - Core architecture, modules
• @off-path - C2 server, protocol
• @itsoktocryyy - Network features, work on Mod Wall Hack
• @wepfen - Documentation, tools

Contributing

Contributions welcome! See CONTRIBUTING.md.

Join us:

• Report bugs
• Propose features
• Submit PRs
• Improve documentation

---

Useful Links

• Full documentation
• ESP-IDF Documentation
• LilyGO T-Call
• French README: README.fr.md

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Originally presented at Le Hack (June 2025)

Made with love for security research and education