username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
2586234473a6f616c2d47f2e6f0ea4699f867210
esp32-hacking/TASKS.md
user 2586234473 feat: Add HMAC command auth, deauth flood detection, sign all tools 
Firmware:
- HMAC-SHA256 command authentication (AUTH command, NVS persisted)
- Deauth flood detection with ring buffer and aggregate ALERT_DATA
- FLOODTHRESH command (count + window, NVS persisted)
- New STATUS fields: auth=on/off, flood_thresh=5/10
- mbedtls dependency in CMakeLists.txt, rx_buf increased to 192

Tools:
- esp-cmd/esp-fleet/esp-ota import sign_command from esp_ctl.auth
- Commands auto-signed when ESP_CMD_SECRET env var is set

Docs:
- CHEATSHEET: AUTH, FLOODTHRESH, HMAC auth, OUI, watch, osint sections
- TASKS: v1.3 completed section with all new features
2026-02-04 21:07:00 +01:00

6.3 KiB
Raw Blame History

ESP32 Hacking Tasks

Last Updated: 2026-02-04

Current Sprint: v1.3 - OSINT & Fleet Ops

P2 - Normal

  • Multi-sensor BLE correlation in esp-ctl (zone tracking)
  • Test OTA rollback (flash bad firmware, verify auto-revert)
  • Create HA webhook automations for deauth_flood / unknown_probe

P3 - Low

  • Document esp-crab dual-antenna capabilities
  • Document esp-radar console features
  • Pin mapping for ESP32-DevKitC V1

Completed: v1.3 - Security & OSINT

  • HMAC command authentication (firmware + esp-ctl/esp-cmd/esp-fleet/esp-ota)
  • AUTH command (set/query/disable secret, NVS persisted)
  • auth=on/off in STATUS
  • Deauth flood detection (ring buffer, aggregate ALERT_DATA)
  • FLOODTHRESH command (count + window, NVS persisted)
  • flood_thresh field in STATUS
  • 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)
  • Watch config file (~/.config/esp-ctl/watch.yaml)

Completed: v1.2

  • On-device CSI 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
  • STATUS fields: csi_mode, hybrid_n
  • Adaptive sampling reuses extracted energy (no duplicate computation in COMPACT/HYBRID)

Completed: v1.1

  • Sensor ID in data packets (hostname prefix on CSI_DATA, BLE_DATA, EVENT)
  • Deauth/disassoc frame detection (ALERT_DATA via promiscuous mode)
  • Chip temperature reporting in STATUS reply
  • BLE alerting (esp-ctl ble --known, alert on unknown MACs)
  • BLE dwell time tracking (dwell column in --track summary)
  • Timestamped event logging (esp-ctl listen --timestamp)
  • Alert filter in esp-ctl (listen -f alert)
  • Runtime HOSTNAME command (NVS persisted, mDNS updated)
  • WiFi probe request capture (PROBE_DATA via promiscuous mode, 10s dedup)
  • mDNS service advertisement (_esp-csi._udp)
  • mDNS sensor discovery (esp-ctl discover)
  • Probe filter in esp-ctl (listen -f probe)
  • OTA fleet to same firmware (ca526ef)
  • CSI packet counter in STATUS (csi_count=)
  • Raw uptime in STATUS (uptime_s=)
  • WiFi reconnect EVENT emission
  • SCANRATE command (BLE scan interval tuning, 5-300s)
  • PROBERATE command (probe dedup cooldown tuning, 1-300s)
  • Fix: promiscuous mode disables CSI on original ESP32 — guarded with #if
  • FreeRTOS CPU runtime stats in PROFILE (trace facility enabled)
  • Increased cmd_task stack 4KB → 6KB (was 516 bytes free)
  • WiFi channel in STATUS (channel=)
  • Boot counter in NVS (boots=)
  • RSSI min/max tracking from CSI frames (rssi_min=, rssi_max=)
  • Actual CSI rate in STATUS (csi_rate=)

Completed: v0.5 - BLE Scanning

  • Enable Bluetooth alongside WiFi (NimBLE, BLE ON/OFF command)
  • Periodic BLE advertisement scanning
  • Report device MAC, RSSI, name via UDP
  • Pi-side BLE device tracking (esp-ctl ble --track)
  • PROFILE command (heap, stack watermarks, CPU runtime stats)
  • TARGET command (runtime UDP destination config)

Completed: v0.4 - Adaptive Sampling

  • On-device CSI wander calculation (coefficient of variation)
  • Adaptive rate: 10 pkt/s idle (3s holdoff) → 100 pkt/s on motion
  • EVENT notification to Pi on rate change
  • ADAPTIVE ON/OFF command (NVS persisted)
  • THRESHOLD command for tuning sensitivity (NVS persisted)
  • RATE command disables adaptive mode
  • adaptive/motion fields in STATUS reply
  • OTA deployed and verified on amber-maple

Completed: v0.3 - OTA Updates

  • Dual OTA partition table (partitions.csv)
  • 4MB flash, custom partitions, rollback in sdkconfig.defaults
  • Firmware: OTA command, ota_task, LED_OTA, rollback validation
  • Firmware: version in STATUS reply
  • Pi-side esp-ota tool (HTTP server + OTA orchestration)
  • esp-fleet ota subcommand (sequential fleet update)
  • Build and USB-flash amber-maple (partition table change)
  • End-to-end OTA test verified
  • Regenerate sdkconfig.sample
  • Update CHEATSHEET.md, USAGE.md

Completed: v0.2 - Remote Management

  • Firmware: UDP command listener (port 5501)
  • Firmware: LED status indicator (GPIO2)
  • Firmware: NVS config persistence (rate, tx_power)
  • Firmware: REBOOT, IDENTIFY, STATUS commands
  • Firmware: RATE command (10-100 Hz, restarts ping)
  • Firmware: POWER command (2-20 dBm)
  • Pi-side: esp-cmd CLI tool
  • Pi-side: esp-fleet fleet management tool
  • mDNS hostname, watchdog, human-readable uptime

Completed: v0.1 - Documentation

  • Copy firmware sources to project
  • Document current firmware and settings
  • Document build & flash workflow
  • Create .gitignore for build artifacts
  • Test building firmware from this repo
  • Document CSI config options

Notes

  • Adaptive threshold varies by environment; 0.001-0.01 is a good starting range
  • NVS keys: 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
  • EVENT packets now include sensor hostname: EVENT,<hostname>,motion=... rate=... wander=...
  • ALERT_DATA format: ALERT_DATA,<hostname>,<deauth|disassoc>,<sender_mac>,<target_mac>,<rssi> or ALERT_DATA,<hostname>,deauth_flood,<count>,<window_s>
  • 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_mode=, hybrid_n=, auth=, flood_thresh=
  • PROBE_DATA format: PROBE_DATA,<hostname>,<mac>,<rssi>,<ssid>
  • 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 <name> sets NVS + mDNS, HOSTNAME queries current
  • ESP32 limitation: Promiscuous mode (deauth/probe detection) disabled — breaks CSI. Works on ESP32-C6+.
Reference in New Issue View Git Blame Copy Permalink