Eun0us/espilon-source
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
espilon-source/README.md
Eun0us 31c312f085 docs: update all documentation for v0.3.0 
Reflect new module architecture, deploy system, Docker support,
honeypot dashboard, and tunnel proxy in documentation.
Updated French README.
2026-02-28 20:16:16 +01:00

467 lines
14 KiB
Markdown
Raw Permalink Blame History

# 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 <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)
```bash
# 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](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](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**
Reference in New Issue View Git Blame Copy Permalink