Отслеживайте активность Bluetooth в вашем районе
# Bluehood
**Bluetooth Neighborhood** — отслеживайте BLE-устройства поблизости и анализируйте шаблоны трафика.
[](https://buymeacoffee.com/d3hkz6gwle)
---
> **ВНИМАНИЕ: Альфа-версия ПО**
>
> Этот проект находится на ранней стадии разработки и **не готов к использованию в production**. Функции могут меняться, ломаться или удаляться без предупреждения. Используйте на свой риск. Собранные данные следует считать экспериментальными.
---
## Скриншоты
*Главная панель со списком устройств, фильтрацией, поиском и статистикой в реальном времени*
*Страница конфигурации с вкладками — Alerts, Operations, Groups и Security*
*Страница Intel с информацией о проекте и обзором возможностей*
## Зачем?
Этот проект был вдохновлён [уязвимостью WhisperPair](https://whisperpair.eu/) ([CVE-2025-36911](https://nvd.nist.gov/vuln/detail/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-образ его не включает.
>
> ```bash
> # 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`
```bash
# 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
| Переменная | По умолчанию | Описание |
|----------|---------|-------------|
| `PUID` | `1000` | UID пользователя контейнера — установите в соответствии с вашим пользователем хоста (`id -u`) при использовании bind mounts |
| `PGID` | `1000` | GID пользователя контейнера — установите в соответствии с вашей группой хоста (`id -g`) при использовании bind mounts |
| `TZ` | UTC | Часовой пояс контейнера (например, `Europe/London`) |
| `BLUEHOOD_ADAPTER` | auto | Bluetooth-адаптер для BLE-сканирования (например, `hci0`) |
| `BLUEHOOD_CLASSIC_ADAPTER` | same as `BLUEHOOD_ADAPTER` | Отдельный адаптер для сканирования classic Bluetooth (например, `hci1`). Если установлен другой адаптер, BLE- и classic-сканирование выполняются одновременно. |
| `BLUEHOOD_DATA_DIR` | `/data` | Каталог хранения базы данных |
| `BLUEHOOD_PORT` | `8080` | Порт веб-панели. Контейнер использует host networking, поэтому измените это значение (а не маппинг портов), если 8080 занят |
| `BLUEHOOD_NTFY_SERVER` | `https://ntfy.sh` | Базовый URL сервера ntfy для push-уведомлений; укажите самостоятельно размещённый экземпляр. Значение, сохранённое на странице Settings, имеет приоритет |
| `BLUEHOOD_METRICS_PORT` | disabled | Порт метрик Prometheus (например, `9199`) |
| `BLUEHOOD_HEARTBEAT_URL` | disabled | URL для POST heartbeat check-in (например, push URL healthchecks.io или uptime-kuma) |
| `BLUEHOOD_HEARTBEAT_INTERVAL` | `300` | Секунды между heartbeat check-in |
| `BLUEHOOD_PRUNE_DAYS` | `0` (disabled) | Автоудаление наблюдений старше N дней для освобождения хранилища |
| `BLUEHOOD_PRUNE_MIN_SIGHTINGS` | `0` (disabled) | Если >0, удалять целые устаревшие устройства (старше `BLUEHOOD_PRUNE_DAYS` и с общим числом наблюдений меньше N) вместо простой обрезки старых строк наблюдений; отслеживаемые устройства никогда не удаляются |
### Требования к 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)
```bash
# 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** (проще всего):
```bash
sudo bluehood
```
2. **Предоставление capabilities Python**:
```bash
sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
bluehood
```
3. **Использование systemd-сервиса** (рекомендуется для постоянной работы):
```bash
sudo cp bluehood.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bluehood
```
### macOS
Bluehood работает нативно на macOS без Docker. macOS использует CoreBluetooth вместо BlueZ, что автоматически обрабатывается библиотекой `bleak`.
```bash
# 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. Вы должны предоставить это разрешение, чтобы сканирование работало.
## Использование
```bash
# 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)
- Индикатором зоны близости
- Полем заметок оператора
- Назначением группы
### Горячие клавиши
| Клавиша | Действие |
|-----|--------|
| `/` | Фокус на строке поиска |
| `r` | Обновить список устройств |
| `c` | Переключить компактный вид |
| `w` | Переключить отслеживание выбранного устройства |
| `Esc` | Закрыть модальное окно |
| `?` | Показать горячие клавиши |
### Режим скриншота
Включите режим скриншота на боковой панели, чтобы обфусцировать конфиденциальные данные перед публикацией скриншотов:
- MAC-адреса показывают только первые 2 октета (например, `AA:BB:XX:XX:XX:XX`)
- Понятные имена показывают только первые 2 символа (например, `Da********`)
- Экспорт CSV также учитывает режим скриншота
## Push-уведомления
Bluehood может отправлять push-уведомления через [ntfy](https://ntfy.sh) — бесплатный сервис уведомлений с открытым исходным кодом. Вы можете использовать публичный сервер 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`.
```bash
# Via environment variable
export BLUEHOOD_METRICS_PORT=9199
# Via CLI
bluehood --metrics-port 9199
```
Метрики доступны по адресу `http://host:9199/metrics`.
### Доступные метрики
| Метрика | Тип | Описание |
|--------|------|-------------|
| `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 | Распределение RSSI BLE-устройств |
| `bluehood_build_info` | Info | Информация о версии |
### Панель Grafana
Готовая к импорту панель Grafana включена в [`grafana/bluehood-dashboard.json`](https://github.com/dannymcc/bluehood/blob/master/grafana/bluehood-dashboard.json). Импортируйте её через UI Grafana (Dashboards > Import) или API:
```bash
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 не установлен или не запущен на хосте. Исправление:
```bash
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](https://github.com/martinh2011) (Martin Hüser) — улучшения кэша производителей MAC
- [@hatedabamboo](https://github.com/hatedabamboo) (Kirill Solovei) — поддержка светлой темы
- [@krnltrp](https://github.com/krnltrp) — улучшения веб-интерфейса
- [@jacobpretorius](https://github.com/jacobpretorius) (Jacob Pretorius) — исправление JS экспорта CSV (#14), открытие настроек по клику (#16)
- [@unqualifiedkoala](https://github.com/unqualifiedkoala) — документирование требований к BLE-адаптеру
- [@dazzag24](https://github.com/dazzag24) — сообщил о проблеме формата адреса macOS
- [@floese](https://github.com/floese) (W.A.Flozart) — исправление двойного клика в Firefox (#29)
- [@GeiserX](https://github.com/GeiserX) (Sergio Fernández) — экспортёр метрик Prometheus (#35), исправление неблокирующей БД производителей (#37), сканирование с двумя адаптерами (#33), надёжное восстановление сканирования с rfkill (#40)
## Лицензия
MIT License — подробности см. в [LICENSE](https://github.com/dannymcc/bluehood/blob/master/LICENSE).
## Отказ от ответственности
Этот инструмент предназначен только для образовательных целей. Соблюдайте законы о приватности в вашей юрисдикции при мониторинге Bluetooth-устройств. Автор не несёт ответственности за любое неправомерное использование этого программного обеспечения.
---
Создано [Danny McClelland](https://github.com/dannymcc)