diff --git a/.gitignore b/.gitignore index e5142be..072c84c 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..698ab4a --- /dev/null +++ b/README.md @@ -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). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..abbc390 --- /dev/null +++ b/SECURITY.md @@ -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. diff --git a/SIGNATURES.md b/SIGNATURES.md new file mode 100644 index 0000000..98a0c61 --- /dev/null +++ b/SIGNATURES.md @@ -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.