# 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) - [Red Team Module](#red-team-module) - [Honeypot Module](#honeypot-module) - [Tunnel Module](#tunnel-module-proxy-socks5) - [CAN Bus Module](#can-bus-module-mcp2515) - [OTA Module](#ota-module) - [Outils](#outils) - [Deploy Tool](#deploy-tool) - [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 deploy tool - 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 │← │ Poly1305 │← │ (nanoPB/TCP) │ │ │ └───────────┘ └──────────┘ └─────────────────┘ │ │ ↓ ↓ ↓ │ │ ┌───────────────────────────────────────────────┐ │ │ │ Module System (FreeRTOS) │ │ │ │ [Network] [Tunnel] [FakeAP] [Recon] │ │ │ │ [RedTeam] [Honeypot] [CAN Bus] [OTA] │ │ │ └───────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ ↕ Encrypted TCP ┌──────────────────────┐ │ C2 Server (C3PO) │ │ - Device Registry │ │ - Group Management │ │ - TUI + Web UI │ └──────────────────────┘ ``` ### Composants Clés - **Core** : Connexion réseau, ChaCha20-Poly1305 AEAD + dérivation HKDF, protocole nanoPB - **Modules** : Système extensible (Network, FakeAP, Recon, etc.) - **C2 (C3PO)** : Serveur Python asyncio + dashboard web pour contrôle multi-agents - **Deploy** : Pipeline unifié build, provision & flash (`tools/deploy.py`) --- ## Modules Disponibles > Les modules s'activent indépendamment via `idf.py menuconfig` → Espilon Bot Configuration → Modules. Plusieurs modules peuvent être actifs simultanément (selon les contraintes flash/RAM). ### 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, tests réseau et proxy tunnel SOCKS5 : - `ping [args...]` : Test de connectivité ICMP - `arp_scan` : Découverte des hôtes sur le réseau local via ARP - `dos_tcp ` : Test de charge TCP (à usage autorisé uniquement) - `tun_start ` : Démarrer le proxy tunnel SOCKS5 vers C3PO (nécessite `CONFIG_MODULE_TUNNEL`) - `tun_stop` : Arrêter le tunnel - `tun_status` : Statut du tunnel (channels, bytes, mode chiffrement) ### 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 ### Red Team Module Hunt WiFi autonome, attaques de credentials, et mesh relay ESP-NOW : - `rt_hunt` : Lancer le cycle scan + attaque WiFi autonome - `rt_stop` : Arrêter le hunt - `rt_status` : Cibles en cours, progression, credentials capturés - `rt_scan` : Scan passif des APs (mode promiscuous, sans association) - `rt_net_add ` / `rt_net_list` : Gérer les réseaux connus - `rt_mesh` : Activer le relay ESP-NOW mesh (multi-hop vers C2 hors portée) - Stealth : randomisation MAC, scan passif, contrôle puissance TX ### Honeypot Module Faux services réseau qui loggent les interactions des attaquants : - `hp_start` / `hp_stop` : Démarrer/arrêter tous les services - Services émulés : SSH, Telnet, HTTP, FTP (ports configurables) - `hp_wifi_mon_start` / `hp_wifi_mon_stop` : Monitor WiFi (probe, deauth, EAPOL, beacon flood) - `hp_net_mon_start` / `hp_net_mon_stop` : Détection anomalies réseau (port scan, SYN flood) - Tous les events remontés au C2 au format `EVT|` (dashboard honeypot C3PO) ### Tunnel Module (Proxy SOCKS5) Proxy tunnel SOCKS5 multiplexé à travers l'ESP32. Utilise n'importe quel outil réseau (`curl`, `nmap`, `proxychains`) pour pivoter à travers le bot sur le réseau cible. - Le SOCKS5 tourne côté C3PO (port 1080) — l'ESP32 ne gère que des frames binaires - Jusqu'à 8 connexions TCP simultanées (configurable via Kconfig) - Résolution DNS côté ESP32 (voit les DNS internes du réseau cible) - Reconnexion automatique avec backoff exponentiel - Chiffrement AEAD ChaCha20-Poly1305 par frame optionnel **Ports C3PO** : 2626 (commandes C2) + 2627 (données tunnel) + 1080 (SOCKS5, localhost uniquement) ```bash # Démarrer le tunnel depuis le C2 send tun_start 2627 # Utiliser n'importe quel outil à travers le proxy curl --socks5-hostname 127.0.0.1:1080 http://cible-interne.local nmap -sT -Pn --proxies socks4://127.0.0.1:1080 192.168.x.0/24 ``` Voir [TUNNEL.md](TUNNEL.md) pour la spécification complète du protocole et le guide de test. ### CAN Bus Module (MCP2515) CAN bus automobile via contrôleur SPI externe MCP2515 : - `can_start [bitrate] [mode]` : Init bus (normal/listen/loopback) - `can_sniff [duration]` / `can_record` / `can_replay` : Capture et replay - `can_send ` : Injection de trame - 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` ### OTA Module Mises à jour firmware over-the-air depuis le serveur C2 : - Téléchargement firmware HTTPS sécurisé (fallback HTTP optionnel) - Schéma dual partition (A/B) pour rollback sécurisé - Reporting de progression vers le 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 ou BLE Trilateration) - `CONFIG_MODULE_REDTEAM` : Red Team Module - `CONFIG_MODULE_HONEYPOT` : Honeypot Module - `CONFIG_MODULE_TUNNEL` : Proxy Tunnel SOCKS5 (nécessite `CONFIG_MODULE_NETWORK`) - `CONFIG_MODULE_CANBUS` : CAN Bus Module (nécessite hardware MCP2515) - `CONFIG_ESPILON_OTA_ENABLED` : OTA Updates --- ## Outils ### Deploy Tool Pipeline unifié pour **build**, **provisionner** (clés crypto), et **flasher** les ESP32 : ```bash cd tools # Assistant interactif python3 deploy.py # Un seul device python3 deploy.py -p /dev/ttyUSB0 -d mon-device \ --wifi MonSSID MonMotDePasse --srv 192.168.1.100 # Deploy batch python3 deploy.py --config deploy.example.json ``` Chaque deploy génère une **master key 256-bit** par device, l'écrit en factory NVS, et l'enregistre dans le keystore C2 (`keys.json`). Voir [tools/README.md](tools/README.md) pour la documentation complète (modes, batch config, OTA vs non-OTA, flash map). ### C2 Server (C3PO) Serveur de Command & Control : ```bash cd tools/C3PO pip3 install -r requirements.txt python3 c3po.py ``` Documentation complète et liste des commandes : voir [tools/C3PO/README.md](tools/C3PO/README.md). --- ## Sécurité ### Chiffrement - **ChaCha20-Poly1305 AEAD** pour le chiffrement authentifié de toutes les communications C2 - **HKDF-SHA256** dérivation de clé (master key per-device + salt device ID) - **Nonce aléatoire de 12 bytes** par message (RNG hardware ESP32) - **Master keys per-device** stockées en partition factory NVS (read-only) - **Protocol Buffers (nanoPB)** pour la sérialisation Provisionner chaque device avec une master key unique via `tools/deploy.py`. Les clés ne sont jamais hardcodées dans le firmware. ### 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 (Complet) - [x] Upgrade crypto ChaCha20-Poly1305 AEAD + HKDF - [x] Provisioning per-device factory NVS - [x] Réécriture C3PO avec crypto per-device - [x] OTA firmware updates - [x] Module Red Team (hunt WiFi autonome) - [x] Module Honeypot (faux services + monitoring) - [x] Module CAN Bus (MCP2515 — sniff, inject, UDS, OBD-II, fuzzing) - [x] Web dashboard avec gestion devices, caméra, MLAT, OTA, CAN - [x] Proxy tunnel SOCKS5 (pivot multiplexé à travers l'ESP32) ### Future - [ ] Module BLE (scan, GATT enum, beacon spoofing) - [ ] Module Sub-GHz (CC1101 — 433/868/915 MHz) - [ ] Module BadUSB (ESP32-S2/S3 HID injection) - [ ] PCB custom Espilon - [ ] Support ESP32-S3/C3 - [ ] Module SDK pour extensions tierces --- ## 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.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) --- **Présenté initialement à Le Hack (Juin 2025)** **Made with love for security research and education**