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. Recursos podem mudar, quebrar ou ser removidos sem aviso. Use por sua própria conta e risco. Os dados coletados devem ser tratados como experimentais.

Capturas de Tela

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

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

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

Por quê?

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

Milhares de dispositivos Bluetooth nos cercam o tempo todo: telefones, 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 normalmente passeia com o cachorro
Detectar quando um visitante chega a uma casa
Identificar padrões nas rotinas diárias com base na presença do dispositivo

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

O Bluehood é uma ferramenta educacional para conscientizar sobre privacidade em Bluetooth. É um projeto de fim de semana, mas as implicações merecem reflexão.

O quê?

Bluehood é um scanner Bluetooth que:

Escaneia continuamente dispositivos Bluetooth próximos (BLE e Clássico)
Identifica dispositivos por fabricante (consulta de endereço MAC) e UUIDs de serviço BLE
Classifica dispositivos em categorias (telefones, áudio, wearables, IoT, veículos, etc.)
Rastreia padrões de presença ao longo do tempo com mapas de calor por hora/dia
Filtra ruídos de endereços MAC aleatórios (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 de modo duplo: Bluetooth Low Energy (BLE) e Bluetooth Clássico
Consulta de fabricante por endereço MAC (banco de dados local + fallback de API online)
Identificação por UUID de serviço BLE para classificação precisa de dispositivos
Interpretação de classe de dispositivo Bluetooth Clássico
Filtragem de MACs aleatórios (ocultos da visualização principal)

Gerenciamento de Dispositivos

Marcar dispositivos como "Monitorados" para rastreamento pessoal
Organizar dispositivos em grupos personalizados
Definir nomes amigáveis para dispositivos conhecidos
Adicionar notas/etiquetas personalizadas a qualquer dispositivo
Detecção de tipo de dispositivo (telefones, áudio, wearables, IoT, veículos, etc.)

Análises

Linha do tempo de presença de 30 dias visualização
Histórico de intensidade de sinal (RSSI) gráfico com dados de 7 dias
Mapas de calor de atividade por hora e 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 ficam ao alcance
Detecção de correlação de dispositivos para encontrar dispositivos que aparecem juntos
Zonas de proximidade (imediata, próxima, distante, remota) com base na intensidade do sinal
Pesquisa por MAC, fabricante ou nome
Pesquisa por intervalo de datas para consultas históricas

Notificações (via ntfy.sh)

Notificações push para seu telefone/desktop
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

Heartbeat check-in — periodicamente envia POST 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
Ambos configuráveis pela interface web ou por variáveis de ambiente

Interface Web

Alternância entre visualização compacta/detalhada para diferentes preferências de exibição
Modo de 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 de dispositivos
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 comunica-se 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 container — 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 o papel 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 para papel 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 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 ao papel 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 o papel BLE Central, o Bluehood será encerrado com:

No Bluetooth adapters with BLE 'central' role found

Você pode verificar as capacidades do seu adaptador com bluetoothctl show e procurar por central nos papéis suportados.

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 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 ligado):

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
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 (telefones, áudio, IoT, etc.) e status de monitoramento
Pesquisa por MAC, fabricante ou nome
Pesquisa por intervalo de datas para encontrar dispositivos vistos em um período específico
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:
- Impressões digitais 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
- Indicador de zona de proximidade
- Campo de notas do operador
- Atribuição de grupo

Atalhos de Teclado

Modo de Captura de Tela

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

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

Notificações Push

O Bluehood pode enviar notificações push via ntfy.sh, um serviço de notificação gratuito e de código aberto.

Crie um tópico no ntfy.sh (ex.: bluehood-meu-nome-alertas)
Inscreva-se no tópico no seu telefone usando o aplicativo ntfy
Nas configurações do Bluehood, insira o nome do seu tópico e ative 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 a localização com variáveis de ambiente:

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

Nota: As configurações de heartbeat e limpeza podem ser configuradas pela interface web (Configurações > Operações) ou por variáveis de ambiente. Os valores da GUI têm prioridade sobre as 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 precisos (Frequência Cardíaca = wearable, A2DP = áudio, etc.)
Padrões de nome de dispositivo - "iPhone", "Galaxy", "AirPods", etc.
Consulta OUI do fabricante - Apple, Samsung, Bose, etc.

MACs Aleatórios

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

Detecta MACs aleatórios (bit de administração local)
Oculta-os da lista principal de dispositivos (não úteis para rastreamento)
Mostra uma contagem de dispositivos aleatórios ocultos

Análise de Padrões

O Bluehood analisa carimbos de data/hora 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 frequentemente aparecem juntos dentro de uma janela de tempo configurável. Isso pode revelar:

Dispositivos pertencentes à mesma pessoa (telefone + 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óximos, a poucos metros
Próxima (-50 a -60 dBm): Por perto, na mesma sala
Distante (-60 a -70 dBm): Mais afastados, salas adjacentes
Remota (< -70 dBm): Distantes, no limite do alcance de detecção

Análise de Tempo de Permanência

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

Métricas do Prometheus

O Bluehood pode expor métricas para coleta pelo Prometheus. Ative 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 do Grafana

Um painel do Grafana pronto para importar 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 papel Central — adaptadores mais antigos não funcionarão
Certifique-se de que o adaptador Bluetooth está ativado: bluetoothctl power on
Verifique se o adaptador é detectado: bluehood --list-adapters
Execute com sudo se o acesso for negado

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. Corrija:

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

Lista de verificação geral:

Certifique-se de que o BlueZ está instalado no host (não apenas no container)
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 fabricantes MAC
@hatedabamboo (Kirill Solovei) - Suporte a tema claro
@krnltrp - Melhorias na interface web
@jacobpretorius (Jacob Pretorius) - Correção JS na exportação CSV (#14), clique para abrir configuração (#16)
@unqualifiedkoala - Documentou requisitos do adaptador BLE
@dazzag24 - Reportou problema com formato de endereço no macOS
@floese (W.A.Flozart) - Correção de duplo clique no Firefox (#29)
@GeiserX (Sergio Fernández) - Exportador de métricas Prometheus (#35), correção não bloqueante do banco de dados de fabricantes (#37), escaneamento com adaptador duplo (#33), recuperação robusta de escaneamento com rfkill (#40)

Licença

Licença MIT - Consulte LICENSE para detalhes.

Aviso Legal

Esta ferramenta é apenas para fins educacionais. Esteja ciente das 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 do usuário do container — defina para corresponder ao seu usuário host (`id -u`) ao usar bind mounts
`PGID`	`1000`	GID do usuário do container — defina para corresponder ao seu grupo host (`id -g`) ao usar bind mounts
`TZ`	UTC	Fuso horário do container (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 Clássico (ex.: `hci1`). Quando definido para um adaptador diferente, escaneamentos BLE e Clássico são executados simultaneamente.
`BLUEHOOD_DATA_DIR`	`/data`	Diretório de armazenamento do banco de dados
`BLUEHOOD_METRICS_PORT`	desabilitado	Porta de métricas do Prometheus (ex.: `9199`)
`BLUEHOOD_HEARTBEAT_URL`	desabilitado	URL para enviar check-ins de heartbeat (ex.: uma URL push do healthchecks.io ou uptime-kuma)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	Segundos entre check-ins de heartbeat
`BLUEHOOD_PRUNE_DAYS`	`0` (desabilitado)	Excluir automaticamente avistamentos mais antigos que N dias para liberar armazenamento

`/`	Focar na barra de pesquisa
`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 (rótulo: `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 (rótulo: `scan_type`)
`bluehood_devices_total`	Gauge	Dispositivos únicos no banco de dados (rótulo: `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 RSSI de dispositivos BLE
`bluehood_build_info`	Info	Informações da versão

Mais Populares

bluehood