Bluehood

Bluetooth Neighborhood — отслеживайте BLE-устройства поблизости и анализируйте шаблоны трафика.

ВНИМАНИЕ: Альфа-версия ПО

Этот проект находится на ранней стадии разработки и не готов к использованию в production. Функции могут меняться, ломаться или удаляться без предупреждения. Используйте на свой риск. Собранные данные следует считать экспериментальными.

Скриншоты

Главная панель со списком устройств, фильтрацией, поиском и статистикой в реальном времени

Страница конфигурации с вкладками — Alerts, Operations, Groups и Security

Страница Intel с информацией о проекте и обзором возможностей

Зачем?

Этот проект был вдохновлён уязвимостью WhisperPair (CVE-2025-36911), которая высветила риски для приватности в Bluetooth-устройствах.

Тысячи Bluetooth-устройств окружают нас постоянно: телефоны, автомобили, телевизоры, наушники, слуховые аппараты, машины доставки и многое другое. Bluehood демонстрирует, насколько просто пассивно обнаруживать эти устройства и наблюдать закономерности их присутствия.

Имея достаточно данных, вы потенциально можете:

• Понять, в какое время кто-то обычно выгуливает собаку
• Определить, когда посетитель приходит в дом
• Выявить закономерности в повседневных routines на основе присутствия устройств

Эти метаданные могут раскрыть на удивление личную информацию без какого-либо активного взаимодействия с устройствами.

Bluehood — это образовательный инструмент для повышения осведомлённости о приватности Bluetooth. Это проект на выходные, но его последствия стоит обдумать.

Что это?

Bluehood — это Bluetooth-сканер, который:

• Непрерывно сканирует ближайшие Bluetooth-устройства (как BLE, так и Classic)
• Идентифицирует устройства по производителю (поиск по MAC-адресу) и UUID сервисов BLE
• Классифицирует устройства по категориям (телефоны, аудио, носимые устройства, IoT, транспорт и т.д.)
• Отслеживает шаблоны присутствия во времени с почасовыми/дневными тепловыми картами
• Отфильтровывает шум от рандомизированных MAC-адресов (устройства с ротацией приватности)
• Анализирует корреляции устройств, чтобы находить устройства, появляющиеся вместе
• Отправляет push-уведомления, когда отслеживаемые устройства появляются или уходят
• Предоставляет веб-панель для мониторинга и анализа

Возможности

Сканирование

• Двухрежимное сканирование: Bluetooth Low Energy (BLE) и Classic Bluetooth
• Поиск производителя по MAC-адресу (локальная база данных + онлайн API как fallback)
• Фингерпринтинг UUID сервисов BLE для точной классификации устройств
• Разбор класса Classic Bluetooth-устройств
• Фильтрация рандомизированных MAC (скрыты из основного представления)

Управление устройствами

• Отмечайте устройства как «Отслеживаемые» для отслеживания личных устройств
• Организуйте устройства в пользовательские группы
• Давайте устройствам пользовательские имена (рекламируемое имя остаётся видимым рядом)
• Переопределяйте обнаруженную классификацию любого устройства
• Добавляйте пользовательские заметки/теги к любому устройству
• Определение типа устройства (телефоны, аудио, носимые устройства, IoT, транспорт и т.д.)

Аналитика

• Визуализация 30-дневной временной шкалы присутствия
• График истории силы сигнала (RSSI) с данными за 7 дней
• Почасовые и дневные тепловые карты активности, показывающие, когда устройства активны
• Анализ шаблонов («Будни, вечера 17:00–21:00»)
• Анализ времени пребывания, показывающий общее время нахождения устройств в зоне действия
• Обнаружение корреляции устройств для поиска устройств, появляющихся вместе (совместное присутствие плюс синхронизированное прибытие/уход)
• Связывание по ротации MAC («Вероятно, одно и то же устройство») — эвристически связывает рандомизированные идентификаторы, которые сменяют друг друга во времени, имеют схожую силу сигнала и пингуются с похожей периодичностью
• Зоны близости (immediate, near, far, remote) на основе силы сигнала
• Поиск по MAC, производителю или имени
• Поиск по диапазону дат для исторических запросов

Уведомления (через ntfy)

• Push-уведомления на телефон/десктоп через ntfy.sh или самостоятельно размещённый сервер ntfy
• Уведомление при обнаружении новых устройств
• Уведомление при возвращении отслеживаемых устройств
• Уведомление при уходе отслеживаемых устройств
• Настраиваемые пороги для прибытия/ухода

Операции

• Heartbeat check-in — периодически отправляет POST-статус в сервис мониторинга доступности (например, Uptime Kuma, Healthchecks.io)
• Ротация хранилища — автоматически удаляет наблюдения старше настраиваемого количества дней; опционально ограничивает очистку целыми устаревшими устройствами, замеченными меньше минимального числа раз (отслеживаемые устройства никогда не удаляются)
• Оба параметра настраиваются из веб-интерфейса или через переменные окружения

Веб-интерфейс

• Переключение компактного/детального вида для разных предпочтений отображения
• Режим скриншота для обфускации MAC-адресов и имён для безопасного обмена
• Горячие клавиши для опытных пользователей (нажмите ? для просмотра)
• Экспорт CSV детальных данных устройств (MAC, производитель, идентификатор, тип, тип BT, класс устройства, флаги watched/ignored, первое/последнее появление, наблюдения, группа, UUID сервисов и заметки) — экспортирует весь отфильтрованный набор, а не только текущую страницу
• Группы устройств для организации связанных устройств
• Опциональная аутентификация для защиты доступа

Как?

Быстрый старт с Docker (рекомендуется)

Предварительные требования — только для Linux-хостов

Bluehood взаимодействует с вашим Bluetooth-адаптером через BlueZ, стек Bluetooth для Linux. BlueZ должен быть установлен и запущен на хосте перед запуском контейнера — сам Docker-образ его не включает.

root@kitploit:~

# 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

Веб-панель будет доступна по адресу http://localhost:8080

Требования Docker

• Docker и Docker Compose
• Linux-хост с BLE-совместимым Bluetooth-адаптером (Bluetooth 4.0+), поддерживающим роль Central
• BlueZ, установленный и запущенный на хосте (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Примечание: Старые адаптеры (Bluetooth 2.x/3.x) не поддерживают BLE-сканирование. Если ваш адаптер не поддерживает роль BLE Central, вы увидите: No Bluetooth adapters with BLE 'central' role found.

Примечание: Docker работает в привилегированном режиме с host networking для доступа к Bluetooth. Это необходимо для BLE-сканирования.

Переменные окружения Docker

Требования к Bluetooth-адаптеру

Bluehood требует BLE-совместимый Bluetooth-адаптер (Bluetooth 4.0 или новее) с поддержкой роли Central. Старые адаптеры Bluetooth 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 .

Разрешения Bluetooth

Bluetooth-сканирование требует повышенных привилегий. Выберите один из вариантов:

1. Запуск от root (проще всего):

   root@kitploit:~

   sudo bluehood
   

2. Предоставление capabilities Python:

   root@kitploit:~

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

3. Использование systemd-сервиса (рекомендуется для постоянной работы):

   root@kitploit:~

   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

Веб-панель будет доступна по адресу http://localhost:8080

Примечание: При первом запуске macOS запросит разрешение на доступ к Bluetooth. Вы должны предоставить это разрешение, чтобы сканирование работало.

Использование

# 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

Веб-панель

Панель предоставляет:

• Список устройств с иконками типов, производителем, MAC, именем, наблюдениями, последним появлением
• Фильтры устройств по типу (телефоны, аудио, IoT и т.д.) и статусу отслеживания
• Поиск по MAC, производителю или имени
• Поиск по диапазону дат для поиска устройств, замеченных в определённом временном окне
• Страница настроек с вкладками — Alerts, Operations, Groups и Security (прямая ссылка через hash, например /settings#operations)
• Модальное окно деталей устройства с:
  • Фингерпринтами сервисов BLE
  • Почасовыми/дневными тепловыми картами активности
  • 30-дневной временной шкалой присутствия
  • Графиком истории силы сигнала (RSSI)
  • Анализом шаблонов
  • Статистикой времени пребывания
  • Списком коррелированных устройств
  • Списком вероятно одинаковых устройств (ротация MAC)
  • Индикатором зоны близости
  • Полем заметок оператора
  • Назначением группы

Горячие клавиши

Режим скриншота

Включите режим скриншота на боковой панели, чтобы обфусцировать конфиденциальные данные перед публикацией скриншотов:

• MAC-адреса показывают только первые 2 октета (например, AA:BB:XX:XX:XX:XX)
• Понятные имена показывают только первые 2 символа (например, Da********)
• Экспорт CSV также учитывает режим скриншота

Push-уведомления

Bluehood может отправлять push-уведомления через 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 — прямой путь к файлу базы данных

Примечание: Настройки heartbeat и очистки можно задать из веб-интерфейса (Settings > Operations) или через переменные окружения. Значения GUI имеют приоритет над переменными окружения.

Как это работает

Классификация устройств

Bluehood классифицирует устройства, используя несколько сигналов (в порядке приоритета):

1. UUID сервисов BLE — наиболее точно (Heart Rate = носимое устройство, A2DP = аудио и т.д.)
2. Шаблоны имён устройств — «iPhone», «Galaxy», «AirPods» и т.д.
3. Поиск производителя по OUI — Apple, Samsung, Bose и т.д.

Рандомизированные MAC-адреса

Современные устройства рандомизируют свои MAC-адреса для приватности. Bluehood:

• Обнаруживает рандомизированные MAC (бит локального администрирования)
• Скрывает их из основного списка устройств (бесполезны для отслеживания)
• Показывает количество скрытых рандомизированных устройств

Анализ шаблонов

Bluehood анализирует временные метки наблюдений для обнаружения шаблонов:

• Время суток: Утро, День, Вечер, Ночь
• День недели: Будни, Выходные
• Частота: Постоянно, Ежедневно, Регулярно, Иногда, Редко

Примеры шаблонов: «Ежедневно, вечера (17:00–21:00)», «Будни, утро (8:00–12:00)»

Корреляция устройств

Bluehood обнаруживает устройства, которые часто появляются вместе в настраиваемом временном окне. Это может выявить:

• Устройства, принадлежащие одному человеку (телефон + смарт-часы)
• Людей, которые путешествуют вместе
• Устройства, имеющие общее расписание

Зоны близости

На основе силы сигнала RSSI устройства классифицируются по зонам близости:

• Immediate (> -50 dBm): Очень близко, в пределах нескольких метров
• Near (-50 до -60 dBm): Рядом, в одной комнате
• Far (-60 до -70 dBm): Дальше, в соседних комнатах
• Remote (< -70 dBm): Далеко, на границе диапазона обнаружения

Анализ времени пребывания

Отслеживает, как долго устройства находятся в зоне действия, анализируя промежутки между наблюдениями. Настраиваемый порог разрыва (по умолчанию 15 минут) определяет, когда начинается новая «сессия».

Метрики Prometheus

Bluehood может предоставлять метрики для сбора Prometheus. Включите, установив переменную окружения BLUEHOOD_METRICS_PORT или флаг CLI --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Метрики доступны по адресу http://host:9199/metrics.

Доступные метрики

Панель Grafana

Готовая к импорту панель Grafana включена в grafana/bluehood-dashboard.json. Импортируйте её через UI Grafana (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 (Bluetooth 4.0+) с ролью Central — старые адаптеры не будут работать
• Убедитесь, что Bluetooth-адаптер включён: 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 установлен на хосте (не только в контейнере)
• Проверьте, что служба Bluetooth запущена: systemctl status bluetooth
• Убедитесь, что ваш адаптер виден: bluetoothctl list

Участие в разработке

Вклад приветствуется! Пожалуйста, откройте issue или PR на GitHub.

Участники

• @martinh2011 (Martin Hüser) — улучшения кэша производителей MAC
• @hatedabamboo (Kirill Solovei) — поддержка светлой темы
• @krnltrp — улучшения веб-интерфейса
• @jacobpretorius (Jacob Pretorius) — исправление JS экспорта CSV (#14), открытие настроек по клику (#16)
• @unqualifiedkoala — документирование требований к BLE-адаптеру
• @dazzag24 — сообщил о проблеме формата адреса macOS
• @floese (W.A.Flozart) — исправление двойного клика в Firefox (#29)
• @GeiserX (Sergio Fernández) — экспортёр метрик Prometheus (#35), исправление неблокирующей БД производителей (#37), сканирование с двумя адаптерами (#33), надёжное восстановление сканирования с rfkill (#40)

Лицензия

MIT License — подробности см. в LICENSE.

Отказ от ответственности

Этот инструмент предназначен только для образовательных целей. Соблюдайте законы о приватности в вашей юрисдикции при мониторинге Bluetooth-устройств. Автор не несёт ответственности за любое неправомерное использование этого программного обеспечения.

Создано Danny McClelland