监视您本地社区的蓝牙活动
Bluetooth Neighborhood - 追踪您所在区域的 BLE 设备并分析流量模式。
警告：Alpha 软件
本项目处于早期开发阶段，尚未准备好用于生产环境。功能可能随时更改、中断或删除，恕不另行通知。使用风险自负。收集的数据应视为实验性质。
主仪表板，显示设备列表，支持筛选、搜索和实时统计
选项卡式配置页面 — 提醒、操作、分组和安全
Intel 页面，展示项目信息和功能概览
本项目灵感来源于 WhisperPair 漏洞 (CVE-2025-36911)，该漏洞凸显了蓝牙设备中的隐私风险。
我们身边始终有成千上万的蓝牙设备：手机、汽车、电视、耳机、助听器、送货车辆等等。Bluehood 展示了被动检测这些设备并观察其出现模式是多么简单。
只要有足够的数据，您可能能够：
这些元数据可以在不与设备进行任何主动交互的情况下，揭示出令人惊讶的个人信息。
Bluehood 是一个教育工具，旨在提高人们对蓝牙隐私的认识。 它只是一个周末项目，但其影响值得我们思考。
Bluehood 是一个蓝牙扫描器，能够：
? 查看）先决条件 — 仅限 Linux 主机
Bluehood 通过 BlueZ（Linux 蓝牙协议栈）与您的蓝牙适配器通信。BlueZ 必须在主机上安装并运行后才能启动容器 — Docker 镜像本身不包含 BlueZ。
# 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
sudo apt install bluez && sudo systemctl enable --now bluetooth）注意：较旧的适配器（蓝牙 2.x/3.x）不支持 BLE 扫描。如果您的适配器缺少 BLE 中央角色支持，您将看到：
No Bluetooth adapters with BLE 'central' role found。
注意：Docker 以特权模式运行并使用主机网络以访问蓝牙。这是 BLE 扫描所必需的。
Bluehood 需要一个 支持 BLE 的蓝牙适配器（蓝牙 4.0 或更高版本）并具备 中央 角色支持。较旧的蓝牙 2.x/3.x 适配器不支持 BLE 扫描，无法使用。
如果您的适配器不支持 BLE 中央角色，Bluehood 将退出并显示：
No Bluetooth adapters with BLE 'central' role found
您可以使用 bluetoothctl show 检查适配器能力，查看支持的角色中是否包含 central。
# 安装系统依赖（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 .
蓝牙扫描需要提升的权限。选择以下之一：
以 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
Bluehood 可在 macOS 上原生运行，无需 Docker。macOS 使用 CoreBluetooth 而非 BlueZ，这由 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 会提示您允许蓝牙访问。您必须授予此权限才能进行扫描。
# 启动并打开 Web 仪表板（默认端口 8080）
bluehood
# 指定不同端口
bluehood --port 9000
# 使用特定蓝牙适配器
bluehood --adapter hci1
# 分别为 BLE 和经典蓝牙使用不同适配器（并发扫描）
bluehood --adapter hci0 --classic-adapter hci1
# 列出可用适配器
bluehood --list-adapters
# 禁用 Web 仪表板（仅扫描）
bluehood --no-web
# 启用 Prometheus 指标导出器（端口 9199）
bluehood --metrics-port 9199
仪表板提供：
/settings#operations）从侧边栏启用截图模式，可在分享截图前模糊敏感数据：
AA:BB:XX:XX:XX:XX）Da********）Bluehood 可通过 ntfy.sh 发送推送通知，ntfy.sh 是一个免费、开源的通知服务。
bluehood-myname-alerts）数据存储在 ~/.local/share/bluehood/bluehood.db（SQLite）。
使用环境变量覆盖位置：
BLUEHOOD_DATA_DIR - 数据文件目录BLUEHOOD_DB_PATH - 数据库文件的直接路径注意：心跳和清理设置可以从 Web UI（设置 > 操作）或通过环境变量配置。GUI 值优先于环境变量。
Bluehood 使用多种信号对设备进行分类（按优先级顺序）：
现代设备为隐私而随机化其 MAC 地址。Bluehood：
Bluehood 分析目击时间戳以检测模式：
示例模式："每天，傍晚（5PM-9PM）"、"工作日，上午（8AM-12PM）"
Bluehood 检测在可配置的时间窗口内经常一起出现的设备。这可以揭示：
基于 RSSI 信号强度，设备被分类到邻近区域：
通过分析目击之间的间隔，追踪设备在范围内停留的时间。可配置的间隔阈值（默认 15 分钟）决定何时开始新的“会话”。
Bluehood 可以公开指标供 Prometheus 抓取。通过设置 BLUEHOOD_METRICS_PORT 环境变量或 --metrics-port CLI 标志启用。
# 通过环境变量
export BLUEHOOD_METRICS_PORT=9199
# 通过 CLI
bluehood --metrics-port 9199
指标服务地址为 http://host:9199/metrics。
项目中包含一个可供导入的 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}"
bluetoothctl power onbluehood --list-adaptersBLE 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
一般检查清单：
systemctl status bluetoothbluetoothctl list欢迎贡献！请通过 GitHub 提交 issue 或 PR。
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_METRICS_PORT | 禁用 | Prometheus 指标端口（例如 9199） |
BLUEHOOD_HEARTBEAT_URL | 禁用 | 发送心跳检查的 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 | 数据库中的唯一设备数（标签：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 | 版本信息 |