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.

Per verificare che gpsd funzioni:

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

Note sulle piattaforme

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)

optional arguments:
  -h, --help            mostra questo messaggio di aiuto ed esce
  -a, --all             Scansiona tutti i dispositivi che trasmettono
  --irk HEX             Risolvi le RPA usando questa chiave di risoluzione dell'identità (32 caratteri hex)
  --irk-file PATH       Leggi una o più IRK da un file (una per riga, formato hex)
  -t, --timeout TIMEOUT Timeout di scansione in secondi (default: 30, o infinito per --irk)
  --output {csv,json,jsonl}
                        Formato di output batch scritto al termine della scansione
  -o, --output-file FILE
                        Percorso del file di output (default: btrpa-scan-results.<formato>;
                        usa - per stdout)
  --log FILE            Trasmette i rilevamenti a un file CSV in tempo reale
  -v, --verbose         Modalità verbose — mostra dettagli aggiuntivi
  -q, --quiet           Modalità quiet — sopprime l'output per dispositivo, mostra solo il riepilogo
  --min-rssi DBM        Soglia RSSI minima (es. -70) — ignora i segnali più deboli
  --rssi-window N       Dimensione della finestra scorrevole RSSI per la media (default: 1 = nessuna media)
  --active              Usa la scansione attiva (invia SCAN_REQ per dati aggiuntivi)
  --environment {free_space,indoor,outdoor}
                        Modello di attenuazione per la stima della distanza (default: free_space)
  --ref-rssi DBM        RSSI calibrata a 1 metro per la stima della distanza
  --name-filter PATTERN Filtra i dispositivi per nome (corrispondenza di sottostringa senza distinzione maiuscole/minuscole)
  --alert-within METERS Avviso di prossimità quando il dispositivo è entro questa distanza
  --tui                 Tabella del terminale ad aggiornamento live invece dell'output scorrevole
  --gui                 Avvia l'interfaccia radar basata su browser
  --gui-port PORT       Porta per il server web della GUI (default: 5000)
  --no-gps              Disabilita la marcatura della posizione GPS (il GPS è attivo per impostazione predefinita tramite gpsd)
  --adapters LIST       Nomi degli adattatori Bluetooth separati da virgola (es. hci0,hci1)

Modalità 1: Scopri tutti i dispositivi

Scansiona tutti i dispositivi BLE che trasmettono (timeout predefinito di 30 secondi):

btrpa-scan --all

Con un timeout personalizzato:

btrpa-scan --all -t 60

Modalità 2: Ricerca mirata

Cerca un dispositivo specifico tramite indirizzo MAC:

btrpa-scan AA:BB:CC:DD:EE:FF

Modalità 3: Risoluzione IRK

Risolvi gli Indirizzi Privati Risolvibili usando una chiave di risoluzione dell'identità. Questa modalità viene eseguita indefinitamente per impostazione predefinita fino a quando non viene interrotta con Ctrl+C:

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF

L'IRK può essere fornita in diversi formati:

IRK da un file

Carica una o più IRK da un file. Ogni riga deve contenere una IRK in qualsiasi formato hex supportato. Le righe che iniziano con # sono trattate come commenti:

btrpa-scan --irk-file keys.txt

Esempio di keys.txt:

# Il telefono di Alice
0123456789ABCDEF0123456789ABCDEF
# L'orologio di Bob
FEDCBA9876543210FEDCBA9876543210

Quando vengono caricate più IRK, ogni RPA rilevata viene controllata contro tutte le chiavi. Il riepilogo mostra il totale delle corrispondenze su tutte le chiavi.

IRK da variabile d'ambiente

Imposta la variabile d'ambiente BTRPA_IRK per evitare di passare la chiave sulla riga di comando:

export BTRPA_IRK=0123456789ABCDEF0123456789ABCDEF
btrpa-scan

Priorità: --irk > --irk-file > BTRPA_IRK

Filtro RSSI

Mostra solo i dispositivi con intensità del segnale superiore a una soglia:

btrpa-scan --all --min-rssi -70

Media RSSI

L'RSSI BLE è intrinsecamente rumoroso. Usa una media a finestra scorrevole per stime di distanza più stabili e per filtrare i rilevamenti deboli spuri:

btrpa-scan --all --rssi-window 5

Quando la finestratura è attiva, la visualizzazione mostra sia l'RSSI grezzo che quello mediato (es. RSSI: -65 dBm (avg: -62 dBm over 5 readings)), e la stima della distanza usa il valore mediato. Il filtro --min-rssi si applica anche all'RSSI mediato, impedendo a un singolo picco rumoroso di far sparire un dispositivo.

Filtro per nome

Filtra i dispositivi per nome usando una corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole:

btrpa-scan --all --name-filter "AirPods"

Vengono mostrati solo i dispositivi il cui nome pubblicizzato contiene il pattern indicato. I dispositivi senza nome vengono esclusi quando è attivo un filtro per nome.

Scansione attiva

La scansione passiva (predefinita) vede solo gli advertisement. La scansione attiva invia SCAN_REQ e riceve SCAN_RSP, che può rivelare UUID di servizi aggiuntivi e nomi di dispositivo:

btrpa-scan --all --active

Nota: Su macOS, CoreBluetooth esegue sempre scansioni attive indipendentemente da questo flag. Su Linux/BlueZ, la scansione attiva può richiedere root o CAP_NET_ADMIN.

Preset ambientali

La stima della distanza usa un esponente di attenuazione del percorso che varia in base all'ambiente. Il default (free_space, n=2.0) presuppone l'assenza di ostacoli. Per stime più realistiche in ambienti interni:

btrpa-scan --all --environment indoor

Valori di n più alti producono stime di distanza maggiori per lo stesso RSSI, riflettendo l'attenuazione del segnale dovuta a muri e ostacoli.

Calibrazione RSSI di riferimento

Per impostazione predefinita btrpa-scan ricava l'RSSI attesa a 1 metro dalla TX Power pubblicizzata usando un offset di 59 dB convalidato empiricamente (lo standard iBeacon). Per una precisione ancora maggiore puoi fornire un valore calibrato misurato nel tuo ambiente:

1. Posiziona il dispositivo target esattamente a 1 metro dallo scanner.
2. Esegui una breve scansione e annota l'RSSI media.
3. Passa quel valore con --ref-rssi:

btrpa-scan --all --ref-rssi -55

Quando viene impostato --ref-rssi, la TX Power viene completamente ignorata. Questo abilita anche le stime di distanza per i dispositivi che non pubblicizzano la TX Power.

Avvisi di prossimità

Attiva un campanello acustico e un avviso visivo quando un dispositivo viene stimato entro una data distanza. Richiede che il dispositivo target pubblichi la TX Power:

btrpa-scan AA:BB:CC:DD:EE:FF --alert-within 5.0

Funziona in tutte le modalità, inclusa la risoluzione IRK:

btrpa-scan --irk <key> --alert-within 3.0

TUI in tempo reale

Sostituisci l'output scorrevole con una tabella del terminale ad aggiornamento live, ordinata per intensità del segnale:

btrpa-scan --all --tui

La TUI mostra tutti i dispositivi rilevati in una tabella compatta con indirizzo, nome, RSSI, RSSI mediata, distanza stimata, conteggio dei rilevamenti e ora dell'ultima visualizzazione. Le corrispondenze IRK risolte sono mostrate in grassetto e i dispositivi entro la soglia --alert-within sono evidenziati.

Combinabile con altri flag:

btrpa-scan --irk <key> --tui --rssi-window 5 --environment indoor --alert-within 5.0

GUI Web

Avvia un'interfaccia radar basata su browser con spazzata animata, tracciamento dei dispositivi in tempo reale e mappa GPS:

btrpa-scan --all --gui

La GUI include:

• Display radar — linea di spazzata animata con anelli di distanza concentrici (1m, 5m, 10m, 20m). I dispositivi appaiono come punti codificati per colore posizionati in base alla distanza stimata (verde = vicino, giallo = medio, rosso = lontano). Layout a tutta altezza con sfondo a pioggia di dati matriciali ed effetti di sfarfallio MAC fantasma
• Elenco dispositivi — pannello laterale destro che elenca tutti i dispositivi rilevati, codificati per colore in base all'intensità del segnale. Fai clic su un dispositivo per bloccarlo e seguirlo
• Dispositivi bloccati — pannello laterale sinistro che mostra gli indirizzi MAC bloccati con aggiornamenti live di RSSI e distanza. Blocca più dispositivi contemporaneamente; fai clic su × per sbloccare
• Mappa GPS — mappa Leaflet.js con tile OpenStreetMap che mostra la posizione dello scanner e quella dei dispositivi. Viene nascosta automaticamente se il GPS non è disponibile
• Suggerimenti al passaggio del mouse — passa il mouse su qualsiasi dispositivo (punto radar, voce dell'elenco o voce bloccata) per vedere i dettagli completi del dispositivo (indirizzo, nome, RSSI, TX power, distanza, GPS, dati del produttore, servizi)
• Tema scuro — estetica hacker verde-matrix progettata per il lavoro sul campo

La modalità GUI esegue la scansione in continuo per impostazione predefinita (nessun timeout di 30 secondi). Premi Ctrl+C per fermarla. Usa -t per impostare una durata di scansione specifica:

# Scansiona per 60 secondi con il modello di attenuazione indoor
btrpa-scan --all --gui -t 60 --environment indoor

# Porta personalizzata
btrpa-scan --all --gui --gui-port 8080

# Combinazione con media RSSI e avvisi di prossimità
btrpa-scan --all --gui --rssi-window 5 --alert-within 5.0

Nota: --gui richiede Flask e flask-socketio (pip install btrpa-scan[gui]). Non può essere combinato con --tui o --quiet.

Registrazione CSV in tempo reale

Trasmette ogni rilevamento a un file CSV in tempo reale (utile per scansioni di lunga durata in cui si vogliono dati incrementali):

btrpa-scan --all --log scan.csv

Può essere combinato con --output per un'esportazione batch separata:

btrpa-scan --all --log live.csv --output json -o results.json

Esportazione in batch

Esporta tutti i risultati al termine della scansione in formato CSV, JSON o JSONL (JSON Lines):

btrpa-scan --all --output json -o results.json -t 30
btrpa-scan --all --output csv -t 30
btrpa-scan --all --output jsonl -o results.jsonl -t 30

JSONL scrive un oggetto JSON per riga, semplificando il passaggio attraverso jq:

btrpa-scan --all --output jsonl -o results.jsonl -t 10
cat results.jsonl | jq .

Scrivi l'output su stdout per il piping:

btrpa-scan --all --output json -o - -t 10 -q | jq .

Scansione multi-adattatore (Linux)

Scansiona con più adattatori Bluetooth contemporaneamente per una copertura più ampia:

btrpa-scan --all --adapters hci0,hci1

Ogni adattatore esegue la propria istanza di scansione che condivide lo stesso callback di rilevamento. Tutti i rilevamenti vengono uniti in un unico output.

Marcatura posizione GPS

Il GPS è attivo per impostazione predefinita. Ogni rilevamento viene etichettato con le coordinate GPS correnti da gpsd. Lo scanner tiene anche traccia della migliore posizione GPS per dispositivo: le coordinate del rilevamento con l'RSSI più forte (prossimità più vicina = posizione più accurata).

Se gpsd non è in esecuzione, lo scanner stampa una nota e continua normalmente senza GPS:

# Con gpsd in esecuzione — i rilevamenti includono lat/lon
btrpa-scan --all --output json

# Senza gpsd — funziona comunque, i campi GPS sono vuoti
btrpa-scan --all

# Disabilita esplicitamente il GPS (salta il tentativo di connessione)
btrpa-scan --all --no-gps

Le coordinate GPS compaiono in:

• Output della console — riga "Best GPS" per dispositivo
• Barra delle impostazioni della TUI — coordinate del fix corrente
• GUI — pannello mappa interattivo con marcatori dei dispositivi e posizione dello scanner
• Intestazione — stato della connessione GPS
• Tabelle di riepilogo — colonna "Best GPS" per dispositivo
• Tutte le esportazioni (CSV, JSON, JSONL, registro in tempo reale) — campi latitude, longitude, gps_altitude

Modalità quiet e verbose

Esegui in modalità quiet (solo riepilogo, nessun output per dispositivo — utile con --output o --log):

btrpa-scan --all -q --output json -t 30

Esegui in modalità verbose (mostra le RPA non corrispondenti in modalità IRK):

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF -v

Come funziona la risoluzione RPA

I dispositivi Bluetooth Low Energy usano gli Indirizzi Privati Risolvibili (RPA) per prevenire il tracciamento. Un RPA è un indirizzo MAC temporaneo che cambia periodicamente, ma può essere risolto da chiunque possieda la chiave di risoluzione dell'identità (IRK) del dispositivo.

Un RPA è composto da:

• prand (3 byte) - Un valore casuale con i due bit più significativi impostati a 01
• hash (3 byte) - Calcolato come AES-128-ECB(IRK, padding || prand) troncato a 3 byte

btrpa-scan implementa la funzione ah() della Specifica Bluetooth Core (Vol 3, Part H, Section 2.2.2) per risolvere questi indirizzi in tempo reale.

Nota su AES-ECB: L'uso di AES in modalità ECB per la funzione ah() è imposto dalla Specifica Bluetooth Core. Poiché viene sempre crittografato un unico blocco da 16 byte, la mancanza di diffusione tra blocchi dell'ECB è irrilevante: non si tratta di una vulnerabilità.

Considerazioni sulla sicurezza

• IRK sulla riga di comando: Gli argomenti della riga di comando sono visibili agli altri utenti del sistema tramite ps. Per evitare di esporre l'IRK, usa --irk-file per leggerla da un file oppure imposta la variabile d'ambiente BTRPA_IRK. L'output della console maschera le IRK per impostazione predefinita (mostrando solo i primi e gli ultimi 4 caratteri hex).
• Coordinate GPS nelle esportazioni: Tutti i formati di esportazione (CSV, JSON, JSONL) e l'output della console includono le coordinate GPS quando disponibili. Se condividi i risultati di una scansione, tieni presente che la tua posizione potrebbe essere divulgata. Usa --no-gps per disabilitare completamente il GPS.
• Percorsi dei file di output: Le opzioni --output-file e --log scrivono nel percorso specificato. Assicurati che la destinazione abbia i permessi appropriati per il tuo caso d'uso.

Esecuzione dei test

pip install pytest
python -m pytest test_btrpa_scan.py -v

Esempio di output

Mode: DISCOVER ALL - showing every broadcasting device
Scanning: passive
GPS: connected (37.774929, -122.419418)
Timeout: 30s  |  Press Ctrl+C to stop
------------------------------------------------------------

============================================================
  DEVICE #1  -  seen 1x
============================================================
  Address      : AA:BB:CC:DD:EE:FF
  Name         : MyDevice
  RSSI         : -45 dBm
  TX Power     : -59 dBm
  Est. Distance: ~0.4 m
  Manufacturer : 0x004C -> 0215abcdef
  Best GPS     : 37.774929, -122.419418
  Timestamp    : 14:32:07
============================================================

------------------------------------------------------------
Scan complete - 30.0s elapsed
  Total detections : 142
  Unique devices   : 12
  Results written to btrpa-scan-results.json

Interrompere una scansione

Premi Ctrl+C in qualsiasi momento per interrompere la scansione in modo pulito e visualizzare le statistiche di riepilogo.