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
  • CAN Bus Module
  • OTA Module
• Tools
  • Multi-Device Flasher
  • 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
- Multi-device flasher 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/flasher/devices.json
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] [FakeAP] [Recon] [RedTeam] [Honeypot]   ||
|  |  [CAN Bus] [OTA] [Custom...]                        ||
|  +-----------------------------------------------------+|
+---------------------------------------------------------+
                        | Encrypted TCP
              +---------------------+
              |   C2 Server (C3PO)  |
              |  - Device Registry  |
              |  - Group Management |
              |  - CLI Interface    |
              +---------------------+

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
• Flasher: Automated multi-device flashing tool

---

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 and testing:

• ping <host> [args...]: ICMP connectivity test
• arp_scan: Discover hosts on local network via ARP
• proxy_start <ip> <port>: Start a TCP proxy
• proxy_stop: Stop the running proxy
• dos_tcp <ip> <port> <count>: TCP load test (authorized use only)

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

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_CANBUS: CAN Bus Module (requires MCP2515 hardware)
• CONFIG_ESPILON_OTA_ENABLED: OTA Updates

---

Tools

Multi-Device Flasher

Automated flasher to configure multiple ESP32s:

cd tools/flasher
python3 flash.py --config devices.json

devices.json:

{
  "project": "/path/to/espilon_bot",
  "devices": [
    {
      "device_id": "esp001",
      "port": "/dev/ttyUSB0",
      "network_mode": "wifi",
      "wifi_ssid": "MyNetwork",
      "wifi_pass": "MyPassword",
      "srv_ip": "192.168.1.100"
    }
  ]
}

See tools/flasher/README.md for complete documentation.

Device Provisioning

Each device needs a unique master key flashed into its factory NVS partition before first use:

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

This generates a 32-byte random master key, writes it to the factory NVS partition, and saves it to the C2 keystore (keys.json).

See tools/provisioning/ for details.

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/provisioning/provision.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

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.md

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Originally presented at Le Hack (June 2025)

Made with love for security research and education