Monitora l'attività Bluetooth del tuo quartiere.
# Bluehood
**Bluetooth Neighborhood** - Traccia i dispositivi BLE nella tua area e analizza i pattern di traffico.
[](https://buymeacoffee.com/d3hkz6gwle)
---
> **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](https://whisperpair.eu/) ([CVE-2025-36911](https://nvd.nist.gov/vuln/detail/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.
>
> ```bash
> # 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`
```bash
# 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
| Variabile | Predefinito | Descrizione |
|----------|---------|-------------|
| `PUID` | `1000` | UID per l'utente del container — impostalo per corrispondere al tuo utente host (`id -u`) quando usi bind mount |
| `PGID` | `1000` | GID per l'utente del container — impostalo per corrispondere al tuo gruppo host (`id -g`) quando usi bind mount |
| `TZ` | UTC | Fuso orario del container (es. `Europe/London`) |
| `BLUEHOOD_ADAPTER` | auto | Adattatore Bluetooth per la scansione BLE (es. `hci0`) |
| `BLUEHOOD_CLASSIC_ADAPTER` | uguale a `BLUEHOOD_ADAPTER` | Adattatore separato per la scansione Bluetooth classic (es. `hci1`). Se impostato su un adattatore diverso, le scansioni BLE e classic vengono eseguite contemporaneamente. |
| `BLUEHOOD_DATA_DIR` | `/data` | Directory di archiviazione del database |
| `BLUEHOOD_PORT` | `8080` | Porta della dashboard web. Il container usa il networking host, quindi cambia questa (invece di una mappatura delle porte) se la 8080 è occupata |
| `BLUEHOOD_NTFY_SERVER` | `https://ntfy.sh` | URL base del server ntfy per le notifiche push; puntalo a un'istanza self-hosted. Il valore salvato nella pagina Impostazioni ha la precedenza |
| `BLUEHOOD_METRICS_PORT` | disabilitato | Porta delle metriche Prometheus (es. `9199`) |
| `BLUEHOOD_HEARTBEAT_URL` | disabilitato | URL a cui inviare i check-in heartbeat tramite POST (es. un URL push di healthchecks.io o uptime-kuma) |
| `BLUEHOOD_HEARTBEAT_INTERVAL` | `300` | Secondi tra i check-in heartbeat |
| `BLUEHOOD_PRUNE_DAYS` | `0` (disabilitato) | Elimina automaticamente gli avvistamenti più vecchi di N giorni per liberare spazio |
| `BLUEHOOD_PRUNE_MIN_SIGHTINGS` | `0` (disabilitato) | Se >0, elimina interi dispositivi obsoleti (più vecchi di `BLUEHOOD_PRUNE_DAYS` e con meno di N avvistamenti totali) invece di limitarsi a rimuovere le righe di avvistamento vecchie; i dispositivi monitorati non vengono mai eliminati |
### 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)
```bash
# 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):
```bash
sudo bluehood
```
2. **Concedi le capabilities a Python**:
```bash
sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
bluehood
```
3. **Usa il servizio systemd** (consigliato per l'esecuzione continua):
```bash
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`.
```bash
# 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
```bash
# 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
| Tasto | Azione |
|-----|--------|
| `/` | Attiva la barra di ricerca |
| `r` | Aggiorna l'elenco dei dispositivi |
| `c` | Attiva/disattiva la vista compatta |
| `w` | Attiva/disattiva il monitoraggio sul dispositivo selezionato |
| `Esc` | Chiudi la modale |
| `?` | Mostra le 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](https://ntfy.sh), 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`.
```bash
# 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
| Metrica | Tipo | Descrizione |
|--------|------|-------------|
| `bluehood_scans_total` | Counter | Cicli di scansione totali completati |
| `bluehood_scan_errors_total` | Counter | Errori di scansione (label: `scan_type`) |
| `bluehood_sightings_total` | Counter | Avvistamenti totali dei dispositivi registrati |
| `bluehood_new_devices_total` | Counter | Nuovi dispositivi unici scoperti |
| `bluehood_last_scan_devices` | Gauge | Dispositivi nell'ultima scansione (label: `scan_type`) |
| `bluehood_devices_total` | Gauge | Dispositivi unici nel DB (label: `bt_type`) |
| `bluehood_devices_active` | Gauge | Dispositivi visti negli ultimi 5 minuti |
| `bluehood_devices_watched` | Gauge | Conteggio dei dispositivi monitorati |
| `bluehood_devices_ignored` | Gauge | Conteggio dei dispositivi ignorati |
| `bluehood_scan_duration_seconds` | Histogram | Durata del ciclo di scansione |
| `bluehood_device_rssi_dbm` | Histogram | Distribuzione RSSI dei dispositivi BLE |
| `bluehood_build_info` | Info | Informazioni sulla versione |
### Dashboard Grafana
Una dashboard Grafana pronta per l'importazione è inclusa in [`grafana/bluehood-dashboard.json`](https://github.com/dannymcc/bluehood/blob/master/grafana/bluehood-dashboard.json). Importala tramite la UI di Grafana (Dashboards > Import) o l'API:
```bash
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:
```bash
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](https://github.com/martinh2011) (Martin Hüser) - Miglioramenti alla cache dei produttori MAC
- [@hatedabamboo](https://github.com/hatedabamboo) (Kirill Solovei) - Supporto al tema chiaro
- [@krnltrp](https://github.com/krnltrp) - Miglioramenti alla UI web
- [@jacobpretorius](https://github.com/jacobpretorius) (Jacob Pretorius) - Fix JS dell'esportazione CSV (#14), click per aprire le impostazioni (#16)
- [@unqualifiedkoala](https://github.com/unqualifiedkoala) - Documentazione dei requisiti dell'adattatore BLE
- [@dazzag24](https://github.com/dazzag24) - Segnalazione del problema del formato dell'indirizzo su macOS
- [@floese](https://github.com/floese) (W.A.Flozart) - Fix del doppio click su Firefox (#29)
- [@GeiserX](https://github.com/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](https://github.com/dannymcc/bluehood/blob/master/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](https://github.com/dannymcc)