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.
98 lines
3.6 KiB
Markdown
98 lines
3.6 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 (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 |
|
|
|
|
## 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/)
|