8b6c1cd53d
Crypto: - Replace broken ChaCha20 (static nonce) with ChaCha20-Poly1305 AEAD - HKDF-SHA256 key derivation from per-device factory NVS master keys - Random 12-byte nonce per message (ESP32 hardware RNG) - crypto_init/encrypt/decrypt API with mbedtls legacy (ESP-IDF v5.3.2) - Custom partition table with factory NVS (fctry at 0x10000) Firmware: - crypto.c full rewrite, messages.c device_id prefix + AEAD encrypt - crypto_init() at boot with esp_restart() on failure - Fix command_t initializations across all modules (sub/help fields) - Clean CMakeLists dependencies for ESP-IDF v5.3.2 C3PO (C2): - Rename tools/c2 + tools/c3po -> tools/C3PO - Per-device CryptoContext with HKDF key derivation - KeyStore (keys.json) for master key management - Transport parses device_id:base64(...) wire format Tools: - New tools/provisioning/provision.py for factory NVS key generation - Updated flasher with mbedtls config for v5.3.2 Docs: - Update all READMEs for new crypto, C3PO paths, provisioning - Update roadmap, architecture diagrams, security sections - Update CONTRIBUTING.md project structure
432 lines
12 KiB
Markdown
432 lines
12 KiB
Markdown
# Espilon
|
|
|
|
|
|
|
|
**Framework d'agents embarqués ESP32 pour la recherche en sécurité et l'IoT**
|
|
|
|
[](LICENSE)
|
|
[](https://github.com/espressif/esp-idf)
|
|
[](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)**
|
|
|
|
|
|
|
|
---
|
|
|
|
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 │← │ Poly1305 │← │ (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, ChaCha20-Poly1305 AEAD + dérivation HKDF, 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 <host> [args...]` : Test de connectivité ICMP
|
|
- `arp_scan` : Découverte des hôtes sur le réseau local via ARP
|
|
- `proxy_start <ip> <port>` : Démarrer un proxy TCP
|
|
- `proxy_stop` : Arrêter le proxy en cours
|
|
- `dos_tcp <ip> <port> <count>` : Test de charge TCP (à usage autorisé uniquement)
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
**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,
|
|
},
|
|
|
|
## 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.
|
|
|
|
### Provisioning des Devices
|
|
|
|
Chaque device nécessite une master key unique flashée dans sa partition factory NVS :
|
|
|
|
```bash
|
|
cd tools/provisioning
|
|
python3 provision.py --device-id mon-device --port /dev/ttyUSB0
|
|
```
|
|
|
|
Génère une clé aléatoire de 32 bytes, l'écrit en factory NVS, et la sauvegarde dans le keystore C2 (`keys.json`).
|
|
|
|
Voir [tools/provisioning/](tools/provisioning/) pour les détails.
|
|
|
|
### 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/provisioning/provision.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 (En cours)
|
|
|
|
- [x] Upgrade crypto ChaCha20-Poly1305 AEAD + HKDF
|
|
- [x] Provisioning per-device factory NVS
|
|
- [x] Réécriture C3PO avec crypto per-device
|
|
- [ ] Mesh networking (BLE/WiFi)
|
|
- [ ] 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**
|