Flock_Detect: GPS-tag BLE detections (v9.16) and fix payload not showing under Reconnaissance

[stratfan]

Summary

Two changes to the Flock_Detect ("Flock You") reconnaissance payload:

1. GPS tagging (v9.15 → v9.16). Each BLE detection is now tagged with a live GPS fix from gpsd, and a machine-readable CSV is written alongside the existing log.
2. Visibility fix. Flock_Detect currently does not appear under Reconnaissance on the Pager because it contains a nested subdirectory. This flattens the payload folder so it renders.

Visibility fix — root cause

The Pager's payload scanner treats any directory that contains a subdirectory as a category (to recurse into) rather than a payload, and lists a folder as a payload only when it's a flat leaf containing payload.sh.

Upstream, Flock_Detect/ contains a flock_lab_sim/ subfolder (the ESP32 companion simulator), so the scanner classifies Flock_Detect as a category, ignores its own payload.sh, and — since flock_lab_sim/ has no payload.sh — nothing is listed. The payload is effectively invisible in the UI.

Fix: move the ESP32 lab simulator out of the deployable payload folder to docs/flock-lab-sim/ (outside the library/ tree). Flock_Detect/ becomes a flat leaf and renders correctly. Verified on-device: after flattening, "Flock You" appears under Reconnaissance. The flat-folder requirement is now documented in the payload README.

The simulator runs on separate Arduino/ESP32 hardware, not the Pager, so it does not belong in the deployable payload directory.

GPS tagging details (v9.16)

• Reads one fix per scan cycle via gpspipe -w + jq (the same pattern used by gps-checker) — position doesn't change meaningfully within a ~12s scan window, and this avoids multiplying GPS delay across multiple detections.
• Appends lat,lon to each on-screen detection line and to the log file.
• Falls back to NO_GPS when there's no 2D/3D fix (no receiver / no lock yet), so the scanner still runs normally without GPS.
• Writes a companion flock_gps_<timestamp>.csv (time,mac,name,lat,lon) for map-ready output.

Testing

• bash -n clean.
• Both tag branches (fix / no-fix) unit-tested.
• get_gps_fix() exercised against a live gpsd on a WiFi Pineapple Pager — correctly returned NO_GPS at mode:1 (no lock) and correct lat,lon on a valid fix.
• Full payload run on-device (timeout-bounded): starts cleanly, survives scan cycles, creates both .txt and .csv outputs, no crash.
• Confirmed the flattened folder now lists under Reconnaissance on the device.

🤖 Generated with Claude Code

[stratfan]

Added a second commit (v9.17) to this PR: multi-signal BLE detection.

Field-testing v9.16 surfaced a real gap — it matched only the BLE device name, but most Flock adverts carry no name (MAC + manufacturer data only), so parking next to a camera produced no alert. v9.17 now detects on three signals and alerts if any fire:

• MANUF — XUNTONG manufacturer ID 0x09C8 in the advertising data (hcidump --raw, signature FF C8 09) — the strongest tell, and the one that catches no-name devices.
• OUI — advertiser MAC prefix matched against the bundled oui_list.txt (Lite-On chipset + verified Flock prefixes), which was previously unused.
• NAME — the original v9.16 substring match, kept as a third signal.

Each cycle runs hcidump --raw + hcitool lescan in parallel and merges hits by MAC. Verified on-device (45s live run, 289 adv reports, no crash) plus an end-to-end test of the detection function against synthetic XUNTONG/Lite-On/verified-Flock/named packets.

[stratfan]

Added v9.19 — field validation plus three fixes from a real drive-by.

Detection confirmed working: a Falcon was caught by its OUI, with zero XUNTONG 0x09C8 across 1,477 devices logged that drive. On this hardware the OUI list, not the manufacturer ID, is what finds Falcons.

The same drive exposed three defects, now fixed and measured on-device:

Symptom	Cause	Result
Set scan parameters failed: I/O error ×786	killing lescan leaves LE scanning enabled, so the next cycle can't set scan params	explicit LE Set Scan Enable=0 between cycles → 786 → 0
alert buzzed ~30 min after the sighting	per-device dedup grepped a growing seen-file (O(n²)) — measured 79 s per cycle at 1,477 devices	single awk pass (~0 ms); hits processed before the bulk write
timestamps stale by minutes	computed once per cycle	taken at the moment of detection

Two platform traps worth flagging for other payload authors (both documented in the README):

• The Pager UI runs a payload from a copy at /tmp/payload-<id>.sh, so pkill -f '<name>/payload.sh' never matches a UI-launched instance — a forgotten one holds the BT adapter and silently invalidates testing.
• This payload deliberately has no EXIT/TERM trap: background subshells inherit an EXIT trap (which would delete live dedup state each cycle), and a TERM trap makes the payload survive being killed, leaving immortal instances contending for the adapter.

Validated with the adapter idle: 0 I/O errors, 0 awk errors, 27 devices logged, 0 malformed MACs, 0 duplicate MACs across cycles, and SIGTERM kills cleanly with 0 survivors.

[hak5peaks]

These files are being moved to the wrong directly, all files must withing the payload folder library/user/reconnaissance/Flock_Detect/*

[stratfan]

Thanks @hak5peaks — moved both lab-sim files into the payload folder (ba3e809). They now sit flat alongside the payload:

library/user/reconnaissance/Flock_Detect/
  payload.sh
  oui_list.txt
  README.md
  flock_lab_sim.py     # ESP32 lab simulator (runs on Arduino, not the Pager)
  LAB_SIMULATOR.md     # its setup guide (renamed from README.md to avoid a collision)

One layout note: I kept them as flat files rather than a flock-lab-sim/ subfolder on purpose — the Pager's payload scanner treats any payload directory that contains a subdirectory as a category and hides the payload from the on-device list (that was the original reason these lived under docs/). Flat files inside Flock_Detect/ avoid that while keeping everything in the payload folder as you asked. The .py runs on ESP32/MicroPython and is inert on the Pager.

Separately, a field-results update while I'm here: I've been driving with this for several weeks and have not seen a Flock camera advertising on any channel in that time — no WiFi OUI match, no XUNTONG 0x09C8, no Flock-/Falcon-style SSID, and no BLE hits — including a stationary capture parked right next to a confirmed camera. Two possibilities: the deployed Falcons are cellular-only (Sierra LTE) and only beacon WiFi/BLE during install; and/or — with the recent public scrutiny over privacy and unauthorized use — WiFi/BLE may have been deliberately disabled on deployed units to reduce their RF detectability. Either way the practical result is the same, so I've toned down the "detection confirmed" language in the README so the OUI list's confidence isn't overstated. Flagging in case others are seeing the same.