btrpa-scan

Ein Bluetooth-Low-Energy-Scanner (BLE) mit fortschrittlicher Auflösung von Resolvable Private Addresses (RPA). Entdecken Sie BLE-Geräte in der Nähe, verfolgen Sie ein bestimmtes Gerät anhand seiner MAC-Adresse oder lösen Sie aus Datenschutzgründen randomisierte Adressen mithilfe eines Identity Resolving Keys (IRK) auf.

Geschrieben von: David Kennedy (@HackingDave) Firma: TrustedSec

Funktionen

• Alle Geräte entdecken – Scannt alle sendenden BLE-Geräte in Reichweite mit Signalstärke, geschätzter Entfernung, Herstellerdaten und Service-UUIDs
• Gezielte Suche – Sucht nach einem bestimmten Gerät anhand der MAC-Adresse und überwacht jede Erkennung
• IRK-Auflösung – Löst Resolvable Private Addresses mit einem oder mehreren Identity Resolving Keys auf, um Geräte zu identifizieren, die aus Datenschutzgründen randomisierte Adressen verwenden
• Mehrere IRKs – Lädt mehrere IRKs aus einer Datei, um Adressen mehrerer Geräte in einem einzigen Scan aufzulösen
• RSSI-Filterung – Filtert schwache Signale mithilfe eines minimalen RSSI-Schwellenwerts
• RSSI-Mittelwertbildung – Ein gleitender Durchschnitt glättet verrauschte BLE-RSSI-Messwerte für stabilere Entfernungsschätzungen
• Namensfilterung – Filtert Geräte nach Namen mit case-insensitivem Teilstring-Abgleich
• Aktives Scannen – Sendet SCAN_REQ, um SCAN_RSP mit zusätzlichen Service-UUIDs und Gerätenamen zu erhalten, die das passive Scannen übersehen würde
• Umgebungsvoreinstellungen – Innen-, Außen- und Freiraum-Pfadverlustmodelle für genauere Entfernungsschätzungen
• Nähewarnungen – Akustischer/visueller Alarm, wenn ein Gerät innerhalb einer konfigurierbaren Entfernung geschätzt wird
• Web-GUI – Browserbasierte Radarschnittstelle mit animiertem Sweep, Entfernungsvisualisierung, GPS-Karte, nach Signalstärke sortierter Geräteliste mit Anpinnen/Lösen und Hover-Tooltips
• Live-TUI – Curses-basierte, live aktualisierte Tabelle, sortiert nach Signalstärke
• Echtzeit-CSV-Protokoll – Schreibt jede Erkennung direkt in eine CSV-Datei, während sie stattfindet
• Stapel-Export – Exportiert Ergebnisse am Ende des Scans als CSV, JSON oder JSONL (unterstützt stdout mit -o -)
• GPS-Standortmarkierung – Markiert jede Erkennung mit GPS-Koordinaten über gpsd; verfolgt die beste Position pro Gerät (stärkstes RSSI = nächste Nähe). Standardmäßig aktiviert; funktioniert bei nicht verfügbarem gpsd eingeschränkt weiter
• Multi-Adapter – Scannt gleichzeitig mit mehreren Bluetooth-Adaptern (Linux)
• Ausführlicher/Ruhemodus – Der ausführliche Modus zeigt zusätzliche Details (z. B. nicht übereinstimmende RPAs im IRK-Modus); der Ruhemodus unterdrückt die Ausgabe pro Gerät und zeigt nur die Zusammenfassung

Voraussetzungen

• Python 3.9+
• Bluetooth-Hardware
• Betriebssysteme: macOS, Linux, Windows
• gpsd (optional) — erforderlich für die GPS-Standortmarkierung

gpsd installieren

Die GPS-Standortmarkierung erfordert den laufenden gpsd-Daemon mit einem angeschlossenen GPS-Empfänger. Wenn gpsd nicht läuft, setzt btrpa-scan den Betrieb normal ohne GPS fort.

Plattform	Installation	Start
macOS	brew install gpsd	gpsd -n /dev/tty.usbserial-*
Debian/Ubuntu	sudo apt install gpsd gpsd-clients	sudo systemctl start gpsd
Fedora/RHEL	sudo dnf install gpsd gpsd-clients	sudo systemctl start gpsd
Arch	sudo pacman -S gpsd	sudo systemctl start gpsd
Windows	gpsd über WSL oder MSYS2 verwenden	Siehe WSL-Anweisungen oben

Um zu überprüfen, ob gpsd funktioniert:

# Check that gpsd is listening
gpspipe -w -n 5
# Or use the curses monitor
cgps

Plattform-Hinweise

Plattform	Hinweise
macOS	Verwendet CoreBluetooth. Der IRK-Modus nutzt eine undokumentierte API, um echte Bluetooth-Adressen anstelle von UUIDs abzurufen. --active hat keine Wirkung – CoreBluetooth scannt immer aktiv.
Linux	Kann für das Scannen root-Rechte oder die Capability CAP_NET_ADMIN erfordern.
Windows	Native WinRT-Bluetooth-API – echte MAC-Adressen nativ verfügbar. Die TUI erfordert pip install windows-curses.

Installation

Dieses Projekt verwendet pyproject.toml (PEP 621), den modernen Python-Packaging-Standard. Es definiert das Projekt als installierbares Paket mit einem registrierten CLI-Befehl – es ist nicht nötig, .py-Dateien direkt auszuführen.

Schnellstart (ohne Installation)

uvx btrpa-scan --all

Von GitHub ausführen (ohne Installation)

uvx --from git+https://github.com/hackingdave/btrpa-scan.git btrpa-scan --all

Als Tool installieren

uv tool install btrpa-scan

Oder direkt von GitHub:

uv tool install git+https://github.com/hackingdave/btrpa-scan.git

Über pip installieren

pip install btrpa-scan

Für GUI-Unterstützung (Flask-basierte Radarschnittstelle):

pip install btrpa-scan[gui]

Aus dem Quellcode

git clone https://github.com/hackingdave/btrpa-scan.git
cd btrpa-scan
pip install .

Verwendung

usage: btrpa-scan [-h] [-a] [--irk HEX] [--irk-file PATH] [-t TIMEOUT]
                     [--output {csv,json,jsonl}] [-o FILE] [--log FILE]
                     [-v | -q] [--min-rssi DBM] [--rssi-window N] [--active]
                     [--environment {free_space,indoor,outdoor}]
                     [--ref-rssi DBM] [--name-filter PATTERN]
                     [--alert-within METERS] [--tui] [--gui] [--gui-port PORT]
                     [--no-gps] [--adapters LIST] [mac]

BLE Scanner — discover all devices or hunt for a specific one

positional arguments:
  mac                   Target MAC address to search for (omit to scan all)

optional arguments:
  -h, --help            show this help message and exit
  -a, --all             Scan for all broadcasting devices
  --irk HEX             Resolve RPAs using this Identity Resolving Key (32 hex chars)
  --irk-file PATH       Read IRK(s) from a file (one per line, hex format)
  -t, --timeout TIMEOUT Scan timeout in seconds (default: 30, or infinite for --irk)
  --output {csv,json,jsonl}
                        Batch output format written at end of scan
  -o, --output-file FILE
                        Output file path (default: btrpa-scan-results.<format>;
                        use - for stdout)
  --log FILE            Stream detections to a CSV file in real time
  -v, --verbose         Verbose mode — show additional details
  -q, --quiet           Quiet mode — suppress per-device output, show summary only
  --min-rssi DBM        Minimum RSSI threshold (e.g. -70) — ignore weaker signals
  --rssi-window N       RSSI sliding window size for averaging (default: 1 = no averaging)
  --active              Use active scanning (sends SCAN_REQ for additional data)
  --environment {free_space,indoor,outdoor}
                        Distance estimation path-loss model (default: free_space)
  --ref-rssi DBM        Calibrated RSSI at 1 metre for distance estimation
  --name-filter PATTERN Filter devices by name (case-insensitive substring match)
  --alert-within METERS Proximity alert when device is within this distance
  --tui                 Live-updating terminal table instead of scrolling output
  --gui                 Launch web-based radar interface in the browser
  --gui-port PORT       Port for GUI web server (default: 5000)
  --no-gps              Disable GPS location stamping (GPS is on by default via gpsd)
  --adapters LIST       Comma-separated Bluetooth adapter names (e.g. hci0,hci1)

Modus 1: Alle Geräte entdecken

Scannt alle sendenden BLE-Geräte (Standard-Timeout: 30 Sekunden):

btrpa-scan --all

Mit einem benutzerdefinierten Timeout:

btrpa-scan --all -t 60

Modus 2: Gezielte Suche