Bluehood

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

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

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

スクリーンショット

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

タブ付き設定ページ — アラート、運用、グループ、セキュリティ

プロジェクト情報と機能概要を表示するインテルページ

なぜ？

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

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

十分なデータがあれば、以下のようなことが可能になる可能性があります：

誰かが通常いつ犬の散歩に行くかを把握する
訪問者が家に到着したタイミングを検出する
デバイスの存在に基づいて日常生活のパターンを特定する

このメタデータは、デバイスと積極的にやり取りしなくても驚くほど個人的な情報を明らかにすることができます。

BluehoodはBluetoothのプライバシーについて認識を高めるための教育ツールです。 週末プロジェクトですが、その影響について考える価値があります。

何？

BluehoodはBluetoothスキャナーで、以下のことを行います：

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

機能

スキャン

デュアルモードスキャン：Bluetooth Low Energy (BLE) およびクラシックBluetooth
MACアドレスベンダールックアップ（ローカルデータベース + オンラインAPIフォールバック）
BLEサービスUUIDフィンガープリンティングによる正確なデバイス分類
クラシックBluetoothデバイスクラスの解析
ランダム化MACフィルタリング（メインビューから非表示）

デバイス管理

個人デバイス追跡のためのデバイスを「監視対象」としてマーク
デバイスをカスタムグループに整理
既知のデバイスにフレンドリーネームを設定
任意のデバイスにカスタムノート/タグを追加
デバイスタイプ検出（スマートフォン、オーディオ、ウェアラブル、IoT、車両など）

分析

30日間の存在タイムラインの可視化
信号強度（RSSI）履歴グラフ（7日間データ）
時間別および日別のアクティビティヒートマップ（デバイスのアクティブ時間を表示）
パターン分析（「平日、夕方5PM-9PM」）
滞在時間分析（デバイスが範囲内に滞在した合計時間を表示）
デバイス相関関係検出（一緒に現れるデバイスを見つける）
近接ゾーン（即時、近距離、遠距離、遠隔）を信号強度に基づいて分類
MAC、ベンダー、名前による検索
過去のクエリのための日付範囲検索

通知（ntfy.sh経由）

スマートフォン/デスクトップへのプッシュ通知
新しいデバイスが検出されたときに通知
監視対象デバイスが戻ってきたときに通知
監視対象デバイスが出発したときに通知
到着/出発のしきい値を設定可能

運用

ハートビートチェックイン — 定期的にアップタイム監視サービス（例：Uptime Kuma、Healthchecks.io）にステータスをPOST
ストレージローテーション — 設定可能な日数より古い視認データを自動的に削除
どちらもWeb UIまたは環境変数から設定可能

Webインターフェース

コンパクト/詳細ビューの切り替え（異なる表示設定に対応）
スクリーンショットモードでMACと名前を難読化して安全に共有
キーボードショートカット（パワーユーザー向け、?で表示）
デバイスデータのCSVエクスポート
デバイスグループ（関連デバイスを整理）
オプションの認証（アクセスを保護）

使い方

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
BLE対応Bluetoothアダプター（Bluetooth 4.0以降） で Central ロールをサポートする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には BLE対応Bluetoothアダプター（Bluetooth 4.0以降） で Central ロールをサポートするものが必要です。古い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

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

注意：初回実行時、macOSはBluetoothアクセスを許可するようプロンプトを表示します。スキャンを機能させるにはこの許可を付与する必要があります。

使用方法

# Webダッシュボードを起動（デフォルトポート8080）
bluehood

# 別のポートを指定
bluehood --port 9000

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

# BLEとクラシックスキャンに別々のアダプターを使用（同時実行）
bluehood --adapter hci0 --classic-adapter hci1

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

# Webダッシュボードを無効にする（スキャンのみ）
bluehood --no-web

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

Webダッシュボード

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

デバイス一覧（タイプアイコン、ベンダー、MAC、名前、視認回数、最終視認）
デバイスフィルター（タイプ別（スマートフォン、オーディオ、IoTなど）、監視状態別）
検索（MAC、ベンダー、名前）
日付範囲検索（特定の時間枠で見られたデバイスを検索）
タブ付き設定ページ — アラート、運用、グループ、セキュリティ（ハッシュによる直接リンク、例：/settings#operations）
デバイス詳細モーダル（以下を含む）：
- BLEサービスフィンガープリント
- 時間別/日別アクティビティヒートマップ
- 30日間存在タイムライン
- 信号強度（RSSI）履歴グラフ
- パターン分析
- 滞在時間統計
- 相関デバイス一覧
- 近接ゾーンインジケーター
- オペレーターノートフィールド
- グループ割り当て

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

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

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

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

プッシュ通知

Bluehoodは無料のオープンソース通知サービスntfy.shを介してプッシュ通知を送信できます。

ntfy.shでトピックを作成します（例：bluehood-myname-alerts）
ntfyアプリを使用してスマートフォンでトピックを購読します
Bluehood設定でトピック名を入力し、通知を有効にします
どのイベントが通知をトリガーするかを設定します：
- 新しいデバイスが検出された
- 監視対象デバイスが戻ってきた（不在後）
- 監視対象デバイスが出発した（X分間見られない）

データストレージ

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

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

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

注意：ハートビートとプルーニングの設定は、Web UI（設定 > 運用）または環境変数から設定できます。GUIの値が環境変数より優先されます。

仕組み

デバイス分類

Bluehoodは複数のシグナルを使用してデバイスを分類します（優先順位順）：

BLEサービスUUID - 最も正確（Heart Rate = ウェアラブル、A2DP = オーディオなど）
デバイス名パターン - "iPhone"、"Galaxy"、"AirPods" など
ベンダーOUIルックアップ - Apple、Samsung、Bose など

ランダム化MAC

最新のデバイスはプライバシーのためMACアドレスをランダム化します。Bluehoodは：

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

パターン分析

Bluehoodは視認タイムスタンプを分析してパターンを検出します：

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

パターンの例: "毎日、夕方（5PM-9PM）"、"平日、午前（8AM-12PM）"

デバイス相関関係

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

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

近接ゾーン

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

即時（> -50 dBm）：非常に近い、数メートル以内
近距離（-50 ～ -60 dBm）：近く、同じ部屋
遠距離（-60 ～ -70 dBm）：さらに離れて、隣の部屋
遠隔（< -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（ダッシュボード > インポート）または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}"

トラブルシューティング

デバイスが見つからない

アダプターがBLE（Bluetooth 4.0+）とCentralロールをサポートしていることを確認してください — 古いアダプターは動作しません
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 を参照してください。

免責事項

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

作成者: Danny McClelland

`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` と同じ	クラシックBluetoothスキャン用の別アダプター（例：`hci1`）。異なるアダプターに設定すると、BLEとクラシックスキャンが同時に実行されます。
`BLUEHOOD_DATA_DIR`	`/data`	データベース保存ディレクトリ
`BLUEHOOD_METRICS_PORT`	無効	Prometheusメトリクスポート（例：`9199`）
`BLUEHOOD_HEARTBEAT_URL`	無効	ハートビートチェックインをPOSTするURL（例：healthchecks.ioまたはuptime-kumaのプッシュURL）
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	ハートビートチェックイン間隔（秒）
`BLUEHOOD_PRUNE_DAYS`	`0`（無効）	N日より古い視認データを自動削除してストレージを節約

`/`	検索バーにフォーカス
`r`	デバイス一覧を更新
`c`	コンパクトビューを切り替え
`w`	選択したデバイスの監視を切り替え
`Esc`	モーダルを閉じる
`?`	キーボードショートカットを表示

`bluehood_scans_total`	Counter	完了したスキャンサイクルの総数
`bluehood_scan_errors_total`	Counter	スキャンエラー（ラベル: `scan_type`）
`bluehood_sightings_total`	Counter	記録されたデバイス視認の総数
`bluehood_new_devices_total`	Counter	発見された新しいユニークデバイスの数
`bluehood_last_scan_devices`	Gauge	最後のスキャンでのデバイス数（ラベル: `scan_type`）
`bluehood_devices_total`	Gauge	DB内のユニークデバイス数（ラベル: `bt_type`）
`bluehood_devices_active`	Gauge	直近5分間に見られたデバイス数
`bluehood_devices_watched`	Gauge	監視対象デバイス数
`bluehood_devices_ignored`	Gauge	無視されたデバイス数
`bluehood_scan_duration_seconds`	Histogram	スキャンサイクルの期間
`bluehood_device_rssi_dbm`	Histogram	BLEデバイスのRSSI分布
`bluehood_build_info`	Info	バージョン情報

人気

bluehood