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

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

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

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.

root@kitploit:~

# 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:

1. Ejecutar como root (lo más sencillo):

   root@kitploit:~

   sudo bluehood
   

2. Conceder capacidades a Python:

   root@kitploit:~

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

3. Usar servicio systemd (recomendado para siempre activo):

   root@kitploit:~

   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.

1. Crea un tema en ntfy.sh (p. ej., bluehood-myname-alerts), o en tu propio servidor ntfy
2. Suscríbete al tema en tu teléfono usando la app ntfy
3. 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
4. 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):

1. UUIDs de servicio BLE - Más preciso (Heart Rate = wearable, A2DP = audio, etc.)
2. Patrones de nombre de dispositivo - "iPhone", "Galaxy", "AirPods", etc.
3. 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