djedi/dantir
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add README, SECURITY policy, signature provenance, and data .gitignore

Browse source 
- 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:
rpriven 2026-05-29 13:50:39 -06:00
parent 5271b1fca0
commit 5099581fc3
Signed by: djedi
GPG key ID: D04DED574622EF45
4 changed files with 320 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
.gitignore vendored
View file

@ -4,3 +4,14 @@
*.swo
*~
.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
View 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
View 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
View 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.