Eun0us/espilon-source
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8b6c1cd53d
espilon-source/README.md
Eun0us 8b6c1cd53d ε - ChaCha20-Poly1305 AEAD + HKDF crypto upgrade + C3PO rewrite + docs 
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
2026-02-10 21:28:45 +01:00

10 KiB
Raw Blame History

Espilon

Espilon Logo

Embedded ESP32 Agent Framework for Security Research and IoT

License: MIT ESP-IDF Platform

Important

: Espilon is intended for security research, authorized penetration testing, and education. Unauthorized use is illegal. Always obtain written permission before any deployment.

Table of Contents

Full Documentation

View the full documentation here

Documentation header

The MkDocs documentation includes:

- Step-by-step installation guide
- Translate EN/FR
- WiFi and GPRS configuration
- Module and command reference
- Multi-device flasher guide
- C2 protocol specification
- Examples and use cases

Quick Start

Prerequisites

  • ESP-IDF v5.3.2
  • Python 3.8+
  • ESP32 (any compatible model)
  • LilyGO T-Call for GPRS mode (optional)

Quick Installation

# 1. Install 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. Clone Espilon
cd ~
git clone https://github.com/Espilon-Net/epsilon-source.git
cd Espilon-Net/espilon_bot

# 3. Configure with menuconfig or tools/flasher/devices.json
idf.py menuconfig

# 4. Build and flash
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

Minimal configuration (menuconfig):

Espilon Bot Configuration
  |- Device ID: "your_unique_id"
  |- Network -> WiFi
  |   |- SSID: "YourWiFi"
  |   |- Password: "YourPassword"
  |- Server
      |- IP: "192.168.1.100"
      |- Port: 2626

menuconfig

What is Espilon?

Espilon transforms affordable ESP32 microcontrollers (~$5) into powerful networked agents for:

  • Security research: WiFi testing, network reconnaissance, IoT pentesting
  • Education: Learning embedded systems, network protocols, FreeRTOS
  • IoT prototyping: Distributed communication, monitoring, sensors

Connectivity Modes

Mode Hardware Range Use Case
WiFi Standard ESP32 50-100m Labs, buildings
GPRS LilyGO T-Call National (2G) Mobile, remote

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

Key Components

  • Core: Network connection, ChaCha20-Poly1305 AEAD + HKDF key derivation, nanoPB protocol
  • Modules: Extensible system (Network, FakeAP, Recon, etc.)
  • C2 (C3PO): Python asyncio server for multi-agent control
  • Flasher: Automated multi-device flashing tool

Available Modules

Important note: Modules are mutually exclusive. You must choose only one module during configuration via menuconfig.

System Module (Built-in, always active)

Basic system commands:

  • system_reboot: Reboot the ESP32
  • system_mem: Display memory usage (heap free, heap min, internal free)
  • system_uptime: Uptime since boot

Network Module

Module for network reconnaissance and testing:

  • ping <host> [args...]: ICMP connectivity test
  • arp_scan: Discover hosts on local network via ARP
  • proxy_start <ip> <port>: Start a TCP proxy
  • proxy_stop: Stop the running proxy
  • dos_tcp <ip> <port> <count>: TCP load test (authorized use only)

FakeAP Module

Module for creating simulated WiFi access points:

  • fakeap_start <ssid> [open|wpa2] [password]: Start a fake access point
  • fakeap_stop: Stop the fake AP
  • fakeap_status: Display status (AP, portal, sniffer, clients)
  • fakeap_clients: List connected clients
  • fakeap_portal_start: Enable captive portal
  • fakeap_portal_stop: Disable captive portal
  • fakeap_sniffer_on: Enable network traffic capture
  • fakeap_sniffer_off: Disable capture

Recon Module

Reconnaissance and data collection module. Two modes available:

Camera Mode (ESP32-CAM)

  • cam_start <ip> <port>: Start UDP video streaming (~7 FPS, QQVGA)
  • cam_stop: Stop streaming

BLE Trilateration Mode

  • trilat start <mac> <url> <bearer>: Start BLE trilateration with HTTP POST
  • trilat stop: Stop trilateration

Configuration: idf.py menuconfig -> Espilon Bot Configuration -> Modules

Choose only one module:

  • CONFIG_MODULE_NETWORK: Enable the Network Module
  • CONFIG_MODULE_FAKEAP: Enable the FakeAP Module
  • CONFIG_MODULE_RECON: Enable the Recon Module
    • Then choose: Camera or BLE Trilateration

Tools

Multi-Device Flasher

Automated flasher to configure multiple ESP32s:

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

devices.json:

{
  "project": "/path/to/espilon_bot",
  "devices": [
    {
      "device_id": "esp001",
      "port": "/dev/ttyUSB0",
      "network_mode": "wifi",
      "wifi_ssid": "MyNetwork",
      "wifi_pass": "MyPassword",
      "srv_ip": "192.168.1.100"
    }
  ]
}

See tools/flasher/README.md for complete documentation.

Device Provisioning

Each device needs a unique master key flashed into its factory NVS partition before first use:

cd tools/provisioning
python3 provision.py --device-id my-device --port /dev/ttyUSB0

This generates a 32-byte random master key, writes it to the factory NVS partition, and saves it to the C2 keystore (keys.json).

See tools/provisioning/ for details.

C2 Server (C3PO)

Command & Control server:

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

Full C2 documentation and command list: see tools/C3PO/README.md.

Security

Encryption

  • ChaCha20-Poly1305 AEAD for authenticated encryption of all C2 communications
  • HKDF-SHA256 key derivation (per-device master key + device ID salt)
  • Random 12-byte nonce per message (ESP32 hardware RNG)
  • Per-device master keys stored in factory NVS partition (read-only)
  • Protocol Buffers (nanoPB) for serialization

Provision each device with a unique master key using tools/provisioning/provision.py. Keys are never hardcoded in firmware.

Responsible Use

Espilon should only be used for:

  • Authorized penetration testing
  • Ethical security research
  • Education and training
  • Legitimate IoT prototyping

Prohibited: Unauthorized access, malicious attacks, privacy violations.

Use Cases

WiFi Pentesting

  • Network security auditing
  • WPA2/WPA3 robustness testing
  • Network mapping

IoT Security Research

  • IoT device testing
  • Protocol analysis
  • Vulnerability detection

Education

  • Cybersecurity labs
  • Embedded systems courses
  • CTF competitions

Roadmap

V2.0 (In Progress)

  • ChaCha20-Poly1305 AEAD + HKDF crypto upgrade
  • Per-device factory NVS key provisioning
  • C3PO C2 rewrite with per-device crypto
  • Mesh networking (BLE/WiFi)
  • OTA updates
  • Collaborative multilateration
  • Memory optimization

Future

  • Custom Espilon PCB
  • ESP32-S3/C3 support
  • Module SDK for third-party extensions
  • Web UI for C2

License

Espilon is licensed under MIT with a security addendum.

See LICENSE for full details.

In summary:

  • Free use for research, education, development
  • Modification and distribution allowed
  • Obtain authorization before any deployment
  • Malicious use strictly prohibited

Contributors

  • @Eun0us - Core architecture, modules
  • @off-path - C2 server, protocol
  • @itsoktocryyy - Network features, work on Mod Wall Hack
  • @wepfen - Documentation, tools

Contributing

Contributions welcome! See CONTRIBUTING.md.

Join us:

  • Report bugs
  • Propose features
  • Submit PRs
  • Improve documentation

Useful Links

Support

Originally presented at Le Hack (June 2025)

Made with love for security research and education