Bluehood

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

ВНИМАНИЕ: Альфа-программное обеспечение

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

Скриншоты

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

Страница с вкладками конфигурации — Уведомления, Операции, Группы и Безопасность

Страница «О программе» с информацией о проекте и обзором возможностей

Зачем?

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

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

При достаточном количестве данных можно потенциально:

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

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

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

Что?

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

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

Функции

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

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

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

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

Аналитика

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

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

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

Операции

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

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

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

Как?

Быстрый старт с 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

# Создайте docker-compose.yml или скачайте его из этого репозитория
# Затем запустите с Docker Compose
docker compose up -d

# Просмотр логов
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 запускается в привилегированном режиме с сетевым доступом хоста для доступа к 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)

# Установка системных зависимостей (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 .

Права для Bluetooth

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

1. Запуск от root (самый простой):

   root@kitploit:~

   sudo bluehood
   

2. Назначение возможностей 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.

# Клонирование репозитория
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

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

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

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

# Запуск с веб-панелью (порт по умолчанию 8080)
bluehood

# Указание другого порта
bluehood --port 9000

# Использование конкретного Bluetooth-адаптера
bluehood --adapter hci1

# Использование отдельных адаптеров для BLE и Classic сканирования (одновременно)
bluehood --adapter hci0 --classic-adapter hci1

# Список доступных адаптеров
bluehood --list-adapters

# Отключение веб-панели (только сканирование)
bluehood --no-web

# Включение экспортера метрик Prometheus на порту 9199
bluehood --metrics-port 9199

Веб-панель

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

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

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

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

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

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

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

Bluehood может отправлять push-уведомления через ntfy.sh — бесплатный сервис уведомлений с открытым исходным кодом.

1. Создайте тему на ntfy.sh (например, bluehood-myname-alerts)
2. Подпишитесь на тему на своём телефоне через приложение ntfy
3. В настройках Bluehood введите имя вашей темы и включите уведомления
4. Настройте, какие события вызывают уведомления:
   • Обнаружено новое устройство
   • Отслеживаемое устройство вернулось (после отсутствия)
   • Отслеживаемое устройство ушло (не замечено в течение X минут)

Хранение данных

Данные хранятся в ~/.local/share/bluehood/bluehood.db (SQLite).

Переопределить расположение можно с помощью переменных окружения:

• BLUEHOOD_DATA_DIR — Директория для файлов данных
• BLUEHOOD_DB_PATH — Прямой путь к файлу базы данных

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

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

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

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

1. BLE-сервисные UUID — Самые точные (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 устройства классифицируются по зонам близости:

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

Анализ времени нахождения

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

Prometheus метрики

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

# Через переменную окружения
export BLUEHOOD_METRICS_PORT=9199

# Через CLI
bluehood --metrics-port 9199

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

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

Grafana Dashboard

Готовая к импорту панель Grafana находится в файле grafana/bluehood-dashboard.json. Импортируйте её через интерфейс Grafana (Панели > Импорт) или через 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 для подробностей.

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

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

Создано Danny McClelland