Bluehood

Bluetooth Neighborhood - Rastrea dispositivos BLE en tu zona y analiza patrones de tráfico.

ADVERTENCIA: Software en fase alfa

Este proyecto está en desarrollo temprano y no está listo para uso en producción. Las funciones pueden cambiar, romperse o eliminarse sin previo aviso. Úsalo bajo tu propio riesgo. Los datos recopilados deben tratarse como experimentales.

Capturas de pantalla

Dashboard Panel principal que muestra la lista de dispositivos con filtrado, búsqueda y estadísticas en tiempo real

Settings Página de configuración con pestañas — Alertas, Operaciones, Grupos y Seguridad

About Página de información con detalles del proyecto y resumen de capacidades

¿Por qué?

Este proyecto se inspiró en la vulnerabilidad WhisperPair (CVE-2025-36911), que puso de manifiesto los riesgos para la privacidad en los dispositivos Bluetooth.

Miles de dispositivos Bluetooth nos rodean en todo momento: teléfonos, coches, televisores, auriculares, audífonos, vehículos de reparto y más. Bluehood demuestra lo sencillo que es detectar estos dispositivos de forma pasiva y observar patrones en su presencia.

Con suficientes datos, podrías potencialmente:

Saber a qué hora suele pasear alguien a su perro
Detectar cuándo llega un visitante a una casa
Identificar patrones en las rutinas diarias según la presencia de dispositivos

Estos metadatos pueden revelar información sorprendentemente personal sin ninguna interacción activa con los dispositivos.

Bluehood es una herramienta educativa para concienciar sobre la privacidad Bluetooth. Es un proyecto de fin de semana, pero las implicaciones merecen reflexión.

¿Qué es?

Bluehood es un escáner Bluetooth que:

Escanea continuamente dispositivos Bluetooth cercanos (tanto BLE como Classic)
Identifica dispositivos por fabricante (búsqueda por dirección MAC) y UUIDs de servicio BLE
Clasifica dispositivos en categorías (teléfonos, audio, wearables, IoT, vehículos, etc.)
Rastrea patrones de presencia a lo largo del tiempo con mapas de calor horarios/diarios
Filtra el ruido de direcciones MAC aleatorizadas (dispositivos con rotación de privacidad)
Analiza correlaciones entre dispositivos para encontrar dispositivos que aparecen juntos
Envía notificaciones push cuando los dispositivos vigilados llegan o se van
Proporciona un panel web para monitorización y análisis

Características

Escaneo

Escaneo de doble modo: Bluetooth Low Energy (BLE) y Bluetooth Classic
Búsqueda de fabricante por dirección MAC (base de datos local + API en línea como respaldo)
Huella de UUID de servicio BLE para una clasificación precisa de dispositivos
Análisis de clase de dispositivo Bluetooth Classic
Filtrado de MAC aleatorizadas (ocultas de la vista principal)

Gestión de dispositivos

Marcar dispositivos como "Vigilados" para rastrear dispositivos personales
Organizar dispositivos en grupos personalizados
Asignar un nombre personalizado a los dispositivos (el nombre anunciado permanece visible junto a él)
Anular la clasificación detectada de cualquier dispositivo
Añadir notas/etiquetas personalizadas a cualquier dispositivo
Detección del tipo de dispositivo (teléfonos, audio, wearables, IoT, vehículos, etc.)

Analíticas

Visualización de línea temporal de presencia de 30 días
Gráfico de historial de intensidad de señal (RSSI) con datos de 7 días
Mapas de calor de actividad horaria y diaria que muestran cuándo están activos los dispositivos
Análisis de patrones ("Días laborables, tardes 17:00-21:00")
Análisis de tiempo de permanencia que muestra el tiempo total que los dispositivos pasan en rango
Detección de correlación entre dispositivos para encontrar dispositivos que aparecen juntos (co-presencia más llegada/salida sincronizada)
Vinculación por rotación de MAC ("Probablemente el mismo dispositivo") — vincula heurísticamente identificadores aleatorizados que se turnan en el tiempo, comparten una intensidad de señal similar y emiten a un ritmo similar
Zonas de proximidad (inmediata, cercana, lejana, remota) según la intensidad de señal
Búsqueda por MAC, fabricante o nombre
Búsqueda por rango de fechas para consultas históricas

Notificaciones (vía ntfy)

Notificaciones push a tu teléfono/escritorio a través de ntfy.sh o un servidor ntfy autoalojado
Notificar cuando se detectan nuevos dispositivos
Notificar cuando regresan dispositivos vigilados
Notificar cuando se van dispositivos vigilados
Umbrales configurables para llegada/salida

Operaciones

Check-in de latido — envía periódicamente el estado mediante POST a un servicio de monitorización de disponibilidad (p. ej., Uptime Kuma, Healthchecks.io)
Rotación de almacenamiento — elimina automáticamente avistamientos más antiguos que un número configurable de días; opcionalmente restringe la eliminación a dispositivos obsoletos completos vistos menos de un número mínimo de veces (los dispositivos vigilados nunca se eliminan)
Ambos configurables desde la interfaz web o mediante variables de entorno

Interfaz web

Alternancia de vista compacta/detallada para diferentes preferencias de visualización
Modo captura de pantalla para ofuscar MACs y nombres para compartir de forma segura
Atajos de teclado para usuarios avanzados (pulsa ? para verlos)
Exportación CSV de datos detallados de dispositivos (MAC, fabricante, identificador, tipo, tipo BT, clase de dispositivo, indicadores de vigilado/ignorado, primera/última vez visto, avistamientos, grupo, UUIDs de servicio y notas) — exporta todo el conjunto filtrado, no solo la página actual
Grupos de dispositivos para organizar dispositivos relacionados
Autenticación opcional para asegurar el acceso

¿Cómo?

Inicio rápido con Docker (Recomendado)

Requisitos previos — solo hosts Linux

Bluehood se comunica con tu adaptador Bluetooth a través de BlueZ, la pila Bluetooth de Linux. BlueZ debe estar instalado y en ejecución en el host antes de iniciar el contenedor — la imagen Docker en sí no lo incluye.
# Debian / Ubuntu (incluido Ubuntu Server)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth
Sin BlueZ en el host verás un error como: 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

La imagen Docker está disponible en GitHub Container Registry:

ghcr.io/dannymcc/bluehood:latest

El panel web estará disponible en http://localhost:8080

Requisitos de Docker

Docker y Docker Compose
Host Linux con un adaptador Bluetooth compatible con BLE (Bluetooth 4.0+) que soporte el rol Central
BlueZ instalado y en ejecución en el host (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Nota: Los adaptadores más antiguos (Bluetooth 2.x/3.x) no soportan el escaneo BLE. Si tu adaptador carece de soporte para el rol BLE 'central', verás: No Bluetooth adapters with BLE 'central' role found.

Nota: Docker se ejecuta en modo privilegiado con red de host para el acceso a Bluetooth. Esto es necesario para el escaneo BLE.

Variables de entorno de Docker

Requisitos del adaptador Bluetooth

Bluehood requiere un adaptador Bluetooth compatible con BLE (Bluetooth 4.0 o posterior) con soporte para el rol Central. Los adaptadores Bluetooth 2.x/3.x más antiguos no soportan el escaneo BLE y no funcionarán.

Si tu adaptador no soporta el rol BLE Central, Bluehood saldrá con:

No Bluetooth adapters with BLE 'central' role found

Puedes comprobar las capacidades de tu adaptador con bluetoothctl show y buscar central en los roles soportados.

Instalación manual (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 .

Permisos de Bluetooth

El escaneo Bluetooth requiere privilegios elevados. Elige uno:

Ejecutar como root (lo más sencillo):
```
sudo bluehood
```

Conceder capacidades a Python:

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

Usar servicio systemd (recomendado para siempre activo):

sudo cp bluehood.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bluehood

macOS

Bluehood funciona de forma nativa en macOS sin Docker. macOS usa CoreBluetooth en lugar de BlueZ, lo cual es gestionado automáticamente por la librería 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

El panel web estará disponible en http://localhost:8080

Nota: En la primera ejecución, macOS te pedirá que permitas el acceso a Bluetooth. Debes conceder este permiso para que el escaneo funcione.

Uso

# 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

Panel web

El panel proporciona:

Lista de dispositivos con iconos de tipo, fabricante, MAC, nombre, avistamientos, última vez visto
Filtros de dispositivos por tipo (teléfonos, audio, IoT, etc.) y estado de vigilancia
Búsqueda por MAC, fabricante o nombre
Búsqueda por rango de fechas para encontrar dispositivos vistos en una ventana de tiempo específica
Página de configuración con pestañas — Alertas, Operaciones, Grupos y Seguridad (enlace directo vía hash, p. ej. /settings#operations)
Modal de detalles del dispositivo con:
- Huellas de servicio BLE
- Mapas de calor de actividad horaria/diaria
- Línea temporal de presencia de 30 días
- Gráfico de historial de intensidad de señal (RSSI)
- Análisis de patrones
- Estadísticas de tiempo de permanencia
- Lista de dispositivos correlacionados
- Lista de probables mismos dispositivos (rotación de MAC)
- Indicador de zona de proximidad
- Campo de notas del operador
- Asignación de grupo

Atajos de teclado

Modo captura de pantalla

Activa el modo captura de pantalla desde la barra lateral para ofuscar datos sensibles antes de compartir capturas:

Las direcciones MAC muestran solo los primeros 2 octetos (p. ej., AA:BB:XX:XX:XX:XX)
Los nombres amigables muestran solo los primeros 2 caracteres (p. ej., Da********)
Las exportaciones CSV también respetan el modo captura de pantalla

Notificaciones push

Bluehood puede enviar notificaciones push a través de ntfy, un servicio de notificaciones gratuito y de código abierto. Puedes usar el servidor público ntfy.sh o tu propia instancia autoalojada.

Crea un tema en ntfy.sh (p. ej., bluehood-myname-alerts), o en tu propio servidor ntfy
Suscríbete al tema en tu teléfono usando la app ntfy
En la configuración de Bluehood, introduce la URL del servidor (por defecto https://ntfy.sh), el nombre de tu tema y un token de acceso si tu servidor lo requiere, luego habilita las notificaciones
Configura qué eventos activan notificaciones:
- Nuevo dispositivo detectado
- Dispositivo vigilado regresa (tras estar ausente)
- Dispositivo vigilado se va (no visto durante X minutos)

Almacenamiento de datos

Los datos se almacenan en ~/.local/share/bluehood/bluehood.db (SQLite).

Anula la ubicación con variables de entorno:

BLUEHOOD_DATA_DIR - Directorio para archivos de datos
BLUEHOOD_DB_PATH - Ruta directa al archivo de base de datos

Nota: La configuración de latido y eliminación se puede configurar desde la interfaz web (Configuración > Operaciones) o mediante variables de entorno. Los valores de la GUI tienen prioridad sobre las variables de entorno.

Cómo funciona

Clasificación de dispositivos

Bluehood clasifica dispositivos usando múltiples señales (en orden de prioridad):

UUIDs de servicio BLE - Más preciso (Heart Rate = wearable, A2DP = audio, etc.)
Patrones de nombre de dispositivo - "iPhone", "Galaxy", "AirPods", etc.
Búsqueda de fabricante por OUI - Apple, Samsung, Bose, etc.

MACs aleatorizadas

Los dispositivos modernos aleatorizan sus direcciones MAC por privacidad. Bluehood:

Detecta MACs aleatorizadas (bit administrado localmente)
Las oculta de la lista principal de dispositivos (no son útiles para rastreo)
Muestra un recuento de dispositivos aleatorizados ocultos

Análisis de patrones

Bluehood analiza las marcas de tiempo de los avistamientos para detectar patrones:

Hora del día: Mañana, Tarde, Noche
Día de la semana: Días laborables, Fines de semana
Frecuencia: Constante, Diaria, Regular, Ocasional, Rara

Patrones de ejemplo: "Diario, tardes (17:00-21:00)", "Días laborables, mañana (8:00-12:00)"

Correlación de dispositivos

Bluehood detecta dispositivos que aparecen frecuentemente juntos dentro de una ventana de tiempo configurable. Esto puede revelar:

Dispositivos propiedad de la misma persona (teléfono + smartwatch)
Personas que viajan juntas
Dispositivos que comparten un horario

Zonas de proximidad

Según la intensidad de señal RSSI, los dispositivos se clasifican en zonas de proximidad:

Inmediata (> -50 dBm): Muy cerca, a pocos metros
Cercana (-50 a -60 dBm): Cerca, misma habitación
Lejana (-60 a -70 dBm): Más lejos, habitaciones adyacentes
Remota (< -70 dBm): Distante, en el borde del rango de detección

Análisis de tiempo de permanencia

Rastrea cuánto tiempo pasan los dispositivos en rango analizando los intervalos entre avistamientos. Un umbral de intervalo configurable (por defecto 15 minutos) determina cuándo comienza una nueva "sesión".

Métricas de Prometheus

Bluehood puede exponer métricas para el scraping de Prometheus. Habilítalo configurando la variable de entorno BLUEHOOD_METRICS_PORT o el flag CLI --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Las métricas se sirven en http://host:9199/metrics.

Métricas disponibles

Panel de Grafana

Se incluye un panel de Grafana listo para importar en grafana/bluehood-dashboard.json. Impórtalo a través de la interfaz de Grafana (Dashboards > Import) o la 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}"

Solución de problemas

No se encuentran dispositivos

Asegúrate de que tu adaptador soporta BLE (Bluetooth 4.0+) con el rol Central — los adaptadores más antiguos no funcionarán
Asegúrate de que el adaptador Bluetooth está habilitado: bluetoothctl power on
Comprueba que el adaptador es detectado: bluehood --list-adapters
Ejecuta con sudo si se deniega el permiso

Problemas con Docker

BLE scan error: org.freedesktop.DBus.Error.ServiceUnknown / The name org.bluez was not provided

BlueZ no está instalado o no se está ejecutando en el host. Solución:

sudo apt install bluez          # Debian/Ubuntu
sudo systemctl enable --now bluetooth
docker compose restart

Lista de verificación general:

Asegúrate de que BlueZ está instalado en el host (no solo en el contenedor)
Verifica que el servicio Bluetooth está en ejecución: systemctl status bluetooth
Confirma que tu adaptador es visible: bluetoothctl list

Contribuir

¡Las contribuciones son bienvenidas! Por favor, abre un issue o PR en GitHub.

Colaboradores

@martinh2011 (Martin Hüser) - Mejoras en la caché de fabricantes MAC
@hatedabamboo (Kirill Solovei) - Soporte para tema claro
@krnltrp - Mejoras en la interfaz web
@jacobpretorius (Jacob Pretorius) - Corrección de JS de exportación CSV (#14), clic para abrir configuración (#16)
@unqualifiedkoala - Documentación de requisitos del adaptador BLE
@dazzag24 - Reportó problema de formato de dirección en macOS
@floese (W.A.Flozart) - Corrección de doble clic en Firefox (#29)
@GeiserX (Sergio Fernández) - Exportador de métricas Prometheus (#35), corrección de BD de fabricantes no bloqueante (#37), escaneo con doble adaptador (#33), recuperación robusta de escaneo con rfkill (#40)

Licencia

Licencia MIT - Consulta LICENSE para más detalles.

Descargo de responsabilidad

Esta herramienta es solo para fines educativos. Sé consciente de las leyes de privacidad en tu jurisdicción al monitorizar dispositivos Bluetooth. El autor no es responsable de ningún uso indebido de este software.

Creado por Danny McClelland

`PUID`	`1000`	UID para el usuario del contenedor — configúralo para que coincida con tu usuario del host (`id -u`) al usar montajes bind
`PGID`	`1000`	GID para el usuario del contenedor — configúralo para que coincida con tu grupo del host (`id -g`) al usar montajes bind
`TZ`	UTC	Zona horaria del contenedor (p. ej., `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	Adaptador Bluetooth para escaneo BLE (p. ej., `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	igual que `BLUEHOOD_ADAPTER`	Adaptador separado para escaneo Bluetooth clásico (p. ej., `hci1`). Cuando se configura con un adaptador diferente, los escaneos BLE y clásico se ejecutan de forma concurrente.
`BLUEHOOD_DATA_DIR`	`/data`	Directorio de almacenamiento de la base de datos
`BLUEHOOD_PORT`	`8080`	Puerto del panel web. El contenedor usa red de host, así que cambia esto (en lugar de un mapeo de puertos) si el 8080 está ocupado
`BLUEHOOD_NTFY_SERVER`	`https://ntfy.sh`	URL base del servidor ntfy para notificaciones push; apúntalo a una instancia autoalojada. El valor guardado en la página de Configuración tiene prioridad
`BLUEHOOD_METRICS_PORT`	deshabilitado	Puerto de métricas Prometheus (p. ej., `9199`)
`BLUEHOOD_HEARTBEAT_URL`	deshabilitado	URL para enviar check-ins de latido mediante POST (p. ej., una URL push de healthchecks.io o uptime-kuma)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	Segundos entre check-ins de latido
`BLUEHOOD_PRUNE_DAYS`	`0` (deshabilitado)	Elimina automáticamente avistamientos más antiguos que N días para liberar almacenamiento
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0` (deshabilitado)	Cuando es >0, elimina dispositivos obsoletos completos (más antiguos que `BLUEHOOD_PRUNE_DAYS` y con menos de N avistamientos totales) en lugar de solo recortar filas de avistamientos antiguos; los dispositivos vigilados nunca se eliminan

`/`	Enfocar la barra de búsqueda
`r`	Actualizar la lista de dispositivos
`c`	Alternar vista compacta
`w`	Alternar vigilancia en el dispositivo seleccionado
`Esc`	Cerrar modal
`?`	Mostrar atajos de teclado

`bluehood_scans_total`	Counter	Total de ciclos de escaneo completados
`bluehood_scan_errors_total`	Counter	Errores de escaneo (etiqueta: `scan_type`)
`bluehood_sightings_total`	Counter	Total de avistamientos de dispositivos registrados
`bluehood_new_devices_total`	Counter	Nuevos dispositivos únicos descubiertos
`bluehood_last_scan_devices`	Gauge	Dispositivos en el último escaneo (etiqueta: `scan_type`)
`bluehood_devices_total`	Gauge	Dispositivos únicos en la BD (etiqueta: `bt_type`)
`bluehood_devices_active`	Gauge	Dispositivos vistos en los últimos 5 minutos
`bluehood_devices_watched`	Gauge	Recuento de dispositivos vigilados
`bluehood_devices_ignored`	Gauge	Recuento de dispositivos ignorados
`bluehood_scan_duration_seconds`	Histogram	Duración del ciclo de escaneo
`bluehood_device_rssi_dbm`	Histogram	Distribución RSSI de dispositivos BLE
`bluehood_build_info`	Info	Información de versión

Más Populares

bluehood