Bluehood

Bluetooth Neighborhood - 周辺のBLEデバイスを追跡し、トラフィックパターンを分析します。

警告: アルファ版ソフトウェア

このプロジェクトは開発の初期段階にあり、本番環境での使用には適していません。機能は予告なく変更、破損、削除される可能性があります。自己責任でご使用ください。収集されたデータは実験的なものとして扱うべきです。

スクリーンショット

フィルタリング、検索、リアルタイム統計を備えたデバイスリストを表示するメインダッシュボード

タブ形式の設定ページ — アラート、オペレーション、グループ、セキュリティ

プロジェクト情報と機能概要を掲載したIntelページ

なぜ?

このプロジェクトは、Bluetoothデバイスにおけるプライバシーリスクを浮き彫りにしたWhisperPair脆弱性(CVE-2025-36911)に触発されて生まれました。

私たちの周囲には常に何千ものBluetoothデバイスが存在しています。スマートフォン、車、テレビ、ヘッドフォン、補聴器、配送車両など、枚挙にいとまがありません。Bluehoodは、こうしたデバイスを受動的に検出し、その存在パターンを観察することがいかに簡単であるかを示します。

十分なデータがあれば、以下のようなことが可能になるかもしれません:

• ある人が普段何時に犬の散歩をしているかを把握する
• 訪問者が家に到着したタイミングを検出する
• デバイスの存在に基づいて日々のルーティンのパターンを特定する

こうしたメタデータは、デバイスとの能動的なやり取りを一切行わずに、驚くほど個人的な情報を明らかにする可能性があります。

Bluehoodは、Bluetoothプライバシーに関する意識を高めるための教育ツールです。 週末プロジェクトではありますが、その意味するところは考える価値があります。

何?

Bluehoodは、以下のことを行うBluetoothスキャナーです:

• 近くのBluetoothデバイス(BLEとClassicの両方)を継続的にスキャン
• ベンダー(MACアドレス検索)とBLEサービスUUIDによってデバイスを識別
• デバイスをカテゴリ(スマートフォン、オーディオ、ウェアラブル、IoT、車両など)に分類
• 時間単位/日単位のヒートマップで存在パターンを経時的に追跡
• ランダム化されたMACアドレス(プライバシーローテーションされたデバイス)からのノイズをフィルタリング
• 一緒に現れるデバイスを見つけるためにデバイス相関を分析
• 監視対象デバイスが到着または離脱した際にプッシュ通知を送信
• 監視と分析のためのWebダッシュボードを提供

機能

スキャン

• デュアルモードスキャン: Bluetooth Low Energy (BLE)とClassic Bluetooth
• MACアドレスベンダー検索(ローカルデータベース + オンラインAPIフォールバック)
• 正確なデバイス分類のためのBLEサービスUUIDフィンガープリンティング
• Classic Bluetoothデバイスクラスの解析
• ランダム化MACのフィルタリング(メインビューから非表示)

デバイス管理

• 個人デバイスを追跡するためにデバイスを「監視対象」としてマーク
• デバイスをカスタムグループに整理
• デバイスにカスタム名を付与(アドバタイズされた名前はそのまま並んで表示されます)
• 任意のデバイスの検出された分類を上書き
• 任意のデバイスにカスタムノート/タグを追加
• デバイスタイプの検出(スマートフォン、オーディオ、ウェアラブル、IoT、車両など)

分析

• 30日間の存在タイムラインの可視化
• 信号強度(RSSI)履歴チャート(7日間のデータ)
• デバイスがいつアクティブかを示す時間単位および日単位のアクティビティヒートマップ
• パターン分析(「平日、夕方17時〜21時」)
• デバイスが範囲内に滞在する合計時間を示す滞在時間分析
• 一緒に現れるデバイスを見つけるためのデバイス相関検出(共起および同期した到着/離脱)
• MACローテーションの紐付け(「同一デバイスの可能性が高い」)— 時間的に引き継がれ、類似した信号強度を共有し、類似した間隔でpingを送信するランダム化識別子をヒューリスティックに紐付け
• 信号強度に基づく近接ゾーン(immediate、near、far、remote)
• MAC、ベンダー、または名前による検索
• 履歴クエリのための日付範囲検索

通知(ntfy経由)

• ntfy.shまたはセルフホストのntfyサーバーを通じて、スマートフォン/デスクトップにプッシュ通知
• 新しいデバイスが検出されたときに通知
• 監視対象デバイスが戻ってきたときに通知
• 監視対象デバイスが離脱したときに通知
• 到着/離脱のための設定可能なしきい値

オペレーション

• ハートビートチェックイン — 定期的に稼働監視サービス(例: Uptime Kuma、Healthchecks.io)にステータスをPOST
• ストレージローテーション — 設定可能な日数より古い目撃情報を自動的に削除。オプションで、最小回数未満しか観測されていない古いデバイス全体に削除を限定可能(監視対象デバイスは決して削除されません)
• いずれもWeb UIまたは環境変数から設定可能

Webインターフェース

• 表示設定を切り替えるためのコンパクト/詳細ビューのトグル
• 安全に共有するためにMACと名前を難読化するスクリーンショットモード
• パワーユーザー向けのキーボードショートカット(?を押して表示)
• 詳細なデバイスデータのCSVエクスポート(MAC、ベンダー、識別子、タイプ、BTタイプ、デバイスクラス、監視/無視フラグ、初回/最終観測、目撃回数、グループ、サービスUUID、ノート)— 現在のページだけでなく、フィルタリングされたセット全体をエクスポート
• 関連デバイスを整理するためのデバイスグループ
• アクセスを保護するためのオプションの認証

どうやって?

Dockerによるクイックスタート(推奨)

前提条件 — Linuxホストのみ

Bluehoodは、LinuxのBluetoothスタックであるBlueZを介してBluetoothアダプターと通信します。コンテナを起動する前に、BlueZがホストにインストールされ、実行されている必要があります — Dockerイメージ自体には含まれていません。

root@kitploit:~

# Debian / Ubuntu (Ubuntu Serverを含む)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

ホストにBlueZがない場合、次のようなエラーが表示されます: BLE scan error: [org.freedesktop.DBus.Error.ServiceUnknown] The name org.bluez was not provided by any .service files

# docker-compose.ymlを作成するか、このリポジトリからダウンロードしてください
# その後、Docker Composeで起動します
docker compose up -d

# ログを表示
docker compose logs -f

DockerイメージはGitHub Container Registryで入手できます:

ghcr.io/dannymcc/bluehood:latest

Webダッシュボードは**http://localhost:8080**で利用可能になります

Dockerの要件

• DockerおよびDocker Compose
• CentralロールをサポートするBLE対応Bluetoothアダプター(Bluetooth 4.0以降)を備えたLinuxホスト
• ホストにインストールされ実行されているBlueZ(sudo apt install bluez && sudo systemctl enable --now bluetooth)

注: 古いアダプター(Bluetooth 2.x/3.x)はBLEスキャンをサポートしていません。アダプターがBLE Centralロールのサポートを欠いている場合、次のように表示されます: No Bluetooth adapters with BLE 'central' role found。

注: DockerはBluetoothアクセスのために特権モードとホストネットワーキングで実行されます。これはBLEスキャンに必要です。

Docker環境変数

Bluetoothアダプターの要件

Bluehoodには、CentralロールをサポートするBLE対応Bluetoothアダプター(Bluetooth 4.0以降)が必要です。古いBluetooth 2.x/3.xアダプターはBLEスキャンをサポートしておらず、動作しません。

アダプターがBLE Centralロールをサポートしていない場合、Bluehoodは次のように終了します:

No Bluetooth adapters with BLE 'central' role found

アダプターの機能はbluetoothctl showで確認でき、サポートされているロールにcentralがあるかを探してください。

手動インストール(Linux)

# システム依存関係をインストール (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# システム依存関係をインストール (Debian/Ubuntu)
sudo apt install bluez python3-pip

# クローンしてインストール
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

Bluetoothの権限

Bluetoothスキャンには昇格された権限が必要です。いずれかを選択してください:

1. rootとして実行(最も簡単):

   root@kitploit:~

   sudo bluehood
   

2. Pythonにケイパビリティを付与:

   root@kitploit:~

   sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
   bluehood
   

3. systemdサービスを使用(常時稼働に推奨):

   root@kitploit:~

   sudo cp bluehood.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now bluehood
   

macOS

BluehoodはDockerなしでmacOS上でネイティブに動作します。macOSはBlueZの代わりにCoreBluetoothを使用し、これはbleakライブラリによって自動的に処理されます。

# リポジトリをクローン
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# 仮想環境を作成
python3 -m venv .venv
source .venv/bin/activate

# インストール
pip install -e .

# 実行
python -m bluehood.daemon

Webダッシュボードは**http://localhost:8080**で利用可能になります

注: 初回実行時、macOSはBluetoothアクセスを許可するよう促します。スキャンを機能させるにはこの権限を付与する必要があります。

使用方法

# Webダッシュボード付きで起動 (デフォルトポート8080)
bluehood

# 別のポートを指定 (またはBLUEHOOD_PORTを設定)
bluehood --port 9000

# 特定のBluetoothアダプターを使用
bluehood --adapter hci1

# BLEとClassicスキャンに別々のアダプターを使用 (同時実行)
bluehood --adapter hci0 --classic-adapter hci1

# 利用可能なアダプターを一覧表示
bluehood --list-adapters

# Webダッシュボードを無効化 (スキャンのみ)
bluehood --no-web

# ポート9199でPrometheusメトリクスエクスポーターを有効化
bluehood --metrics-port 9199

Webダッシュボード

ダッシュボードは以下を提供します:

• タイプアイコン、ベンダー、MAC、名前、目撃回数、最終観測を備えたデバイスリスト
• タイプ(スマートフォン、オーディオ、IoTなど)と監視ステータスによるデバイスフィルター
• MAC、ベンダー、または名前による検索
• 特定の時間枠で観測されたデバイスを見つける日付範囲検索
• タブ形式の設定ページ — アラート、オペレーション、グループ、セキュリティ(ハッシュによる直接リンク、例: /settings#operations)
• 以下を含むデバイス詳細モーダル:
  • BLEサービスフィンガープリント
  • 時間単位/日単位のアクティビティヒートマップ
  • 30日間の存在タイムライン
  • 信号強度(RSSI)履歴チャート
  • パターン分析
  • 滞在時間統計
  • 相関デバイスリスト
  • 同一デバイスの可能性が高いもの(MACローテーション)リスト
  • 近接ゾーンインジケーター
  • オペレーターノートフィールド
  • グループ割り当て

キーボードショートカット

スクリーンショットモード

サイドバーからスクリーンショットモードを有効にすると、スクリーンショットを共有する前に機密データを難読化できます:

• MACアドレスは最初の2オクテットのみ表示(例: AA:BB:XX:XX:XX:XX)
• フレンドリ名は最初の2文字のみ表示(例: Da********)
• CSVエクスポートもスクリーンショットモードに従います

プッシュ通知

Bluehoodは、無料のオープンソース通知サービスであるntfyを介してプッシュ通知を送信できます。公開ntfy.shサーバーまたは独自のセルフホストインスタンスを使用できます。

1. ntfy.sh(例: bluehood-myname-alerts)または独自のntfyサーバーでトピックを作成
2. ntfyアプリを使用してスマートフォンでトピックを購読
3. Bluehoodの設定で、サーバーURL(デフォルトはhttps://ntfy.sh)、トピック名、サーバーが要求する場合はアクセストークンを入力し、通知を有効化
4. 通知をトリガーするイベントを設定:
   • 新しいデバイスが検出された
   • 監視対象デバイスが(不在後に)戻ってきた
   • 監視対象デバイスが離脱した(X分間観測されない)

データストレージ

データは~/.local/share/bluehood/bluehood.db(SQLite)に保存されます。

環境変数で場所を上書きできます:

• BLUEHOOD_DATA_DIR - データファイル用のディレクトリ
• BLUEHOOD_DB_PATH - データベースファイルへの直接パス

注: ハートビートと削除の設定は、Web UI(設定 > オペレーション)または環境変数から設定できます。GUIの値が環境変数より優先されます。

仕組み

デバイス分類

Bluehoodは複数のシグナルを使用してデバイスを分類します(優先順):

1. BLEサービスUUID - 最も正確(Heart Rate = ウェアラブル、A2DP = オーディオなど)
2. デバイス名のパターン - 「iPhone」、「Galaxy」、「AirPods」など
3. ベンダーOUI検索 - Apple、Samsung、Boseなど

ランダム化されたMAC

現代のデバイスはプライバシーのためにMACアドレスをランダム化します。Bluehoodは:

• ランダム化されたMAC(ローカル管理ビット)を検出
• メインデバイスリストから非表示(追跡には役立たないため)
• 非表示のランダム化デバイスの数を表示

パターン分析

Bluehoodは目撃のタイムスタンプを分析してパターンを検出します:

• 時間帯: 朝、午後、夕方、夜
• 曜日: 平日、週末
• 頻度: 常時、毎日、定期的、時々、まれ

パターンの例: 「毎日、夕方(17時〜21時)」、「平日、朝(8時〜12時)」

デバイス相関

Bluehoodは、設定可能な時間枠内で頻繁に一緒に現れるデバイスを検出します。これは以下を明らかにする可能性があります:

• 同じ人物が所有するデバイス(スマートフォン + スマートウォッチ)
• 一緒に移動する人々
• スケジュールを共有するデバイス

近接ゾーン

RSSI信号強度に基づいて、デバイスは近接ゾーンに分類されます:

• Immediate(> -50 dBm): 非常に近い、数メートル以内
• Near(-50〜-60 dBm): 近く、同じ部屋
• Far(-60〜-70 dBm): やや遠い、隣接する部屋
• Remote(< -70 dBm): 遠い、検出範囲の端

滞在時間分析

目撃間のギャップを分析することで、デバイスが範囲内に滞在する時間を追跡します。設定可能なギャップしきい値(デフォルト15分)が、新しい「セッション」がいつ始まるかを決定します。

Prometheusメトリクス

BluehoodはPrometheusスクレイピング用のメトリクスを公開できます。BLUEHOOD_METRICS_PORT環境変数または--metrics-port CLIフラグを設定して有効化します。

# 環境変数経由
export BLUEHOOD_METRICS_PORT=9199

# CLI経由
bluehood --metrics-port 9199

メトリクスはhttp://host:9199/metricsで提供されます。

利用可能なメトリクス

Grafanaダッシュボード

すぐにインポートできるGrafanaダッシュボードがgrafana/bluehood-dashboard.jsonに含まれています。Grafana UI(Dashboards > Import)またはAPI経由でインポートしてください:

curl -X POST "http://localhost:3000/api/dashboards/db" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"dashboard\": $(cat grafana/bluehood-dashboard.json), \"overwrite\": true}"

トラブルシューティング

デバイスが見つからない

• アダプターがCentralロールを備えたBLE(Bluetooth 4.0以降)をサポートしていることを確認してください — 古いアダプターは動作しません
• Bluetoothアダプターが有効になっていることを確認: bluetoothctl power on
• アダプターが検出されているか確認: bluehood --list-adapters
• 権限が拒否された場合はsudoで実行

Dockerの問題

BLE scan error: org.freedesktop.DBus.Error.ServiceUnknown / The name org.bluez was not provided

BlueZがホストにインストールされていないか、実行されていません。修正方法:

sudo apt install bluez          # Debian/Ubuntu
sudo systemctl enable --now bluetooth
docker compose restart

一般的なチェックリスト:

• BlueZが(コンテナ内だけでなく)ホストにインストールされていることを確認
• Bluetoothサービスが実行されていることを確認: systemctl status bluetooth
• アダプターが認識されていることを確認: bluetoothctl list

コントリビューション

コントリビューションを歓迎します! GitHubでissueまたはPRを作成してください。

コントリビューター

• @martinh2011 (Martin Hüser) - MACベンダーキャッシュの改善
• @hatedabamboo (Kirill Solovei) - ライトテーマのサポート
• @krnltrp - Web UIの機能強化
• @jacobpretorius (Jacob Pretorius) - CSVエクスポートのJS修正(#14)、クリックで設定を開く(#16)
• @unqualifiedkoala - BLEアダプター要件の文書化
• @dazzag24 - macOSのアドレス形式の問題を報告
• @floese (W.A.Flozart) - Firefoxのダブルクリック修正(#29)
• @GeiserX (Sergio Fernández) - Prometheusメトリクスエクスポーター(#35)、非ブロッキングベンダーDB修正(#37)、デュアルアダプタースキャン(#33)、rfkillによる堅牢なスキャンリカバリ(#40)

ライセンス

MIT License - 詳細はLICENSEを参照してください。

免責事項

このツールは教育目的のみを意図しています。Bluetoothデバイスを監視する際は、お住まいの地域のプライバシー法にご注意ください。作者は本ソフトウェアのいかなる誤用についても責任を負いません。

Created by Danny McClelland