# Espilon ![Espilon Logo](assets/images/espilon-logo.jpg) **Embedded ESP32 Agent Framework for Security Research and IoT** [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![ESP-IDF](https://img.shields.io/badge/ESP--IDF-v5.3.2-green.svg)](https://github.com/espressif/esp-idf) [![Platform](https://img.shields.io/badge/Platform-ESP32-red.svg)](https://www.espressif.com/en/products/socs/esp32) > **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](QUICKSTART.md) — get a working C2 with a simulated device in under 5 minutes, no ESP32 required. --- ## Table of Contents - [Full Documentation](#full-documentation) - [Quick Start](#quick-start) - [Prerequisites](#prerequisites) - [Quick Installation](#quick-installation) - [What is Espilon?](#what-is-espilon) - [Connectivity Modes](#connectivity-modes) - [Architecture](#architecture) - [Key Components](#key-components) - [Available Modules](#available-modules) - [System Module](#system-module-built-in-always-active) - [Network Module](#network-module) - [FakeAP Module](#fakeap-module) - [Recon Module](#recon-module) - [Red Team Module](#red-team-module) - [Honeypot Module](#honeypot-module) - [Tunnel Module](#tunnel-module-socks5-proxy) - [CAN Bus Module](#can-bus-module-mcp2515) - [OTA Module](#ota-module) - [Tools](#tools) - [Deploy Tool](#deploy-tool) - [C2 Server (C3PO)](#c2-server-c3po) - [Security](#security) - [Encryption](#encryption) - [Responsible Use](#responsible-use) - [Use Cases](#use-cases) - [Roadmap](#roadmap) - [License](#license) - [Contributors](#contributors) - [Useful Links](#useful-links) - [Support](#support) --- ## Full Documentation **[View the full documentation here](https://docs.espilon.net)** ![Documentation header](assets/images/documentation-header.png) --- The MkDocs documentation includes: ```md - 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 ```bash # 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): ```c Espilon Bot Configuration |- Device ID: "your_unique_id" |- Network -> WiFi | |- SSID: "YourWiFi" | |- Password: "YourPassword" |- Server |- IP: "192.168.1.100" |- Port: 2626 ``` ![menuconfig](assets/images/menuconfig.png) --- ## 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 [args...]`: ICMP connectivity test - `arp_scan`: Discover hosts on local network via ARP - `dos_tcp `: TCP load test (authorized use only) - `tun_start `: 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 [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 `: Start UDP video streaming (~7 FPS, QQVGA) - `cam_stop`: Stop streaming #### BLE Trilateration Mode - `trilat start `: 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) ```bash # Start tunnel from C2 send tun_start 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](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 `: Frame injection - UDS: `can_scan_ecu`, `can_uds_read`, `can_uds_dump`, `can_uds_auth` - OBD-II: `can_obd `, `can_obd_vin`, `can_obd_dtc`, `can_obd_monitor` - Fuzzing: `can_fuzz_id`, `can_fuzz_data`, `can_fuzz_random` See [mod_canbus documentation](espilon_bot/components/mod_canbus/README.md) 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: ```bash 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](tools/README.md) for complete documentation (modes, batch config, OTA vs non-OTA, flash map). ### C2 Server (C3PO) Command & Control server: ```bash cd tools/C3PO pip3 install -r requirements.txt python3 c3po.py ``` Full C2 documentation and command list: see [tools/C3PO/README.md](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) - [x] ChaCha20-Poly1305 AEAD + HKDF crypto upgrade - [x] Per-device factory NVS key provisioning - [x] C3PO C2 rewrite with per-device crypto - [x] OTA firmware updates - [x] Red Team module (autonomous WiFi hunting) - [x] Honeypot module (fake services + monitoring) - [x] CAN Bus module (MCP2515 — sniff, inject, UDS, OBD-II, fuzzing) - [x] Web dashboard with device management, camera, MLAT, OTA, CAN - [x] 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](MODULE_IDEAS.md) for the full list of planned modules. --- ## License Espilon is licensed under **MIT** with a security addendum. See [LICENSE](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](CONTRIBUTING.md). **Join us**: - Report bugs - Propose features - Submit PRs - Improve documentation --- ## Useful Links - **[Full documentation](https://docs.espilon.net)** - **[ESP-IDF Documentation](https://docs.espressif.com/projects/esp-idf/)** - **[LilyGO T-Call](https://github.com/Xinyuan-LilyGO/LilyGO-T-Call-SIM800)** - **French README**: [README.fr.md](README.fr.md) --- ## Support - **Issues**: [GitHub Issues](https://github.com/Espilon-Net/Espilon-Source/issues) - **Discussions**: [GitHub Discussions](https://github.com/Espilon-Net/Espilon-Source/discussions) --- **Originally presented at Le Hack (June 2025)** **Made with love for security research and education**