espilon-source/README.fr.md

Espilon

Framework d'agents embarqués ESP32 pour la recherche en sécurité et l'IoT

⚠️ 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
• Quick Start
  • Prérequis
  • Installation Rapide
• Qu'est-ce qu'Espilon ?
  • Modes de Connectivité
• Architecture
  • Composants Clés
• Modules Disponibles
  • System Module
  • Network Module
  • FakeAP Module
  • Recon Module
• Outils
  • Multi-Device Flasher
  • C2 Server (C3PO)
• Sécurité
  • Chiffrement
  • Usage Responsable
• Cas d'Usage
• Roadmap
• Licence
• Contributeurs
• Liens Utiles
• Support

---

Documentation Complète

Consultez la documentation complète ici

---

La documentation MkDocs inclut :

- 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

# 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) :

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

┌─────────────────────────────────────────────────────┐
│                   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 :

cd tools/flasher
python3 flash.py --config devices.json

devices.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 pour la documentation complète.

Provisioning des Devices

Chaque device nécessite une master key unique flashée dans sa partition factory NVS :

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/ pour les détails.

C2 Server (C3PO)

Serveur de Command & Control :

cd tools/C3PO
pip3 install -r requirements.txt
python3 c3po.py

Documentation complète et liste des commandes : voir 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)

• Upgrade crypto ChaCha20-Poly1305 AEAD + HKDF
• Provisioning per-device factory NVS
• 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 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.

Rejoignez-nous :

• Rapporter des bugs
• Proposer des features
• Soumettre des PRs
• Améliorer la doc

---

Liens Utiles

• Documentation complète
• ESP-IDF Documentation
• LilyGO T-Call
• English README : README.en.md

---

Support

• Issues : GitHub Issues
• Discussions : GitHub Discussions

---

Présenté initialement à Le Hack (Juin 2025)

Made with love for security research and education