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.

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

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

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

Установка

Этот проект использует 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

Режим 2: Целевой поиск

Поиск конкретного устройства по MAC-адресу:

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

Режим 3: Разрешение IRK

Разрешение Resolvable Private Addresses с помощью Identity Resolving Key. Этот режим по умолчанию работает бесконечно, пока не будет остановлен с помощью Ctrl+C:

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF

IRK может быть указан в нескольких форматах:

Формат	Пример
Простой hex	`0123456789ABCDEF0123456789ABCDEF`
Через двоеточие	`01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF`

IRK из файла

Загрузите один или несколько IRK из файла. Каждая строка должна содержать один IRK в любом поддерживаемом hex-формате. Строки, начинающиеся с #, считаются комментариями:

btrpa-scan --irk-file keys.txt

Пример keys.txt:

# Alice's phone
0123456789ABCDEF0123456789ABCDEF
# Bob's watch
FEDCBA9876543210FEDCBA9876543210

Когда загружено несколько IRK, каждый обнаруженный RPA проверяется по всем ключам. Сводка показывает общее количество совпадений по всем ключам.

IRK из переменной окружения

Установите переменную окружения BTRPA_IRK, чтобы не передавать ключ в командной строке:

export BTRPA_IRK=0123456789ABCDEF0123456789ABCDEF
btrpa-scan

Приоритет: --irk > --irk-file > BTRPA_IRK

Фильтрация по RSSI

Показывать только устройства с уровнем сигнала выше порога:

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

Усреднение RSSI

BLE RSSI по своей природе зашумлён. Используйте скользящее окно усреднения для более стабильной оценки расстояния и отсеивания ложных слабых обнаружений:

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

Когда окно усреднения активно, на дисплее отображаются как исходный, так и усреднённый RSSI (например, RSSI: -65 dBm (avg: -62 dBm over 5 readings)), а оценка расстояния использует усреднённое значение. Фильтр --min-rssi также применяется к усреднённому RSSI, не позволяя единичному шумовому всплеску убрать устройство из списка.

Фильтрация по имени

Фильтруйте устройства по имени с поиском подстроки без учёта регистра:

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

Будут показаны только устройства, чьё рекламируемое имя содержит указанный шаблон. Устройства без имени исключаются, когда активен фильтр по имени.

Активное сканирование

Пассивное сканирование (по умолчанию) видит только рекламные пакеты. Активное сканирование отправляет SCAN_REQ и получает SCAN_RSP, которые могут раскрыть дополнительные UUID сервисов и имена устройств:

btrpa-scan --all --active

Примечание: На macOS CoreBluetooth всегда выполняет активное сканирование независимо от этого флага. На Linux/BlueZ для активного сканирования могут потребоваться права root или возможность CAP_NET_ADMIN.

Пресеты окружения

Оценка расстояния использует показатель потерь пути, который зависит от окружения. По умолчанию (free_space, n=2.0) предполагается отсутствие препятствий. Для более реалистичной оценки внутри помещений:

btrpa-scan --all --environment indoor

Пресет	Показатель потерь пути (n)	Применение
`free_space`	2.0	Открытый воздух, прямая видимость

Более высокие значения n дают большие оценки расстояния при том же RSSI, отражая затухание сигнала от стен и препятствий.

Калибровка опорного RSSI

По умолчанию btrpa-scan вычисляет ожидаемый RSSI на расстоянии 1 метр из рекламируемой мощности TX Power, используя эмпирически подтверждённое смещение 59 дБ (стандарт iBeacon). Для ещё большей точности вы можете указать калиброванное значение, измеренное в вашем окружении:

Разместите целевое устройство ровно в 1 метре от сканера.
Выполните короткое сканирование и запишите средний RSSI.
Передайте это значение с ключом --ref-rssi:

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

Когда задан --ref-rssi, TX Power полностью игнорируется. Это также позволяет оценивать расстояние для устройств, которые не передают TX Power.

Оповещения о близости

Подача звукового сигнала и визуального оповещения, когда устройство, по оценке, находится в пределах заданного расстояния. Требуется, чтобы целевое устройство передавало TX Power:

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

Работает во всех режимах, включая разрешение IRK:

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

Живой TUI

Заменяет прокручиваемый вывод таблицей в терминале, обновляемой в реальном времени и отсортированной по уровню сигнала:

btrpa-scan --all --tui

TUI показывает все обнаруженные устройства в компактной таблице с адресом, именем, RSSI, усреднённым RSSI, оценочным расстоянием, количеством обнаружений и временем последнего появления. Совпадения, разрешённые через IRK, отображаются полужирным шрифтом, а устройства в пределах порога --alert-within выделяются.

Комбинируется с другими флагами:

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

Веб-интерфейс

Запускает браузерный радар с анимированной развёрткой, отслеживанием устройств в реальном времени и GPS-картой:

btrpa-scan --all --gui

Возможности интерфейса:

Радар - анимированная линия развёртки с концентрическими кольцами расстояния (1m, 5m, 10m, 20m). Устройства отображаются в виде цветных точек, расположенных по оценочному расстоянию (зелёный — близко, жёлтый — средне, красный — далеко). Макет на всю высоту с фоном в виде матричного дождя и эффектом мерцания призрачных MAC-адресов
Список устройств - правая панель со списком всех обнаруженных устройств, цветовая кодировка по уровню сигнала. Нажмите на любое устройство, чтобы закрепить его для отслеживания
Закреплённые устройства - левая панель с закреплёнными MAC-адресами и обновлением RSSI и расстояния в реальном времени. Можно закрепить несколько устройств одновременно; нажмите ×, чтобы открепить
GPS-карта - карта Leaflet.js с тайлами OpenStreetMap, показывающая положение сканера и местоположения устройств. Автоматически скрывается, если GPS недоступен
Всплывающие подсказки - наведите курсор на любое устройство (точку на радаре, элемент списка или закреплённый элемент), чтобы увидеть полные сведения об устройстве (адрес, имя, RSSI, TX power, расстояние, GPS, данные производителя, сервисы)
Тёмная тема - хакерская эстетика «матричного» зелёного цвета, создана для полевых работ

Режим GUI по умолчанию сканирует непрерывно (без 30-секундного тайм-аута). Нажмите Ctrl+C для остановки. Используйте -t, чтобы задать конкретную продолжительность сканирования:

# Scan for 60 seconds with indoor path-loss model
btrpa-scan --all --gui -t 60 --environment indoor

# Custom port
btrpa-scan --all --gui --gui-port 8080

# Combine with RSSI averaging and proximity alerts
btrpa-scan --all --gui --rssi-window 5 --alert-within 5.0

Примечание: Для --gui требуются Flask и flask-socketio (pip install btrpa-scan[gui]). Нельзя комбинировать с --tui или --quiet.

Журнал CSV в реальном времени

Потоковая запись каждого обнаружения в CSV-файл по мере его появления (полезно для длительных сканирований, когда нужны инкрементальные данные):

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

Это можно комбинировать с --output для отдельного пакетного экспорта:

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

Пакетный экспорт

Экспорт всех результатов по окончании сканирования в формате CSV, JSON или 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 записывает по одному JSON-объекту в строку, что упрощает передачу через jq:

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

Вывод результатов в stdout для передачи по конвейеру:

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

Сканирование с несколькими адаптерами (Linux)

Одновременное сканирование несколькими Bluetooth-адаптерами для более широкого покрытия:

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

Каждый адаптер запускает собственный экземпляр сканера, использующий общий callback обнаружения. Все обнаружения объединяются в единый вывод.

Привязка GPS-координат

GPS включён по умолчанию. Каждое обнаружение помечается текущими GPS-координатами из gpsd. Сканер также отслеживает наилучшую GPS-фиксацию для каждого устройства — координаты из обнаружения с самым сильным RSSI (ближайшее расположение = наиболее точное местоположение).

Если gpsd не запущен, сканер выводит уведомление и продолжает обычную работу без GPS:

# With gpsd running — detections include lat/lon
btrpa-scan --all --output json

# Without gpsd — works fine, GPS fields are empty
btrpa-scan --all

# Explicitly disable GPS (skips connection attempt)
btrpa-scan --all --no-gps

GPS-координаты отображаются:

Консольный вывод - строка «Best GPS» для каждого устройства
Панель настроек TUI - текущие координаты фиксации
GUI - интерактивная карта с маркерами устройств и положением сканера
Заголовок - статус подключения GPS
Сводные таблицы - столбец «Best GPS» для каждого устройства
Все экспорты (CSV, JSON, JSONL, журнал реального времени) - поля latitude, longitude, gps_altitude

Тихий и подробный режимы

Запуск в тихом режиме (только сводка, без вывода по каждому устройству — полезно с --output или --log):

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

Запуск в подробном режиме (показ несовпадающих RPA в режиме IRK):

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF -v

Как работает разрешение RPA

Устройства Bluetooth Low Energy используют Resolvable Private Addresses (RPA) для защиты от отслеживания. RPA — это временный MAC-адрес, который периодически меняется, но может быть разрешён любым, кто владеет Identity Resolving Key (IRK) устройства.

RPA состоит из:

prand (3 байта) - случайное значение, у которого два старших бита установлены в 01
hash (3 байта) - вычисляется как AES-128-ECB(IRK, padding || prand), усечённый до 3 байт

btrpa-scan реализует функцию ah() из спецификации Bluetooth Core (Vol 3, Part H, Section 2.2.2) для разрешения этих адресов в реальном времени.

Примечание об AES-ECB: Использование AES в режиме ECB для функции ah() предписано спецификацией Bluetooth Core. Поскольку шифруется только один 16-байтовый блок, отсутствие диффузии между блоками в ECB не имеет значения — это не уязвимость.

Запуск тестов

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

Пример вывода

Mode: DISCOVER ALL - showing every broadcasting device
Scanning: passive
GPS: connected (37.774929, -122.419418)
Timeout: 30s  |  Press Ctrl+C to stop
------------------------------------------------------------

============================================================
  DEVICE #1  -  seen 1x
============================================================
  Address      : AA:BB:CC:DD:EE:FF
  Name         : MyDevice
  RSSI         : -45 dBm
  TX Power     : -59 dBm
  Est. Distance: ~0.4 m
  Manufacturer : 0x004C -> 0215abcdef
  Best GPS     : 37.774929, -122.419418
  Timestamp    : 14:32:07
============================================================

------------------------------------------------------------
Scan complete - 30.0s elapsed
  Total detections : 142
  Unique devices   : 12
  Results written to btrpa-scan-results.json

Остановка сканирования

Нажмите Ctrl+C в любой момент, чтобы корректно остановить сканирование и вывести сводную статистику.

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 выше

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

btrpa-scan

Популярное

btrpa-scan

Возможности

Требования

Установка gpsd

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

Установка

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

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

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

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

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

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

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

Режим 2: Целевой поиск

Режим 3: Разрешение IRK

IRK из файла

IRK из переменной окружения

Фильтрация по RSSI

Усреднение RSSI

Фильтрация по имени

Активное сканирование

Пресеты окружения

Калибровка опорного RSSI

Оповещения о близости

Живой TUI

Веб-интерфейс

Журнал CSV в реальном времени

Пакетный экспорт

Сканирование с несколькими адаптерами (Linux)

Привязка GPS-координат

Тихий и подробный режимы

Как работает разрешение RPA

Рекомендации по безопасности

Запуск тестов

Пример вывода

Остановка сканирования