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.
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# ESP32 Hacking TODO
|
|
|
|
## Flask API (`~/git/esp32-web/`)
|
|
|
|
### Architecture
|
|
- [ ] App factory pattern (`create_app()`)
|
|
- [ ] Blueprints: `api`, `collector`
|
|
- [ ] SQLAlchemy with migrations (Flask-Migrate)
|
|
- [ ] Background UDP collector (threading or Celery)
|
|
- [ ] Config from environment variables
|
|
- [ ] Port 5500: HTTP API (TCP) + UDP collector (UDP) on same port number
|
|
|
|
### Database Schema
|
|
- [ ] `sensors` — id, hostname, ip, last_seen, status, config_json
|
|
- [ ] `devices` — mac, type (ble/wifi), vendor, first_seen, last_seen
|
|
- [ ] `sightings` — device_id, sensor_id, rssi, timestamp
|
|
- [ ] `alerts` — sensor_id, type, source_mac, target_mac, rssi, timestamp
|
|
- [ ] `probes` — device_id, sensor_id, ssid, rssi, channel, timestamp
|
|
- [ ] `events` — sensor_id, event_type, payload_json, timestamp
|
|
|
|
### API Endpoints
|
|
- [ ] Sensors: list, detail, status, command, config, history
|
|
- [ ] Devices: list, detail, profile, sightings
|
|
- [ ] Alerts: list with filters (type, sensor, time range)
|
|
- [ ] Probes: list, group by SSID, group by MAC
|
|
- [ ] Events: list with filters
|
|
- [ ] Stats: counts, activity graphs data
|
|
- [ ] Export: CSV, JSON for devices/alerts/probes
|
|
|
|
### UDP Collector
|
|
- [ ] Parse CSI_DATA (hostname, count, mac, rssi, features)
|
|
- [ ] Parse BLE_DATA (hostname, mac, rssi, type, name, company_id, tx_power, flags)
|
|
- [ ] Parse PROBE_DATA (hostname, mac, rssi, ssid, channel)
|
|
- [ ] Parse ALERT_DATA (hostname, type, source, target, rssi OR flood count)
|
|
- [ ] Parse EVENT (hostname, key=value pairs)
|
|
- [ ] Heartbeat timeout detection (mark sensor offline)
|
|
|
|
### OSINT
|
|
- [ ] IEEE OUI database (download + parse)
|
|
- [ ] BLE company ID database (Bluetooth SIG)
|
|
- [ ] Device fingerprinting by BLE advertisement patterns
|
|
- [ ] Probe request SSID profiling (home networks, corporate, etc.)
|
|
|
|
## Firmware
|
|
|
|
- [ ] Deep sleep mode with wake-on-CSI-motion
|
|
- [ ] Battery-optimized duty cycling
|
|
- [ ] AP+STA config portal (captive portal for initial setup)
|
|
|
|
## Tools (esp-ctl)
|
|
|
|
- [ ] Migrate OSINT database to Flask API (esp-ctl becomes thin client)
|
|
- [ ] `esp-ctl api` subcommand (query Flask API)
|
|
|
|
## Testing
|
|
|
|
- [ ] Benchmark: CSI callback latency
|
|
- [ ] Benchmark: UDP throughput at different rates
|
|
- [ ] Power consumption measurements (per-mode: idle, CSI, BLE, probe)
|
|
- [ ] API load testing (concurrent requests)
|
|
|
|
## Documentation
|
|
|
|
- [ ] Flask API: OpenAPI/Swagger spec
|
|
- [ ] Deployment guide (podman, systemd)
|
|
- [ ] Pin mapping for ESP32-DevKitC V1
|
|
- [ ] Compare CSI quality: passive (router) vs active (ESP-NOW)
|
|
- [ ] Multi-sensor deployment guide (placement, zones, triangulation)
|
|
|
|
## Ideas
|
|
|
|
- ESP-NOW mesh for direct ESP32-to-ESP32 CSI
|
|
- External PIR sensor for CSI ground truth validation
|
|
- RSSI triangulation with 3+ sensors (approximate device location)
|
|
- Home Assistant MQTT discovery integration
|
|
- Grafana dashboards for long-term analytics
|
|
- ML-based device classification (phone vs laptop vs IoT)
|
|
- Webhook callbacks for alerts (Slack, Discord, ntfy)
|
|
- Rate limiting and API authentication (JWT)
|