bot/esp32-cluster
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add deauth detection, Alerts tab, Search tab, node detail cards, UI improvements

Browse Source
This commit is contained in:
bot
2026-04-04 12:47:43 +03:00
parent fbf5b5c738
commit 5c0ec8cc5a
7 changed files with 668 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -15
View File
@@ -2,17 +2,26 @@
## What this is
A distributed WiFi reconnaissance system using ESP32-S3 nodes and an Orange Pi as coordinator.
A distributed WiFi reconnaissance system using ESP32-S3 nodes and an Orange Pi as coordinator. The goal is passive RF awareness — mapping what is happening in the surrounding WiFi environment without transmitting or interacting with any networks.
Each ESP32 node scans the WiFi environment, builds structured events (not raw data), and ships them over UDP to a coordinator. The coordinator stores events to SQLite. A separate web dashboard reads the database and displays everything in real time via SSE.
The system is designed around a clear separation of concerns: nodes are dumb sensors, the Orange Pi does all storage and analysis, the browser does all rendering. No logic lives on the nodes beyond capturing and formatting events.
Practical use cases this has already demonstrated:
- Mapping every network and client device in a city-center apartment building
- Detecting sustained deauth flood attacks targeting specific devices (confirmed live)
- Reconstructing device travel history from probe request SSID lists
- Identifying device types by OUI (phones, IoT devices, laptops, cars, smart home hardware)
- Correlating attack victims across multiple impersonated APs using deauth dst MAC
This is a learning/research project covering distributed systems, event-driven architecture, sensor fusion, and detection engineering concepts.
---
## Hardware
- **Nodes:** ESP32-S3 N16R8 (2 active, scaling later)
- **Nodes:** ESP32-S3 N16R8 (3 active, scattered across apartment)
- **Coordinator:** Orange Pi at `192.168.1.133`, runs 24/7 as systemd services
- **Dev machine:** This PC at `192.168.1.101` — coding and flashing only
- **Flashing:** Arduino CLI on this PC
@@ -206,15 +215,16 @@ The same binary works on every node — `node_id` is auto-derived from the MAC,
### config.h reference
| Constant | Default | Purpose |
|-------------------|------------------|-------------------------------------------|
| `WIFI_SSID` | `sandbox` | WiFi network to connect to |
| `COORDINATOR_IP` | `192.168.1.133` | Orange Pi address |
| `COORDINATOR_PORT`| `5005` | UDP port |
| `SCAN_INTERVAL_MS`| `15000` | How often to run a beacon scan (ms) |
| `PROBE_SNIFF` | `1` | Enable/disable probe sniffing (1/0) |
| `PROBE_DEDUP_SECS`| `30` | Suppress duplicate probe MAC+SSID (secs) |
| `PROBE_QUEUE_SIZE`| `32` | Max probe events buffered between scans |
| Constant | Default | Purpose |
|--------------------|------------------|-------------------------------------------|
| `WIFI_SSID` | `sandbox` | WiFi network to connect to |
| `COORDINATOR_IP` | `192.168.1.133` | Orange Pi address |
| `COORDINATOR_PORT` | `5005` | UDP port |
| `SCAN_INTERVAL_MS` | `15000` | How often to run a beacon scan (ms) |
| `PROBE_SNIFF` | `1` | Enable/disable probe sniffing (1/0) |
| `PROBE_DEDUP_SECS` | `30` | Suppress duplicate probe MAC+SSID (secs) |
| `PROBE_QUEUE_SIZE` | `32` | Max probe events buffered between scans |
| `DEAUTH_QUEUE_SIZE`| `32` | Max deauth/disassoc events buffered |
---
@@ -249,20 +259,32 @@ Open `http://192.168.1.133:8080` in your browser.
- **RSSI history chart** — opens from any Networks row. Shows signal strength over time per node (1h / 2h / 6h / 24h selectable). Each node gets its own coloured line. Useful for spotting interference patterns, seeing how signal fluctuates by time of day, and comparing which node consistently hears a given AP better. Updates live as new scans arrive.
- **Cross-node** — side-by-side per-node RSSI for every AP. Shows which node is physically closer to each network. Filter to multi-node only to focus on confirmed cross-node observations.
- **Clients** — probe request data: unique MACs, vendor (OUI lookup), what SSIDs they're searching for, signal, which nodes saw them.
- **Alerts** — deauth/disassoc frame detection with two sections:
- *Detected Bursts* — fires when ≥10 deauth or disassoc frames are seen for the same BSSID within a 5-minute window. Highlighted red when confirmed by 2+ nodes (high confidence, source is physically nearby). Burst rows include BSSID, SSID, frame count, unique source MACs, and node count.
- *Raw Feed* — last 100 deauth/disassoc events with src, dst, BSSID, reason code, and RSSI. Useful for inspecting specific events. `dst = FF:FF:FF:FF:FF:FF` (broadcast deauth) is a classic attack tool signature.
- **Alerts** — deauth/disassoc frame detection with four sections:
- *1h Summary strip* — total frames, deauth vs disassoc counts, unique BSSIDs and sources in the last hour
- *Most Impersonated Networks* — APs whose BSSID is being spoofed as the deauth source, ranked by frame count
- *Most Targeted Devices* — actual victim devices (by `dst` MAC), ranked by frames received across all impersonated APs
- *Detected Bursts* — fires when ≥10 frames for the same BSSID within 5 minutes. Highlighted red when confirmed by 2+ nodes. Reason code 2 at volume is the primary attack indicator.
- *Raw Feed* — last 100 deauth/disassoc events with full src/dst/BSSID/reason/RSSI detail.
- **Search** — cross-table lookup by any identifier. Supports MAC address, SSID, BSSID, and vendor name (e.g. "Raspberry", "Tuya", "Intel"). Returns all matching data across beacon, probe, and deauth tables in labelled sections. Vendor name search works by matching against the OUI database and finding all devices with those MAC prefixes.
- **Presence** — three sections driven entirely by probe data:
- *Present Now* — real (non-randomized) MACs seen 2+ times in the last hour. Filters out the city-center noise of transient devices.
- *New Arrivals* — devices and networks first seen in the last 24 hours, split into two side-by-side tables.
- *Regulars* — devices and networks seen on 2 or more distinct calendar days. Takes at least two days of data to populate.
- **Node detail** — click a node in the sidebar for stats: total events, unique SSIDs/BSSIDs, RSSI range, first/last seen, uptime, free heap, AP signal, last 100 events.
### Node detail
Click any node in the sidebar to open the detail view. Ten stat cards arranged in a 2×5 grid show: status, total events, unique SSIDs, unique BSSIDs, avg RSSI, first seen, last seen, uptime, free heap, and AP signal. Below the cards is a table of the last 100 events for that node.
### Sidebar
Always visible: node list with online/offline status dot, last seen time, event count, and a compact heartbeat line (uptime · free heap · AP signal).
Always visible: node list with online/offline status dot, last seen time, event count, and a compact heartbeat line (uptime · free heap · AP signal). Nodes are sorted alphabetically by node ID so the order stays fixed as more nodes are added.
A node is considered **online** if a heartbeat was received within the last 30 seconds. Falls back to beacon timestamp (60s threshold) if no heartbeat has been received yet.
### UI
Font: Roboto (Google Fonts). Chosen for readability at small sizes — the previous monospace font felt too thin at the smaller label sizes used throughout the dashboard.
### Live updates
SSE stream pushes new beacon events as they arrive. The feed updates immediately. All other views (sidebar, networks, chart, cross-node, presence, alerts) refresh on a 2-second debounce so a single scan burst doesn't flood the server with requests.
@@ -313,6 +335,10 @@ The `oui.txt` file is the IEEE public OUI database (39,171 entries as of downloa
- [x] RSSI history chart per network (canvas, per-node coloured lines, 1h/2h/6h/24h range)
- [x] Presence tab — Present Now, New Arrivals, Regulars
- [x] Deauth/disassoc frame detection — burst detection with multi-node confirmation, Alerts tab
- [x] Alerts tab — most impersonated networks, most targeted devices, burst detection, raw feed
- [x] Search tab — cross-table lookup by MAC, SSID, BSSID, or vendor name
- [x] Node detail view — 2×5 stat cards with animated border, fixed alphabetical sidebar order
- [ ] Attack session reconstruction — group deauth events into discrete sessions by source/time
- [ ] Scan interval control from dashboard
- [ ] DB pruning / retention policy (events.db grows indefinitely)