btrpa-scan

高度な Resolvable Private Address（RPA）解決機能を備えた Bluetooth Low Energy（BLE）スキャナー。近くの BLE デバイスの発見、MAC アドレスによる特定デバイスの追跡、Identity Resolving Key（IRK）を使用したプライバシーランダム化アドレスの解決が可能です。

作者: David Kennedy (@HackingDave) 会社: TrustedSec

機能

• 全デバイスの発見 - レンジ内のすべてのブロードキャスト BLE デバイスを、信号強度、推定距離、メーカーデータ、サービス UUID とともにスキャンします
• ターゲット検索 - MAC アドレスで特定のデバイスを検索し、すべての検出を監視します
• IRK 解決 - 1 つ以上の Identity Resolving Key に対して Resolvable Private Address を解決し、プライバシー保護のためにランダム化アドレスを使用するデバイスを識別します
• 複数 IRK - ファイルから複数の IRK を読み込み、1 回のスキャンで複数のデバイスのアドレスを解決します
• 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 が利用できない場合はグレースフルに機能低下します
• マルチアダプタ - 複数の Bluetooth アダプタで同時にスキャンします（Linux）
• 詳細/クワイエットモード - 詳細モードは追加の詳細（IRK モードでの非一致 RPA など）を表示します。クワイエットモードはデバイスごとの出力を抑止し、サマリーのみを表示します

要件

• Python 3.9+
• Bluetooth ハードウェア
• 対応 OS: macOS、Linux、Windows
• gpsd（オプション）— GPS 位置情報スタンプに必要です

gpsd のインストール

GPS 位置情報スタンプには、GPS レシーバーを接続した gpsd デーモンが実行されている必要があります。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	WSL または MSYS2 経由で gpsd を使用	上記の WSL 手順を参照

gpsd の動作確認:

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

プラットフォーム別メモ

プラットフォーム	メモ
macOS	CoreBluetooth を使用します。IRK モードは、UUID の代わりに実際の Bluetooth アドレスを取得するために非公開 API を利用します。--active は効果がありません — CoreBluetooth は常にアクティブスキャンを行います。
Linux	スキャンには root または CAP_NET_ADMIN ケーパビリティが必要な場合があります。
Windows	ネイティブ WinRT Bluetooth API — 実際の MAC アドレスがネイティブで利用可能です。TUI には pip install windows-curses が必要です。

インストール

このプロジェクトは、最新の Python パッケージング標準である pyproject.toml（PEP 621）を使用しています。登録済み 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 解決

Identity Resolving Key を使用して Resolvable Private Address を解決します。このモードはデフォルトで、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
ダッシュ区切り	01-23-45-67-89-AB-CD-EF-01-23-45-67-89-AB-CD-EF
0x プレフィックス付き	0x0123456789ABCDEF0123456789ABCDEF

ファイルからの IRK

ファイルから 1 つ以上の IRK を読み込みます。各行には、サポートされている任意の hex 形式で 1 つの IRK を記述します。# で始まる行はコメントとして扱われます:

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 の両方が表示され（例: RSSI: -65 dBm (avg: -62 dBm over 5 readings)）、距離推定には平均値が使用されます。--min-rssi フィルタも平均化された RSSI に適用されるため、単発のノイズスパイクによってデバイスが除外されるのを防ぎます。

名前フィルタリング

大文字小文字を区別しない部分文字列マッチングを使用して、名前によりデバイスをフィルタリングします:

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

アドバタイズされた名前に指定パターンを含むデバイスのみが表示されます。名前フィルタが有効な場合、名前のないデバイスは除外されます。

アクティブスキャン

パッシブスキャン（デフォルト）はアドバタイズのみを認識します。アクティブスキャンは SCAN_REQ を送信して SCAN_RSP を取得し、追加のサービス UUID やデバイス名を明らかにできます: