btrpa-scan

Scansione Bluetooth Low Energy (BLE) con risoluzione avanzata degli Indirizzi Privati Risolvibili (RPA). Scopri i dispositivi BLE nelle vicinanze, traccia un dispositivo specifico tramite indirizzo MAC o risolvi gli indirizzi randomizzati per la privacy utilizzando una chiave di risoluzione dell'identità (IRK).

Scritto da: David Kennedy (@HackingDave) Azienda: TrustedSec

Funzionalità

• Scopri tutti i dispositivi - Scansiona tutti i dispositivi BLE che trasmettono nel raggio d'azione, con intensità del segnale, distanza stimata, dati del produttore e UUID dei servizi
• Ricerca mirata - Cerca un dispositivo specifico tramite indirizzo MAC e monitora ogni rilevamento
• Risoluzione IRK - Risolvi gli Indirizzi Privati Risolvibili confrontandoli con una o più chiavi di risoluzione dell'identità per identificare i dispositivi che utilizzano indirizzi randomizzati per la privacy
• IRK multiple - Carica più IRK da un file per risolvere gli indirizzi di più dispositivi in una singola scansione
• Filtro RSSI - Filtra i segnali deboli con una soglia RSSI minima
• Media RSSI - La media a finestra scorrevole smussa le letture RSSI BLE rumorose per stime di distanza più stabili
• Filtro per nome - Filtra i dispositivi per nome con corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole
• Scansione attiva - Invia SCAN_REQ per ottenere SCAN_RSP con UUID di servizi aggiuntivi e nomi di dispositivo che la scansione passiva non rileva
• Preset ambientali - Modelli di attenuazione del percorso per ambienti interni, esterni e spazio libero per una stima della distanza più accurata
• Avvisi di prossimità - Avviso acustico/visivo quando un dispositivo viene stimato entro una distanza configurabile
• GUI Web - Interfaccia radar basata su browser con spazzata animata, visualizzazione della distanza, mappa GPS, elenco dispositivi con intensità del segnale con blocco/sblocco e suggerimenti al passaggio del mouse
• TUI in tempo reale - Tabella curses ad aggiornamento live ordinata per intensità del segnale
• Registrazione CSV in tempo reale - Trasmette ogni rilevamento a un file CSV in tempo reale
• Esportazione in batch - Esporta i risultati in CSV, JSON o JSONL al termine della scansione (supporta stdout con -o -)
• Marcatura posizione GPS - Etichetta ogni rilevamento con coordinate GPS tramite gpsd; tiene traccia della posizione migliore per dispositivo (RSSI più alto = prossimità più vicina). Attiva per impostazione predefinita, degrada con garbo se gpsd non è disponibile
• Multi-adattatore - Scansiona con più adattatori Bluetooth contemporaneamente (Linux)
• Modalità verbose/quiet - La modalità verbose mostra dettagli aggiuntivi (es. RPA non corrispondenti in modalità IRK); la modalità quiet sopprime l'output per dispositivo e mostra solo il riepilogo

Requisiti

• Python 3.9+
• Hardware Bluetooth
• Supporto sistema operativo: macOS, Linux, Windows
• gpsd (opzionale) — richiesto per la marcatura della posizione GPS

Installazione di gpsd

La marcatura della posizione GPS richiede che il daemon gpsd sia in esecuzione con un ricevitore GPS collegato. Se gpsd non è in esecuzione, btrpa-scan continua normalmente senza GPS.

Piattaforma	Installazione	Avvio
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	Usa gpsd tramite WSL o MSYS2	Vedi le istruzioni WSL sopra

Per verificare che gpsd funzioni:

# Controlla che gpsd sia in ascolto
gpspipe -w -n 5
# Oppure usa il monitor curses
cgps

Note sulle piattaforme

Piattaforma	Note
macOS	Usa CoreBluetooth. La modalità IRK sfrutta un'API non documentata per recuperare i veri indirizzi Bluetooth invece degli UUID. --active non ha effetto: CoreBluetooth esegue sempre scansioni attive.
Linux	Può richiedere la capacità root o CAP_NET_ADMIN per la scansione.
Windows	API Bluetooth WinRT nativa: i veri indirizzi MAC sono disponibili in modo nativo. La TUI richiede pip install windows-curses.

Installazione

Questo progetto usa pyproject.toml (PEP 621), lo standard moderno di packaging Python. Definisce il progetto come pacchetto installabile con un comando CLI registrato: non è necessario eseguire i file .py direttamente.

Esecuzione rapida (senza installazione)

uvx btrpa-scan --all

Esecuzione da GitHub (senza installazione)

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

Installazione come strumento

uv tool install btrpa-scan

Oppure direttamente da GitHub:

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

Installazione tramite pip

pip install btrpa-scan

Per il supporto GUI (interfaccia radar basata su Flask):

pip install btrpa-scan[gui]

Dal sorgente

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

Utilizzo

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 — scopri tutti i dispositivi o cerca uno specifico

positional arguments:
  mac                   Indirizzo MAC del dispositivo da cercare (ometti per scansionare tutto)