监视您本地社区的蓝牙活动
# Bluehood
**蓝牙邻里** - 追踪您周围的 BLE 设备并分析流量模式。
[](https://buymeacoffee.com/d3hkz6gwle)
---
> **警告:Alpha 软件**
>
> 本项目处于早期开发阶段,**尚未准备好用于生产环境**。功能可能会在无通知的情况下变更、损坏或被移除。使用风险自负。收集的数据应视为实验性数据。
---
## 截图

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

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

*情报页面,包含项目信息和功能概览*
## 为什么?
本项目的灵感来自 [WhisperPair 漏洞](https://whisperpair.eu/)([CVE-2025-36911](https://nvd.nist.gov/vuln/detail/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 镜像本身不包含它。
>
> ```bash
> # 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`
```bash
# 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 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `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 次),而不是仅修剪旧的目击记录行;被监视的设备永远不会被清理 |
### 蓝牙适配器要求
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)
```bash
# 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 .
```
#### 蓝牙权限
蓝牙扫描需要提升的权限。选择以下之一:
1. **以 root 身份运行**(最简单):
```bash
sudo bluehood
```
2. **为 Python 授予能力**:
```bash
sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
bluehood
```
3. **使用 systemd 服务**(推荐用于常开运行):
```bash
sudo cp bluehood.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bluehood
```
### macOS
Bluehood 可以在 macOS 上原生运行,无需 Docker。macOS 使用 CoreBluetooth 而不是 BlueZ,`bleak` 库会自动处理这一点。
```bash
# 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 会提示您允许蓝牙访问。您必须授予此权限,扫描才能正常工作。
## 用法
```bash
# 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 轮换)列表
- 距离区域指示器
- 操作员备注字段
- 分组分配
### 键盘快捷键
| 按键 | 操作 |
|-----|--------|
| `/` | 聚焦搜索栏 |
| `r` | 刷新设备列表 |
| `c` | 切换紧凑视图 |
| `w` | 切换所选设备的监视状态 |
| `Esc` | 关闭模态框 |
| `?` | 显示键盘快捷键 |
### 截图模式
从侧边栏启用截图模式,以便在分享截图前混淆敏感数据:
- MAC 地址仅显示前 2 个八位字节(例如 `AA:BB:XX:XX:XX:XX`)
- 友好名称仅显示前 2 个字符(例如 `Da********`)
- CSV 导出也遵循截图模式
## 推送通知
Bluehood 可以通过 [ntfy](https://ntfy.sh) 发送推送通知,这是一个免费的开源通知服务。您可以使用公共 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** - 最准确(心率 = 可穿戴设备,A2DP = 音频等)
2. **设备名称模式** - “iPhone”、“Galaxy”、“AirPods”等
3. **厂商 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 标志来启用。
```bash
# Via environment variable
export BLUEHOOD_METRICS_PORT=9199
# Via CLI
bluehood --metrics-port 9199
```
指标在 `http://host:9199/metrics` 上提供。
### 可用指标
| 指标 | 类型 | 描述 |
|--------|------|-------------|
| `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 | 版本信息 |
### Grafana 仪表板
一个可直接导入的 Grafana 仪表板包含在 [`grafana/bluehood-dashboard.json`](https://github.com/dannymcc/bluehood/blob/master/grafana/bluehood-dashboard.json)。通过 Grafana UI(Dashboards > Import)或 API 导入:
```bash
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 未在主机上安装或未运行。修复:
```bash
sudo apt install bluez # Debian/Ubuntu
sudo systemctl enable --now bluetooth
docker compose restart
```
**通用检查清单:**
- 确保 BlueZ 已安装在**主机**上(而不仅仅是在容器中)
- 验证蓝牙服务正在运行:`systemctl status bluetooth`
- 确认您的适配器可见:`bluetoothctl list`
## 贡献
欢迎贡献!请在 GitHub 上提交 issue 或 PR。
### 贡献者
- [@martinh2011](https://github.com/martinh2011)(Martin Hüser) - MAC 厂商缓存改进
- [@hatedabamboo](https://github.com/hatedabamboo)(Kirill Solovei) - 浅色主题支持
- [@krnltrp](https://github.com/krnltrp) - Web UI 增强
- [@jacobpretorius](https://github.com/jacobpretorius)(Jacob Pretorius) - CSV 导出 JS 修复(#14),点击打开设置(#16)
- [@unqualifiedkoala](https://github.com/unqualifiedkoala) - 记录了 BLE 适配器要求
- [@dazzag24](https://github.com/dazzag24) - 报告了 macOS 地址格式问题
- [@floese](https://github.com/floese)(W.A.Flozart) - Firefox 双击修复(#29)
- [@GeiserX](https://github.com/GeiserX)(Sergio Fernández) - Prometheus 指标导出器(#35),非阻塞厂商数据库修复(#37),双适配器扫描(#33),使用 rfkill 的稳健扫描恢复(#40)
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](https://github.com/dannymcc/bluehood/blob/master/LICENSE)。
## 免责声明
本工具仅供教育目的使用。在监控蓝牙设备时,请注意您所在司法管辖区的隐私法律。作者不对本软件的任何滥用负责。
---
由 [Danny McClelland](https://github.com/dannymcc) 创建