Bluehood

蓝牙邻里 - 追踪您周围的 BLE 设备并分析流量模式。

警告：Alpha 软件

本项目处于早期开发阶段，尚未准备好用于生产环境。功能可能会在无通知的情况下变更、损坏或被移除。使用风险自负。收集的数据应视为实验性数据。

截图

Dashboard 主仪表板，显示设备列表，支持筛选、搜索和实时统计

Settings 标签式配置页面 — 警报、操作、分组和安全

About 情报页面，包含项目信息和功能概览

为什么？

本项目的灵感来自 WhisperPair 漏洞（CVE-2025-36911），该漏洞凸显了蓝牙设备中的隐私风险。

我们身边始终围绕着成千上万的蓝牙设备：手机、汽车、电视、耳机、助听器、配送车辆等等。Bluehood 展示了被动检测这些设备并观察其存在模式是多么简单。

有了足够的数据，您可能可以：

了解某人通常在什么时间遛狗
检测访客何时到达某处住宅
根据设备存在情况识别日常作息规律

这些元数据可以在不与设备进行任何主动交互的情况下，揭示出令人惊讶的个人信息。

Bluehood 是一个教育工具，旨在提高人们对蓝牙隐私的意识。 这是一个周末项目，但其影响值得思考。

是什么？

Bluehood 是一个蓝牙扫描器，它可以：

持续扫描附近的蓝牙设备（包括 BLE 和经典蓝牙）
识别设备，通过厂商（MAC 地址查询）和 BLE 服务 UUID
分类设备，将其归入不同类别（手机、音频、可穿戴设备、物联网、车辆等）
追踪存在模式，通过每小时/每天的热力图随时间变化
过滤噪声，排除随机化 MAC 地址（隐私轮换设备）
分析设备关联性，找出同时出现的设备
发送推送通知，当被监视的设备到达或离开时
提供 Web 仪表板，用于监控和分析

功能

扫描

双模式扫描：低功耗蓝牙（BLE）和经典蓝牙
MAC 地址厂商查询（本地数据库 + 在线 API 回退）
BLE 服务 UUID 指纹识别，实现准确的设备分类
经典蓝牙设备类别解析
随机化 MAC 过滤（从主视图中隐藏）

设备管理

将设备标记为“监视”，用于追踪个人设备
将设备组织到自定义分组中
为设备设置自定义名称（广播名称仍会同时显示）
覆盖任何设备的检测分类
为任何设备添加自定义备注/标签
设备类型检测（手机、音频、可穿戴设备、物联网、车辆等）

分析

30 天存在时间线可视化
信号强度（RSSI）历史图表，包含 7 天数据
每小时和每天活动热力图，显示设备活跃时间
模式分析（“工作日，傍晚 17:00-21:00”）
停留时间分析，显示设备在范围内的总时间
设备关联检测，找出同时出现的设备（共现加上同步的到达/离开）
MAC 轮换关联（“可能是同一设备”）—— 启发式地关联在时间上交接、信号强度相似且以相似频率出现的随机化标识符
距离区域（极近、近、远、极远），基于信号强度
按 MAC、厂商或名称搜索
日期范围搜索，用于历史查询

通知（通过 ntfy）

通过 ntfy.sh 或自托管的 ntfy 服务器向您的手机/桌面发送推送通知
检测到新设备时通知
被监视设备返回时通知
被监视设备离开时通知
可配置到达/离开的阈值

操作

心跳签到 — 定期向正常运行时间监控服务（例如 Uptime Kuma、Healthchecks.io）POST 状态
存储轮换 — 自动清理超过可配置天数的目击记录；可选地将清理限制为仅清理出现次数少于最低次数的整个陈旧设备（被监视的设备永远不会被清理）
两者均可从 Web UI 或通过环境变量配置

Web 界面

紧凑/详细视图切换，适应不同的显示偏好
截图模式，对 MAC 和名称进行混淆，以便安全分享
键盘快捷键，供高级用户使用（按 ? 查看）
CSV 导出详细设备数据（MAC、厂商、标识符、类型、蓝牙类型、设备类别、监视/忽略标志、首次/最后出现、目击次数、分组、服务 UUID 和备注）—— 导出整个筛选后的集合，而不仅仅是当前页面
设备分组，用于组织相关设备
可选身份验证，保护访问安全

如何？

使用 Docker 快速开始（推荐）

先决条件 — 仅限 Linux 主机

Bluehood 通过 BlueZ（Linux 蓝牙协议栈）与您的蓝牙适配器通信。在启动容器之前，必须在主机上安装并运行 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

# Create a docker-compose.yml or download the one from this repo
# Then start with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

Docker 镜像可在 GitHub Container Registry 上获取：

ghcr.io/dannymcc/bluehood:latest

Web 仪表板将可通过 http://localhost:8080 访问

Docker 要求

Docker 和 Docker Compose
具有支持 BLE 的蓝牙适配器（蓝牙 4.0+）并支持 Central 角色的 Linux 主机
主机上已安装并运行 BlueZ（sudo apt install bluez && sudo systemctl enable --now bluetooth）

注意：较旧的适配器（蓝牙 2.x/3.x）不支持 BLE 扫描。如果您的适配器不支持 BLE Central 角色，您将看到：No Bluetooth adapters with BLE 'central' role found。

注意：Docker 以特权模式运行，并使用主机网络以访问蓝牙。这是 BLE 扫描所必需的。

Docker 环境变量

蓝牙适配器要求

Bluehood 需要支持 BLE 的蓝牙适配器（蓝牙 4.0 或更高版本）并支持 Central 角色。较旧的蓝牙 2.x/3.x 适配器不支持 BLE 扫描，将无法工作。

如果您的适配器不支持 BLE Central 角色，Bluehood 将退出并显示：

No Bluetooth adapters with BLE 'central' role found

您可以使用 bluetoothctl show 检查适配器的能力，并在支持的角色中查找 central。

手动安装（Linux）

# Install system dependencies (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# Install system dependencies (Debian/Ubuntu)
sudo apt install bluez python3-pip

# Clone and install
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

蓝牙权限

蓝牙扫描需要提升的权限。选择以下之一：

以 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 可以在 macOS 上原生运行，无需 Docker。macOS 使用 CoreBluetooth 而不是 BlueZ，bleak 库会自动处理这一点。

# Clone the repository
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Run
python -m bluehood.daemon

Web 仪表板将可通过 http://localhost:8080 访问

注意：首次运行时，macOS 会提示您允许蓝牙访问。您必须授予此权限，扫描才能正常工作。

用法

# Start with web dashboard (default port 8080)
bluehood

# Specify a different port (or set BLUEHOOD_PORT)
bluehood --port 9000

# Use a specific Bluetooth adapter
bluehood --adapter hci1

# Use separate adapters for BLE and classic scanning (concurrent)
bluehood --adapter hci0 --classic-adapter hci1

# List available adapters
bluehood --list-adapters

# Disable web dashboard (scanning only)
bluehood --no-web

# Enable Prometheus metrics exporter on port 9199
bluehood --metrics-port 9199

Web 仪表板

仪表板提供：

设备列表，包含类型图标、厂商、MAC、名称、目击次数、最后出现时间
设备筛选，按类型（手机、音频、物联网等）和监视状态
搜索，按 MAC、厂商或名称
日期范围搜索，查找在特定时间窗口内出现的设备
标签式设置页面 — 警报、操作、分组和安全（通过哈希直接链接，例如 /settings#operations）
设备详情模态框，包含：
- BLE 服务指纹
- 每小时/每天活动热力图
- 30 天存在时间线
- 信号强度（RSSI）历史图表
- 模式分析
- 停留时间统计
- 关联设备列表
- 可能是同一设备（MAC 轮换）列表
- 距离区域指示器
- 操作员备注字段
- 分组分配

键盘快捷键

截图模式

从侧边栏启用截图模式，以便在分享截图前混淆敏感数据：

MAC 地址仅显示前 2 个八位字节（例如 AA:BB:XX:XX:XX:XX）
友好名称仅显示前 2 个字符（例如 Da********）
CSV 导出也遵循截图模式

推送通知

Bluehood 可以通过 ntfy 发送推送通知，这是一个免费的开源通知服务。您可以使用公共 ntfy.sh 服务器或您自己的自托管实例。

在 ntfy.sh 上创建一个主题（例如 bluehood-myname-alerts），或在您自己的 ntfy 服务器上创建
使用 ntfy 应用在手机上订阅该主题
在 Bluehood 设置中，输入服务器 URL（默认为 https://ntfy.sh）、您的主题名称，以及如果您的服务器需要，输入访问令牌，然后启用通知
配置哪些事件触发通知：
- 检测到新设备
- 被监视设备返回（在缺席之后）
- 被监视设备离开（X 分钟未出现）

数据存储

数据存储在 ~/.local/share/bluehood/bluehood.db（SQLite）。

使用环境变量覆盖位置：

BLUEHOOD_DATA_DIR - 数据文件目录
BLUEHOOD_DB_PATH - 数据库文件的直接路径

注意：心跳和清理设置可以从 Web UI（设置 > 操作）或通过环境变量配置。GUI 值优先于环境变量。

工作原理

设备分类

Bluehood 使用多种信号对设备进行分类（按优先级顺序）：

BLE 服务 UUID - 最准确（心率 = 可穿戴设备，A2DP = 音频等）
设备名称模式 - “iPhone”、“Galaxy”、“AirPods”等
厂商 OUI 查询 - Apple、Samsung、Bose 等

随机化 MAC

现代设备会随机化其 MAC 地址以保护隐私。Bluehood：

检测随机化 MAC（本地管理位）
从主设备列表中隐藏它们（对追踪无用）
显示隐藏的随机化设备数量

模式分析

Bluehood 分析目击时间戳以检测模式：

一天中的时间：早晨、下午、傍晚、夜间
星期几：工作日、周末
频率：持续、每天、规律、偶尔、罕见

示例模式：“每天，傍晚（17:00-21:00）”、“工作日，早晨（08:00-12:00）”

设备关联

Bluehood 检测在可配置时间窗口内频繁同时出现的设备。这可以揭示：

同一人拥有的设备（手机 + 智能手表）
一起出行的人
共享时间表的设备

距离区域

基于 RSSI 信号强度，设备被分类到距离区域：

极近（> -50 dBm）：非常近，几米之内
近（-50 到 -60 dBm）：附近，同一房间
远（-60 到 -70 dBm）：较远，相邻房间
极远（< -70 dBm）：遥远，处于检测范围边缘

停留时间分析

通过分析目击之间的间隔来追踪设备在范围内停留的时间。可配置的间隔阈值（默认 15 分钟）决定何时开始新的“会话”。

Prometheus 指标

Bluehood 可以暴露指标以供 Prometheus 抓取。通过设置 BLUEHOOD_METRICS_PORT 环境变量或 --metrics-port CLI 标志来启用。

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via 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}"

故障排除

未找到设备

确保您的适配器支持 BLE（蓝牙 4.0+）并具有 Central 角色 — 较旧的适配器无法工作
确保蓝牙适配器已启用：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 已安装在主机上（而不仅仅是在容器中）
验证蓝牙服务正在运行：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），非阻塞厂商数据库修复（#37），双适配器扫描（#33），使用 rfkill 的稳健扫描恢复（#40）

许可证

MIT 许可证 - 详情请参阅 LICENSE。

免责声明

本工具仅供教育目的使用。在监控蓝牙设备时，请注意您所在司法管辖区的隐私法律。作者不对本软件的任何滥用负责。

由 Danny McClelland 创建

`PUID`	`1000`	容器用户的 UID — 使用绑定挂载时，设置为与您的主机用户匹配（`id -u`）
`PGID`	`1000`	容器用户的 GID — 使用绑定挂载时，设置为与您的主机组匹配（`id -g`）
`TZ`	UTC	容器时区（例如 `Europe/London`）
`BLUEHOOD_ADAPTER`	auto	用于 BLE 扫描的蓝牙适配器（例如 `hci0`）
`BLUEHOOD_CLASSIC_ADAPTER`	与 `BLUEHOOD_ADAPTER` 相同	用于经典蓝牙扫描的单独适配器（例如 `hci1`）。当设置为不同的适配器时，BLE 和经典扫描将并发运行。
`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`（禁用）	自动删除超过 N 天的目击记录以释放存储空间
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0`（禁用）	当 >0 时，清理整个陈旧设备（超过 `BLUEHOOD_PRUNE_DAYS` 且总目击次数少于 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	数据库中的唯一设备数（标签：`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