From b6068057667b6e6383ee23de399cd59d9682ca26 Mon Sep 17 00:00:00 2001 From: Colonel Panic Date: Mon, 20 Apr 2026 07:40:29 -0400 Subject: [PATCH] readme: document promiscuous WiFi companion on this branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explains how the new WiFi promiscuous firmware in promiscuis-flock-you/ complements the existing BLE detector — same hardware class, same Flask dashboard schema, complementary RF coverage. Full research credit to ØяĐöØцяöЪöяцฐ / @NitekryDPaul for the 30-OUI target list and the addr1-receiver detection technique. Added to Acknowledgments. --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index 7526737..bf9f1de 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,40 @@ No WiFi sniffing — the radio is dedicated to serving the dashboard AP while BL --- +## What's on this branch (`promiscious`) + +This branch adds a **WiFi sibling** to the BLE detector in a new `promiscuis-flock-you/` subdirectory. Same hardware class (XIAO ESP32-S3), same Flask dashboard, complementary RF coverage. + +| | BLE detector (`src/main.cpp`) | WiFi promiscuous detector (`promiscuis-flock-you/main.cpp`) | +|---|---|---| +| Radio | 2.4 GHz BLE scan | 2.4 GHz 802.11 promiscuous sniff | +| Targets | Flock / Raven BLE fingerprints | Flock Safety WiFi infrastructure OUIs | +| Dashboard | Hosts own AP + web UI at `192.168.4.1` | No AP — emits Flask JSON only | +| GPS | Phone geolocation via on-device AP | Flask-side (USB NMEA / browser) | +| Persistence | SPIFFS session file | SPIFFS session file (same envelope+CRC format) | +| Coverage | BLE-advertising Flock gear | Flock infrastructure seen on air, including stations silent on the transmitter-side due to burst-sleep duty cycles | + +Both firmwares emit the same Flask-compatible JSON schema over USB, so `api/flockyou.py` ingests them interchangeably. Run one, the other, or both in parallel on the same host — you get a merged detection map. + +### WiFi firmware highlights + +- **Promiscuous-mode sniff** on channels 1 / 6 / 11 with 350 ms dwell (configurable) +- **`addr1` + `addr2` matching** — the receiver-side check catches Flock stations that are silent on the transmitter side during their burst-sleep windows +- **Randomised-MAC and multicast guards** applied before OUI match to eliminate false positives +- **30-OUI target list** for Flock Safety infrastructure +- **SPIFFS persistence** with atomic CRC-envelope writes, `/prev_session.json` promotion on boot +- **Onboard LED flash + buzzer beep** per detection +- **Boot melody** — first 6 notes of SMB World 1-2 underground +- **USB-optional** — standalone operation with non-blocking Serial TX + +See [`promiscuis-flock-you/README.md`](promiscuis-flock-you/README.md) for the full walkthrough. + +### Research credit + +All WiFi promiscuous research — the 30-OUI target list and the addr1-receiver detection technique — is the work of **ØяĐöØцяöЪöяцฐ / @NitekryDPaul**. The firmware on this branch is a mod of his original promiscuous-mode firmware with added SPIFFS persistence and Flask-dashboard integration. Full attribution and methodology in [`datasets/NitekryDPaul_wifi_ouis.md`](datasets/NitekryDPaul_wifi_ouis.md). + +--- + ## Detection Methods All detection is BLE-based: @@ -130,6 +164,7 @@ Firmware version is estimated automatically from which service UUIDs are adverti ## Acknowledgments +- **ØяĐöØцяöЪöяцฐ (@NitekryDPaul)** — **WiFi promiscuous detection research**: 30-OUI Flock Safety target list and the addr1-receiver detection technique that form the `promiscuis-flock-you` firmware on this branch. See `promiscuis-flock-you/` and `datasets/NitekryDPaul_wifi_ouis.md`. The WiFi firmware here is a mod of his original promiscuous-mode firmware. - **Will Greenberg** ([@wgreenberg](https://github.com/wgreenberg)) — BLE manufacturer company ID detection (`0x09C8` XUNTONG) sourced from his [flock-you](https://github.com/wgreenberg/flock-you) fork - **[DeFlock](https://deflock.me)** ([FoggedLens/deflock](https://github.com/FoggedLens/deflock)) — crowdsourced ALPR location data and detection methodologies. Datasets included in `datasets/` - **[GainSec](https://github.com/GainSec)** — Raven BLE service UUID dataset (`raven_configurations.json`) enabling detection of SoundThinking/ShotSpotter acoustic surveillance devices