Files

user 31724df63f docs: Add pentest results and update project docs

Executed non-invasive pentest against amber-maple (v1.12-dev):
- Phase 1: mDNS, port scan, binary analysis, eFuse readout
- Phase 2: HMAC timing, command injection (27 tests), replay (6 tests)
- Phase 3: NVS analysis, CVE check (12 CVEs), binary structure
All network-facing tests PASS. Physical security gaps documented.

2026-02-14 21:55:47 +01:00

10 KiB

Raw Blame History

ESP32 Hacking Roadmap

v0.1 - Documentation & Setup [DONE]

Copy firmware sources from esp-csi
Document current firmware behavior
Document CSI data format
Document build & flash process
List firmware modification ideas with priorities
Verify build from repo (ESP-IDF v5.5.2, aarch64)

v0.2 - Remote Management [DONE]

Add UDP command listener on ESP32 (port 5501)
Implement REBOOT command
Implement IDENTIFY command (LED solid 5s)
Implement STATUS command (uptime, heap, RSSI, tx_power, rate, version)
Implement RATE command (change ping Hz, NVS persist)
Implement POWER command (TX power dBm, NVS persist)
Add LED status indicator (off/slow blink/fast blink/solid)
NVS persistence for rate and tx_power settings
Pi-side esp-cmd and esp-fleet CLI tools
mDNS hostname, watchdog, human-readable uptime
Build and flash to device
Update CHEATSHEET.md with new commands

v0.3 - OTA Updates [DONE]

Dual OTA partition table (ota_0 + ota_1, 1920 KB each)
4MB flash config, custom partitions in sdkconfig.defaults
OTA command handler + ota_task in firmware
LED_OTA double-blink pattern during download
Bootloader rollback on failed update (30s watchdog)
Version field in STATUS reply
Pi-side esp-ota tool (HTTP server + OTA orchestration)
esp-fleet ota subcommand (sequential fleet update)
USB-flash first device (partition table change)
End-to-end OTA test

v0.4 - Adaptive Sampling [DONE]

On-device CSI wander calculation (coefficient of variation)
Reduce to 10 pkt/s when idle (3s holdoff)
Increase to 100 pkt/s on motion detection
Rate change EVENT notification to Pi via UDP
ADAPTIVE ON/OFF command (NVS persisted)
THRESHOLD command for tuning sensitivity (NVS persisted)
RATE command disables adaptive mode
adaptive/motion fields in STATUS reply

v0.5 - BLE Scanning [DONE]

Enable Bluetooth alongside WiFi (NimBLE, BLE ON/OFF command)
Periodic BLE advertisement scanning
Report device MAC, RSSI, name via UDP (BLE_DATA,<mac>,<rssi>,<type>,<name>)
Pi-side BLE device tracking (esp-ctl ble --track, dedup, summary table)

v1.0 - Production Firmware [DONE]

mDNS auto-discovery
Watchdog + auto-recovery
Configuration via UDP (TARGET <ip> [port], NVS persisted)
Comprehensive error handling (watchdog, WiFi reconnect via example_connect)
esp-ctl unified CLI tool (cmd, status, listen, serial, ble, target, profile)
PROFILE command (heap, stack watermarks, CPU runtime stats)

v1.1 - Passive Sensing & Multi-Sensor [DONE]

Sensor ID in data packets (hostname prefix on CSI_DATA, BLE_DATA, EVENT)
WiFi probe request capture (PROBE_DATA,<sensor>,<mac>,<rssi>,<ssid>, 10s dedup)
Deauth/disassoc frame detection (ALERT_DATA,<sensor>,<type>,<sender>,<target>,<rssi>)
BLE alerting (esp-ctl ble --known, alert on unknown MACs)
BLE dwell time tracking (esp-ctl ble --track dwell column)
Timestamped event logging (esp-ctl listen --timestamp)
Runtime HOSTNAME command (NVS persisted, mDNS updated)
mDNS service advertisement (_esp-csi._udp) + discovery (esp-ctl discover)
SCANRATE / PROBERATE tuning commands (NVS persisted)
Chip temperature reporting in STATUS (temp= field)
Channel, boot count, RSSI min/max, actual CSI rate in STATUS
FreeRTOS CPU runtime stats in PROFILE

Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — breaks CSI callback. Works on ESP32-C6+.

v1.2 - On-Device CSI Processing [DONE]

On-device feature extraction (amp_rms, amp_std, amp_max, amp_max_idx, energy)
CSIMODE command: RAW, COMPACT, HYBRID N (NVS persisted)
Compact payload format (F:rms,std,max,idx,energy — ~80% bandwidth reduction)
Hybrid mode: compact every packet, raw every Nth
Adaptive sampling reuses extracted energy (no duplicate computation)

v1.3 - Security & OSINT [DONE]

HMAC-SHA256 command authentication (firmware + esp-ctl/esp-cmd/esp-fleet/esp-ota)
AUTH command (set/query/disable secret, NVS persisted)
Deauth flood detection (ring buffer, aggregate ALERT_DATA)
FLOODTHRESH command (count + window, NVS persisted)
MAC OUI vendor lookup (esp-ctl oui, IEEE CSV database)
OSINT SQLite database (probe_ssids, device_sightings tables)
Watch daemon (esp-ctl watch — listen + enrich + store)
OSINT query CLI (esp-ctl osint probes/devices/mac/stats)
Home Assistant webhook integration (deauth_flood, unknown_probe, unknown_ble)
Parallel OTA fleet updates (esp-fleet ota --parallel)

v1.4 - Multi-Sensor & Validation [DONE]

Multi-sensor BLE correlation in esp-ctl (zone tracking by source sensor)
Zone tracking with EMA RSSI (esp-ctl osint zones, device_zones table)
Per-sensor breakdown in MAC profile (esp-ctl osint mac)
POWERTEST command (7-phase power profiling with EVENT markers)

v1.5 - Event Handling & NVS Persistence [DONE]

EVENT packet parsing in watch daemon (motion, wifi_reconnect, powertest)
Sensor heartbeat tracking (offline/online detection, configurable timeout)
sensor_events table with indexed queries (esp-ctl osint events)
HA webhooks for sensor_offline, sensor_online, motion_change
NVS persistence for SCANRATE and PROBERATE commands
Sensor events count in esp-ctl osint stats

v1.6 - Power Management [DONE]

ESP-IDF power management framework (DFS 240/80 MHz + light sleep)
POWERSAVE command (WiFi modem sleep toggle, NVS persisted, default off)
POWERTEST save/restore of powersave state
sdkconfig: CONFIG_PM_ENABLE, CONFIG_FREERTOS_USE_TICKLESS_IDLE

v1.7 - Baseline Calibration & Presence Detection [DONE]

CALIBRATE command (capture N seconds of CSI with room empty, average per-subcarrier amplitudes, store in NVS)
CALIBRATE STATUS / CALIBRATE CLEAR subcommands
Presence scoring (normalized Euclidean distance of live CSI vs baseline, rolling window)
PRESENCE ON/OFF command (NVS persisted, requires valid baseline)
PRESENCE THRESHOLD command (tunable 0.001-1.0, NVS persisted)
Presence events (EVENT,<hostname>,presence=<0|1> score=<float>) with 10s holdoff
Calibration done event (EVENT,<hostname>,calibrate=done packets=<n> nsub=<n>)
presence= and pr_score= fields in STATUS reply
NVS persistence for baseline (bl_amps blob, bl_nsub) and presence config

v1.8 - HTTPS OTA Support [DONE]

Support HTTPS URLs for OTA updates (esp_https_ota)
CI: Upload firmware to Gitea releases for OTA
CI: Simplify deploy script to pure POSIX sh

v1.9 - Multi-Channel Scanning & BLE Fingerprinting [DONE]

CHANSCAN command (ON/OFF/NOW/INTERVAL)
Channel hopping (1-13) with 100ms dwell, pause CSI during scan
chanscan= field in STATUS, chanscan_int NVS persistence
BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA
Historical presence sessions support

v1.10 - LED Quiet Mode & CI Hardening [DONE]

LED quiet mode (off normally, solid on motion/presence, blinks on OTA)
Default LED to quiet mode
Build metadata in STATUS (date, time, IDF version, chip info)
CI security checks (secrets scan, config validation, size check)
Size optimization (-Os, saves ~75KB vs -O2)
CSI ON/OFF toggle command (NVS persisted)

v1.11 - Diagnostics & Usability [DONE]

HELP command (lists all commands with syntax)
CONFIG command (dump all running config key=value)
FACTORY command (erase NVS config + reboot)
PING command (echo reply for connectivity tests)
LOG command (runtime log level control)
RSSI RESET command (reset min/max counters)
OTA rollback validation (crasher firmware + bootloader rollback confirmed)
Tagged v1.11.0 and OTA deployed to all 3 sensors

v1.12 - Security Hardening & Monitoring (unreleased)

ALERT command (temp/heap thresholds, EVENT emission, 60s holdoff, NVS persisted)
Auth whitelist (read-only queries only without HMAC)
AUTH OFF disabled remotely (serial/FACTORY only)
STATUS split (minimal unauthed vs full authed)
Rate limiter (50ms throttle, 20 cmd/s)
NVS write throttle (20 writes per 10s)
CSI buffer bounds checking (UDP_REM macro)
PMF required (CONFIG_ESP_WIFI_PMF_REQUIRED=y)
mDNS stripped to hostname-only (no service advertisement)
Serial console AUTH management
Auto-generated auth secret on first boot
Pentest completed: 50+ tests, all network-facing tests PASS
Enable stack canaries (CONFIG_COMPILER_STACK_CHECK_MODE_NORM)
Enable heap poisoning (CONFIG_HEAP_POISONING_LIGHT)
Multi-target (send data to 2+ UDP destinations)

Web Backend (`~/git/esp32-web/`)

Tracked in its own repository. See ~/git/esp32-web/ROADMAP.md.

Current: v0.1.5 (zones, intelligence dashboard, fleet management, 77 tests). Next: v0.1.6 (auth, rate limiting, production deployment).

v3.0 - Hardware Upgrade (ESP32-S3/C6)

Requires replacing current ESP32 (original) DevKitC V1 boards with ESP32-S3 or ESP32-C6 modules. The original ESP32 lacks FTM and has CSI/promiscuous mode conflicts.

Select target chip (ESP32-S3 for dual-core + BLE 5, or C6 for WiFi 6 + 802.15.4)
Port firmware to new target (idf.py set-target, adjust #if CONFIG_IDF_TARGET_*)
WiFi FTM / 802.11mc support (Fine Timing Measurement, ~1-2m accuracy)
- FTM initiator + responder mode on each sensor
- Inter-sensor ranging (3 pairs from 3 sensors)
- Auto-calibrate sensor positions for 3D floor plan
Enable promiscuous mode alongside CSI (works on S2/S3/C3/C6)
Validate CSI quality on new chip (subcarrier count differs)
Update parsers for chip-specific CSI format

Future

AP+STA config portal (WIFI_MODE_APSTA, captive portal for initial setup)
ESP-NOW mesh (ESP32-to-ESP32 CSI)
External sensor support (PIR, temp/humidity via GPIO)
Pin mapping for ESP32-DevKitC V1
Compare CSI quality: passive (router) vs active (ESP-NOW)
Multi-sensor deployment guide (placement, zones, triangulation)
Home Assistant integration (MQTT discovery, entity creation)
Grafana dashboards for long-term analytics
ML-based device classification (phone vs laptop vs IoT)
RSSI triangulation with 3+ sensors (approximate device location)

10 KiB Raw Blame History