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.

Plateforme	Installation	Démarrage
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	Utilisez gpsd via WSL ou MSYS2	Voir les instructions WSL ci-dessus

Pour vérifier que gpsd fonctionne :

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

Remarques par plateforme

Plateforme	Remarques
macOS	Utilise CoreBluetooth. Le mode IRK exploite une API non documentée pour récupérer les véritables adresses Bluetooth au lieu des UUID. --active n'a aucun effet — CoreBluetooth analyse toujours activement.
Linux	Peut nécessiter les droits root ou la capacité CAP_NET_ADMIN pour l'analyse.
Windows	API Bluetooth WinRT native — les véritables adresses MAC sont disponibles nativement. La TUI nécessite pip install windows-curses.

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)