btrpa-scan

Un escáner Bluetooth Low Energy (BLE) con resolución avanzada de direcciones privadas resolubles (RPA). Descubre dispositivos BLE cercanos, rastrea un dispositivo específico por dirección MAC o resuelve direcciones aleatorizadas por privacidad mediante una clave de resolución de identidad (IRK).

Escrito por: David Kennedy (@HackingDave) Empresa: TrustedSec

Características

• Descubrir todos los dispositivos - Escanea todos los dispositivos BLE que estén emitiendo dentro del alcance, con intensidad de señal, distancia estimada, datos del fabricante y UUIDs de servicios
• Búsqueda dirigida - Busca un dispositivo específico por dirección MAC y supervisa cada detección
• Resolución IRK - Resuelve direcciones privadas resolubles contra una o más claves de resolución de identidad para identificar dispositivos que usan direcciones aleatorizadas por privacidad
• Múltiples IRKs - Carga varias IRKs desde un archivo para resolver direcciones de varios dispositivos en un solo escaneo
• Filtrado por RSSI - Filtra las señales débiles con un umbral mínimo de RSSI
• Promediado de RSSI - El promedio con ventana deslizante suaviza las lecturas ruidosas de RSSI BLE para obtener estimaciones de distancia más estables
• Filtrado por nombre - Filtra dispositivos por nombre con coincidencia de subcadena sin distinguir mayúsculas
• Escaneo activo - Envía SCAN_REQ para obtener SCAN_RSP con UUIDs de servicios y nombres de dispositivo adicionales que el escaneo pasivo no capta
• Presets de entorno - Modelos de pérdida de trayecto en interiores, exteriores y espacio libre para una estimación de distancia más precisa
• Alertas de proximidad - Alerta audible/visual cuando se estima que un dispositivo está dentro de una distancia configurable
• GUI web - Interfaz de radar basada en navegador con barrido animado, visualización de distancia, mapa GPS, lista de dispositivos por intensidad de señal con fijar/desfijar y tooltips al pasar el cursor
• TUI en vivo - Tabla de actualización en vivo basada en curses ordenada por intensidad de señal
• Registro CSV en tiempo real - Transmite cada detección a un archivo CSV a medida que ocurre
• Exportación por lotes - Exporta resultados a CSV, JSON o JSONL al final del escaneo (admite stdout con -o -)
• Etiquetado de ubicación GPS - Etiqueta cada detección con coordenadas GPS mediante gpsd; rastrea la mejor ubicación por dispositivo (el RSSI más fuerte = mayor proximidad). Activado por defecto, degrada con elegancia si gpsd no está disponible
• Multiadaptador - Escanea con varios adaptadores Bluetooth simultáneamente (Linux)
• Modos detallado/silencioso - El modo detallado muestra detalles adicionales (p. ej., RPA que no coinciden en modo IRK); el modo silencioso suprime la salida por dispositivo y muestra solo el resumen

Requisitos

• Python 3.9+
• Hardware Bluetooth
• Sistemas operativos compatibles: macOS, Linux, Windows
• gpsd (opcional) — necesario para el etiquetado de ubicación GPS

Instalación de gpsd

El etiquetado de ubicación GPS requiere que el daemon gpsd esté en ejecución con un receptor GPS conectado. Si gpsd no está en ejecución, btrpa-scan continúa con normalidad sin GPS.

Plataforma	Instalación	Inicio
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 mediante WSL o MSYS2	Consulta las instrucciones de WSL anteriores

Para verificar que gpsd funciona:

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

Notas por plataforma

Plataforma	Notas
macOS	Usa CoreBluetooth. El modo IRK aprovecha una API no documentada para obtener direcciones Bluetooth reales en lugar de UUIDs. --active no tiene efecto — CoreBluetooth siempre escanea de forma activa.
Linux	Puede requerir root o la capacidad CAP_NET_ADMIN para escanear.
Windows	API Bluetooth WinRT nativa — direcciones MAC reales disponibles de forma nativa. La TUI requiere pip install windows-curses.

Instalación

Este proyecto usa pyproject.toml (PEP 621), el estándar moderno de empaquetado de Python. Define el proyecto como un paquete instalable con un comando CLI registrado — no es necesario ejecutar archivos .py directamente.

Ejecución rápida (sin instalar)

uvx btrpa-scan --all

Ejecutar desde GitHub (sin instalar)

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

Instalar como herramienta

uv tool install btrpa-scan

O directamente desde GitHub:

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

Instalar con pip

pip install btrpa-scan

Para soporte de GUI (interfaz de radar basada en Flask):

pip install btrpa-scan[gui]

Desde el código fuente

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

Uso

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)

Modo 1: Descubrir todos los dispositivos