username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

feat: Add HMAC command auth, deauth flood detection, sign all tools

Browse Source 
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
This commit is contained in:
user
2026-02-04 21:07:00 +01:00
parent 7ca58fee72
commit 2586234473
7 changed files with 495 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/CHEATSHEET.md
View File

@@ -46,6 +46,15 @@ esp-cmd <host> OTA http://pi:8070/fw # Trigger OTA update (use esp-ota instea
esp-cmd <host> HOSTNAME mydevice # Set hostname (NVS saved, mDNS updated)
esp-cmd <host> SCANRATE 60 # BLE scan restart interval (5-300s)
esp-cmd <host> PROBERATE 5 # Probe dedup cooldown (1-300s)
esp-cmd <host> CSIMODE # Query current CSI output mode
esp-cmd <host> CSIMODE RAW # Full I/Q array (default, ~900 B/pkt)
esp-cmd <host> CSIMODE COMPACT # Features only (~200 B/pkt)
esp-cmd <host> CSIMODE HYBRID 10 # Compact + raw every Nth packet
esp-cmd <host> AUTH # Query auth status (on/off)
esp-cmd <host> AUTH mysecret123 # Enable HMAC auth (8-64 char secret)
esp-cmd <host> AUTH OFF # Disable auth
esp-cmd <host> FLOODTHRESH # Query deauth flood threshold (5/10s)
esp-cmd <host> FLOODTHRESH 10 30 # Set: 10 deauths in 30s = flood
esp-cmd <host> REBOOT # Restart device
```
@@ -91,6 +100,33 @@ After that, all updates are OTA.
If new firmware crashes or hangs, the 30s watchdog reboots and bootloader
automatically rolls back to the previous firmware.
## CSI Output Modes
| Mode | Payload | Size | BW @ 100 Hz |
|------|---------|------|-------------|
| RAW (default) | `"[I,Q,I,Q,...]"` (128 values) | ~900 B | ~90 KB/s |
| COMPACT | `"F:rms,std,max,idx,energy"` | ~200 B | ~20 KB/s |
| HYBRID N | Compact every packet, raw every Nth | ~270 B avg (N=10) | ~27 KB/s |
Compact features (per packet, from 64 I/Q subcarrier pairs):
| Feature | Type | Description |
|---------|------|-------------|
| amp_rms | float | RMS amplitude = sqrt(mean(I²+Q²)) |
| amp_std | float | Std dev of per-subcarrier amplitudes |
| amp_max | float | Peak subcarrier amplitude |
| amp_max_idx | uint8 | Index (0-63) of peak subcarrier |
| energy | uint32 | L1 norm (same as adaptive sampling) |
```bash
esp-cmd amber-maple.local CSIMODE COMPACT # Switch to compact
esp-cmd amber-maple.local CSIMODE HYBRID 10 # Raw every 10th packet
esp-cmd amber-maple.local CSIMODE RAW # Back to full I/Q
esp-cmd amber-maple.local CSIMODE # Query current mode
```
Mode is NVS-persisted and survives reboots.
## Adaptive Sampling
When enabled, the device automatically adjusts ping rate based on CSI wander:
@@ -127,6 +163,48 @@ esp-ctl target --discover # Query targets via discovery
Requires firmware with `_esp-csi._udp` mDNS service (v1.1+).
## HMAC Command Authentication
```bash
# Set auth secret on device
esp-ctl cmd amber-maple.local "AUTH mysecretkey123"
# Set env var so all tools sign commands automatically
export ESP_CMD_SECRET="mysecretkey123" # add to ~/.bashrc.secrets
# All esp-cmd/esp-ctl/esp-fleet/esp-ota commands auto-sign when ESP_CMD_SECRET is set
# Unsigned commands are rejected with "ERR AUTH required"
esp-ctl cmd amber-maple.local "AUTH OFF" # Disable auth
```
Protocol: `HMAC:<16hex>:<cmd>` — first 16 hex chars of HMAC-SHA256(secret, cmd).
## OUI Vendor Lookup
```bash
esp-ctl oui --update # Download IEEE OUI database (~30k entries)
esp-ctl oui b0:be:76:a1:2d:c0 # Look up vendor for a MAC
```
## Watch Daemon & OSINT
```bash
esp-ctl watch # Listen on :5500, store probes/BLE/alerts in DB
esp-ctl watch -c ~/my-config.yaml # Custom config (HA webhooks, known MACs)
esp-ctl watch -v # Verbose logging
esp-ctl osint probes # Probe SSID history table
esp-ctl osint probes --mac AA:BB:CC:DD:EE:FF # Filter by MAC
esp-ctl osint devices # All device sightings
esp-ctl osint devices -t ble # BLE only
esp-ctl osint mac AA:BB:CC:DD:EE:FF # Full profile for one MAC
esp-ctl osint stats # Summary counts
```
DB: `~/.local/share/esp-ctl/osint.db` (SQLite with WAL).
Config: `~/.config/esp-ctl/watch.yaml` (HA webhooks, known MACs file).
## Test CSI Reception
```bash
@@ -168,13 +246,17 @@ esp-ctl listen -f alert # Monitor deauth/disassoc alerts (ESP32-
All data packets include sensor hostname after the type tag:
```
CSI_DATA,<hostname>,seq,mac,rssi,rate,...,len,first_word,"[I,Q,...]"
CSI_DATA,<hostname>,seq,mac,rssi,rate,...,len,first_word,"[I,Q,...]" # RAW mode
CSI_DATA,<hostname>,seq,mac,rssi,rate,...,len,first_word,"F:rms,std,max,idx,energy" # COMPACT mode
BLE_DATA,<hostname>,mac,rssi,pub|rnd,name
EVENT,<hostname>,motion=0|1 rate=<hz> wander=<value>
ALERT_DATA,<hostname>,deauth|disassoc,sender_mac,target_mac,rssi
ALERT_DATA,<hostname>,deauth_flood,<count>,<window_s>
PROBE_DATA,<hostname>,mac,rssi,ssid
```
**CSI mode discriminator:** quoted field starts with `[` (raw) or `F:` (compact).
**Note:** On original ESP32, promiscuous mode (ALERT_DATA, PROBE_DATA) is disabled
because it breaks CSI data collection at the driver level. These packet types are
only generated on ESP32-C6 and newer chips.
@@ -202,6 +284,10 @@ only generated on ESP32-C6 and newer chips.
| boots | 3 | Boot count (NVS persisted) |
| rssi_min | -71 | Lowest RSSI since boot |
| rssi_max | -62 | Highest RSSI since boot |
| csi_mode | raw/compact/hybrid | CSI output mode |
| hybrid_n | 10 | Raw packet interval (hybrid mode) |
| auth | on/off | HMAC command authentication |
| flood_thresh | 5/10 | Deauth flood: count/window_seconds |
## PROFILE Sections