122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# ESP32 Hacking Project
|
|
|
|
## Overview
|
|
|
|
Firmware and tooling for ESP32 CSI (Channel State Information) sensors used for passive wireless sensing, device tracking, and security monitoring (OPSEC/OSINT/Purple team).
|
|
|
|
## Goals
|
|
|
|
- Custom ESP32 firmware with remote management, OTA updates, adaptive sampling
|
|
- BLE scanning and WiFi probe/deauth detection for device intelligence
|
|
- CSI-based presence detection without cameras
|
|
- Flask REST API backend for data aggregation and OSINT queries
|
|
- Fleet management for multiple sensors
|
|
|
|
## Components
|
|
|
|
| Component | Location | Description |
|
|
|-----------|----------|-------------|
|
|
| Firmware | `get-started/csi_recv_router/` | ESP32 sensor firmware (C, ESP-IDF) |
|
|
| CLI Tools | `~/git/esp-tools/` | `esp-ctl`, `esp-fleet`, `esp-ota` |
|
|
| Flask API | `~/git/esp32-web/` | REST API backend (v0.1.5, Python, Flask) |
|
|
|
|
## Current State
|
|
|
|
### Firmware: v1.11.0 (+ unreleased v1.12 changes)
|
|
|
|
- 3x ESP32-DevKitC V1 deployed with custom firmware
|
|
- 31 UDP commands (ALERT, HELP, CONFIG, FACTORY, STATUS, PING, LOG, CSI, CALIBRATE, PRESENCE, ...)
|
|
- 28 NVS-persisted configuration keys
|
|
- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
|
|
- Remote management via UDP commands (port 5501)
|
|
- OTA firmware updates (HTTP/HTTPS) with rollback
|
|
- Presence detection via CSI baseline calibration
|
|
- Multi-channel scanning for broader WiFi coverage
|
|
- BLE fingerprinting (company_id, tx_power, flags)
|
|
- LED quiet mode (default off, solid on motion/presence)
|
|
|
|
### Web Backend: v0.1.5
|
|
|
|
- Flask + SQLAlchemy + SQLite (WAL mode)
|
|
- UDP collector (all 5 sensor streams)
|
|
- REST API: sensors, devices, alerts, probes, events, stats, export, zones
|
|
- Intelligence dashboard: vendor treemap, SSID graph, fingerprint clusters, presence timeline
|
|
- 3D floorplan, OpenAPI/Swagger, 77 tests passing
|
|
|
|
## Hardware
|
|
|
|
| Device | Chip | IP Address | Location |
|
|
|--------|------|------------|----------|
|
|
| muddy-storm | ESP32-WROOM-32 | 192.168.129.29 | Living Room |
|
|
| amber-maple | ESP32-WROOM-32 | 192.168.129.30 | Office |
|
|
| hollow-acorn | ESP32-WROOM-32 | 192.168.129.31 | Kitchen |
|
|
|
|
## Network Ports
|
|
|
|
| Port | Protocol | Direction | Description |
|
|
|------|----------|-----------|-------------|
|
|
| 5500 | UDP | Sensors → Flask | Sensor data streams (CSI, BLE, probes, alerts, events) |
|
|
| 5500 | TCP | Clients → Flask | REST API (HTTP) |
|
|
| 5501 | UDP | Flask → Sensors | Sensor commands |
|
|
|
|
## Data Streams (UDP 5500)
|
|
|
|
| Stream | Format | Use Case |
|
|
|--------|--------|----------|
|
|
| CSI_DATA | hostname,count,mac,rssi,... | Motion/presence detection |
|
|
| BLE_DATA | hostname,mac,rssi,type,name,company_id,tx_power,flags | Device fingerprinting |
|
|
| PROBE_DATA | hostname,mac,rssi,ssid,channel | Device tracking, SSID enumeration |
|
|
| ALERT_DATA | hostname,type,source,target,rssi | Wireless IDS (deauth detection) |
|
|
| EVENT | hostname,key=value pairs | Motion, presence, calibration events |
|
|
|
|
## Software Stack
|
|
|
|
| Component | Version | Purpose |
|
|
|-----------|---------|---------|
|
|
| ESP-IDF | v5.5.2 | Firmware development framework |
|
|
| Flask | 3.x | REST API backend |
|
|
| SQLAlchemy | 2.x | Database ORM |
|
|
| SQLite/PostgreSQL | - | Data storage |
|
|
| podman | - | Container runtime |
|
|
|
|
## Key Paths
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `~/git/esp32-hacking/` | This project (firmware sources, docs) |
|
|
| `~/git/esp32-web/` | Flask API backend (v0.1.5) |
|
|
| `~/git/esp-tools/` | CLI tools (esp-ctl, esp-fleet, esp-ota) |
|
|
| `~/esp/esp-idf/` | ESP-IDF toolchain |
|
|
|
|
## API Endpoints
|
|
|
|
Base URL: `http://<host>:5500/api/v1`
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/sensors` | List sensors with status |
|
|
| GET | `/sensors/<id>` | Sensor detail |
|
|
| GET | `/sensors/<id>/config` | Sensor configuration |
|
|
| PUT | `/sensors/<id>/config` | Update sensor config |
|
|
| POST | `/sensors/<id>/command` | Send UDP command |
|
|
| POST | `/sensors/<id>/ota` | Trigger OTA update |
|
|
| POST | `/sensors/<id>/calibrate` | Trigger calibration |
|
|
| GET | `/devices` | List discovered devices |
|
|
| GET | `/devices/<id>` | Device detail |
|
|
| GET | `/alerts` | Alert feed with filters |
|
|
| GET | `/probes` | Probe requests |
|
|
| GET | `/events` | Sensor events |
|
|
| GET | `/stats` | Aggregate statistics |
|
|
| GET | `/zones` | List zones |
|
|
| POST | `/zones` | Create zone |
|
|
| PUT | `/zones/<id>` | Update zone |
|
|
| GET | `/export/devices.csv` | Export devices |
|
|
| GET | `/intelligence/*` | Vendor treemap, SSID graph, fingerprints, presence |
|
|
|
|
## References
|
|
|
|
- [ESP-IDF Docs](https://docs.espressif.com/projects/esp-idf/en/latest/)
|
|
- [ESP-CSI GitHub](https://github.com/espressif/esp-csi)
|
|
- [IEEE OUI Database](https://standards-oui.ieee.org/)
|
|
- [Bluetooth Company Identifiers](https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/)
|