btrpa-scan

一款蓝牙低功耗（BLE）扫描器，具有高级可解析私有地址（RPA）解析功能。发现附近的 BLE 设备，通过 MAC 地址跟踪特定设备，或使用身份解析密钥（IRK）解析隐私随机化地址。

作者： David Kennedy (@HackingDave) 公司： TrustedSec

功能

发现所有设备 - 扫描范围内所有广播的 BLE 设备，包含信号强度、估计距离、制造商数据和服务 UUID
定向搜索 - 通过 MAC 地址搜索特定设备并监控每次检测
IRK 解析 - 使用一个或多个身份解析密钥解析可解析私有地址，以识别使用随机地址保护隐私的设备
多 IRK - 从文件加载多个 IRK，在单次扫描中解析多个设备的地址
RSSI 过滤 - 通过最小 RSSI 阈值过滤掉弱信号
RSSI 平均 - 滑动窗口平均平滑嘈杂的 BLE RSSI 读数，使距离估计更稳定
名称过滤 - 通过名称过滤设备，支持不区分大小写的子串匹配
主动扫描 - 发送 SCAN_REQ 以获取被动扫描遗漏的附加服务 UUID 和设备名称的 SCAN_RSP
环境预设 - 室内、室外和自由空间路径损耗模型，实现更准确的距离估计
临近警报 - 当设备估计在可配置距离内时发出声音/视觉警报
Web GUI - 基于浏览器的雷达界面，具有动画扫描线、距离可视化、GPS 地图、带固定/取消固定的信号强度设备列表和悬停提示
实时 TUI - 基于 curses 的实时更新表格，按信号强度排序
实时 CSV 日志 - 每当检测发生时，将每次检测流式写入 CSV 文件
批量导出 - 扫描结束时将结果导出为 CSV、JSON 或 JSONL（支持使用 -o - 输出到标准输出）
GPS 位置标记 - 通过 gpsd 为每次检测标记 GPS 坐标；跟踪每台设备的最佳位置（最强 RSSI = 最近距离）。默认开启，如果 gpsd 不可用则优雅降级
多适配器 - 同时使用多个蓝牙适配器扫描（Linux）
详细/安静模式 - 详细模式显示额外细节（例如 IRK 模式下不匹配的 RPA）；安静模式抑制每设备输出，仅显示摘要

要求

Python 3.9+
蓝牙硬件
操作系统支持：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	Use gpsd via WSL or MSYS2	See WSL instructions above

验证 gpsd 是否正常工作：

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

平台说明

平台	说明
macOS	使用 CoreBluetooth。IRK 模式利用未公开的 API 获取真实的蓝牙地址而非 UUID。`--active` 无效——CoreBluetooth 始终主动扫描。
Linux	扫描可能需要 `root` 或 `CAP_NET_ADMIN` 权限。
Windows	原生 WinRT 蓝牙 API——可直接获取真实 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

对于 GUI 支持（基于 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 解析

使用身份解析密钥解析可解析私有地址。此模式默认无限运行，直到按 Ctrl+C 停止：

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF

IRK 可以以多种格式提供：

格式	示例
纯十六进制	`0123456789ABCDEF0123456789ABCDEF`
冒号分隔	`01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF`
短横线分隔	`01-23-45-67-89-AB-CD-EF-01-23-45-67-89-AB-CD-EF`
0x 前缀	`0x0123456789ABCDEF0123456789ABCDEF`

从文件加载 IRK

从文件加载一个或多个 IRK。每行应包含一个 IRK，格式为任何支持的十六进制格式。以 # 开头的行被视为注释：

btrpa-scan --irk-file keys.txt

示例 keys.txt：

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

从环境变量加载 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	开阔空气、视线
`outdoor`	2.2	公园、停车场
`indoor`	3.0	办公室、家庭、建筑

较高的 n 值在相同 RSSI 下产生更大的距离估计，反映墙壁和障碍物的信号衰减。

参考 RSSI 校准

默认情况下，btrpa-scan 使用经验验证的 59 dB 偏移（iBeacon 标准）从广播的 TX Power 推导出 1 米处的预期 RSSI。为了获得更好的精度，您可以提供在自己环境中测量的校准值：

将目标设备精确放置在距扫描仪 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

最受欢迎

btrpa-scan

功能

要求

安装 gpsd

平台说明

安装

快速运行（无需安装）

从 GitHub 运行（无需安装）

作为工具安装

通过 pip 安装

从源码安装

用法

模式 1：发现所有设备

模式 2：定向搜索

模式 3：IRK 解析

从文件加载 IRK

从环境变量加载 IRK

RSSI 过滤

RSSI 平均

名称过滤

主动扫描

环境预设

参考 RSSI 校准

接近警报

实时 TUI