# ESP32 Hacking Tasks **Last Updated:** 2026-02-14 ## Completed: v1.12-dev — Security Hardening & Pentest Security hardening deployed to amber-maple. Full pentest executed 2026-02-14. - [x] Auth whitelist: only read-only queries work without HMAC auth - [x] AUTH OFF disabled remotely (serial console or FACTORY reset only) - [x] HMAC 128-bit (32 hex chars), replay window +/-5s, nonce dedup cache (8 entries) - [x] STATUS split: minimal (unauthed) vs full (authed) response - [x] Rate limiter: 50ms inter-command throttle (20 cmd/s max) - [x] NVS write throttle: 20 writes per 10s window - [x] CSI buffer bounds checking (UDP_REM macro) - [x] PMF (802.11w) required: `CONFIG_ESP_WIFI_PMF_REQUIRED=y` - [x] mDNS: hostname only, no service advertisement - [x] Serial console AUTH management (UART0, 921600 baud) - [x] ALERT command (temp/heap thresholds, EVENT emission) - [x] Secret auto-generated on first boot, redacted in boot log - [x] Pentest: mDNS service discovery — PASS (no service ads) - [x] Pentest: Port scan — PASS (only 5353/udp + 5501/udp open, 0 TCP) - [x] Pentest: Firmware binary analysis — PASS (no hardcoded secrets) - [x] Pentest: eFuse readout — all security fuses unburned (expected for dev) - [x] Pentest: HMAC timing oracle — PASS (constant-time comparison effective) - [x] Pentest: Command injection (27 tests) — PASS (all handled safely) - [x] Pentest: Replay attack (6 tests) — PASS (all rejected) - [x] Pentest: NVS partition analysis — auth_secret in plaintext (expected without flash encryption) - [x] Pentest: ESP-IDF CVE check (12 CVEs) — 8 N/A, 4 LOW risk - [x] Pentest: Binary structure — no stack canaries, no heap poisoning (fix recommended) - [x] Pentest results documented in `docs/PENTEST-RESULTS.md` ## Completed: v1.11.0 — Diagnostics & Usability Deployed to fleet 2026-02-14. - [x] CSI ON/OFF command to toggle CSI collection - [x] HELP command (lists all 30 commands with syntax) - [x] FACTORY command (erase NVS config + reboot) - [x] CONFIG command (dump all running config key=value) - [x] PING command (echo reply, returns OK PONG) - [x] LOG command (runtime log level: NONE/ERROR/WARN/INFO/DEBUG/VERBOSE) - [x] RSSI RESET command (reset min/max counters) - [x] Tagged v1.11.0 and OTA deployed to all 3 sensors ## Web Backend (`~/git/esp32-web/`) Tracked separately in `~/git/esp32-web/TASKS.md`. Currently at v0.1.5. ## Firmware Backlog ### P1 - High - [x] Test OTA rollback — crasher firmware flashed to amber-maple, bootloader rolled back to v1.11.0 (2026-02-14) - [ ] Enable stack canaries: `CONFIG_COMPILER_STACK_CHECK_MODE_NORM=y` - [ ] Enable heap poisoning: `CONFIG_HEAP_POISONING_LIGHT=y` ### P2 - Normal - [ ] Tune presence threshold per room with real-world testing - [ ] Power consumption measurements using POWERTEST + external meter - [ ] Multi-target (send UDP to 2+ destinations) ### P3 - Low - [x] ALERT command — temp/heap threshold monitoring with EVENT emission (2026-02-14) - [ ] Deep sleep mode with wake-on-CSI-motion - [ ] Battery-optimized duty cycling - [ ] AP+STA config portal (captive portal for initial setup) ### Documentation - [ ] Document esp-crab dual-antenna capabilities - [ ] Document esp-radar console features - [ ] Pin mapping for ESP32-DevKitC V1 ## Completed: v1.10 - LED Quiet Mode & CI Hardening - [x] LED quiet mode (off normally, solid on motion/presence, blinks on OTA) - [x] Default LED to quiet mode - [x] Build metadata in STATUS reply - [x] CI security checks (secrets scan, config validation) - [x] Firmware size check and version tag validation - [x] Size optimization (`-Os`, saves ~75KB) - [x] CSI ON/OFF toggle command ## Completed: v1.9 - Multi-Channel Scanning & BLE Fingerprinting - [x] CHANSCAN command (ON/OFF/NOW/INTERVAL) - [x] Channel hopping (1-13) with 100ms dwell, pause CSI during scan - [x] chanscan= field in STATUS, chanscan_int NVS persistence - [x] BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA - [x] Historical presence sessions support ## Completed: v1.8 - HTTPS OTA Support - [x] Support HTTPS URLs for OTA updates (esp_https_ota) - [x] CI: Upload firmware to Gitea releases for OTA - [x] CI: Simplify deploy script to pure POSIX sh ## Completed: v1.7 - Baseline Calibration & Presence Detection - [x] CALIBRATE command (capture N seconds of CSI, average per-subcarrier amplitudes) - [x] CALIBRATE STATUS / CALIBRATE CLEAR subcommands - [x] Presence scoring (normalized Euclidean distance vs baseline, rolling window of 50) - [x] PRESENCE ON/OFF command (NVS persisted, requires valid baseline) - [x] PRESENCE THRESHOLD command (0.001-1.0, NVS persisted, default 0.05) - [x] Presence events (`EVENT,,presence=<0|1> score=`) with 10s holdoff - [x] Calibration done event (`EVENT,,calibrate=done packets= nsub=`) - [x] presence= and pr_score= fields in STATUS reply - [x] NVS persistence: bl_amps (blob), bl_nsub (i8), presence (i8), pr_thresh (i32) - [x] config_save_blob / config_erase_key NVS helpers - [x] n_sub field in csi_features_t, amps_out parameter in csi_extract_features - [x] Pi-side: parse presence/calibrate events in watch daemon - [x] Pi-side: store in sensor_events table (`esp-ctl osint events`) - [x] Pi-side: HA webhooks for presence_change and calibrate_done - [x] Fleet OTA to v1.7, calibrated hollow-acorn + amber-maple ## Completed: v1.6 - Power Management - [x] ESP-IDF power management framework (DFS 240/80 MHz + light sleep) - [x] sdkconfig: CONFIG_PM_ENABLE, CONFIG_FREERTOS_USE_TICKLESS_IDLE - [x] POWERSAVE command (WiFi modem sleep toggle, NVS persisted, default off) - [x] powersave= field in STATUS reply - [x] POWERTEST save/restore of powersave state - [x] Deployed to fleet, NVS persistence verified ## Completed: v1.5 - Event Handling & NVS Persistence - [x] EVENT packet parsing in watch daemon (motion, wifi_reconnect, powertest) - [x] Sensor heartbeat tracking (offline/online detection, configurable timeout) - [x] sensor_events table with indexed queries (`esp-ctl osint events`) - [x] HA webhooks for sensor_offline, sensor_online, motion_change - [x] NVS persistence for SCANRATE and PROBERATE commands - [x] Sensor events count in `esp-ctl osint stats` ## Completed: v1.4 - Multi-Sensor & Validation - [x] Multi-sensor BLE correlation in esp-ctl (zone tracking by source sensor) - [x] Zone tracking with EMA RSSI (`esp-ctl osint zones`, `device_zones` table) - [x] Per-sensor breakdown in MAC profile (`esp-ctl osint mac`) - [x] POWERTEST command (7-phase power profiling with EVENT markers) - [x] Parallel OTA fleet updates (`esp-fleet ota --parallel`) ## Completed: v1.3 - Security & OSINT - [x] HMAC command authentication (firmware + esp-ctl/esp-cmd/esp-fleet/esp-ota) - [x] AUTH command (set/query/disable secret, NVS persisted) - [x] auth=on/off in STATUS - [x] Deauth flood detection (ring buffer, aggregate ALERT_DATA) - [x] FLOODTHRESH command (count + window, NVS persisted) - [x] flood_thresh field in STATUS - [x] MAC OUI vendor lookup (`esp-ctl oui`, IEEE CSV database) - [x] OSINT SQLite database (probe_ssids, device_sightings tables) - [x] Watch daemon (`esp-ctl watch` — listen + enrich + store) - [x] OSINT query CLI (`esp-ctl osint probes/devices/mac/stats`) - [x] Home Assistant webhook integration (deauth_flood, unknown_probe, unknown_ble) - [x] Watch config file (`~/.config/esp-ctl/watch.yaml`) ## Completed: v1.2 - [x] On-device CSI feature extraction (amp_rms, amp_std, amp_max, amp_max_idx, energy) - [x] CSIMODE command: RAW, COMPACT, HYBRID N (NVS persisted) - [x] Compact payload format `"F:rms,std,max,idx,energy"` (~80% bandwidth reduction) - [x] Hybrid mode: compact every packet, raw every Nth - [x] STATUS fields: csi_mode, hybrid_n - [x] Adaptive sampling reuses extracted energy (no duplicate computation in COMPACT/HYBRID) ## Completed: v1.1 - [x] Sensor ID in data packets (hostname prefix on CSI_DATA, BLE_DATA, EVENT) - [x] Deauth/disassoc frame detection (ALERT_DATA via promiscuous mode) - [x] Chip temperature reporting in STATUS reply - [x] BLE alerting (`esp-ctl ble --known`, alert on unknown MACs) - [x] BLE dwell time tracking (dwell column in `--track` summary) - [x] Timestamped event logging (`esp-ctl listen --timestamp`) - [x] Alert filter in esp-ctl (`listen -f alert`) - [x] Runtime HOSTNAME command (NVS persisted, mDNS updated) - [x] WiFi probe request capture (PROBE_DATA via promiscuous mode, 10s dedup) - [x] mDNS service advertisement (`_esp-csi._udp`) - [x] mDNS sensor discovery (`esp-ctl discover`) - [x] Probe filter in esp-ctl (`listen -f probe`) - [x] OTA fleet to same firmware (ca526ef) - [x] CSI packet counter in STATUS (`csi_count=`) - [x] Raw uptime in STATUS (`uptime_s=`) - [x] WiFi reconnect EVENT emission - [x] SCANRATE command (BLE scan interval tuning, 5-300s) - [x] PROBERATE command (probe dedup cooldown tuning, 1-300s) - [x] Fix: promiscuous mode disables CSI on original ESP32 — guarded with `#if` - [x] FreeRTOS CPU runtime stats in PROFILE (trace facility enabled) - [x] Increased cmd_task stack 4KB → 6KB (was 516 bytes free) - [x] WiFi channel in STATUS (`channel=`) - [x] Boot counter in NVS (`boots=`) - [x] RSSI min/max tracking from CSI frames (`rssi_min=`, `rssi_max=`) - [x] Actual CSI rate in STATUS (`csi_rate=`) ## Completed: v0.5 - BLE Scanning - [x] Enable Bluetooth alongside WiFi (NimBLE, BLE ON/OFF command) - [x] Periodic BLE advertisement scanning - [x] Report device MAC, RSSI, name via UDP - [x] Pi-side BLE device tracking (`esp-ctl ble --track`) - [x] PROFILE command (heap, stack watermarks, CPU runtime stats) - [x] TARGET command (runtime UDP destination config) ## Completed: v0.4 - Adaptive Sampling - [x] On-device CSI wander calculation (coefficient of variation) - [x] Adaptive rate: 10 pkt/s idle (3s holdoff) → 100 pkt/s on motion - [x] EVENT notification to Pi on rate change - [x] ADAPTIVE ON/OFF command (NVS persisted) - [x] THRESHOLD command for tuning sensitivity (NVS persisted) - [x] RATE command disables adaptive mode - [x] adaptive/motion fields in STATUS reply - [x] OTA deployed and verified on amber-maple ## Completed: v0.3 - OTA Updates - [x] Dual OTA partition table (`partitions.csv`) - [x] 4MB flash, custom partitions, rollback in sdkconfig.defaults - [x] Firmware: OTA command, ota_task, LED_OTA, rollback validation - [x] Firmware: version in STATUS reply - [x] Pi-side `esp-ota` tool (HTTP server + OTA orchestration) - [x] `esp-fleet ota` subcommand (sequential fleet update) - [x] Build and USB-flash amber-maple (partition table change) - [x] End-to-end OTA test verified - [x] Regenerate sdkconfig.sample - [x] Update CHEATSHEET.md, USAGE.md ## Completed: v0.2 - Remote Management - [x] Firmware: UDP command listener (port 5501) - [x] Firmware: LED status indicator (GPIO2) - [x] Firmware: NVS config persistence (rate, tx_power) - [x] Firmware: REBOOT, IDENTIFY, STATUS commands - [x] Firmware: RATE command (10-100 Hz, restarts ping) - [x] Firmware: POWER command (2-20 dBm) - [x] Pi-side: `esp-cmd` CLI tool - [x] Pi-side: `esp-fleet` fleet management tool - [x] mDNS hostname, watchdog, human-readable uptime ## Completed: v0.1 - Documentation - [x] Copy firmware sources to project - [x] Document current firmware and settings - [x] Document build & flash workflow - [x] Create .gitignore for build artifacts - [x] Test building firmware from this repo - [x] Document CSI config options ## Notes - Adaptive threshold varies by environment; 0.001-0.01 is a good starting range - NVS keys (28 total): `send_rate`, `tx_power`, `adaptive`, `threshold`, `ble_scan`, `target_ip`, `target_port`, `hostname`, `boot_count`, `csi_mode`, `hybrid_n`, `auth_secret`, `flood_thresh`, `flood_window`, `scan_rate`, `probe_rate`, `powersave`, `presence`, `pr_thresh`, `bl_nsub`, `bl_amps`, `chanscan`, `chanscan_int`, `led_quiet`, `csi_enabled`, `alert_temp`, `alert_heap` - UDP commands (28 total): STATUS, CONFIG, RATE, POWER, TARGET, HOSTNAME, CSI, CSIMODE, ADAPTIVE, THRESHOLD, BLE, SCANRATE, PROBERATE, CALIBRATE, PRESENCE, CHANSCAN, LED, POWERSAVE, AUTH, FLOODTHRESH, ALERT, OTA, POWERTEST, PROFILE, PING, LOG, RSSI RESET, IDENTIFY, REBOOT, FACTORY, HELP - EVENT packets include sensor hostname: `EVENT,,motion=... rate=... wander=...` - Alert events: `EVENT,,alert=heap free= thresh=` and `EVENT,,alert=temp value= thresh=` - ALERT_DATA format: `ALERT_DATA,,,,,` or `ALERT_DATA,,deauth_flood,,` - STATUS fields: `uptime=`, `uptime_s=`, `heap=`, `rssi=`, `channel=`, `tx_power=`, `rate=`, `csi_rate=`, `hostname=`, `version=`, `adaptive=`, `motion=`, `ble=`, `target=`, `temp=`, `csi_count=`, `boots=`, `rssi_min=`, `rssi_max=`, `csi=`, `csi_mode=`, `hybrid_n=`, `auth=`, `flood_thresh=`, `powersave=`, `presence=`, `pr_score=`, `chanscan=`, `led=`, `alert_temp=`, `alert_heap=`, `nvs_used=`, `nvs_free=`, `nvs_total=`, `part_size=`, `built=`, `idf=`, `chip=` - PROBE_DATA format: `PROBE_DATA,,,,` - Probe requests deduped per MAC (default 10s cooldown, tunable via PROBERATE) - mDNS service: `_esp-csi._udp` on data port (for sensor discovery) - HOSTNAME command: `HOSTNAME ` sets NVS + mDNS, `HOSTNAME` queries current - **ESP32 limitation:** Promiscuous mode (deauth/probe detection) disabled — breaks CSI. Works on ESP32-C6+.