btrpa-scan

Um scanner Bluetooth Low Energy (BLE) com resolução avançada de Endereço Privado Resolvível (RPA). Descubra dispositivos BLE próximos, rastreie um dispositivo específico por endereço MAC ou resolva endereços randomizados por privacidade usando uma Chave de Resolução de Identidade (IRK).

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

Recursos

• Descobrir todos os dispositivos - Escaneia todos os dispositivos BLE transmitindo na área com intensidade de sinal, distância estimada, dados do fabricante e UUIDs de serviço
• Busca direcionada - Procura um dispositivo específico por endereço MAC e monitora cada detecção
• Resolução de IRK - Resolve Endereços Privados Resolvíveis contra uma ou mais Chaves de Resolução de Identidade para identificar dispositivos que usam endereços randomizados por privacidade
• Múltiplas IRKs - Carrega várias IRKs de um arquivo para resolver endereços de vários dispositivos em uma única varredura
• Filtro de RSSI - Filtra sinais fracos com um limite mínimo de RSSI
• Média de RSSI - A média por janela deslizante suaviza leituras de RSSI BLE ruidosas para estimativas de distância mais estáveis
• Filtro por nome - Filtra dispositivos por nome com correspondência de substring sem diferenciar maiúsculas/minúsculas
• Varredura ativa - Envia SCAN_REQ para obter SCAN_RSP com UUIDs de serviço e nomes de dispositivos adicionais que a varredura passiva não captura
• Predefinições de ambiente - Modelos de perda de percurso para ambientes internos, externos e espaço livre para estimativa de distância mais precisa
• Alertas de proximidade - Alerta audível/visual quando um dispositivo é estimado dentro de uma distância configurável
• Interface web (GUI) - Interface de radar baseada em navegador com varredura animada, visualização de distância, mapa GPS, lista de dispositivos por intensidade de sinal com fixar/desfixar e tooltips ao passar o mouse
• TUI ao vivo - Tabela baseada em curses com atualização em tempo real ordenada por intensidade de sinal
• Log CSV em tempo real - Transmite cada detecção para um arquivo CSV conforme ela ocorre
• Exportação em lote - Exporta resultados para CSV, JSON ou JSONL ao final da varredura (suporta stdout com -o -)
• Registro de localização GPS - Marca cada detecção com coordenadas GPS via gpsd; rastreia a melhor localização por dispositivo (RSSI mais forte = proximidade mais próxima). Ativado por padrão, degrada suavemente se o gpsd estiver indisponível
• Multi-adaptador - Escaneia com vários adaptadores Bluetooth simultaneamente (Linux)
• Modos verboso/quieto - O modo verboso mostra detalhes adicionais (ex.: RPAs sem correspondência no modo IRK); o modo quieto suprime a saída por dispositivo e mostra apenas o resumo

Requisitos

• Python 3.9+
• Hardware Bluetooth
• Suporte a sistema operacional: macOS, Linux, Windows
• gpsd (opcional) — necessário para o registro de localização GPS

Instalando o gpsd

O registro de localização GPS requer o daemon gpsd em execução com um receptor GPS conectado. Se o gpsd não estiver em execução, o btrpa-scan continua normalmente sem GPS.

Plataforma	Instalação	Inicialização
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	Use o gpsd via WSL ou MSYS2	Veja as instruções do WSL acima

Para verificar se o gpsd está funcionando:

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

Notas por plataforma

Plataforma	Notas
macOS	Usa CoreBluetooth. O modo IRK aproveita uma API não documentada para obter endereços Bluetooth reais em vez de UUIDs. --active não tem efeito — o CoreBluetooth sempre faz varredura ativa.
Linux	Pode exigir root ou a capacidade CAP_NET_ADMIN para varredura.
Windows	API nativa WinRT Bluetooth — endereços MAC reais disponíveis nativamente. A TUI exige pip install windows-curses.

Instalação

Este projeto usa pyproject.toml (PEP 621), o padrão moderno de empacotamento Python. Ele define o projeto como um pacote instalável com um comando CLI registrado — não é necessário executar arquivos .py diretamente.

Execução rápida (sem instalação)

uvx btrpa-scan --all

Executar do GitHub (sem instalação)

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

Instalar como ferramenta

uv tool install btrpa-scan

Ou diretamente do GitHub:

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

Instalar via pip

pip install btrpa-scan

Para suporte à interface gráfica (interface de radar baseada em Flask):

pip install btrpa-scan[gui]

A partir do código-fonte

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: Descobrir todos os dispositivos

Escaneia todos os dispositivos BLE transmitindo na área (tempo limite padrão de 30 segundos):

btrpa-scan --all