Bluehood

Bluetooth Neighborhood - Tieni traccia dei dispositivi BLE nella tua zona e analizza i modelli di traffico.

AVVERTENZA: Software Alpha

Questo progetto è in fase iniziale di sviluppo 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 dovrebbero essere considerati sperimentali.

Schermate

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

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

Pagina Informazioni con panoramica del progetto e delle capacità

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 consegne e altro ancora. Bluehood dimostra quanto sia semplice rilevare passivamente questi dispositivi e osservare pattern nella loro presenza.

Con abbastanza dati, 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 basati sulla presenza di 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 del fine settimana, ma le implicazioni meritano di essere considerate.

Cosa?

Bluehood è uno scanner Bluetooth che:

• Esegue scansioni continue dei dispositivi Bluetooth nelle vicinanze (sia BLE che Classic)
• Identifica i dispositivi per produttore (ricerca MAC address) e UUID dei servizi BLE
• Classifica i dispositivi in categorie (telefoni, audio, indossabili, IoT, veicoli, ecc.)
• Tiene traccia dei 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 osservati arrivano o se ne vanno
• Fornisce un dashboard web per monitoraggio e analisi

Funzionalità

Scansione

• Scansione dual-mode: Bluetooth Low Energy (BLE) e Bluetooth Classic
• Ricerca produttore MAC address (database locale + fallback API online)
• Impronta digitale UUID dei servizi BLE per una classificazione accurata dei dispositivi
• Analisi della classe dei dispositivi Bluetooth Classic
• Filtro MAC randomizzati (nascosto dalla vista principale)

Gestione Dispositivi

• Segna dispositivi come "Osservati" per tracciare dispositivi personali
• Organizza i dispositivi in gruppi personalizzati
• Imposta nomi amichevoli per dispositivi conosciuti
• Aggiungi note/etichette personalizzate a qualsiasi dispositivo
• Rilevamento del tipo di dispositivo (telefoni, audio, indossabili, IoT, veicoli, ecc.)

Analisi

• Visualizzazione della timeline di presenza di 30 giorni
• Grafico della cronologia dell'intensità del segnale (RSSI) con dati di 7 giorni
• Mappe di calore dell'attività oraria e giornaliera che mostrano quando i dispositivi sono attivi
• Analisi dei pattern ("Giorni feriali, serate 17:00-21:00")
• Analisi del tempo di permanenza che mostra il tempo totale che i dispositivi passano nel raggio
• Rilevamento della correlazione tra dispositivi per trovare dispositivi che appaiono insieme
• Zone di prossimità (immediato, vicino, lontano, remoto) basate sull'intensità del segnale
• Ricerca per MAC, produttore o nome
• Ricerca per intervallo di date per query storiche

Notifiche (tramite ntfy.sh)

• Notifiche push sul telefono/desktop
• Notifica quando vengono rilevati nuovi dispositivi
• Notifica quando i dispositivi osservati tornano
• Notifica quando i dispositivi osservati se ne vanno
• Soglie configurabili per arrivo/partenza

Operazioni

• Heartbeat check-in — invia periodicamente lo stato 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
• Entrambi configurabili dall'interfaccia web o tramite variabili d'ambiente

Interfaccia Web

• Interruttore 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 visualizzare)
• Esportazione CSV dei dati dei dispositivi
• 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

# Crea un docker-compose.yml o scarica quello da questo repository
# Quindi avvia con Docker Compose
docker compose up -d

# Visualizza i log
docker compose logs -f

L'immagine Docker è disponibile su GitHub Container Registry:

ghcr.io/dannymcc/bluehood:latest

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

Requisiti Docker

• Docker e Docker Compose
• Host Linux con un adattatore Bluetooth con supporto 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 ha il supporto per il ruolo Central BLE, 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 con supporto BLE (Bluetooth 4.0 o successivo) con supporto del 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 Central BLE, Bluehood terminerà con:

No Bluetooth adapters with BLE 'central' role found

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

Installazione Manuale (Linux)

# Installa le dipendenze di sistema (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# Installa le dipendenze di sistema (Debian/Ubuntu)
sudo apt install bluez python3-pip

# Clona e installa
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

Permessi Bluetooth

La scansione Bluetooth richiede privilegi elevati. Scegli una opzione:

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

   root@kitploit:~

   sudo bluehood
   

2. Concedi capacità 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 sempre acceso):

   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, gestito automaticamente dalla libreria bleak.

# Clona il repository
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# Crea un ambiente virtuale
python3 -m venv .venv
source .venv/bin/activate

# Installa
pip install -e .

# Esegui
python -m bluehood.daemon

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

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

Utilizzo

# Avvia con dashboard web (porta predefinita 8080)
bluehood

# Specifica una porta diversa
bluehood --port 9000

# Usa un adattatore Bluetooth specifico
bluehood --adapter hci1

# Usa adattatori separati per scansione BLE e classica (contemporanea)
bluehood --adapter hci0 --classic-adapter hci1

# Elenca gli adattatori disponibili
bluehood --list-adapters

# Disabilita il dashboard web (solo scansione)
bluehood --no-web

# Abilita l'esportatore di metriche Prometheus sulla porta 9199
bluehood --metrics-port 9199

Dashboard Web

Il dashboard fornisce:

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

Scorciatoie da Tastiera

Modalità Screenshot

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

• Gli indirizzi MAC mostrano solo i primi 2 ottetti (es. AA:BB:XX:XX:XX:XX)
• I nomi amichevoli 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.sh, un servizio di notifica gratuito e open-source.

1. Crea un topic su ntfy.sh (es. bluehood-myname-alerts)
2. Iscriviti al topic sul tuo telefono usando l'app ntfy
3. Nelle impostazioni di Bluehood, inserisci il nome del topic e abilita le notifiche
4. Configura quali eventi attivano le notifiche:
   • Nuovo dispositivo rilevato
   • Dispositivo osservato torna (dopo essere stato assente)
   • Dispositivo osservato se ne va (non visto per X minuti)

Archiviazione Dati

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

Sovrascrivi la posizione con 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 dall'interfaccia web (Impostazioni > Operazioni) o tramite variabili d'ambiente. I valori dell'interfaccia grafica hanno la priorità sulle variabili d'ambiente.

Come Funziona

Classificazione dei Dispositivi

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

1. UUID dei servizi BLE - Più accurati (Heart Rate = indossabile, A2DP = audio, ecc.)
2. Pattern dei nomi dei dispositivi - "iPhone", "Galaxy", "AirPods", ecc.
3. Ricerca OUI del produttore - Apple, Samsung, Bose, ecc.

MAC Randomizzati

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

• Rileva MAC randomizzati (bit di amministrazione locale)
• 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, Giornaliero, Regolare, Occasionale, Raro

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

Correlazione tra Dispositivi

Bluehood rileva dispositivi che appaiono frequentemente insieme entro 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à

Basandosi sull'intensità del segnale RSSI, i dispositivi sono classificati in zone di prossimità:

• Immediato (> -50 dBm): Molto vicino, entro pochi metri
• Vicino (da -50 a -60 dBm): Nelle vicinanze, stessa stanza
• Lontano (da -60 a -70 dBm): Più distante, stanze adiacenti
• Remoto (< -70 dBm): Distante, al limite del raggio di rilevamento

Analisi del Tempo di Permanenza

Tiene traccia di quanto tempo i dispositivi passano nel raggio analizzando gli intervalli tra gli avvistamenti. Una soglia di intervallo configurabile (default 15 minuti) determina quando inizia una nuova "sessione".

Metriche Prometheus

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

# Tramite variabile d'ambiente
export BLUEHOOD_METRICS_PORT=9199

# Tramite CLI
bluehood --metrics-port 9199

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

Metriche Disponibili

Dashboard Grafana

Un dashboard Grafana pronto per l'importazione è incluso in grafana/bluehood-dashboard.json. Importalo tramite l'interfaccia Grafana (Dashboard > Import) o tramite 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
• Controlla che l'adattatore sia rilevato: bluehood --list-adapters
• Esegui con sudo se il permesso è negato

Problemi 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. Risolvi:

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

Lista di controllo 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 un issue o una PR su GitHub.

Collaboratori

• @martinh2011 (Martin Hüser) - Miglioramenti cache produttore MAC
• @hatedabamboo (Kirill Solovei) - Supporto tema chiaro
• @krnltrp - Miglioramenti interfaccia web
• @jacobpretorius (Jacob Pretorius) - Correzione JS esportazione CSV (#14), clic per aprire impostazioni (#16)
• @unqualifiedkoala - Requisiti adattatore BLE documentati
• @dazzag24 - Segnalato problema formato indirizzo macOS
• @floese (W.A.Flozart) - Correzione doppio clic Firefox (#29)
• @GeiserX (Sergio Fernández) - Esportatore metriche Prometheus (#35), correzione database produttori non bloccante (#37), scansione dual-adattatore (#33), recupero robusto scansione con rfkill (#40)

Licenza

Licenza MIT - Vedi LICENSE per i dettagli.

Disclaimer

Questo strumento è solo a scopo educativo. Presta attenzione alle 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