Bluehood

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

---

警告：Alpha 软件

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

---

截图

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

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

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

为什么？

本项目的灵感来自 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 环境变量

变量	默认值	描述
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）

# 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 身份运行（最简单）：

   sudo bluehood
   

2. 为 Python 授予能力：

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

3. 使用 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 轮换）列表
  • 距离区域指示器
  • 操作员备注字段
  • 分组分配

键盘快捷键

按键	操作
/	聚焦搜索栏
r	刷新设备列表
c	切换紧凑视图
w	切换所选设备的监视状态
Esc	关闭模态框
?	显示键盘快捷键

截图模式

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

• 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 值优先于环境变量。

工作原理

设备分类