Nightrider

A terminal wardriving dashboard for Linux. Scans WiFi and BLE, tags captures with GPS from your phone over a local HTTPS link, and exports/uploads to WiGLE.

  _  _ ___ ___ _  _ _____ ___ ___ ___  ___ ___
 | \| |_ _/ __| || |_   _| _ \_ _|   \| __| _ \
 | .` || | (_ | __ | | | |   /| || |) | _||   /
 |_|\_|___\___|_||_| |_| |_|_\___|___/|___|_|_\
 802.11 + BLE RECON :: wigle uplink

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ◉ SCANNING │ AP 10  BLE 12  OPEN:1 │ GEO:LOCK │ wlan1:iw     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ SIGNAL  SSID          CH   dBm  ┃┃ ▸ AP   homenet  -42dBm    ┃
┃ █████   homenet        6   -24  ┃┃ ◈ OPEN guestwifi  -40dBm  ┃
┃ ████░   guestwifi     36   -40  ┃┃ ▸ BLE  Watch  -50dBm      ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛┗━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Features

• WiFi scanning via iw for true per-AP RSSI, with nmcli as fallback. Many drivers peg nmcli's 0–100 quality metric at 100, collapsing every AP to the same signal level; iw reports real dBm, which is what WiGLE stores.
• BLE scanning via bleak with real RSSI. Starts bluetoothd and brings the adapter up automatically.
• Phone GPS over HTTPS. Scan a QR code with your phone and it streams watchPosition fixes to the desktop. Self-signed TLS is generated on first run (iOS Safari refuses geolocation over plain HTTP).
• Stale-fix protection. Every fix is timestamped. If your phone's browser tab is suspended, captures are left explicitly unlocated rather than tagged with a position you've already driven past.
• Autosave. Located captures append to a WiGLE-format CSV as they're found, with fsync, so a crash doesn't lose the drive.
• Dongle preference. USB WiFi/Bluetooth adapters are chosen over built-in radios, so scanning doesn't disturb your active connection.
• Open networks highlighted in the table, the feed, and a header counter.

Requirements

• Linux (developed on Kali/Debian), Python 3.9+
• iw, network-manager, bluez, openssl
• A WiFi adapter and a Bluetooth adapter (USB dongles recommended)
• Root, for iw scan and for bringing the Bluetooth adapter up

sudo apt install iw network-manager bluez openssl

Install

git clone https://github.com/darkLabz001/nightrider.git
cd nightrider
./setup.sh

setup.sh creates a venv, installs Python dependencies, and drops a wd launcher into /usr/local/bin pointing at wherever you cloned it.

Usage

sudo wd

Button	Action
START / STOP	Begin or end the scan loop
GPS	Enter fixed coordinates manually (never expires)
QR	Show a QR code your phone scans to share live GPS
WIGLE	Enter and save your WiGLE API credentials
UPLOAD	Write a WiGLE CSV and upload it
QUIT	Exit

Getting GPS from your phone

1. Put the phone on the same network as the machine.
2. Press QR and scan the code, or open https://<host-ip>:8888 manually.
3. Accept the self-signed certificate warning, then tap START GPS and allow location access.
4. The dashboard shows ▓ LOCKED ▓ with the fix age. Keep the tab in the foreground — a backgrounded tab stops sending, and the dashboard will switch to ▓ STALE ▓ and stop tagging captures.

WiGLE credentials

None are bundled — supply your own. Get them from wigle.net → Account → Show My Token (you need the API Name and API Token, not your web login). Press WIGLE, enter both, and they're saved to ~/.wardriver/wigle.json with mode 0600 and loaded automatically on later runs.

Where your data lives

Everything personal stays in ~/.wardriver/, outside the repo and git-ignored:

Path	Contents
~/.wardriver/wigle.json	Your API credentials (mode 0600)
~/.wardriver/cert.pem, key.pem	Self-signed TLS for the GPS server
~/.wardriver/scans/	Captured CSVs
~/.wardriver/wardriver.log	Debug log

Captures contain your precise location history and third parties' MAC addresses. Don't commit them.

Status of optional pieces

• ble_node_server.py (Biscuit Manager node) is not wired into the dashboard and is incomplete — it needs the Biscuit GATT service and characteristic UUIDs, which aren't published. See BISCUIT_INTEGRATION.md for the design and what's missing. Treat it as a starting point, not a working feature.
• wardrive_cli.py is a non-interactive alternative to the TUI and gets less testing than the dashboard.

Configuration

Environment variable	Effect
WARDRIVER_PORT	Port for the phone GPS server (default 8888)
WARDRIVER_NO_UPLOAD	If set, UPLOAD writes the CSV but skips the network POST

Troubleshooting

GPS stays offline. Only one instance can bind port 8888. Check for a stale process (pkill -f wardriver_tui.py); the feed reports the bind failure.

Signal shows nmcli instead of iw in the status bar. iw scan needs root — run with sudo. Without it the tool falls back to nmcli, whose RSSI is coarse.

No BLE devices. Confirm the adapter exists (hciconfig) and isn't blocked (rfkill list bluetooth). The tool starts bluetoothd and brings the adapter up itself, but both need root.

Nothing has GPS coordinates. Uploads require a fix. Check for ▓ STALE ▓ or NO FIX in the GPS row.

Legal

Passively observing broadcast beacons is generally lawful in many jurisdictions, but the rules vary and this is not legal advice. You are responsible for how you use this. Don't connect to, deauthenticate, or otherwise interfere with networks you don't own, and consider that uploads publish third parties' access points and your own movements to a public database.

License

MIT — see LICENSE.