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

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

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

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

Executar como root (mais simples):
```
sudo bluehood
```

Conceder capacidades ao Python:

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

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

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.

Crie um tópico no ntfy.sh (ex.: bluehood-myname-alerts), ou em seu próprio servidor ntfy
Inscreva-se no tópico no seu celular usando o aplicativo ntfy
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
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):

UUIDs de Serviço BLE - Mais preciso (Heart Rate = vestível, A2DP = áudio, etc.)
Padrões de nome de dispositivo - "iPhone", "Galaxy", "AirPods", etc.
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

`PUID`	`1000`	UID para o usuário do contêiner — defina para corresponder ao seu usuário do host (`id -u`) ao usar bind mounts
`PGID`	`1000`	GID para o usuário do contêiner — defina para corresponder ao seu grupo do host (`id -g`) ao usar bind mounts
`TZ`	UTC	Fuso horário do contêiner (ex.: `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	Adaptador Bluetooth para escaneamento BLE (ex.: `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	mesmo que `BLUEHOOD_ADAPTER`	Adaptador separado para escaneamento Bluetooth classic (ex.: `hci1`). Quando definido para um adaptador diferente, os escaneamentos BLE e classic são executados simultaneamente.
`BLUEHOOD_DATA_DIR`	`/data`	Diretório de armazenamento do banco de dados
`BLUEHOOD_PORT`	`8080`	Porta do painel web. O contêiner usa rede do host, então altere isto (em vez de um mapeamento de porta) se a 8080 estiver ocupada
`BLUEHOOD_NTFY_SERVER`	`https://ntfy.sh`	URL base do servidor ntfy para notificações push; aponte para uma instância auto-hospedada. O valor salvo na página de Configurações tem precedência
`BLUEHOOD_METRICS_PORT`	desabilitado	Porta de métricas Prometheus (ex.: `9199`)
`BLUEHOOD_HEARTBEAT_URL`	desabilitado	URL para POST de check-ins de heartbeat (ex.: uma URL de push do healthchecks.io ou uptime-kuma)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	Segundos entre check-ins de heartbeat
`BLUEHOOD_PRUNE_DAYS`	`0` (desabilitado)	Exclui automaticamente avistamentos mais antigos que N dias para liberar armazenamento
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0` (desabilitado)	Quando >0, remove dispositivos obsoletos inteiros (mais antigos que `BLUEHOOD_PRUNE_DAYS` e com menos de N avistamentos totais) em vez de apenas cortar linhas de avistamentos antigos; dispositivos monitorados nunca são removidos

`/`	Focar na barra de busca
`r`	Atualizar lista de dispositivos
`c`	Alternar visualização compacta
`w`	Alternar monitoramento no dispositivo selecionado
`Esc`	Fechar modal
`?`	Mostrar atalhos de teclado

`bluehood_scans_total`	Counter	Total de ciclos de escaneamento concluídos
`bluehood_scan_errors_total`	Counter	Erros de escaneamento (label: `scan_type`)
`bluehood_sightings_total`	Counter	Total de avistamentos de dispositivos registrados
`bluehood_new_devices_total`	Counter	Novos dispositivos únicos descobertos
`bluehood_last_scan_devices`	Gauge	Dispositivos no último escaneamento (label: `scan_type`)
`bluehood_devices_total`	Gauge	Dispositivos únicos no BD (label: `bt_type`)
`bluehood_devices_active`	Gauge	Dispositivos vistos nos últimos 5 minutos
`bluehood_devices_watched`	Gauge	Contagem de dispositivos monitorados
`bluehood_devices_ignored`	Gauge	Contagem de dispositivos ignorados
`bluehood_scan_duration_seconds`	Histogram	Duração do ciclo de escaneamento
`bluehood_device_rssi_dbm`	Histogram	Distribuição de RSSI dos dispositivos BLE
`bluehood_build_info`	Info	Informações de versão

Mais Populares

bluehood