btrpa-scan

A Bluetooth Low Energy (BLE) scanner with advanced Resolvable Private Address (RPA) resolution. Discover nearby BLE devices, track a specific device by MAC address, or resolve privacy-randomized addresses using an Identity Resolving Key (IRK).

Written by: David Kennedy (@HackingDave) Company: TrustedSec

Возможности

• Обнаружение всех устройств - Сканирование всех передающих BLE-устройств в зоне действия с уровнем сигнала, оценочным расстоянием, данными производителя и UUID сервисов
• Целевой поиск - Поиск конкретного устройства по MAC-адресу и отслеживание каждого обнаружения
• Разрешение IRK - Разрешение Resolvable Private Addresses с помощью одного или нескольких Identity Resolving Keys для идентификации устройств, использующих рандомизированные адреса для конфиденциальности
• Несколько IRK - Загрузка нескольких IRK из файла для разрешения адресов нескольких устройств за одно сканирование
• Фильтрация по RSSI - Отсеивание слабых сигналов с помощью минимального порога RSSI
• Усреднение RSSI - Скользящее окно усреднения сглаживает зашумлённые показания BLE RSSI для более стабильной оценки расстояния
• Фильтрация по имени - Фильтрация устройств по имени с поиском подстроки без учёта регистра
• Активное сканирование - Отправка SCAN_REQ для получения SCAN_RSP с дополнительными UUID сервисов и именами устройств, которые пропускает пассивное сканирование
• Пресеты окружения - Модели потерь пути indoor, outdoor и free-space для более точной оценки расстояния
• Оповещения о близости - Звуковое/визуальное оповещение, когда устройство, по оценке, находится в пределах настраиваемого расстояния
• Веб-интерфейс - Браузерный радар с анимированной развёрткой, визуализацией расстояния, GPS-картой, списком устройств по уровню сигнала с возможностью закрепления/открепления и всплывающими подсказками
• Живой TUI - Таблица на основе curses, обновляющаяся в реальном времени и отсортированная по уровню сигнала
• Журнал CSV в реальном времени - Потоковая запись каждого обнаружения в CSV-файл по мере появления
• Пакетный экспорт - Экспорт результатов в CSV, JSON или JSONL по окончании сканирования (поддерживает stdout с -o -)
• Привязка GPS-координат - Добавление GPS-координат к каждому обнаружению через gpsd; отслеживается лучшее местоположение для каждого устройства (самый сильный RSSI = ближайшее расположение). Включено по умолчанию, при отсутствии gpsd корректно работает без GPS
• Несколько адаптеров - Одновременное сканирование несколькими Bluetooth-адаптерами (Linux)
• Подробный/тихий режим - Подробный режим показывает дополнительные сведения (например, несовпадающие RPA в режиме IRK); тихий режим скрывает вывод по каждому устройству и показывает только сводку

Требования

• Python 3.9+
• Аппаратное обеспечение Bluetooth
• Поддержка ОС: macOS, Linux, Windows
• gpsd (необязательно) — требуется для привязки GPS-координат

Установка gpsd

Для привязки GPS-координат требуется запущенный демон gpsd с подключённым GPS-приёмником. Если gpsd не запущен, btrpa-scan продолжает работу без GPS.

Платформа	Установка	Запуск
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	Используйте gpsd через WSL или MSYS2	См. инструкции для WSL выше

Чтобы проверить, что gpsd работает:

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

Примечания по платформам

Платформа	Примечания
macOS	Использует CoreBluetooth. Режим IRK использует недокументированный API для получения реальных Bluetooth-адресов вместо UUID. --active не действует — CoreBluetooth всегда выполняет активное сканирование.
Linux	Для сканирования могут потребоваться права root или возможность CAP_NET_ADMIN.
Windows	Собственный API Bluetooth WinRT — реальные MAC-адреса доступны изначально. Для TUI требуется pip install windows-curses.

Установка

Этот проект использует pyproject.toml (PEP 621) — современный стандарт упаковки Python. Он определяет проект как устанавливаемый пакет с зарегистрированной CLI-командой — нет необходимости запускать .py-файлы напрямую.

Быстрый запуск (без установки)

uvx btrpa-scan --all

Запуск с GitHub (без установки)

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

Установка как инструмента

uv tool install btrpa-scan

Или напрямую с GitHub:

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

Установка через pip

pip install btrpa-scan

Для поддержки графического интерфейса (радар на основе Flask):

pip install btrpa-scan[gui]

Из исходного кода

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

Использование

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)

Режим 1: Обнаружение всех устройств

Сканирование всех передающих BLE-устройств (тайм-аут по умолчанию 30 секунд):

btrpa-scan --all

С собственным тайм-аутом:

btrpa-scan --all -t 60