Bluehood

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

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

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

スクリーンショット

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

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

About プロジェクト情報と機能概要を掲載した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イメージ自体には含まれていません。
# 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環境変数

Variable	Default	Description
`PUID`	`1000`	コンテナユーザーのUID — バインドマウントを使用する場合はホストユーザー(`id -u`)に合わせて設定
`PGID`	`1000`	コンテナユーザーのGID — バインドマウントを使用する場合はホストグループ(`id -g`)に合わせて設定
`TZ`	UTC	コンテナのタイムゾーン(例: `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	BLEスキャン用のBluetoothアダプター(例: `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	`BLUEHOOD_ADAPTER`と同じ	Classic Bluetoothスキャン用の別アダプター(例: `hci1`)。別のアダプターに設定すると、BLEとClassicのスキャンが同時に実行されます。
`BLUEHOOD_DATA_DIR`	`/data`	データベースの保存ディレクトリ
`BLUEHOOD_PORT`	`8080`	Webダッシュボードのポート。コンテナはホストネットワーキングを使用するため、8080が使用中の場合は(ポートマッピングではなく)これを変更してください
`BLUEHOOD_NTFY_SERVER`	`https://ntfy.sh`	プッシュ通知用のntfyサーバーのベースURL。セルフホストインスタンスを指定してください。設定ページで保存された値が優先されます
`BLUEHOOD_METRICS_PORT`	disabled	Prometheusメトリクスポート(例: `9199`)
`BLUEHOOD_HEARTBEAT_URL`	disabled	ハートビートチェックインをPOSTするURL(例: healthchecks.ioやuptime-kumaのプッシュURL)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	ハートビートチェックイン間の秒数
`BLUEHOOD_PRUNE_DAYS`	`0` (disabled)	ストレージを解放するために、N日より古い目撃情報を自動削除
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0` (disabled)	0より大きい場合、古い目撃情報の行のみを削除するのではなく、古いデバイス全体(`BLUEHOOD_PRUNE_DAYS`より古く、合計目撃回数がN回未満)を削除します。監視対象デバイスは決して削除されません

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スキャンには昇格された権限が必要です。いずれかを選択してください:

rootとして実行(最も簡単):
```
sudo bluehood
```

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

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

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

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