f87ddec742
Plan for REST API backend (purple team/OPSEC/OSINT): - Phase 1: Project scaffold, SQLAlchemy models, podman - Phase 2: UDP collector for sensor data streams - Phase 3: Core API endpoints (sensors, devices, alerts, probes, events) - Phase 4: OSINT features (OUI lookup, BLE company ID mapping) - Phase 5: Fleet management API Port allocation: - TCP 5500: HTTP REST API - UDP 5500: Sensor data collector - UDP 5501: Sensor commands (outbound) Also documents completed v1.8 (HTTPS OTA) and v1.9 (multi-channel scanning, BLE fingerprinting) milestones.
3.6 KiB
3.6 KiB
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 (Python, Flask) |
Current State (v1.9)
- 3x ESP32-DevKitC V1 deployed with custom firmware
- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
- Remote management via UDP commands (port 5501)
- OTA firmware updates (HTTP/HTTPS)
- Presence detection via CSI baseline calibration
- Multi-channel scanning for broader WiFi coverage
- BLE fingerprinting (company_id, tx_power, flags)
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 (planned) |
~/git/esp-tools/ |
CLI tools (esp-ctl, esp-fleet, esp-ota) |
~/esp/esp-idf/ |
ESP-IDF toolchain |
API Endpoints (Planned)
Base URL: http://<host>:5500/api/v1
| Method | Endpoint | Description |
|---|---|---|
| GET | /sensors |
List sensors with status |
| GET | /devices |
List discovered devices |
| GET | /alerts |
Alert feed with filters |
| GET | /probes |
Probe requests |
| GET | /events |
Sensor events |
| POST | /sensors/<id>/command |
Send command to sensor |
| GET | /stats |
Aggregate statistics |