Bluehood

Bluetooth Neighborhood - Rastreie dispositivos BLE na sua área e analise padrões de tráfego.

AVISO: Software Alpha

Este projeto está em desenvolvimento inicial e não está pronto para uso em produção. Funcionalidades podem mudar, quebrar ou ser removidas sem aviso prévio. Use por sua conta e risco. Os dados coletados devem ser tratados como experimentais.

Capturas de Tela

Painel principal mostrando a lista de dispositivos com filtragem, busca e estatísticas em tempo real

Página de configuração com abas — Alertas, Operações, Grupos e Segurança

Página de informações com detalhes do projeto e visão geral das capacidades

Por quê?

Este projeto foi inspirado na vulnerabilidade WhisperPair (CVE-2025-36911), que destacou riscos à privacidade em dispositivos Bluetooth.

Milhares de dispositivos Bluetooth nos cercam o tempo todo: celulares, carros, TVs, fones de ouvido, aparelhos auditivos, veículos de entrega e muito mais. O Bluehood demonstra como é simples detectar passivamente esses dispositivos e observar padrões em sua presença.

Com dados suficientes, você poderia potencialmente:

• Entender a que horas alguém costuma passear com o cachorro
• Detectar quando um visitante chega a uma casa
• Identificar padrões em rotinas diárias com base na presença de dispositivos

Esses metadados podem revelar informações surpreendentemente pessoais sem qualquer interação ativa com os dispositivos.

O Bluehood é uma ferramenta educacional para conscientizar sobre a privacidade no Bluetooth. É um projeto de fim de semana, mas as implicações valem a pena ser consideradas.

O quê?

O Bluehood é um scanner de Bluetooth que:

• Escaneia continuamente dispositivos Bluetooth próximos (tanto BLE quanto Classic)
• Identifica dispositivos por fabricante (consulta de endereço MAC) e UUIDs de serviço BLE
• Classifica dispositivos em categorias (celulares, áudio, vestíveis, IoT, veículos, etc.)
• Rastreia padrões de presença ao longo do tempo com mapas de calor por hora/dia
• Filtra ruído de endereços MAC aleatorizados (dispositivos com rotação de privacidade)
• Analisa correlações entre dispositivos para encontrar dispositivos que aparecem juntos
• Envia notificações push quando dispositivos monitorados chegam ou saem
• Fornece um painel web para monitoramento e análise

Funcionalidades

Escaneamento

• Escaneamento em modo duplo: Bluetooth Low Energy (BLE) e Bluetooth Classic
• Consulta de fabricante por endereço MAC (banco de dados local + fallback para API online)
• Fingerprinting de UUID de serviço BLE para classificação precisa de dispositivos
• Análise de classe de dispositivo Bluetooth Classic
• Filtragem de MAC aleatorizado (oculto da visualização principal)

Gerenciamento de Dispositivos

• Marcar dispositivos como "Monitorados" para rastrear dispositivos pessoais
• Organizar dispositivos em grupos personalizados
• Dar um nome personalizado aos dispositivos (o nome anunciado permanece visível ao lado dele)
• Substituir a classificação detectada de qualquer dispositivo
• Adicionar notas/tags personalizadas a qualquer dispositivo
• Detecção de tipo de dispositivo (celulares, áudio, vestíveis, IoT, veículos, etc.)

Análises

• Visualização de linha do tempo de presença de 30 dias
• Gráfico de histórico de intensidade de sinal (RSSI) com dados de 7 dias
• Mapas de calor de atividade por hora e por dia mostrando quando os dispositivos estão ativos
• Análise de padrões ("Dias úteis, noites 17h-21h")
• Análise de tempo de permanência mostrando o tempo total que os dispositivos passam no alcance
• Detecção de correlação entre dispositivos para encontrar dispositivos que aparecem juntos (co-presença mais chegada/saída sincronizada)
• Vinculação por rotação de MAC ("Provavelmente o mesmo dispositivo") — vincula heuristicamente identificadores aleatorizados que se alternam no tempo, compartilham intensidade de sinal semelhante e pingam em cadência similar
• Zonas de proximidade (imediata, próxima, distante, remota) com base na intensidade do sinal
• Busca por MAC, fabricante ou nome
• Busca por intervalo de datas para consultas históricas

Notificações (via ntfy)

• Notificações push para seu celular/desktop através do ntfy.sh ou de um servidor ntfy auto-hospedado
• Notificar quando novos dispositivos são detectados
• Notificar quando dispositivos monitorados retornam
• Notificar quando dispositivos monitorados saem
• Limiares configuráveis para chegada/saída

Operações

• Check-in de heartbeat — POST periódico de status para um serviço de monitoramento de uptime (ex.: Uptime Kuma, Healthchecks.io)
• Rotação de armazenamento — remove automaticamente avistamentos mais antigos que um número configurável de dias; opcionalmente restringe a remoção a dispositivos obsoletos inteiros vistos menos que um número mínimo de vezes (dispositivos monitorados nunca são removidos)
• Ambos configuráveis pela interface web ou via variáveis de ambiente

Interface Web

• Alternância entre visualização Compacta/Detalhada para diferentes preferências de exibição
• Modo captura de tela para ofuscar MACs e nomes para compartilhamento seguro
• Atalhos de teclado para usuários avançados (pressione ? para visualizar)
• Exportação CSV de dados detalhados dos dispositivos (MAC, fabricante, identificador, tipo, tipo BT, classe de dispositivo, flags de monitorado/ignorado, primeira/última vez visto, avistamentos, grupo, UUIDs de serviço e notas) — exporta todo o conjunto filtrado, não apenas a página atual
• Grupos de dispositivos para organizar dispositivos relacionados
• Autenticação opcional para proteger o acesso

Como?

Início Rápido com Docker (Recomendado)

Pré-requisitos — apenas hosts Linux

O Bluehood se comunica com seu adaptador Bluetooth via BlueZ, a pilha Bluetooth do Linux. O BlueZ deve estar instalado e em execução no host antes de iniciar o contêiner — a imagem Docker em si não o inclui.

root@kitploit:~

# Debian / Ubuntu (incluindo Ubuntu Server)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

Sem o BlueZ no host, você verá um erro 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

A imagem Docker está disponível no GitHub Container Registry:

ghcr.io/dannymcc/bluehood:latest

O painel web estará disponível em http://localhost:8080

Requisitos do Docker

• Docker e Docker Compose
• Host Linux com um adaptador Bluetooth compatível com BLE (Bluetooth 4.0+) que suporte a função Central
• BlueZ instalado e em execução no host (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Nota: Adaptadores mais antigos (Bluetooth 2.x/3.x) não suportam escaneamento BLE. Se seu adaptador não tiver suporte à função BLE 'central', você verá: No Bluetooth adapters with BLE 'central' role found.

Nota: O Docker é executado em modo privilegiado com rede do host para acesso ao Bluetooth. Isso é necessário para o escaneamento BLE.

Variáveis de Ambiente do Docker

Requisitos do Adaptador Bluetooth

O Bluehood requer um adaptador Bluetooth compatível com BLE (Bluetooth 4.0 ou posterior) com suporte à função Central. Adaptadores Bluetooth 2.x/3.x mais antigos não suportam escaneamento BLE e não funcionarão.

Se seu adaptador não suportar a função BLE Central, o Bluehood encerrará com:

No Bluetooth adapters with BLE 'central' role found

Você pode verificar as capacidades do seu adaptador com bluetoothctl show e procurar por central nas funções suportadas.

Instalação 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 .

Permissões de Bluetooth

O escaneamento Bluetooth requer privilégios elevados. Escolha uma opção:

1. Executar como root (mais simples):

   root@kitploit:~

   sudo bluehood
   

2. Conceder capacidades ao Python:

   root@kitploit:~

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

3. Usar serviço systemd (recomendado para sempre ativo):

   root@kitploit:~

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

macOS

O Bluehood funciona nativamente no macOS sem Docker. O macOS usa CoreBluetooth em vez do BlueZ, o que é tratado automaticamente pela biblioteca 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

O painel web estará disponível em http://localhost:8080

Nota: Na primeira execução, o macOS solicitará que você permita o acesso ao Bluetooth. Você deve conceder essa permissão para que o escaneamento 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

Painel Web

O painel fornece:

• Lista de dispositivos com ícones de tipo, fabricante, MAC, nome, avistamentos, última vez visto
• Filtros de dispositivos por tipo (celulares, áudio, IoT, etc.) e status de monitoramento
• Busca por MAC, fabricante ou nome
• Busca por intervalo de datas para encontrar dispositivos vistos em uma janela de tempo específica
• Página de configurações com abas — Alertas, Operações, Grupos e Segurança (link direto via hash, ex.: /settings#operations)
• Modal de detalhes do dispositivo com:
  • Fingerprints de serviço BLE
  • Mapas de calor de atividade por hora/dia
  • Linha do tempo de presença de 30 dias
  • Gráfico de histórico de intensidade de sinal (RSSI)
  • Análise de padrões
  • Estatísticas de tempo de permanência
  • Lista de dispositivos correlacionados
  • Lista de provavelmente o mesmo dispositivo (rotação de MAC)
  • Indicador de zona de proximidade
  • Campo de notas do operador
  • Atribuição de grupo

Atalhos de Teclado

Modo Captura de Tela

Ative o modo captura de tela na barra lateral para ofuscar dados sensíveis antes de compartilhar capturas de tela:

• Endereços MAC mostram apenas os 2 primeiros octetos (ex.: AA:BB:XX:XX:XX:XX)
• Nomes amigáveis mostram apenas os 2 primeiros caracteres (ex.: Da********)
• Exportações CSV também respeitam o modo captura de tela

Notificações Push

O Bluehood pode enviar notificações push via ntfy, um serviço de notificação gratuito e de código aberto. Você pode usar o servidor público ntfy.sh ou sua própria instância auto-hospedada.

1. Crie um tópico no ntfy.sh (ex.: bluehood-myname-alerts), ou em seu próprio servidor ntfy
2. Inscreva-se no tópico no seu celular usando o aplicativo ntfy
3. Nas configurações do Bluehood, insira a URL do servidor (padrão https://ntfy.sh), o nome do seu tópico e um token de acesso se seu servidor exigir, depois habilite as notificações
4. Configure quais eventos disparam notificações:
   • Novo dispositivo detectado
   • Dispositivo monitorado retorna (após estar ausente)
   • Dispositivo monitorado sai (não visto por X minutos)

Armazenamento de Dados

Os dados são armazenados em ~/.local/share/bluehood/bluehood.db (SQLite).

Substitua o local com variáveis de ambiente:

• BLUEHOOD_DATA_DIR - Diretório para arquivos de dados
• BLUEHOOD_DB_PATH - Caminho direto para o arquivo do banco de dados

Nota: As configurações de heartbeat e remoção podem ser configuradas pela interface web (Configurações > Operações) ou via variáveis de ambiente. Valores da GUI têm prioridade sobre variáveis de ambiente.

Como Funciona

Classificação de Dispositivos

O Bluehood classifica dispositivos usando múltiplos sinais (em ordem de prioridade):

1. UUIDs de Serviço BLE - Mais preciso (Heart Rate = vestível, A2DP = áudio, etc.)
2. Padrões de nome de dispositivo - "iPhone", "Galaxy", "AirPods", etc.
3. Consulta de OUI do fabricante - Apple, Samsung, Bose, etc.

MACs Aleatorizados

Dispositivos modernos aleatorizam seus endereços MAC por privacidade. O Bluehood:

• Detecta MACs aleatorizados (bit administrado localmente)
• Oculta-os da lista principal de dispositivos (não úteis para rastreamento)
• Mostra uma contagem de dispositivos aleatorizados ocultos

Análise de Padrões

O Bluehood analisa timestamps de avistamentos para detectar padrões:

• Hora do dia: Manhã, Tarde, Noite, Madrugada
• Dia da semana: Dias úteis, Fins de semana
• Frequência: Constante, Diário, Regular, Ocasional, Raro

Exemplos de padrões: "Diário, noites (17h-21h)", "Dias úteis, manhã (8h-12h)"

Correlação de Dispositivos

O Bluehood detecta dispositivos que aparecem frequentemente juntos dentro de uma janela de tempo configurável. Isso pode revelar:

• Dispositivos pertencentes à mesma pessoa (celular + smartwatch)
• Pessoas que viajam juntas
• Dispositivos que compartilham uma agenda

Zonas de Proximidade

Com base na intensidade do sinal RSSI, os dispositivos são classificados em zonas de proximidade:

• Imediata (> -50 dBm): Muito próximo, dentro de alguns metros
• Próxima (-50 a -60 dBm): Próximo, mesma sala
• Distante (-60 a -70 dBm): Mais longe, salas adjacentes
• Remota (< -70 dBm): Distante, no limite do alcance de detecção

Análise de Tempo de Permanência

Rastreia quanto tempo os dispositivos passam no alcance analisando lacunas entre avistamentos. Um limiar de lacuna configurável (padrão 15 minutos) determina quando uma nova "sessão" começa.

Métricas Prometheus

O Bluehood pode expor métricas para coleta do Prometheus. Habilite definindo a variável de ambiente BLUEHOOD_METRICS_PORT ou a flag CLI --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

As métricas são servidas em http://host:9199/metrics.

Métricas Disponíveis

Painel Grafana

Um painel Grafana pronto para importação está incluído em grafana/bluehood-dashboard.json. Importe-o pela interface do Grafana (Dashboards > Import) ou pela 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}"

Solução de Problemas

Nenhum dispositivo encontrado

• Certifique-se de que seu adaptador suporta BLE (Bluetooth 4.0+) com a função Central — adaptadores mais antigos não funcionarão
• Certifique-se de que o adaptador Bluetooth está habilitado: bluetoothctl power on
• Verifique se o adaptador é detectado: bluehood --list-adapters
• Execute com sudo se a permissão for negada

Problemas com Docker

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

O BlueZ não está instalado ou não está em execução no host. Correção:

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

Checklist geral:

• Certifique-se de que o BlueZ está instalado no host (não apenas no contêiner)
• Verifique se o serviço Bluetooth está em execução: systemctl status bluetooth
• Confirme que seu adaptador está visível: bluetoothctl list

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou PR no GitHub.

Contribuidores

• @martinh2011 (Martin Hüser) - Melhorias no cache de fabricante MAC
• @hatedabamboo (Kirill Solovei) - Suporte a tema claro
• @krnltrp - Melhorias na interface web
• @jacobpretorius (Jacob Pretorius) - Correção de JS na exportação CSV (#14), clique para abrir configuração (#16)
• @unqualifiedkoala - Documentou os requisitos do adaptador BLE
• @dazzag24 - Reportou problema de formato de endereço no macOS
• @floese (W.A.Flozart) - Correção de clique duplo no Firefox (#29)
• @GeiserX (Sergio Fernández) - Exportador de métricas Prometheus (#35), correção de BD de fabricante não bloqueante (#37), escaneamento com adaptador duplo (#33), recuperação robusta de escaneamento com rfkill (#40)

Licença

Licença MIT - Veja LICENSE para detalhes.

Aviso Legal

Esta ferramenta é apenas para fins educacionais. Esteja atento às leis de privacidade em sua jurisdição ao monitorar dispositivos Bluetooth. O autor não é responsável por qualquer uso indevido deste software.

Criado por Danny McClelland