diff --git a/README.en.md b/README.en.md deleted file mode 100644 index c02b7d0..0000000 --- a/README.en.md +++ /dev/null @@ -1,371 +0,0 @@ -# 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. - ---- - -## 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 [args...]`: ICMP connectivity test -- `arp_scan`: Discover hosts on local network via ARP -- `proxy_start `: Start a TCP proxy -- `proxy_stop`: Stop the running proxy -- `dos_tcp `: TCP load test (authorized use only) - -### FakeAP Module - -Module for creating simulated WiFi access points: - -- `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`: 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 `: 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 - ---- - -**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 `: Select an agent -- `cmd `: 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** diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..b4976e5 --- /dev/null +++ b/README.fr.md @@ -0,0 +1,428 @@ +# Espilon + +![Espilon Logo](assets/images/espilon-logo.jpg) + +**Framework d'agents embarqués ESP32 pour la recherche en sécurité et l'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 est destiné à la recherche en sécurité, aux tests d'intrusion autorisés et à l'éducation. L'utilisation non autorisée est illégale. Obtenez toujours une autorisation écrite avant tout déploiement. + +--- + +## Sommaire + +- [Documentation Complète](#documentation-complète) +- [Quick Start](#quick-start) + - [Prérequis](#prérequis) + - [Installation Rapide](#installation-rapide) +- [Qu'est-ce qu'Espilon ?](#quest-ce-quespilon-) + - [Modes de Connectivité](#modes-de-connectivité) +- [Architecture](#architecture) + - [Composants Clés](#composants-clés) +- [Modules Disponibles](#modules-disponibles) + - [System Module](#system-module-built-in-toujours-actif) + - [Network Module](#network-module) + - [FakeAP Module](#fakeap-module) + - [Recon Module](#recon-module) +- [Outils](#outils) + - [Multi-Device Flasher](#multi-device-flasher) + - [C2 Server (C3PO)](#c2-server-c3po) +- [Sécurité](#sécurité) + - [Chiffrement](#chiffrement) + - [Usage Responsable](#usage-responsable) +- [Cas d'Usage](#cas-dusage) +- [Roadmap](#roadmap) +- [Licence](#licence) +- [Contributeurs](#contributeurs) +- [Liens Utiles](#liens-utiles) +- [Support](#support) + +--- + +## Documentation Complète + +**[Consultez la documentation complète ici](https://docs.espilon.net)** + +![Documentation header](assets/images/documentation-header.png) + +--- + +La documentation MkDocs inclut : + +```md +- Guide d'installation pas à pas +- Traduction EN/FR +- Configuration WiFi et GPRS +- Référence des modules et commandes +- Guide du flasher multi-device +- Spécification du protocole C2 +- Exemples et cas d'usage +``` + +--- + +## Quick Start + +### Prérequis + +- ESP-IDF v5.3.2 +- Python 3.8+ +- ESP32 (tout modèle compatible) +- LilyGO T-Call pour le mode GPRS (optionnel) + +### Installation Rapide + +```bash +# 1. Installer 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. Cloner Espilon +cd ~ +git clone https://github.com/Espilon-Net/epsilon-source.git +cd epsilon/espilon_bot + +# 3. Configurer +idf.py menuconfig + +# 4. Compiler et flasher +idf.py build +idf.py -p /dev/ttyUSB0 flash monitor +``` + +**Configuration minimale** (menuconfig) : + +```c +Espilon Bot Configuration + ├─ Device ID: "votre_id_unique" + ├─ Network → WiFi + │ ├─ SSID: "VotreWiFi" + │ └─ Password: "VotreMotDePasse" + └─ Server + ├─ IP: "192.168.1.100" + └─ Port: 2626 +``` + +--- + +## Qu'est-ce qu'Espilon ? + +Espilon transforme des microcontrôleurs ESP32 abordables à **~5€** en agents networked puissants pour : + +- **Recherche en sécurité** : Tests WiFi, reconnaissance réseau, IoT pentesting +- **Éducation** : Apprentissage de l'embarqué, protocoles réseau, FreeRTOS +- **Prototypage IoT** : Communication distribuée, monitoring, capteurs + +### Modes de Connectivité + +| Mode | Hardware | Portée | Use Case | +|------|----------|--------|----------| +| **WiFi** | ESP32 standard | 50-100m | Labs, bâtiments | +| **GPRS** | LilyGO T-Call | National (2G) | Mobile, remote | + +**General Packet Radio Service** vs **WiFi** + +--- + +## Architecture + +```md +┌─────────────────────────────────────────────────────┐ +│ 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 │ + └──────────────────────┘ +``` + +### Composants Clés + +- **Core** : Connexion réseau, crypto ChaCha20, protocole nanoPB +- **Modules** : Système extensible (Network, FakeAP, Recon, etc.) +- **C2 (C3PO)** : Serveur Python asyncio pour contrôle multi-agents +- **C3PO**: Ancien c2 (serveur web - Trilateration + Front affichage caméra) +- **Flasher** : Outil de flash multi-device automatisé + +--- + +## Modules Disponibles + +> **Note importante** : Les modules sont **mutuellement exclusifs**. Vous devez choisir **un seul module** lors de la configuration via menuconfig. + +### System Module (Built-in, toujours actif) + +Commandes système de base : + +- `system_reboot` : Redémarrage de l'ESP32 +- `system_mem` : Affichage de l'utilisation mémoire (heap free, heap min, internal free) +- `system_uptime` : Temps de fonctionnement depuis le boot + +### Network Module + +Module pour reconnaissance et tests réseau : + +- `ping [args...]` : Test de connectivité ICMP +- `arp_scan` : Découverte des hôtes sur le réseau local via ARP +- `proxy_start ` : Démarrer un proxy TCP +- `proxy_stop` : Arrêter le proxy en cours +- `dos_tcp ` : Test de charge TCP (à usage autorisé uniquement) + +### FakeAP Module + +Module pour création de points d'accès WiFi simulés : + +- `fakeap_start [open|wpa2] [password]` : Démarrer un faux point d'accès +- `fakeap_stop` : Arrêter le faux AP +- `fakeap_status` : Afficher le statut (AP, portal, sniffer, clients) +- `fakeap_clients` : Lister les clients connectés +- `fakeap_portal_start` : Activer le portail captif +- `fakeap_portal_stop` : Désactiver le portail captif +- `fakeap_sniffer_on` : Activer la capture de trafic réseau +- `fakeap_sniffer_off` : Désactiver la capture + +### Recon Module + +Module de reconnaissance et collecte de données. Deux modes disponibles : + +#### Mode Camera (ESP32-CAM) + +- `cam_start ` : Démarrer le streaming vidéo UDP (~7 FPS, QQVGA) +- `cam_stop` : Arrêter le streaming + +#### Mode BLE Trilateration + +- `trilat start ` : Démarrer la trilatération BLE avec POST HTTP +- `trilat stop` : Arrêter la trilatération + +--- + +**Configuration** : `idf.py menuconfig` → Espilon Bot Configuration → Modules + +Choisissez **un seul module** : + +- `CONFIG_MODULE_NETWORK` : Active le Network Module +- `CONFIG_MODULE_FAKEAP` : Active le FakeAP Module +- `CONFIG_MODULE_RECON` : Active le Recon Module + - Puis choisir : `Camera` ou `BLE Trilateration` + +--- + +## Outils + +### Multi-Device Flasher + +Flasher automatisé pour configurer plusieurs ESP32 : + +```bash +cd tools/flasher +python3 flash.py --config devices.json +``` + +**devices.json** : + +```json +{ + "project": "/home/user/epsilon/espilon_bot", + "devices": [ + ## WiFi AGENT ## + { + "device_id": "ce4f626b", + "port": "/dev/ttyUSB0", + "srv_ip": "192.168.1.13", + "srv_port": 2626, + "network_mode": "wifi", + "wifi_ssid": "MyWiFi", + "wifi_pass": "MyPassword123", + "hostname": "pixel-8-pro", + "module_network": true, + "module_recon": false, + "module_fakeap": false, + "recon_camera": false, + "recon_ble_trilat": false, + "crypto_key": "testde32chars00000000000000000000", + "crypto_nonce": "noncenonceno" + }, + + ## GPRS AGENT ## + { + "device_id": "a91dd021", + "port": "/dev/ttyUSB1", + "srv_ip": "203.0.113.10", + "srv_port": 2626, + "network_mode": "gprs", + "gprs_apn": "sl2sfr", + "hostname": "galaxy-s24-ultra", + "module_network": true, + "module_recon": false, + "module_fakeap": false + } + ] +} +``` + +Voir [tools/flasher/README.md](tools/flasher/README.md) pour la documentation complète. + +### C2 Server (C3PO) + +Serveur de Command & Control : + +```bash +cd tools/c2 +pip3 install -r requirements.txt +python3 c3po.py --port 2626 +``` + +**Commandes** : + +- `list` : Lister les agents connectés +- `select ` : Sélectionner un agent +- `cmd ` : Exécuter une commande +- `group` : Gérer les groupes d'agents + +--- + +## Sécurité + +### Chiffrement + +- **ChaCha20** pour les communications C2 +- **Clés configurables** via menuconfig +- **Protocol Buffers (nanoPB)** pour la sérialisation + +⚠️ **CHANGEZ LES CLÉS PAR DÉFAUT** pour un usage en production : + +```bash +# Générer des clés aléatoires +openssl rand -hex 32 # ChaCha20 key (32 bytes) +openssl rand -hex 12 # Nonce (12 bytes) +``` + +### Usage Responsable + +Espilon doit être utilisé uniquement pour : + +- Tests d'intrusion **autorisés** +- Recherche en sécurité **éthique** +- Éducation et formation +- Prototypage IoT légitime + +**Interdit** : Accès non autorisé, attaques malveillantes, violation de confidentialité. + +--- + +## Cas d'Usage + +### Pentest WiFi + +- Audit de sécurité réseau +- Test de robustesse WPA2/WPA3 +- Cartographie réseau + +### IoT Security Research + +- Test de devices IoT +- Analyse de protocoles +- Détection de vulnérabilités + +### Éducation + +- Labs de cybersécurité +- Cours d'embarqué +- CTF competitions + +--- + +## Roadmap + +### V2.0 (En cours) + +- [ ] Mesh networking (BLE/WiFi) +- [ ] Implémenter Module reccoon dans C3PO +- [ ] Améliorer la Documentations [here](https://docs.espilon.net) +- [ ] OTA updates +- [ ] Multilatération collaborative +- [ ] Optimisation mémoire + +### Future + +- [ ] PCB custom Espilon +- [ ] Support ESP32-S3/C3 +- [ ] Module SDK pour extensions tierces +- [ ] Web UI pour C2 + +--- + +## Licence + +Espilon est sous licence **MIT** avec addendum de sécurité. + +Voir [LICENSE](LICENSE) pour les détails complets. + +**En résumé** : + +- Utilisation libre pour recherche, éducation, développement +- Modification et distribution autorisées +- **Obtenir autorisation** avant tout déploiement +- Usage malveillant strictement interdit + +--- + +## Contributeurs + +- **@Eun0us** - Core architecture, modules +- **@off-path** - C2 server, protocol +- **@itsoktocryyy** - Network features, Wall Hack +- **@wepfen** - Documentation, tools + +### Contribuer + +Contributions bienvenues ! Voir [CONTRIBUTING.md](CONTRIBUTING.md). + +**Rejoignez-nous** : + +- Rapporter des bugs +- Proposer des features +- Soumettre des PRs +- Améliorer la doc + +--- + +## Liens Utiles + +- **[Documentation complète](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)** +- **English README** : [README.en.md](README.en.md) + +--- + +## Support + +- **Issues** : [GitHub Issues](https://github.com/Espilon-Net/Espilon-Source/issues) +- **Discussions** : [GitHub Discussions](https://github.com/Espilon-Net/Espilon-Source/discussions) + +--- + +**Présenté initialement à Le Hack (Juin 2025)** + +**Made with love for security research and education** diff --git a/README.md b/README.md index 0b28049..a8df945 100644 --- a/README.md +++ b/README.md @@ -2,51 +2,81 @@ ![Espilon Logo](assets/images/espilon-logo.jpg) -**Framework d'agents embarqués ESP32 pour la recherche en sécurité et l'IoT** +**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 est destiné à la recherche en sécurité, aux tests d'intrusion autorisés et à l'éducation. L'utilisation non autorisée est illégale. Obtenez toujours une autorisation écrite avant tout déploiement. +> **IMPORTANT**: Espilon is intended for security research, authorized penetration testing, and education. Unauthorized use is illegal. Always obtain written permission before any deployment. --- -## Documentation Complète +## Table of Contents -**[Consultez la documentation complète ici](https://docs.espilon.net)** +- [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) --- -La documentation MkDocs inclut : +The MkDocs documentation includes: ```md -- Guide d'installation pas à pas -- Traduction EN/FR -- Configuration WiFi et GPRS -- Référence des modules et commandes -- Guide du flasher multi-device -- Spécification du protocole C2 -- Exemples et cas d'usage +- 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 -### Prérequis +### Prerequisites - ESP-IDF v5.3.2 - Python 3.8+ -- ESP32 (tout modèle compatible) -- LilyGO T-Call pour le mode GPRS (optionnel) +- ESP32 (any compatible model) +- LilyGO T-Call for GPRS mode (optional) -### Installation Rapide +### Quick Installation ```bash -# 1. Installer ESP-IDF v5.3.2 +# 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 @@ -54,207 +84,182 @@ cd esp-idf ./install.sh esp32 . ./export.sh -# 2. Cloner Espilon +# 2. Clone Espilon cd ~ git clone https://github.com/Espilon-Net/epsilon-source.git -cd epsilon/espilon_bot +cd Espilon-Net/espilon_bot -# 3. Configurer +# 3. Configure with menuconfig or tools/flasher/devices.json idf.py menuconfig -# 4. Compiler et flasher +# 4. Build and flash idf.py build idf.py -p /dev/ttyUSB0 flash monitor ``` -**Configuration minimale** (menuconfig) : +**Minimal configuration** (menuconfig): ```c Espilon Bot Configuration - ├─ Device ID: "votre_id_unique" - ├─ Network → WiFi - │ ├─ SSID: "VotreWiFi" - │ └─ Password: "VotreMotDePasse" - └─ Server - ├─ IP: "192.168.1.100" - └─ Port: 2626 + |- Device ID: "your_unique_id" + |- Network -> WiFi + | |- SSID: "YourWiFi" + | |- Password: "YourPassword" + |- Server + |- IP: "192.168.1.100" + |- Port: 2626 ``` +![menuconfig](assets/images/menuconfig.png) + --- -## Qu'est-ce qu'Espilon ? +## What is Espilon? -Espilon transforme des microcontrôleurs ESP32 abordables à **~5€** en agents networked puissants pour : +Espilon transforms affordable ESP32 microcontrollers (~$5) into powerful networked agents for: -- **Recherche en sécurité** : Tests WiFi, reconnaissance réseau, IoT pentesting -- **Éducation** : Apprentissage de l'embarqué, protocoles réseau, FreeRTOS -- **Prototypage IoT** : Communication distribuée, monitoring, capteurs +- **Security research**: WiFi testing, network reconnaissance, IoT pentesting +- **Education**: Learning embedded systems, network protocols, FreeRTOS +- **IoT prototyping**: Distributed communication, monitoring, sensors -### Modes de Connectivité +### Connectivity Modes -| Mode | Hardware | Portée | Use Case | -|------|----------|--------|----------| -| **WiFi** | ESP32 standard | 50-100m | Labs, bâtiments | +| Mode | Hardware | Range | Use Case | +|------|----------|-------|----------| +| **WiFi** | Standard ESP32 | 50-100m | Labs, buildings | | **GPRS** | LilyGO T-Call | National (2G) | Mobile, remote | -**General Packet Radio Service** vs **WiFi** - --- ## Architecture -```md -┌─────────────────────────────────────────────────────┐ -│ 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 │ - └──────────────────────┘ +``` ++---------------------------------------------------------+ +| 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 | + +---------------------+ ``` -### Composants Clés +### Key Components -- **Core** : Connexion réseau, crypto ChaCha20, protocole nanoPB -- **Modules** : Système extensible (Network, FakeAP, Recon, etc.) -- **C2 (C3PO)** : Serveur Python asyncio pour contrôle multi-agents -- **C3PO**: Ancien c2 (serveur web - Trilateration + Front affichage caméra) -- **Flasher** : Outil de flash multi-device automatisé +- **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 --- -## Modules Disponibles +## Available Modules -> **Note importante** : Les modules sont **mutuellement exclusifs**. Vous devez choisir **un seul module** lors de la configuration via menuconfig. +> **Important note**: Modules are **mutually exclusive**. You must choose **only one module** during configuration via menuconfig. -### System Module (Built-in, toujours actif) +### System Module (Built-in, always active) -Commandes système de base : +Basic system commands: -- `system_reboot` : Redémarrage de l'ESP32 -- `system_mem` : Affichage de l'utilisation mémoire (heap free, heap min, internal free) -- `system_uptime` : Temps de fonctionnement depuis le boot +- `system_reboot`: Reboot the ESP32 +- `system_mem`: Display memory usage (heap free, heap min, internal free) +- `system_uptime`: Uptime since boot ### Network Module -Module pour reconnaissance et tests réseau : +Module for network reconnaissance and testing: -- `ping [args...]` : Test de connectivité ICMP -- `arp_scan` : Découverte des hôtes sur le réseau local via ARP -- `proxy_start ` : Démarrer un proxy TCP -- `proxy_stop` : Arrêter le proxy en cours -- `dos_tcp ` : Test de charge TCP (à usage autorisé uniquement) +- `ping [args...]`: ICMP connectivity test +- `arp_scan`: Discover hosts on local network via ARP +- `proxy_start `: Start a TCP proxy +- `proxy_stop`: Stop the running proxy +- `dos_tcp `: TCP load test (authorized use only) ### FakeAP Module -Module pour création de points d'accès WiFi simulés : +Module for creating simulated WiFi access points: -- `fakeap_start [open|wpa2] [password]` : Démarrer un faux point d'accès -- `fakeap_stop` : Arrêter le faux AP -- `fakeap_status` : Afficher le statut (AP, portal, sniffer, clients) -- `fakeap_clients` : Lister les clients connectés -- `fakeap_portal_start` : Activer le portail captif -- `fakeap_portal_stop` : Désactiver le portail captif -- `fakeap_sniffer_on` : Activer la capture de trafic réseau -- `fakeap_sniffer_off` : Désactiver la capture +- `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`: Enable captive portal +- `fakeap_portal_stop`: Disable captive portal +- `fakeap_sniffer_on`: Enable network traffic capture +- `fakeap_sniffer_off`: Disable capture ### Recon Module -Module de reconnaissance et collecte de données. Deux modes disponibles : +Reconnaissance and data collection module. Two modes available: -#### Mode Camera (ESP32-CAM) +#### Camera Mode (ESP32-CAM) -- `cam_start ` : Démarrer le streaming vidéo UDP (~7 FPS, QQVGA) -- `cam_stop` : Arrêter le streaming +- `cam_start `: Start UDP video streaming (~7 FPS, QQVGA) +- `cam_stop`: Stop streaming -#### Mode BLE Trilateration +#### BLE Trilateration Mode -- `trilat start ` : Démarrer la trilatération BLE avec POST HTTP -- `trilat stop` : Arrêter la trilatération +- `trilat start `: Start BLE trilateration with HTTP POST +- `trilat stop`: Stop trilateration --- -**Configuration** : `idf.py menuconfig` → Espilon Bot Configuration → Modules +**Configuration**: `idf.py menuconfig` -> Espilon Bot Configuration -> Modules -Choisissez **un seul module** : +Choose **only one module**: -- `CONFIG_MODULE_NETWORK` : Active le Network Module -- `CONFIG_MODULE_FAKEAP` : Active le FakeAP Module -- `CONFIG_MODULE_RECON` : Active le Recon Module - - Puis choisir : `Camera` ou `BLE Trilateration` +- `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` --- -## Outils +## Tools ### Multi-Device Flasher -Flasher automatisé pour configurer plusieurs ESP32 : +Automated flasher to configure multiple ESP32s: ```bash cd tools/flasher python3 flash.py --config devices.json ``` -**devices.json** : +**devices.json**: ```json { - "project": "/home/user/epsilon/espilon_bot", + "project": "/path/to/espilon_bot", "devices": [ - ## WiFi AGENT ## { - "device_id": "ce4f626b", + "device_id": "esp001", "port": "/dev/ttyUSB0", - "srv_ip": "192.168.1.13", - "srv_port": 2626, "network_mode": "wifi", - "wifi_ssid": "MyWiFi", - "wifi_pass": "MyPassword123", - "hostname": "pixel-8-pro", - "module_network": true, - "module_recon": false, - "module_fakeap": false, - "recon_camera": false, - "recon_ble_trilat": false, - "crypto_key": "testde32chars00000000000000000000", - "crypto_nonce": "noncenonceno" - }, - - ## GPRS AGENT ## - { - "device_id": "a91dd021", - "port": "/dev/ttyUSB1", - "srv_ip": "203.0.113.10", - "srv_port": 2626, - "network_mode": "gprs", - "gprs_apn": "sl2sfr", - "hostname": "galaxy-s24-ultra", - "module_network": true, - "module_recon": false, - "module_fakeap": false + "wifi_ssid": "MyNetwork", + "wifi_pass": "MyPassword", + "srv_ip": "192.168.1.100" } ] } ``` -Voir [tools/flasher/README.md](tools/flasher/README.md) pour la documentation complète. +See [tools/flasher/README.md](tools/flasher/README.md) for complete documentation. ### C2 Server (C3PO) -Serveur de Command & Control : +Command & Control server: ```bash cd tools/c2 @@ -262,137 +267,135 @@ pip3 install -r requirements.txt python3 c3po.py --port 2626 ``` -**Commandes** : +**Commands**: -- `list` : Lister les agents connectés -- `select ` : Sélectionner un agent -- `cmd ` : Exécuter une commande -- `group` : Gérer les groupes d'agents +- `list`: List connected agents +- `select `: Select an agent +- `cmd `: Execute a command +- `group`: Manage agent groups --- -## Sécurité +## Security -### Chiffrement +### Encryption -- **ChaCha20** pour les communications C2 -- **Clés configurables** via menuconfig -- **Protocol Buffers (nanoPB)** pour la sérialisation +- **ChaCha20** for C2 communications +- **Configurable keys** via menuconfig +- **Protocol Buffers (nanoPB)** for serialization -⚠️ **CHANGEZ LES CLÉS PAR DÉFAUT** pour un usage en production : +**CHANGE DEFAULT KEYS** for production use: ```bash -# Générer des clés aléatoires +# Generate random keys openssl rand -hex 32 # ChaCha20 key (32 bytes) openssl rand -hex 12 # Nonce (12 bytes) ``` -### Usage Responsable +### Responsible Use -Espilon doit être utilisé uniquement pour : +Espilon should only be used for: -- Tests d'intrusion **autorisés** -- Recherche en sécurité **éthique** -- Éducation et formation -- Prototypage IoT légitime +- **Authorized** penetration testing +- **Ethical** security research +- Education and training +- Legitimate IoT prototyping -**Interdit** : Accès non autorisé, attaques malveillantes, violation de confidentialité. +**Prohibited**: Unauthorized access, malicious attacks, privacy violations. --- -## Cas d'Usage +## Use Cases -### Pentest WiFi +### WiFi Pentesting -- Audit de sécurité réseau -- Test de robustesse WPA2/WPA3 -- Cartographie réseau +- Network security auditing +- WPA2/WPA3 robustness testing +- Network mapping ### IoT Security Research -- Test de devices IoT -- Analyse de protocoles -- Détection de vulnérabilités +- IoT device testing +- Protocol analysis +- Vulnerability detection -### Éducation +### Education -- Labs de cybersécurité -- Cours d'embarqué +- Cybersecurity labs +- Embedded systems courses - CTF competitions --- ## Roadmap -### V2.0 (En cours) +### V2.0 (In Progress) - [ ] Mesh networking (BLE/WiFi) -- [ ] Implémenter Module reccoon dans C3PO -- [ ] Améliorer la Documentations [here](https://docs.espilon.net) +- [ ] Improve documentation - [ ] OTA updates -- [ ] Multilatération collaborative -- [ ] Optimisation mémoire +- [ ] Collaborative multilateration +- [ ] Memory optimization ### Future -- [ ] PCB custom Espilon -- [ ] Support ESP32-S3/C3 -- [ ] Module SDK pour extensions tierces -- [ ] Web UI pour C2 +- [ ] Custom Espilon PCB +- [ ] ESP32-S3/C3 support +- [ ] Module SDK for third-party extensions +- [ ] Web UI for C2 --- -## Licence +## License -Espilon est sous licence **MIT** avec addendum de sécurité. +Espilon is licensed under **MIT** with a security addendum. -Voir [LICENSE](LICENSE) pour les détails complets. +See [LICENSE](LICENSE) for full details. -**En résumé** : - -- Utilisation libre pour recherche, éducation, développement -- Modification et distribution autorisées -- **Obtenir autorisation** avant tout déploiement -- Usage malveillant strictement interdit +**In summary**: +- Free use for research, education, development +- Modification and distribution allowed +- **Obtain authorization** before any deployment +- Malicious use strictly prohibited --- -## Contributeurs +## Contributors - **@Eun0us** - Core architecture, modules - **@off-path** - C2 server, protocol -- **@itsoktocryyy** - Network features, Wall Hack +- **@itsoktocryyy** - Network features, work on Mod Wall Hack - **@wepfen** - Documentation, tools -### Contribuer +### Contributing -Contributions bienvenues ! Voir [CONTRIBUTING.md](CONTRIBUTING.md). +Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). -**Rejoignez-nous** : +**Join us**: -- Rapporter des bugs -- Proposer des features -- Soumettre des PRs -- Améliorer la doc +- Report bugs +- Propose features +- Submit PRs +- Improve documentation --- -## Liens Utiles +## Useful Links -- **[Documentation complète](https://docs.espilon.net)** +- **[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)** -- **English README** : [README.en.md](README.en.md) +- **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) +- **Issues**: [GitHub Issues](https://github.com/Espilon-Net/Espilon-Source/issues) +- **Discussions**: [GitHub Discussions](https://github.com/Espilon-Net/Espilon-Source/discussions) --- -**Présenté initialement à Le Hack (Juin 2025)** +**Originally presented at Le Hack (June 2025)** **Made with love for security research and education** diff --git a/espilon_bot/sdkconfig.defaults b/espilon_bot/sdkconfig.defaults deleted file mode 100644 index aa3166f..0000000 --- a/espilon_bot/sdkconfig.defaults +++ /dev/null @@ -1,16 +0,0 @@ -CONFIG_ID="f34592e0" -CONFIG_WIFI_SSID="Livebox-CC80" -CONFIG_WIFI_PASS="PqKXRmcprmeWChcfQD" -CONFIG_SERVER_IP="192.168.1.13" -CONFIG_SERVER_PORT=2626 -CONFIG_MBEDTLS_CHACHA20_C=y -CONFIG_LWIP_IPV4_NAPT=y -CONFIG_LWIP_IPV4_NAPT_PORTMAP=y -CONFIG_LWIP_IP_FORWARD=y -CONFIG_LWIP_LOCAL_HOSTNAME="pixel-8-pro" -CONFIG_ENABLE_CAMERA=n - -# Bluetooth configuration -CONFIG_BT_ENABLED=y -CONFIG_BT_BLUEDROID_ENABLED=y -CONFIG_BT_BLE_ENABLED=y