Eun0us/espilon-source
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
espilon-source/README.fr.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

466 lines
15 KiB
Markdown
Raw Permalink Blame History

# 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 <host> [args...]` : Test de connectivité ICMP
- `arp_scan` : Découverte des hôtes sur le réseau local via ARP
- `dos_tcp <ip> <port> <count>` : Test de charge TCP (à usage autorisé uniquement)
- `tun_start <ip> <port>` : 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 <ssid> [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 <ip> <port>` : Démarrer le streaming vidéo UDP (~7 FPS, QQVGA)
- `cam_stop` : Arrêter le streaming
#### Mode BLE Trilateration
- `trilat start <mac> <url> <bearer>` : 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 <ssid> <pass>` / `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 <device_id> tun_start <c3po_ip> 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 <id> <data>` : Injection de trame
- 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`
### 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**
Reference in New Issue View Git Blame Copy Permalink