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

15 KiB
Raw Permalink Blame History

Espilon

Espilon Logo

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

License: MIT ESP-IDF Platform

⚠️ 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

Consultez la documentation complète ici

Documentation header

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 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

# 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] [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)

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

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 pour la documentation complète (modes, batch config, OTA vs non-OTA, flash map).

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/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)

  • Upgrade crypto ChaCha20-Poly1305 AEAD + HKDF
  • Provisioning per-device factory NVS
  • Réécriture C3PO avec crypto per-device
  • OTA firmware updates
  • Module Red Team (hunt WiFi autonome)
  • Module Honeypot (faux services + monitoring)
  • Module CAN Bus (MCP2515 — sniff, inject, UDS, OBD-II, fuzzing)
  • Web dashboard avec gestion devices, caméra, MLAT, OTA, CAN
  • 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 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

Support

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

Made with love for security research and education