Bluehood

Bluetooth Neighborhood - Traccia i dispositivi BLE nella tua area e analizza i pattern di traffico.

ATTENZIONE: Software Alpha

Questo progetto è in fase di sviluppo iniziale e non è pronto per l'uso in produzione. Le funzionalità possono cambiare, rompersi o essere rimosse senza preavviso. Usalo a tuo rischio. I dati raccolti devono essere considerati sperimentali.

Screenshot

Dashboard principale che mostra l'elenco dei dispositivi con filtri, ricerca e statistiche in tempo reale

Pagina di configurazione a schede — Avvisi, Operazioni, Gruppi e Sicurezza

Pagina Intel con informazioni sul progetto e panoramica delle funzionalità

Perché?

Questo progetto è stato ispirato dalla vulnerabilità WhisperPair (CVE-2025-36911), che ha evidenziato i rischi per la privacy nei dispositivi Bluetooth.

Migliaia di dispositivi Bluetooth ci circondano in ogni momento: telefoni, auto, TV, cuffie, apparecchi acustici, veicoli per le consegne e altro ancora. Bluehood dimostra quanto sia semplice rilevare passivamente questi dispositivi e osservare i pattern della loro presenza.

Con dati sufficienti, potresti potenzialmente:

• Capire a che ora qualcuno porta abitualmente a spasso il cane
• Rilevare quando un visitatore arriva a casa
• Identificare pattern nelle routine quotidiane in base alla presenza dei dispositivi

Questi metadati possono rivelare informazioni sorprendentemente personali senza alcuna interazione attiva con i dispositivi.

Bluehood è uno strumento educativo per sensibilizzare sulla privacy Bluetooth. È un progetto da weekend, ma le implicazioni meritano una riflessione.

Cosa?

Bluehood è uno scanner Bluetooth che:

• Scansiona continuamente i dispositivi Bluetooth nelle vicinanze (sia BLE che Classic)
• Identifica i dispositivi per produttore (lookup dell'indirizzo MAC) e UUID dei servizi BLE
• Classifica i dispositivi in categorie (telefoni, audio, indossabili, IoT, veicoli, ecc.)
• Traccia i pattern di presenza nel tempo con mappe di calore orarie/giornaliere
• Filtra il rumore dagli indirizzi MAC randomizzati (dispositivi con rotazione della privacy)
• Analizza le correlazioni tra dispositivi per trovare dispositivi che appaiono insieme
• Invia notifiche push quando i dispositivi monitorati arrivano o partono
• Fornisce una dashboard web per il monitoraggio e l'analisi

Funzionalità

Scansione

• Scansione dual-mode: Bluetooth Low Energy (BLE) e Bluetooth Classic
• Lookup del produttore dall'indirizzo MAC (database locale + fallback su API online)
• Fingerprinting degli UUID dei servizi BLE per una classificazione accurata dei dispositivi
• Parsing della classe dei dispositivi Bluetooth Classic
• Filtro dei MAC randomizzati (nascosti dalla vista principale)

Gestione dei dispositivi

• Contrassegna i dispositivi come "Monitorati" per tracciare i dispositivi personali
• Organizza i dispositivi in gruppi personalizzati
• Assegna un nome personalizzato ai dispositivi (il nome pubblicizzato rimane visibile accanto ad esso)
• Sovrascrivi la classificazione rilevata di qualsiasi dispositivo
• Aggiungi note/tag personalizzati a qualsiasi dispositivo
• Rilevamento del tipo di dispositivo (telefoni, audio, indossabili, IoT, veicoli, ecc.)

Analisi

• Visualizzazione della timeline di presenza a 30 giorni
• Grafico della cronologia dell'intensità del segnale (RSSI) con dati a 7 giorni
• Mappe di calore dell'attività oraria e giornaliera che mostrano quando i dispositivi sono attivi
• Analisi dei pattern ("Giorni feriali, sera 17:00-21:00")
• Analisi del tempo di permanenza che mostra il tempo totale che i dispositivi trascorrono nel raggio d'azione
• Rilevamento della correlazione tra dispositivi per trovare dispositivi che appaiono insieme (co-presenza più arrivo/partenza sincronizzati)
• Collegamento per rotazione MAC ("Probabilmente stesso dispositivo") — collega euristicamente identificatori randomizzati che si alternano nel tempo, condividono un'intensità del segnale simile e trasmettono con una cadenza simile
• Zone di prossimità (immediata, vicina, lontana, remota) in base all'intensità del segnale
• Ricerca per MAC, produttore o nome
• Ricerca per intervallo di date per query storiche

Notifiche (tramite ntfy)

• Notifiche push al tuo telefono/desktop tramite ntfy.sh o un server ntfy self-hosted
• Notifica quando vengono rilevati nuovi dispositivi
• Notifica quando i dispositivi monitorati ritornano
• Notifica quando i dispositivi monitorati partono
• Soglie configurabili per arrivo/partenza

Operazioni

• Check-in heartbeat — invia periodicamente lo stato tramite POST a un servizio di monitoraggio uptime (es. Uptime Kuma, Healthchecks.io)
• Rotazione dello storage — elimina automaticamente gli avvistamenti più vecchi di un numero configurabile di giorni; opzionalmente limita l'eliminazione a interi dispositivi obsoleti visti meno di un numero minimo di volte (i dispositivi monitorati non vengono mai eliminati)
• Entrambi configurabili dalla UI web o tramite variabili d'ambiente

Interfaccia Web

• Alternanza vista Compatta/Dettagliata per diverse preferenze di visualizzazione
• Modalità screenshot per offuscare MAC e nomi per una condivisione sicura
• Scorciatoie da tastiera per utenti esperti (premi ? per visualizzarle)
• Esportazione CSV dei dati dettagliati dei dispositivi (MAC, produttore, identificatore, tipo, tipo BT, classe del dispositivo, flag monitorato/ignorato, primo/ultimo avvistamento, avvistamenti, gruppo, UUID dei servizi e note) — esporta l'intero set filtrato, non solo la pagina corrente
• Gruppi di dispositivi per organizzare dispositivi correlati
• Autenticazione opzionale per proteggere l'accesso

Come?

Avvio Rapido con Docker (Consigliato)

Prerequisiti — solo host Linux

Bluehood comunica con il tuo adattatore Bluetooth tramite BlueZ, lo stack Bluetooth di Linux. BlueZ deve essere installato e in esecuzione sull'host prima di avviare il container — l'immagine Docker stessa non lo include.

root@kitploit:~

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

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

Senza BlueZ sull'host vedrai un errore come: 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

L'immagine Docker è disponibile su GitHub Container Registry:

ghcr.io/dannymcc/bluehood:latest

La dashboard web sarà disponibile all'indirizzo http://localhost:8080

Requisiti Docker

• Docker e Docker Compose
• Host Linux con un adattatore Bluetooth compatibile BLE (Bluetooth 4.0+) che supporti il ruolo Central
• BlueZ installato e in esecuzione sull'host (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Nota: Gli adattatori più vecchi (Bluetooth 2.x/3.x) non supportano la scansione BLE. Se il tuo adattatore non supporta il ruolo BLE Central, vedrai: No Bluetooth adapters with BLE 'central' role found.

Nota: Docker viene eseguito in modalità privilegiata con networking host per l'accesso Bluetooth. Questo è necessario per la scansione BLE.

Variabili d'Ambiente Docker

Requisiti dell'Adattatore Bluetooth

Bluehood richiede un adattatore Bluetooth compatibile BLE (Bluetooth 4.0 o successivo) con supporto al ruolo Central. Gli adattatori Bluetooth 2.x/3.x più vecchi non supportano la scansione BLE e non funzioneranno.

Se il tuo adattatore non supporta il ruolo BLE Central, Bluehood terminerà con:

No Bluetooth adapters with BLE 'central' role found

Puoi verificare le capacità del tuo adattatore con bluetoothctl show e cercare central tra i ruoli supportati.

Installazione Manuale (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 .

Permessi Bluetooth

La scansione Bluetooth richiede privilegi elevati. Scegli una delle seguenti opzioni:

1. Esegui come root (il più semplice):

   root@kitploit:~

   sudo bluehood
   

2. Concedi le capabilities a Python:

   root@kitploit:~

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

3. Usa il servizio systemd (consigliato per l'esecuzione continua):

   root@kitploit:~

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

macOS

Bluehood funziona nativamente su macOS senza Docker. macOS usa CoreBluetooth invece di BlueZ, che viene gestito automaticamente dalla libreria 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

La dashboard web sarà disponibile all'indirizzo http://localhost:8080

Nota: Al primo avvio, macOS ti chiederà di consentire l'accesso al Bluetooth. Devi concedere questa autorizzazione affinché la scansione funzioni.

Utilizzo

# 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

Dashboard Web

La dashboard fornisce:

• Elenco dei dispositivi con icone del tipo, produttore, MAC, nome, avvistamenti, ultimo avvistamento
• Filtri dei dispositivi per tipo (telefoni, audio, IoT, ecc.) e stato di monitoraggio
• Ricerca per MAC, produttore o nome
• Ricerca per intervallo di date per trovare dispositivi visti in una specifica finestra temporale
• Pagina delle impostazioni a schede — Avvisi, Operazioni, Gruppi e Sicurezza (collegamento diretto tramite hash, es. /settings#operations)
• Modale dei dettagli del dispositivo con:
  • Fingerprint dei servizi BLE
  • Mappe di calore dell'attività oraria/giornaliera
  • Timeline di presenza a 30 giorni
  • Grafico della cronologia dell'intensità del segnale (RSSI)
  • Analisi dei pattern
  • Statistiche del tempo di permanenza
  • Elenco dei dispositivi correlati
  • Elenco dei probabili stessi dispositivi (rotazione MAC)
  • Indicatore della zona di prossimità
  • Campo note dell'operatore
  • Assegnazione del gruppo

Scorciatoie da Tastiera

Modalità Screenshot

Attiva la modalità screenshot dalla barra laterale per offuscare i dati sensibili prima di condividere gli screenshot:

• Gli indirizzi MAC mostrano solo i primi 2 ottetti (es. AA:BB:XX:XX:XX:XX)
• I nomi descrittivi mostrano solo i primi 2 caratteri (es. Da********)
• Anche le esportazioni CSV rispettano la modalità screenshot

Notifiche Push

Bluehood può inviare notifiche push tramite ntfy, un servizio di notifica gratuito e open-source. Puoi usare il server pubblico ntfy.sh o la tua istanza self-hosted.

1. Crea un topic su ntfy.sh (es. bluehood-mionome-alerts), o sul tuo server ntfy
2. Iscriviti al topic sul tuo telefono usando l'app ntfy
3. Nelle impostazioni di Bluehood, inserisci l'URL del server (predefinito https://ntfy.sh), il nome del tuo topic e un token di accesso se il tuo server lo richiede, poi abilita le notifiche
4. Configura quali eventi attivano le notifiche:
   • Nuovo dispositivo rilevato
   • Dispositivo monitorato ritorna (dopo essere stato assente)
   • Dispositivo monitorato parte (non visto per X minuti)

Archiviazione dei Dati

I dati sono archiviati in ~/.local/share/bluehood/bluehood.db (SQLite).

Sovrascrivi la posizione con le variabili d'ambiente:

• BLUEHOOD_DATA_DIR - Directory per i file di dati
• BLUEHOOD_DB_PATH - Percorso diretto al file del database

Nota: Le impostazioni di heartbeat e pruning possono essere configurate dalla UI web (Impostazioni > Operazioni) o tramite variabili d'ambiente. I valori della GUI hanno la priorità sulle variabili d'ambiente.

Come Funziona

Classificazione dei Dispositivi

Bluehood classifica i dispositivi usando molteplici segnali (in ordine di priorità):

1. UUID dei servizi BLE - Il più accurato (Heart Rate = indossabile, A2DP = audio, ecc.)
2. Pattern del nome del dispositivo - "iPhone", "Galaxy", "AirPods", ecc.
3. Lookup del produttore OUI - Apple, Samsung, Bose, ecc.

MAC Randomizzati

I dispositivi moderni randomizzano i loro indirizzi MAC per la privacy. Bluehood:

• Rileva i MAC randomizzati (bit locally administered)
• Li nasconde dall'elenco principale dei dispositivi (non utili per il tracciamento)
• Mostra un conteggio dei dispositivi randomizzati nascosti

Analisi dei Pattern

Bluehood analizza i timestamp degli avvistamenti per rilevare pattern:

• Ora del giorno: Mattina, Pomeriggio, Sera, Notte
• Giorno della settimana: Giorni feriali, Fine settimana
• Frequenza: Costante, Quotidiana, Regolare, Occasionale, Rara

Esempi di pattern: "Quotidiano, sera (17:00-21:00)", "Giorni feriali, mattina (8:00-12:00)"

Correlazione dei Dispositivi

Bluehood rileva i dispositivi che appaiono frequentemente insieme all'interno di una finestra temporale configurabile. Questo può rivelare:

• Dispositivi posseduti dalla stessa persona (telefono + smartwatch)
• Persone che viaggiano insieme
• Dispositivi che condividono un programma

Zone di Prossimità

In base all'intensità del segnale RSSI, i dispositivi sono classificati in zone di prossimità:

• Immediata (> -50 dBm): Molto vicino, entro pochi metri
• Vicina (-50 a -60 dBm): Nelle vicinanze, stessa stanza
• Lontana (-60 a -70 dBm): Più lontano, stanze adiacenti
• Remota (< -70 dBm): Distante, al limite del raggio di rilevamento

Analisi del Tempo di Permanenza

Traccia quanto tempo i dispositivi trascorrono nel raggio d'azione analizzando gli intervalli tra gli avvistamenti. Una soglia di intervallo configurabile (predefinita 15 minuti) determina quando inizia una nuova "sessione".

Metriche Prometheus

Bluehood può esporre metriche per lo scraping di Prometheus. Abilita impostando la variabile d'ambiente BLUEHOOD_METRICS_PORT o il flag CLI --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Le metriche sono servite all'indirizzo http://host:9199/metrics.

Metriche Disponibili

Dashboard Grafana

Una dashboard Grafana pronta per l'importazione è inclusa in grafana/bluehood-dashboard.json. Importala tramite la UI di Grafana (Dashboards > Import) o l'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}"

Risoluzione dei Problemi

Nessun dispositivo trovato

• Assicurati che il tuo adattatore supporti BLE (Bluetooth 4.0+) con il ruolo Central — gli adattatori più vecchi non funzioneranno
• Assicurati che l'adattatore Bluetooth sia abilitato: bluetoothctl power on
• Verifica che l'adattatore sia rilevato: bluehood --list-adapters
• Esegui con sudo se ricevi un errore di permesso negato

Problemi con Docker

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

BlueZ non è installato o non è in esecuzione sull'host. Soluzione:

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

Checklist generale:

• Assicurati che BlueZ sia installato sull'host (non solo nel container)
• Verifica che il servizio Bluetooth sia in esecuzione: systemctl status bluetooth
• Conferma che il tuo adattatore sia visibile: bluetoothctl list

Contribuire

Contributi benvenuti! Apri una issue o una PR su GitHub.

Contributori

• @martinh2011 (Martin Hüser) - Miglioramenti alla cache dei produttori MAC
• @hatedabamboo (Kirill Solovei) - Supporto al tema chiaro
• @krnltrp - Miglioramenti alla UI web
• @jacobpretorius (Jacob Pretorius) - Fix JS dell'esportazione CSV (#14), click per aprire le impostazioni (#16)
• @unqualifiedkoala - Documentazione dei requisiti dell'adattatore BLE
• @dazzag24 - Segnalazione del problema del formato dell'indirizzo su macOS
• @floese (W.A.Flozart) - Fix del doppio click su Firefox (#29)
• @GeiserX (Sergio Fernández) - Esportatore di metriche Prometheus (#35), fix del DB dei produttori non bloccante (#37), scansione dual-adapter (#33), recupero robusto della scansione con rfkill (#40)

Licenza

Licenza MIT - Vedi LICENSE per i dettagli.

Disclaimer

Questo strumento è solo a scopo educativo. Sii consapevole delle leggi sulla privacy nella tua giurisdizione quando monitori dispositivi Bluetooth. L'autore non è responsabile per qualsiasi uso improprio di questo software.

Creato da Danny McClelland