Eun0us/espilon-source
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f2a5b50bfd
espilon-source/README.md
Eun0us f2a5b50bfd ε - README-UPDATE
2026-02-05 21:51:43 +01:00

402 lines
9.6 KiB
Markdown
Raw 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.
---
## 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)
- [Tools](#tools)
- [Multi-Device Flasher](#multi-device-flasher)
- [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
- 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
```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/flasher/devices.json
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 |<-| Crypto |<-| (nanoPB/TCP) | |
| +-----------+ +----------+ +---------------------+ |
| | | | |
| +-----------------------------------------------------+|
| | Module System (FreeRTOS) ||
| | [Network] [FakeAP] [Recon] [Custom...] ||
| +-----------------------------------------------------+|
+---------------------------------------------------------+
| Encrypted TCP
+---------------------+
| C2 Server (C3PO) |
| - Device Registry |
| - Group Management |
| - CLI Interface |
+---------------------+
```
### Key Components
- **Core**: Network connection, ChaCha20 crypto, 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
> **Important note**: Modules are **mutually exclusive**. You must choose **only one module** during configuration via menuconfig.
### 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
### Network Module
Module for 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
Module for creating simulated WiFi access points:
- `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`: Enable captive portal
- `fakeap_portal_stop`: Disable captive portal
- `fakeap_sniffer_on`: Enable network traffic capture
- `fakeap_sniffer_off`: Disable capture
### Recon Module
Reconnaissance and data collection module. Two modes available:
#### 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
---
**Configuration**: `idf.py menuconfig` -> Espilon Bot Configuration -> Modules
Choose **only one module**:
- `CONFIG_MODULE_NETWORK`: Enable the Network Module
- `CONFIG_MODULE_FAKEAP`: Enable the FakeAP Module
- `CONFIG_MODULE_RECON`: Enable the Recon Module
- Then choose: `Camera` or `BLE Trilateration`
---
## Tools
### Multi-Device Flasher
Automated flasher to configure multiple ESP32s:
```bash
cd tools/flasher
python3 flash.py --config devices.json
```
**devices.json**:
```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](tools/flasher/README.md) for complete documentation.
### C2 Server (C3PO)
Command & Control server:
```bash
cd tools/c2
pip3 install -r requirements.txt
python3 c3po.py --port 2626
```
**Commands**:
- `list`: List connected agents
- `select <id>`: Select an agent
- `cmd <command>`: Execute a command
- `group`: Manage agent groups
---
## Security
### Encryption
- **ChaCha20** for C2 communications
- **Configurable keys** via menuconfig
- **Protocol Buffers (nanoPB)** for serialization
**CHANGE DEFAULT KEYS** for production use:
```bash
# Generate random keys
openssl rand -hex 32 # ChaCha20 key (32 bytes)
openssl rand -hex 12 # Nonce (12 bytes)
```
### 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 (In Progress)
- [ ] Mesh networking (BLE/WiFi)
- [ ] Improve documentation
- [ ] OTA updates
- [ ] Collaborative multilateration
- [ ] Memory optimization
### Future
- [ ] Custom Espilon PCB
- [ ] ESP32-S3/C3 support
- [ ] Module SDK for third-party extensions
- [ ] Web UI for C2
---
## 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.md](README.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