btrpa-scan

Un scanner Bluetooth Low Energy (BLE) doté d'une résolution avancée des adresses privées résolubles (RPA). Découvrez les appareils BLE à proximité, suivez un appareil spécifique par adresse MAC ou résolvez les adresses randomisées pour la confidentialité à l'aide d'une clé de résolution d'identité (IRK).

Écrit par : David Kennedy (@HackingDave) Société : TrustedSec

Fonctionnalités

• Découvrir tous les appareils — Analyse tous les appareils BLE diffusant à portée avec intensité du signal, distance estimée, données fabricant et UUID de services
• Recherche ciblée — Recherche un appareil spécifique par adresse MAC et surveille chaque détection
• Résolution IRK — Résout les adresses privées résolubles à l'aide d'une ou plusieurs clés de résolution d'identité pour identifier les appareils qui utilisent des adresses randomisées pour la confidentialité
• IRK multiples — Charge plusieurs IRK depuis un fichier pour résoudre les adresses de plusieurs appareils en une seule analyse
• Filtrage RSSI — Élimine les signaux faibles grâce à un seuil RSSI minimum
• Moyenne RSSI — Une moyenne glissante lisse les lectures RSSI BLE bruitées pour des estimations de distance plus stables
• Filtrage par nom — Filtre les appareils par nom avec correspondance de sous-chaîne insensible à la casse
• Analyse active — Envoie SCAN_REQ pour obtenir SCAN_RSP avec des UUID de services et noms d'appareils supplémentaires que l'analyse passive ne détecte pas
• Préréglages d'environnement — Modèles d'affaiblissement intérieur, extérieur et en espace libre pour une estimation de distance plus précise
• Alertes de proximité — Alerte sonore/visuelle lorsqu'un appareil est estimé à une distance configurable
• Interface Web — Interface radar dans le navigateur avec balayage animé, visualisation de distance, carte GPS, liste d'appareils par intensité du signal avec épinglage/désépinglage et infobulles au survol
• TUI en direct — Tableau en direct basé sur curses, mis à jour en temps réel et trié par intensité du signal
• Journal CSV en temps réel — Diffuse chaque détection vers un fichier CSV au fur et à mesure
• Export par lot — Exporte les résultats en CSV, JSON ou JSONL à la fin de l'analyse (prend en charge stdout avec -o -)
• Horodatage de localisation GPS — Marque chaque détection avec les coordonnées GPS via gpsd ; suit la meilleure position par appareil (RSSI le plus fort = proximité la plus proche). Activé par défaut, se dégrade gracieusement si gpsd est indisponible
• Multi-adaptateur — Analyse avec plusieurs adaptateurs Bluetooth simultanément (Linux)
• Modes verbeux/silencieux — Le mode verbeux affiche des détails supplémentaires (par ex. les RPA non correspondantes en mode IRK) ; le mode silencieux supprime la sortie par appareil et n'affiche que le résumé

Prérequis

• Python 3.9+
• Matériel Bluetooth
• Systèmes d'exploitation pris en charge : macOS, Linux, Windows
• gpsd (facultatif) — requis pour l'horodatage de localisation GPS

Installation de gpsd

L'horodatage de localisation GPS nécessite que le démon gpsd soit en cours d'exécution avec un récepteur GPS connecté. Si gpsd ne fonctionne pas, btrpa-scan continue normalement sans GPS.

Pour vérifier que gpsd fonctionne :

# Vérifie que gpsd écoute
gpspipe -w -n 5
# Ou utilise le moniteur curses
cgps

Remarques par plateforme

Installation

Ce projet utilise pyproject.toml (PEP 621), la norme moderne d'empaquetage Python. Il définit le projet comme un paquet installable doté d'une commande CLI enregistrée — nul besoin d'exécuter les fichiers .py directement.

Exécution rapide (sans installation)

uvx btrpa-scan --all

Exécution depuis GitHub (sans installation)

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

Installation en tant qu'outil

uv tool install btrpa-scan

Ou directement depuis GitHub :

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

Installation via pip

pip install btrpa-scan

Pour la prise en charge de l'interface graphique (interface radar basée sur Flask) :

pip install btrpa-scan[gui]

Depuis les sources

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

Utilisation

utilisation : 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 — découvrez tous les appareils ou traquez un appareil spécifique

arguments positionnels :
  mac                   Adresse MAC cible à rechercher (omettre pour analyser tout)

arguments optionnels :
  -h, --help            Affiche ce message d'aide et quitte
  -a, --all             Analyse tous les appareils diffusant
  --irk HEX             Résout les RPA à l'aide de cette clé de résolution d'identité (32 caractères hexadécimaux)
  --irk-file PATH       Lit la ou les IRK depuis un fichier (une par ligne, format hexadécimal)
  -t, --timeout TIMEOUT Délai d'analyse en secondes (défaut : 30, ou infini pour --irk)
  --output {csv,json,jsonl}
                        Format de sortie par lot écrit à la fin de l'analyse
  -o, --output-file FILE
                        Chemin du fichier de sortie (défaut : btrpa-scan-results.<format> ;
                        utiliser - pour la sortie standard)
  --log FILE            Diffuse les détections vers un fichier CSV en temps réel
  -v, --verbose         Mode verbeux — affiche des détails supplémentaires
  -q, --quiet           Mode silencieux — supprime la sortie par appareil, résumé uniquement
  --min-rssi DBM        Seuil RSSI minimum (par ex. -70) — ignore les signaux plus faibles
  --rssi-window N       Taille de la fenêtre glissante RSSI pour la moyenne (défaut : 1 = pas de moyenne)
  --active              Utilise l'analyse active (envoie SCAN_REQ pour des données supplémentaires)
  --environment {free_space,indoor,outdoor}
                        Modèle d'affaiblissement pour l'estimation de distance (défaut : free_space)
  --ref-rssi DBM        RSSI calibré à 1 mètre pour l'estimation de distance
  --name-filter PATTERN Filtre les appareils par nom (correspondance de sous-chaîne insensible à la casse)
  --alert-within METERS Alerte de proximité lorsque l'appareil se trouve à cette distance
  --tui                 Tableau de terminal mis à jour en direct au lieu d'une sortie défilante
  --gui                 Lance l'interface radar web dans le navigateur
  --gui-port PORT       Port du serveur web de l'interface graphique (défaut : 5000)
  --no-gps              Désactive l'horodatage de localisation GPS (GPS activé par défaut via gpsd)
  --adapters LIST       Noms des adaptateurs Bluetooth séparés par des virgules (par ex. hci0,hci1)

Mode 1 : Découvrir tous les appareils

Analyse tous les appareils BLE diffusant (délai d'expiration par défaut de 30 secondes) :

btrpa-scan --all

Avec un délai d'expiration personnalisé :

btrpa-scan --all -t 60

Mode 2 : Recherche ciblée

Recherche un appareil spécifique par adresse MAC :

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

Mode 3 : Résolution IRK

Résout les adresses privées résolubles à l'aide d'une clé de résolution d'identité. Ce mode s'exécute indéfiniment par défaut jusqu'à son arrêt avec Ctrl+C :

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF

L'IRK peut être fournie dans plusieurs formats :

IRK depuis un fichier

Charge une ou plusieurs IRK depuis un fichier. Chaque ligne doit contenir une IRK dans n'importe quel format hexadécimal pris en charge. Les lignes commençant par # sont considérées comme des commentaires :

btrpa-scan --irk-file keys.txt

Exemple de keys.txt :

# Le téléphone d'Alice
0123456789ABCDEF0123456789ABCDEF
# La montre de Bob
FEDCBA9876543210FEDCBA9876543210

Lorsque plusieurs IRK sont chargées, chaque RPA détectée est vérifiée par rapport à toutes les clés. Le résumé affiche le nombre total de correspondances pour toutes les clés.

IRK depuis une variable d'environnement

Définissez la variable d'environnement BTRPA_IRK pour éviter de passer la clé en ligne de commande :

export BTRPA_IRK=0123456789ABCDEF0123456789ABCDEF
btrpa-scan

Priorité : --irk > --irk-file > BTRPA_IRK

Filtrage RSSI

Affiche uniquement les appareils dont l'intensité du signal est supérieure à un seuil :

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

Moyenne RSSI

Le RSSI BLE est intrinsèquement bruité. Utilisez une moyenne glissante pour des estimations de distance plus stables et pour éliminer les détections faibles erronées :

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

Lorsque le fenêtrage est actif, l'affichage montre à la fois le RSSI brut et le RSSI moyenné (par ex. RSSI: -65 dBm (avg: -62 dBm over 5 readings)), et l'estimation de distance utilise la valeur moyennée. Le filtre --min-rssi s'applique également au RSSI moyenné, empêchant qu'un seul pic bruité fasse disparaître un appareil.

Filtrage par nom

Filtre les appareils par nom à l'aide d'une correspondance de sous-chaîne insensible à la casse :

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

Seuls les appareils dont le nom diffusé contient le motif donné seront affichés. Les appareils sans nom sont exclus lorsqu'un filtre par nom est actif.

Analyse active

L'analyse passive (par défaut) ne voit que les publicités. L'analyse active envoie SCAN_REQ et reçoit SCAN_RSP, ce qui peut révéler des UUID de services et des noms d'appareils supplémentaires :

btrpa-scan --all --active

Remarque : Sur macOS, CoreBluetooth analyse toujours activement quel que soit ce drapeau. Sur Linux/BlueZ, l'analyse active peut nécessiter les droits root ou la capacité CAP_NET_ADMIN.

Préréglages d'environnement

L'estimation de distance utilise un exposant d'affaiblissement de propagation qui varie selon l'environnement. La valeur par défaut (free_space, n=2.0) suppose une absence d'obstacles. Pour des estimations plus réalistes en intérieur :

btrpa-scan --all --environment indoor

Des valeurs n plus élevées produisent des estimations de distance plus grandes pour le même RSSI, ce qui reflète l'atténuation du signal par les murs et les obstacles.

Calibrage du RSSI de référence

Par défaut, btrpa-scan déduit le RSSI attendu à 1 mètre de la puissance TX diffusée à l'aide d'un décalage de 59 dB validé empiriquement (la norme iBeacon). Pour une précision encore meilleure, vous pouvez fournir une valeur calibrée mesurée dans votre propre environnement :

1. Placez l'appareil cible à exactement 1 mètre du scanner.
2. Lancez une courte analyse et notez le RSSI moyen.
3. Transmettez cette valeur avec --ref-rssi :

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

Lorsque --ref-rssi est défini, la puissance TX est entièrement ignorée. Cela permet également les estimations de distance pour les appareils qui ne diffusent pas de puissance TX.

Alertes de proximité

Déclenche une sonnerie et une alerte visuelle lorsqu'un appareil est estimé à une distance donnée. Nécessite que l'appareil cible diffuse la puissance TX :

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

Fonctionne dans tous les modes, y compris la résolution IRK :

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

TUI en direct

Remplace la sortie défilante par un tableau de terminal mis à jour en direct, trié par intensité du signal :

btrpa-scan --all --tui

La TUI affiche tous les appareils détectés dans un tableau compact avec l'adresse, le nom, le RSSI, le RSSI moyenné, la distance estimée, le nombre de détections et l'heure de dernière apparition. Les correspondances IRK résolues sont affichées en gras et les appareils situés dans le seuil --alert-within sont mis en évidence.

À combiner avec d'autres drapeaux :

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

Interface Web

Lance une interface radar dans le navigateur avec balayage animé, suivi des appareils en temps réel et carte GPS :

btrpa-scan --all --gui

L'interface graphique comprend :

• Affichage radar — ligne de balayage animée avec anneaux de distance concentriques (1 m, 5 m, 10 m, 20 m). Les appareils apparaissent sous forme de points codés par couleur positionnés selon la distance estimée (vert = proche, jaune = moyen, rouge = loin). Mise en page pleine hauteur avec fond de pluie de données matricielle et effets de scintillement MAC fantôme
• Liste des appareils — panneau latéral droit listant tous les appareils détectés, codés par couleur selon l'intensité du signal. Cliquez sur n'importe quel appareil pour l'épingler et le suivre
• Appareils épinglés — panneau latéral gauche affichant les adresses MAC épinglées avec mises à jour en direct du RSSI et de la distance. Épinglez plusieurs appareils simultanément ; cliquez sur × pour désépingler
• Carte GPS — carte Leaflet.js avec tuiles OpenStreetMap affichant la position du scanner et les emplacements des appareils. Masquée automatiquement si aucun GPS n'est disponible
• Infobulles au survol — survolez n'importe quel appareil (point radar, entrée de liste ou entrée épinglée) pour voir tous les détails de l'appareil (adresse, nom, RSSI, puissance TX, distance, GPS, données fabricant, services)
• Thème sombre — esthétique hacker vert matriciel conçue pour le travail sur le terrain

Le mode interface graphique analyse en continu par défaut (aucun délai d'expiration de 30 secondes). Appuyez sur Ctrl+C pour arrêter. Utilisez -t pour définir une durée d'analyse spécifique :

# Analyse pendant 60 secondes avec le modèle d'affaiblissement intérieur
btrpa-scan --all --gui -t 60 --environment indoor

# Port personnalisé
btrpa-scan --all --gui --gui-port 8080

# À combiner avec la moyenne RSSI et les alertes de proximité
btrpa-scan --all --gui --rssi-window 5 --alert-within 5.0

Remarque : --gui nécessite Flask et flask-socketio (pip install btrpa-scan[gui]). Ne peut pas être combiné avec --tui ou --quiet.

Journal CSV en temps réel

Diffuse chaque détection vers un fichier CSV au fur et à mesure (utile pour les analyses de longue durée lorsque vous souhaitez des données incrémentales) :

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

Cela peut être combiné avec --output pour un export par lot séparé :

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

Export par lot

Exporte tous les résultats à la fin de l'analyse au format CSV, JSON ou 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 écrit un objet JSON par ligne, ce qui permet de le transmettre facilement à jq :

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

Écrivez la sortie sur stdout pour l'utiliser dans un pipeline :

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

Analyse multi-adaptateur (Linux)

Analysez avec plusieurs adaptateurs Bluetooth simultanément pour une couverture plus large :

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

Chaque adaptateur exécute sa propre instance de scanner partageant le même rappel de détection. Toutes les détections sont fusionnées dans une seule sortie.

Horodatage de localisation GPS

Le GPS est activé par défaut. Chaque détection est marquée avec les coordonnées GPS actuelles provenant de gpsd. Le scanner suit également la meilleure position GPS par appareil — les coordonnées de la détection avec le RSSI le plus fort (proximité la plus proche = position la plus précise).

Si gpsd ne fonctionne pas, le scanner affiche une note et continue normalement sans GPS :

# Avec gpsd en cours d'exécution — les détections incluent lat/lon
btrpa-scan --all --output json

# Sans gpsd — fonctionne parfaitement, les champs GPS sont vides
btrpa-scan --all

# Désactive explicitement le GPS (ignore la tentative de connexion)
btrpa-scan --all --no-gps

Les coordonnées GPS apparaissent dans :

• Sortie console — ligne « Best GPS » par appareil
• Barre de paramètres de la TUI — coordonnées actuelles de la position
• Interface graphique — panneau de carte interactif avec marqueurs d'appareils et position du scanner
• En-tête — état de la connexion GPS
• Tableaux récapitulatifs — colonne « Best GPS » par appareil
• Tous les exports (CSV, JSON, JSONL, journal en temps réel) — champs latitude, longitude, gps_altitude

Modes silencieux et verbeux

Exécution en mode silencieux (résumé uniquement, aucune sortie par appareil — utile avec --output ou --log) :

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

Exécution en mode verbeux (affiche les RPA non correspondantes en mode IRK) :

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF -v

Comment fonctionne la résolution RPA

Les appareils Bluetooth Low Energy utilisent des adresses privées résolubles (RPA) pour empêcher le suivi. Une RPA est une adresse MAC temporaire qui change périodiquement, mais qui peut être résolue par quiconque possède la clé de résolution d'identité (IRK) de l'appareil.

Une RPA se compose de :

• prand (3 octets) — une valeur aléatoire dont les deux bits de poids fort sont définis sur 01
• hash (3 octets) — calculé comme AES-128-ECB(IRK, padding || prand) tronqué à 3 octets

btrpa-scan implémente la fonction ah() de la spécification Bluetooth Core (Vol 3, Part H, Section 2.2.2) pour résoudre ces adresses en temps réel.

Remarque sur AES-ECB : L'utilisation d'AES en mode ECB pour la fonction ah() est imposée par la spécification Bluetooth Core. Comme un seul bloc de 16 octets est toujours chiffré, l'absence de diffusion d'ECB entre les blocs est sans importance — il ne s'agit pas d'une vulnérabilité.

Considérations de sécurité

• IRK en ligne de commande : Les arguments de ligne de commande sont visibles par les autres utilisateurs du système via ps. Pour éviter d'exposer l'IRK, utilisez --irk-file pour la lire depuis un fichier, ou définissez la variable d'environnement BTRPA_IRK. La sortie console masque les IRK par défaut (n'affichant que les 4 premiers et 4 derniers caractères hexadécimaux).
• Coordonnées GPS dans les exports : Tous les formats d'export (CSV, JSON, JSONL) et la sortie console incluent les coordonnées GPS lorsqu'elles sont disponibles. Si vous partagez des résultats d'analyse, sachez que votre position peut être divulguée. Utilisez --no-gps pour désactiver entièrement le GPS.
• Chemins des fichiers de sortie : Les options --output-file et --log écrivent dans le chemin spécifié. Assurez-vous que la destination dispose des autorisations appropriées pour votre cas d'utilisation.

Exécution des tests

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

Exemple de sortie

Mode : DÉCOUVERTE DE TOUS - affiche chaque appareil diffusant
Analyse : passive
GPS : connecté (37.774929, -122.419418)
Délai : 30s  |  Appuyez sur Ctrl+C pour arrêter
------------------------------------------------------------

============================================================
  APPAREIL #1  -  vu 1x
============================================================
  Adresse      : AA:BB:CC:DD:EE:FF
  Nom          : MyDevice
  RSSI         : -45 dBm
  TX Power     : -59 dBm
  Dist. estimée: ~0.4 m
  Fabricant    : 0x004C -> 0215abcdef
  Meilleur GPS : 37.774929, -122.419418
  Horodatage   : 14:32:07
============================================================

------------------------------------------------------------
Analyse terminée - 30.0s écoulées
  Total des détections : 142
  Appareils uniques    : 12
  Résultats écrits dans btrpa-scan-results.json

Arrêt d'une analyse

Appuyez sur Ctrl+C à tout moment pour arrêter proprement l'analyse et afficher les statistiques récapitulatives.