Add README, SECURITY policy, signature provenance, and data .gitignore
- README.md: overview, hardware, build/flash, usage, web API, exports - SECURITY.md: passive-receiver scope + vulnerability disclosure - SIGNATURES.md: signature provenance and upstream credit - .gitignore: block GPS-tagged detection exports from being committed Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
5271b1fca0
commit
5099581fc3
GPG key ID:
D04DED574622EF45
4 changed files with 320 additions and 0 deletions
11
.gitignore
vendored
11
.gitignore
vendored
|
|
@ -4,3 +4,14 @@
|
||||||
*.swo
|
*.swo
|
||||||
*~
|
*~
|
||||||
.DS_Store
|
.DS_Store
|
||||||
|
|
||||||
|
# Detection data — NEVER commit. Contains GPS coordinates of real
|
||||||
|
# locations and movement routes. One leaked export deanonymizes home + routes.
|
||||||
|
dantir_*.json
|
||||||
|
dantir_*.kml
|
||||||
|
dantir_*.csv
|
||||||
|
*.kml
|
||||||
|
data/
|
||||||
|
dantir-data/
|
||||||
|
exports/
|
||||||
|
sessions/
|
||||||
|
|
|
||||||
242
README.md
Normal file
242
README.md
Normal file
|
|
@ -0,0 +1,242 @@
|
||||||
|
# Dantir — Surveillance Counter-Watcher
|
||||||
|
|
||||||
|
> *Sindarin:* **dan** (against / back) + **tir** (to watch) = *"counter-watcher."*
|
||||||
|
|
||||||
|
Dantir is a pocket-sized **BLE + WiFi surveillance-detection device** for the
|
||||||
|
Seeed XIAO ESP32-S3. It passively listens for the radio signatures of
|
||||||
|
surveillance hardware around you — Flock Safety ALPR cameras, Ring/Amazon
|
||||||
|
cameras, recording smart glasses, Bluetooth trackers, gunshot-detector nodes,
|
||||||
|
and law-enforcement gear — then alerts you with audio, light, and a live web
|
||||||
|
dashboard with a proximity radar.
|
||||||
|
|
||||||
|
It only **detects and documents**. It does not jam, spoof, or interfere with
|
||||||
|
anything. Awareness is the point: you can't push back against what you can't
|
||||||
|
see.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Credits & Lineage
|
||||||
|
|
||||||
|
Dantir stands on the shoulders of others' work. Full respect and thanks to:
|
||||||
|
|
||||||
|
- **[Colonel Panic](https://colonelpanic.tech/) — [OUI Spy Unified Blue](https://github.com/colonelpanichacks/oui-spy-unified-blue)**
|
||||||
|
Dantir is a fork of OUI Spy Unified Blue's *Flock-You* mode. The detection
|
||||||
|
engine, session persistence, GPS handling, export pipeline, and dashboard
|
||||||
|
foundations all originate there. If you want a polished, pre-built detector,
|
||||||
|
buy one from Colonel Panic — support the upstream project.
|
||||||
|
- **[wgreenberg / flock-you](https://github.com/wgreenberg/flock-you)** — BLE
|
||||||
|
detection research and signature work that informs how Flock devices are
|
||||||
|
identified.
|
||||||
|
- **[deflock.me](https://deflock.me/)** — community-sourced surveillance device
|
||||||
|
signatures.
|
||||||
|
|
||||||
|
Dantir's changes over upstream: standalone single-mode firmware (no BOOT-button
|
||||||
|
mode dance), added WiFi promiscuous detection (Ring/Blink), expanded BLE
|
||||||
|
manufacturer-ID and category coverage, Morse-code category alerts, a proximity
|
||||||
|
radar dashboard, and peak-RSSI GPS tracking.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What it detects
|
||||||
|
|
||||||
|
Dantir uses **seven detection methods** across BLE and WiFi:
|
||||||
|
|
||||||
|
| Method | Radio | How it matches |
|
||||||
|
|--------|-------|----------------|
|
||||||
|
| `mac_prefix` | BLE | MAC OUI against ~20 Flock Safety prefixes |
|
||||||
|
| `device_name` | BLE | Advertised name patterns (Flock, Penguin, Pigvision, Ring, Ray-Ban…) |
|
||||||
|
| `ble_mfr_id` | BLE | Bluetooth manufacturer company IDs |
|
||||||
|
| `raven_uuid` | BLE | Raven gunshot-detector service UUIDs (+ firmware-version estimate) |
|
||||||
|
| `wifi_probe` | WiFi | Probe-request source MAC OUI (promiscuous mode) |
|
||||||
|
| `wifi_beacon` | WiFi | Beacon-frame source MAC OUI (promiscuous mode) |
|
||||||
|
|
||||||
|
Detections are grouped into **eight categories**, each with its own Morse-code
|
||||||
|
audio signature on the buzzer:
|
||||||
|
|
||||||
|
| Category | Morse | What it covers |
|
||||||
|
|----------|:-----:|----------------|
|
||||||
|
| `flock` | ··-· (F) | Flock Safety / ALPR cameras, Penguin, Pigvision |
|
||||||
|
| `glasses` | --· (G) | Recording smart glasses (Ray-Ban Meta, Oakley, Snap) |
|
||||||
|
| `tracker` | - (T) | Bluetooth trackers (Tile, etc.) |
|
||||||
|
| `lawenf` | ·-·· (L) | Law-enforcement gear (TASER/Axon, Motorola Solutions) |
|
||||||
|
| `ring` | ·-· (R) | Ring / Blink / Amazon cameras |
|
||||||
|
| `camera` | ··· (S) | Other surveillance cameras (Hikvision, Arlo, Wyze) |
|
||||||
|
| `raven` | ···- (V) | Raven gunshot-detector nodes |
|
||||||
|
| `wifi` | ·-- (W) | Generic WiFi-side detections |
|
||||||
|
|
||||||
|
> **Detection is signature-based, not proof.** OUI/manufacturer matches catch
|
||||||
|
> consumer hardware that shares the same chipset vendors (e.g. some Wyze, Hue,
|
||||||
|
> or OBD-II dongles can trip a low-confidence match). Treat `device_name` and
|
||||||
|
> `ble_mfr_id` hits as higher confidence than a bare `mac_prefix` match, and
|
||||||
|
> confirm visually before drawing conclusions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Dual-radio scanning** — BLE active scan + WiFi promiscuous capture running
|
||||||
|
alongside the dashboard access point.
|
||||||
|
- **Morse-code alerts** — each category beeps its letter, so you can ID a hit
|
||||||
|
by ear without looking.
|
||||||
|
- **Foxhunter / proximity mode** — once a device is in range, a heartbeat beep
|
||||||
|
every 10 s helps you locate it; clears after 30 s with no new sightings.
|
||||||
|
- **NeoPixel feedback** — purple breathing when idle, red/pink flash on
|
||||||
|
detection, dim heartbeat glow while a device is nearby.
|
||||||
|
- **Live web dashboard** — proximity radar, live detection cards, stats, and
|
||||||
|
three themes (Purple, Tactical, Ithildin).
|
||||||
|
- **GPS tagging** — hardware GNSS (Seeed L76K) with phone-browser geolocation
|
||||||
|
fallback; tracks both first-seen and **peak-RSSI (closest-approach)** position.
|
||||||
|
- **Exports** — download a session as JSON, CSV, or KML (Google Earth).
|
||||||
|
- **Session persistence** — detections survive reboots; the prior session is
|
||||||
|
auto-backed up to onboard flash.
|
||||||
|
- **Optional battery monitoring** — LiPo percentage via a voltage divider, or
|
||||||
|
uptime display if the ADC is disabled.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hardware
|
||||||
|
|
||||||
|
### Bill of materials (per unit)
|
||||||
|
|
||||||
|
| Part | Notes | Approx. |
|
||||||
|
|------|-------|---------|
|
||||||
|
| Seeed XIAO ESP32-S3 (N8R8) | Main board; needs PSRAM variant | ~$9 |
|
||||||
|
| Passive buzzer | Audio + Morse alerts | ~$1 |
|
||||||
|
| WS2812 / NeoPixel | Status LED | ~$1 |
|
||||||
|
| Seeed L76K GNSS module | *Optional* — GPS tagging | ~$10 |
|
||||||
|
| U.FL→SMA pigtail + 2.4 GHz antenna | *Optional* — extends range | ~$6 |
|
||||||
|
|
||||||
|
> For external antenna use, the XIAO's RF switch 0-ohm resistor must be moved to
|
||||||
|
> the U.FL pad. The onboard PCB antenna works fine for getting started.
|
||||||
|
|
||||||
|
### Pin map
|
||||||
|
|
||||||
|
| Function | GPIO | XIAO pin |
|
||||||
|
|----------|:----:|:--------:|
|
||||||
|
| Buzzer | 3 | — |
|
||||||
|
| NeoPixel | 4 | — |
|
||||||
|
| GPS RX | 44 | D7 |
|
||||||
|
| GPS TX | 43 | D6 |
|
||||||
|
| Battery ADC *(optional, `-1` = off)* | 1 | A0 / D0 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Build & flash
|
||||||
|
|
||||||
|
Dantir is a [PlatformIO](https://platformio.org/) project (no Arduino IDE
|
||||||
|
sketch juggling required).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/rpriven/dantir.git
|
||||||
|
cd dantir
|
||||||
|
|
||||||
|
# Build
|
||||||
|
pio run
|
||||||
|
|
||||||
|
# Flash + open serial monitor (auto-detects the XIAO on USB)
|
||||||
|
pio run --target upload
|
||||||
|
pio device monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
Target environment: `seeed_xiao_esp32s3` (defined in `platformio.ini`).
|
||||||
|
Libraries are pulled automatically: NimBLE-Arduino, ESP Async WebServer,
|
||||||
|
Adafruit NeoPixel, ArduinoJson, and TinyGPSPlus.
|
||||||
|
|
||||||
|
If `pio` isn't installed: `pip install platformio` (or use the PlatformIO IDE
|
||||||
|
extension for VS Code).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
1. **Power on.** Dantir plays a boot "crow call" and starts scanning
|
||||||
|
immediately — no mode selection needed.
|
||||||
|
2. **Connect to the dashboard.** Join the WiFi access point:
|
||||||
|
- **SSID:** `dantir` • **Password:** `dantir123`
|
||||||
|
- Open **`http://192.168.4.1`** in a browser.
|
||||||
|
|
||||||
|
> ⚠️ **Change the defaults before any real use.** The stock AP credentials
|
||||||
|
> (`dantir` / `dantir123`) are published here and in the source — anyone
|
||||||
|
> within WiFi range of a device on stock firmware can open your live
|
||||||
|
> detection feed and GPS position. Edit `FY_AP_SSID` / `FY_AP_PASS` in
|
||||||
|
> `src/main.cpp` and re-flash before you take it out.
|
||||||
|
3. **(Optional) share phone GPS.** The dashboard can push your phone's
|
||||||
|
geolocation to the device as a fallback when no hardware GNSS fix is present.
|
||||||
|
Hardware GPS always takes priority when available.
|
||||||
|
4. **Walk.** Watch the radar and detection cards populate. Listen for the
|
||||||
|
Morse-letter beeps to ID categories by ear.
|
||||||
|
5. **Export.** Download the session as JSON / CSV / KML, or clear it to start
|
||||||
|
fresh (the cleared session is backed up automatically).
|
||||||
|
|
||||||
|
### Web API
|
||||||
|
|
||||||
|
The onboard server (port 80) exposes a small JSON API used by the dashboard:
|
||||||
|
|
||||||
|
| Endpoint | Purpose |
|
||||||
|
|----------|---------|
|
||||||
|
| `GET /` | Dashboard UI |
|
||||||
|
| `GET /api/detections` | Live detection list |
|
||||||
|
| `GET /api/stats` | Counts, GPS status, battery/uptime |
|
||||||
|
| `GET /api/gps?lat=&lon=&acc=` | Push phone GPS to the device |
|
||||||
|
| `GET /api/patterns` | Full signature database (MACs, names, MFR IDs, UUIDs) |
|
||||||
|
| `GET /api/export/{json,csv,kml}` | Download current session |
|
||||||
|
| `GET /api/history` · `/api/history/{json,kml}` | Prior session |
|
||||||
|
| `GET /api/clear` | Clear detections (backs up first) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data & exports
|
||||||
|
|
||||||
|
Each detection records MAC, name, RSSI, detection method, category, first/last
|
||||||
|
seen, re-sighting count, Raven flag + firmware estimate, and **two** GPS fixes:
|
||||||
|
first-seen and peak-RSSI (closest approach). Exports:
|
||||||
|
|
||||||
|
- **JSON** — full structured record incl. `gps` and `best_gps` objects.
|
||||||
|
- **CSV** — flat table for spreadsheets/analysis.
|
||||||
|
- **KML** — placemarks for Google Earth; uses the peak-RSSI position when
|
||||||
|
available for the most accurate location.
|
||||||
|
|
||||||
|
Sessions auto-save to onboard flash (SPIFFS) every ~15 s and are restored on
|
||||||
|
boot, so a power cycle won't lose your data.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key configuration
|
||||||
|
|
||||||
|
Tunable `#define`s at the top of `src/main.cpp`:
|
||||||
|
|
||||||
|
| Setting | Default | Meaning |
|
||||||
|
|---------|:-------:|---------|
|
||||||
|
| `BLE_SCAN_DURATION` / `BLE_SCAN_INTERVAL` | 2 s / 3000 ms | BLE scan timing |
|
||||||
|
| `MAX_DETECTIONS` | 200 | Stored-detection capacity |
|
||||||
|
| `BATTERY_ADC_PIN` | `-1` | Set to a GPIO to enable battery monitoring |
|
||||||
|
| `BATTERY_FULL_V` / `BATTERY_EMPTY_V` | 4.2 V / 3.0 V | LiPo range |
|
||||||
|
| `FY_AP_SSID` / `FY_AP_PASS` | `dantir` / `dantir123` | Dashboard AP credentials |
|
||||||
|
| `FY_SAVE_INTERVAL` | 15000 ms | Session auto-save interval |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Responsible use
|
||||||
|
|
||||||
|
Dantir is a **defensive, educational, passive** tool. It receives radio signals
|
||||||
|
that devices already broadcast publicly — the same advertisements your phone
|
||||||
|
sees — and matches them against known signatures. It transmits nothing at the
|
||||||
|
targets and interferes with nothing.
|
||||||
|
|
||||||
|
You are responsible for using it lawfully in your jurisdiction. Detect, learn,
|
||||||
|
document — don't harass, stalk, or disrupt. The goal is to make an invisible
|
||||||
|
surveillance landscape visible, not to interfere with it.
|
||||||
|
|
||||||
|
**A note on the tracker category.** Detecting Bluetooth trackers (Tile,
|
||||||
|
AirTag-class devices) is a defensive, anti-stalking use — it helps someone find
|
||||||
|
a tracker another person has planted on their car or belongings. Dantir
|
||||||
|
identifies *device classes* by their public radio signatures; it is not built
|
||||||
|
to locate or follow a specific person, and we ask that you don't try to.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
[MIT](LICENSE) — Copyright (c) 2026 rpriven.
|
||||||
|
Based on **OUI Spy Unified Blue** by
|
||||||
|
[colonelpanichacks](https://github.com/colonelpanichacks/oui-spy-unified-blue).
|
||||||
37
SECURITY.md
Normal file
37
SECURITY.md
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
# Security Policy
|
||||||
|
|
||||||
|
## What Dantir is (and isn't)
|
||||||
|
|
||||||
|
Dantir is a **passive radio receiver**. It listens for Bluetooth Low Energy
|
||||||
|
advertisements and WiFi management frames (beacons and probe requests) that
|
||||||
|
devices already broadcast openly to anyone in range — the same packets your
|
||||||
|
phone's Bluetooth and WiFi scanners receive — and matches those public
|
||||||
|
signatures against known surveillance-device patterns.
|
||||||
|
|
||||||
|
Dantir does **not**:
|
||||||
|
|
||||||
|
- transmit anything at the devices it detects;
|
||||||
|
- connect to, authenticate against, or query any third-party device;
|
||||||
|
- jam, spoof, deauthenticate, or otherwise interfere with any radio signal;
|
||||||
|
- capture the *content* of any communication — only broadcast metadata
|
||||||
|
(MAC address, advertised name, manufacturer ID, service UUID).
|
||||||
|
|
||||||
|
The device runs its own local WiFi access point solely to serve its dashboard.
|
||||||
|
|
||||||
|
## Reporting a vulnerability
|
||||||
|
|
||||||
|
If you find a security issue in the firmware or dashboard, please report it
|
||||||
|
privately rather than opening a public issue:
|
||||||
|
|
||||||
|
- Open a **GitHub security advisory** on this repository, or
|
||||||
|
- Contact the maintainer via the profile linked on the repository.
|
||||||
|
|
||||||
|
Please include reproduction steps and the firmware version/commit. We aim to
|
||||||
|
acknowledge reports promptly and will credit reporters who wish to be named.
|
||||||
|
|
||||||
|
## Operating it responsibly
|
||||||
|
|
||||||
|
- Change the default dashboard credentials (`FY_AP_SSID` / `FY_AP_PASS`) before
|
||||||
|
any real-world use — the defaults are public.
|
||||||
|
- Detection is signature-based and is **not proof** of any specific device.
|
||||||
|
- Use it lawfully in your jurisdiction. Detect and document — never interfere.
|
||||||
30
SIGNATURES.md
Normal file
30
SIGNATURES.md
Normal file
|
|
@ -0,0 +1,30 @@
|
||||||
|
# Signature Provenance
|
||||||
|
|
||||||
|
Dantir detects devices by matching publicly broadcast radio signatures —
|
||||||
|
Bluetooth MAC OUI prefixes, advertised device-name patterns, BLE manufacturer
|
||||||
|
company IDs, service UUIDs, and WiFi management-frame source OUIs. None of this
|
||||||
|
data is proprietary; it comes from public registries and open community
|
||||||
|
research.
|
||||||
|
|
||||||
|
## Sources & credit
|
||||||
|
|
||||||
|
- **[OUI Spy Unified Blue](https://github.com/colonelpanichacks/oui-spy-unified-blue)**
|
||||||
|
by **colonelpanichacks** ([colonelpanic.tech](https://colonelpanic.tech/)) —
|
||||||
|
the upstream project Dantir is forked from, and the origin of the core
|
||||||
|
detection engine and much of the BLE signature set.
|
||||||
|
- **[flock-you](https://github.com/wgreenberg/flock-you)** by **wgreenberg** —
|
||||||
|
BLE detection research on Flock Safety hardware.
|
||||||
|
- **[deflock.me](https://deflock.me/)** — community-maintained, crowd-sourced
|
||||||
|
catalog of surveillance-device signatures (ALPR cameras and related gear).
|
||||||
|
- **IEEE MA-L (OUI) registry** — public assignments mapping MAC prefixes to
|
||||||
|
manufacturers.
|
||||||
|
- **Bluetooth SIG company identifiers** — manufacturer company IDs carried in
|
||||||
|
BLE advertisements, published by the Bluetooth SIG.
|
||||||
|
|
||||||
|
## Nature of the data
|
||||||
|
|
||||||
|
These signatures describe what publicly observable radio emissions *look like* —
|
||||||
|
facts about how devices identify themselves over the air, compiled for
|
||||||
|
interoperability and security-research purposes. A detection indicates only
|
||||||
|
that a matching broadcast was observed nearby. It is **not** proof of the
|
||||||
|
presence, ownership, or operation of any specific device or party.
|
||||||
Loading…
Add table
Reference in a new issue