返回更新列表
新发布Sep 14, 2026

bluehood v0.8.0

监视您本地社区的蓝牙活动

分享

Bluehood

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

"Buy Me A Coffee"

警告：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 环境变量

变量默认值描述
PUID1000容器用户的 UID — 使用绑定挂载时，设置为与您的主机用户匹配（id -u）
PGID1000容器用户的 GID — 使用绑定挂载时，设置为与您的主机组匹配（id -g）
TZUTC容器时区（例如 Europe/London）
BLUEHOOD_ADAPTERauto用于 BLE 扫描的蓝牙适配器（例如 hci0）
BLUEHOOD_CLASSIC_ADAPTER与 BLUEHOOD_ADAPTER 相同用于经典蓝牙扫描的单独适配器（例如 hci1）。当设置为不同的适配器时，BLE 和经典扫描将并发运行。
BLUEHOOD_DATA_DIR/data数据库存储目录
BLUEHOOD_PORT8080Web 仪表板端口。容器使用主机网络，因此如果 8080 被占用，请更改此值（而不是端口映射）
BLUEHOOD_NTFY_SERVERhttps://ntfy.sh用于推送通知的 ntfy 服务器基础 URL；将其指向自托管实例。设置页面中保存的值优先
BLUEHOOD_METRICS_PORTdisabledPrometheus 指标端口（例如 9199）
BLUEHOOD_HEARTBEAT_URLdisabled用于 POST 心跳签到的 URL（例如 healthchecks.io 或 uptime-kuma 推送 URL）
BLUEHOOD_HEARTBEAT_INTERVAL300心跳签到之间的秒数
BLUEHOOD_PRUNE_DAYS0（禁用）自动删除超过 N 天的目击记录以释放存储空间
BLUEHOOD_PRUNE_MIN_SIGHTINGS0（禁用）当 >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 值优先于环境变量。

工作原理

设备分类

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 标志来启用。

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

指标在 http://host:9199/metrics 上提供。

可用指标

指标类型描述
bluehood_scans_totalCounter完成的扫描周期总数
bluehood_scan_errors_totalCounter扫描错误（标签：scan_type）
bluehood_sightings_totalCounter记录的设备目击总数
bluehood_new_devices_totalCounter发现的新唯一设备数
bluehood_last_scan_devicesGauge上次扫描中的设备数（标签：scan_type）
bluehood_devices_totalGauge数据库中的唯一设备数（标签：bt_type）
bluehood_devices_activeGauge过去 5 分钟内出现的设备数
bluehood_devices_watchedGauge被监视设备数量
bluehood_devices_ignoredGauge被忽略设备数量
bluehood_scan_duration_secondsHistogram扫描周期持续时间
bluehood_device_rssi_dbmHistogramBLE 设备的 RSSI 分布
bluehood_build_infoInfo版本信息

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 创建

阅读更多

分类

OSINT (开源情报)侦察蓝牙安全物联网安全网络映射信息收集无线安全隐私保护威胁情报学习与教育异常检测