Bluehood

Quartier Bluetooth - Suivez les appareils BLE dans votre zone et analysez les schémas de trafic.

ATTENTION : Logiciel en version alpha

Ce projet est en début de développement et n'est pas prêt pour une utilisation en production. Les fonctionnalités peuvent changer, casser ou être supprimées sans préavis. Utilisez-le à vos risques et périls. Les données collectées doivent être considérées comme expérimentales.

Captures d'écran

Tableau de bord principal montrant la liste des appareils avec filtrage, recherche et statistiques en temps réel

Paramètres Page de configuration à onglets — Alertes, Opérations, Groupes et Sécurité

À propos Page d'informations avec les détails du projet et un aperçu des capacités

Pourquoi ?

Ce projet a été inspiré par la vulnérabilité WhisperPair (CVE-2025-36911), qui a mis en évidence les risques pour la vie privée des appareils Bluetooth.

Des milliers d'appareils Bluetooth nous entourent en permanence : téléphones, voitures, téléviseurs, écouteurs, appareils auditifs, véhicules de livraison, et bien d'autres. Bluehood démontre à quel point il est simple de détecter passivement ces appareils et d'observer des schémas dans leur présence.

Avec suffisamment de données, vous pourriez potentiellement :

Comprendre à quelle heure quelqu'un promène habituellement son chien
Détecter quand un visiteur arrive chez une personne
Identifier des schémas dans les routines quotidiennes basés sur la présence des appareils

Ces métadonnées peuvent révéler des informations étonnamment personnelles sans aucune interaction active avec les appareils.

Bluehood est un outil éducatif visant à sensibiliser à la confidentialité Bluetooth. C'est un projet de week-end, mais les implications méritent réflexion.

Quoi ?

Bluehood est un scanner Bluetooth qui :

Analyse en continu les appareils Bluetooth à proximité (BLE et Classique)
Identifie les appareils par fabricant (recherche d'adresse MAC) et par UUID de service BLE
Classe les appareils en catégories (téléphones, audio, wearables, IoT, véhicules, etc.)
Suit les schémas de présence au fil du temps avec des cartes de chaleur horaires/quotidiennes
Filtre le bruit des adresses MAC randomisées (appareils à rotation de confidentialité)
Analyse les corrélations d'appareils pour trouver ceux qui apparaissent ensemble
Envoie des notifications push lorsque des appareils surveillés arrivent ou partent
Fournit un tableau de bord web pour la surveillance et l'analyse

Fonctionnalités

Scanner

Scan double mode : Bluetooth Low Energy (BLE) et Bluetooth classique
Recherche de fabricant par adresse MAC (base de données locale + repli API en ligne)
Empreintes digitales UUID de service BLE pour une classification précise des appareils
Analyse de la classe d'appareil Bluetooth classique
Filtrage des MAC randomisées (cachées de la vue principale)

Gestion des appareils

Marquer les appareils comme « Surveillés » pour le suivi des appareils personnels
Organiser les appareils en groupes personnalisés
Définir des noms conviviaux pour les appareils connus
Ajouter des notes/balises personnalisées à tout appareil
Détection du type d'appareil (téléphones, audio, wearables, IoT, véhicules, etc.)

Analyses

Visualisation de la chronologie de présence sur 30 jours
Historique de la force du signal (RSSI) avec données sur 7 jours
Cartes de chaleur d'activité horaires et quotidiennes montrant quand les appareils sont actifs
Analyse de schémas (« Jours de semaine, soirs 17h-21h »)
Analyse du temps de présence montrant le temps total que les appareils passent à portée
Détection de corrélation d'appareils pour trouver ceux qui apparaissent ensemble
Zones de proximité (immédiate, proche, lointaine, éloignée) basées sur la force du signal
Recherche par MAC, fabricant ou nom
Recherche par plage de dates pour des requêtes historiques

Notifications (via ntfy.sh)

Notifications push sur votre téléphone/bureau
Notifier lors de la détection de nouveaux appareils
Notifier lorsque des appareils surveillés reviennent
Notifier lorsque des appareils surveillés partent
Seuils configurables pour l'arrivée/départ

Opérations

Battement de cœur (heartbeat) — publication périodique de l'état sur un service de surveillance de disponibilité (p. ex. Uptime Kuma, Healthchecks.io)
Rotation du stockage — suppression automatique des observations plus anciennes qu'un nombre configurable de jours
Les deux sont configurables depuis l'interface web ou via des variables d'environnement

Interface web

Bascule vue compacte/détaillée pour différentes préférences d'affichage
Mode capture d'écran pour masquer les MAC et les noms pour un partage sécurisé
Raccourcis clavier pour les utilisateurs avancés (appuyez sur ? pour les voir)
Export CSV des données des appareils
Groupes d'appareils pour organiser les appareils liés
Authentification optionnelle pour sécuriser l'accès

Comment ?

Démarrage rapide avec Docker (recommandé)

Prérequis — Hôtes Linux uniquement

Bluehood communique avec votre adaptateur Bluetooth via BlueZ, la pile Bluetooth Linux. BlueZ doit être installé et exécuté sur l'hôte avant de démarrer le conteneur — l'image Docker elle-même ne l'inclut pas.
# Debian / Ubuntu (y compris Ubuntu Server)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth
Sans BlueZ sur l'hôte, vous verrez une erreur du type : BLE scan error: [org.freedesktop.DBus.Error.ServiceUnknown] The name org.bluez was not provided by any .service files

# Créez un fichier docker-compose.yml ou téléchargez celui de ce dépôt
# Puis démarrez avec Docker Compose
docker compose up -d

# Afficher les logs
docker compose logs -f

L'image Docker est disponible sur GitHub Container Registry :

ghcr.io/dannymcc/bluehood:latest

Le tableau de bord web sera accessible à l'adresse http://localhost:8080

Prérequis Docker

Docker et Docker Compose
Hôte Linux avec un adaptateur Bluetooth compatible BLE (Bluetooth 4.0+) supportant le rôle Central
BlueZ installé et exécuté sur l'hôte (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Remarque : Les adaptateurs plus anciens (Bluetooth 2.x/3.x) ne supportent pas le scan BLE. Si votre adaptateur ne prend pas en charge le rôle Central BLE, vous verrez : No Bluetooth adapters with BLE 'central' role found.

Remarque : Docker s'exécute en mode privilégié avec le réseau de l'hôte pour l'accès Bluetooth. Ceci est nécessaire pour le scan BLE.

Variables d'environnement Docker

Prérequis pour l'adaptateur Bluetooth

Bluehood nécessite un adaptateur Bluetooth compatible BLE (Bluetooth 4.0 ou ultérieur) avec prise en charge du rôle Central. Les adaptateurs Bluetooth 2.x/3.x plus anciens ne supportent pas le scan BLE et ne fonctionneront pas.

Si votre adaptateur ne supporte pas le rôle Central BLE, Bluehood se fermera avec le message :

No Bluetooth adapters with BLE 'central' role found

Vous pouvez vérifier les capacités de votre adaptateur avec bluetoothctl show et rechercher central dans les rôles supportés.

Installation manuelle (Linux)

# Installer les dépendances système (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# Installer les dépendances système (Debian/Ubuntu)
sudo apt install bluez python3-pip

# Cloner et installer
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

Permissions Bluetooth

Le scan Bluetooth nécessite des privilèges élevés. Choisissez-en un :

Exécuter en tant que root (le plus simple) :
```
sudo bluehood
```

Accorder des capacités à Python :

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

Utiliser le service systemd (recommandé pour une exécution permanente) :

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

macOS

Bluehood fonctionne nativement sur macOS sans Docker. macOS utilise CoreBluetooth au lieu de BlueZ, ce qui est géré automatiquement par la bibliothèque bleak.

# Cloner le dépôt
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# Créer un environnement virtuel
python3 -m venv .venv
source .venv/bin/activate

# Installer
pip install -e .

# Exécuter
python -m bluehood.daemon

Le tableau de bord web sera accessible à l'adresse http://localhost:8080

Remarque : Lors de la première exécution, macOS vous demandera d'autoriser l'accès Bluetooth. Vous devez accorder cette permission pour que le scan fonctionne.

Utilisation

# Démarrer avec le tableau de bord web (port par défaut 8080)
bluehood

# Spécifier un autre port
bluehood --port 9000

# Utiliser un adaptateur Bluetooth spécifique
bluehood --adapter hci1

# Utiliser des adaptateurs séparés pour le scan BLE et classique (simultané)
bluehood --adapter hci0 --classic-adapter hci1

# Lister les adaptateurs disponibles
bluehood --list-adapters

# Désactiver le tableau de bord web (scan uniquement)
bluehood --no-web

# Activer l'exportateur de métriques Prometheus sur le port 9199
bluehood --metrics-port 9199

Tableau de bord web

Le tableau de bord propose :

Liste des appareils avec icônes de type, fabricant, MAC, nom, observations, dernière apparition
Filtres d'appareils par type (téléphones, audio, IoT, etc.) et statut surveillé
Recherche par MAC, fabricant ou nom
Recherche par plage de dates pour trouver les appareils vus dans une fenêtre temporelle spécifique
Page de paramètres à onglets — Alertes, Opérations, Groupes, Sécurité (lien direct via hachage, p. ex. /settings#operations)
Fenêtre modale des détails de l'appareil avec :
- Empreintes de service BLE
- Cartes de chaleur d'activité horaires/quotidiennes
- Chronologie de présence sur 30 jours
- Historique de la force du signal (RSSI)
- Analyse de schémas
- Statistiques de temps de présence
- Liste des appareils corrélés
- Indicateur de zone de proximité
- Champ de notes d'opérateur
- Affectation de groupe

Raccourcis clavier

Mode capture d'écran

Activez le mode capture d'écran depuis la barre latérale pour masquer les données sensibles avant de partager des captures d'écran :

Les adresses MAC n'affichent que les 2 premiers octets (p. ex., AA:BB:XX:XX:XX:XX)
Les noms conviviaux n'affichent que les 2 premiers caractères (p. ex., Da********)
Les exports CSV respectent également le mode capture d'écran

Notifications push

Bluehood peut envoyer des notifications push via ntfy.sh, un service de notification gratuit et open-source.

Créez un sujet sur ntfy.sh (p. ex., bluehood-myname-alerts)
Abonnez-vous au sujet sur votre téléphone à l'aide de l'application ntfy
Dans les paramètres de Bluehood, saisissez le nom de votre sujet et activez les notifications
Configurez les événements qui déclenchent des notifications :
- Nouvel appareil détecté
- Appareil surveillé de retour (après une absence)
- Appareil surveillé parti (non vu depuis X minutes)

Stockage des données

Les données sont stockées dans ~/.local/share/bluehood/bluehood.db (SQLite).

Remplacez l'emplacement avec les variables d'environnement :

BLUEHOOD_DATA_DIR - Répertoire des fichiers de données
BLUEHOOD_DB_PATH - Chemin direct vers le fichier de base de données

Remarque : Les paramètres de battement de cœur et de nettoyage peuvent être configurés depuis l'interface web (Paramètres > Opérations) ou via des variables d'environnement. Les valeurs de l'interface graphique priment sur les variables d'environnement.

Comment ça fonctionne

Classification des appareils

Bluehood classe les appareils en utilisant plusieurs signaux (par ordre de priorité) :

UUID de service BLE - Le plus précis (Fréquence cardiaque = wearable, A2DP = audio, etc.)
Motifs dans les noms d'appareils - « iPhone », « Galaxy », « AirPods », etc.
Recherche OUI du fabricant - Apple, Samsung, Bose, etc.

MAC randomisées

Les appareils modernes randomisent leurs adresses MAC pour la confidentialité. Bluehood :

Détecte les MAC randomisées (bit d'administration locale)
Les cache de la liste principale des appareils (inutiles pour le suivi)
Affiche un compte des appareils randomisés cachés

Analyse de schémas

Bluehood analyse les horodatages des observations pour détecter des schémas :

Moment de la journée : Matin, Après-midi, Soir, Nuit
Jour de la semaine : Jours ouvrables, Week-ends
Fréquence : Constante, Quotidienne, Régulière, Occasionnelle, Rare

Exemples de schémas : « Quotidien, soirs (17h-21h) », « Jours ouvrables, matin (8h-12h) »

Corrélation d'appareils

Bluehood détecte les appareils qui apparaissent fréquemment ensemble dans une fenêtre temporelle configurable. Cela peut révéler :

Les appareils appartenant à la même personne (téléphone + montre connectée)
Les personnes qui voyagent ensemble
Les appareils qui partagent un emploi du temps

Zones de proximité

En fonction de la force du signal RSSI, les appareils sont classés en zones de proximité :

Immédiate (> -50 dBm) : Très proche, à quelques mètres
Proche (-50 à -60 dBm) : À proximité, même pièce
Lointaine (-60 à -70 dBm) : Plus loin, pièces adjacentes
Éloignée (< -70 dBm) : Distant, en limite de portée de détection

Analyse du temps de présence

Suit le temps que les appareils passent à portée en analysant les écarts entre les observations. Un seuil d'écart configurable (par défaut 15 minutes) détermine quand une nouvelle « session » commence.

Métriques Prometheus

Bluehood peut exposer des métriques pour le scraping Prometheus. Activez en définissant la variable d'environnement BLUEHOOD_METRICS_PORT ou le flag CLI --metrics-port.

# Via variable d'environnement
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Les métriques sont servies à http://host:9199/metrics.

Métriques disponibles

Tableau de bord Grafana

Un tableau de bord Grafana prêt à importer est inclus dans grafana/bluehood-dashboard.json. Importez-le via l'interface Grafana (Tableaux de bord > Importer) ou via l'API :

curl -X POST "http://localhost:3000/api/dashboards/db" \
  -H "Authorization: Bearer <votre-clé-api>" \
  -H "Content-Type: application/json" \
  -d "{\"dashboard\": $(cat grafana/bluehood-dashboard.json), \"overwrite\": true}"

Dépannage

Aucun appareil trouvé

Assurez-vous que votre adaptateur supporte le BLE (Bluetooth 4.0+) avec le rôle Central — les adaptateurs plus anciens ne fonctionneront pas
Assurez-vous que l'adaptateur Bluetooth est activé : bluetoothctl power on
Vérifiez que l'adaptateur est détecté : bluehood --list-adapters
Exécutez avec sudo si l'accès est refusé

Problèmes Docker

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

BlueZ n'est pas installé ou n'est pas en cours d'exécution sur l'hôte. Solution :

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

Liste de vérification générale :

Assurez-vous que BlueZ est installé sur l'hôte (pas seulement dans le conteneur)
Vérifiez que le service Bluetooth est en cours d'exécution : systemctl status bluetooth
Confirmez que votre adaptateur est visible : bluetoothctl list

Contribuer

Les contributions sont les bienvenues ! Veuillez ouvrir une issue ou une PR sur GitHub.

Contributeurs

@martinh2011 (Martin Hüser) - Améliorations du cache des fabricants MAC
@hatedabamboo (Kirill Solovei) - Prise en charge du thème clair
@krnltrp - Améliorations de l'interface web
@jacobpretorius (Jacob Pretorius) - Correction JS d'export CSV (#14), clic pour ouvrir paramètre (#16)
@unqualifiedkoala - Documentation des prérequis de l'adaptateur BLE
@dazzag24 - Signalement d'un problème de format d'adresse macOS
@floese (W.A.Flozart) - Correction double-clic Firefox (#29)
@GeiserX (Sergio Fernández) - Exportateur de métriques Prometheus (#35), correction non bloquante de la base de données fabricants (#37), scan double adaptateur (#33), récupération robuste des scans avec rfkill (#40)

Licence

Licence MIT - Voir LICENSE pour les détails.

Avertissement

Cet outil est destiné à des fins éducatives uniquement. Soyez conscient des lois sur la vie privée dans votre juridiction lorsque vous surveillez des appareils Bluetooth. L'auteur n'est pas responsable de toute utilisation abusive de ce logiciel.

Créé par Danny McClelland

`PUID`	`1000`	UID pour l'utilisateur du conteneur — définissez-le pour correspondre à votre utilisateur hôte (`id -u`) lorsque vous utilisez des montages bind
`PGID`	`1000`	GID pour l'utilisateur du conteneur — définissez-le pour correspondre à votre groupe hôte (`id -g`) lorsque vous utilisez des montages bind
`TZ`	UTC	Fuseau horaire du conteneur (p. ex., `Europe/Paris`)
`BLUEHOOD_ADAPTER`	auto	Adaptateur Bluetooth pour le scan BLE (p. ex., `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	identique à `BLUEHOOD_ADAPTER`	Adaptateur séparé pour le scan Bluetooth classique (p. ex., `hci1`). Lorsqu'il est défini sur un adaptateur différent, les scans BLE et classique s'exécutent simultanément.
`BLUEHOOD_DATA_DIR`	`/data`	Répertoire de stockage de la base de données
`BLUEHOOD_METRICS_PORT`	désactivé	Port des métriques Prometheus (p. ex., `9199`)
`BLUEHOOD_HEARTBEAT_URL`	désactivé	URL pour envoyer les battements de cœur (p. ex., une URL push healthchecks.io ou uptime-kuma)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	Secondes entre les battements de cœur
`BLUEHOOD_PRUNE_DAYS`	`0` (désactivé)	Suppression automatique des observations plus anciennes que N jours pour libérer de l'espace

`/`	Mettre le focus sur la barre de recherche
`r`	Actualiser la liste des appareils
`c`	Basculer la vue compacte
`w`	Basculer la surveillance de l'appareil sélectionné
`Esc`	Fermer la fenêtre modale
`?`	Afficher les raccourcis clavier

`bluehood_scans_total`	Counter	Nombre total de cycles de scan effectués
`bluehood_scan_errors_total`	Counter	Erreurs de scan (label : `scan_type`)
`bluehood_sightings_total`	Counter	Nombre total d'observations d'appareils enregistrées
`bluehood_new_devices_total`	Counter	Nouveaux appareils uniques découverts
`bluehood_last_scan_devices`	Gauge	Appareils lors du dernier scan (label : `scan_type`)
`bluehood_devices_total`	Gauge	Appareils uniques dans la base de données (label : `bt_type`)
`bluehood_devices_active`	Gauge	Appareils vus dans les 5 dernières minutes
`bluehood_devices_watched`	Gauge	Nombre d'appareils surveillés
`bluehood_devices_ignored`	Gauge	Nombre d'appareils ignorés
`bluehood_scan_duration_seconds`	Histogram	Durée du cycle de scan
`bluehood_device_rssi_dbm`	Histogram	Distribution RSSI des appareils BLE
`bluehood_build_info`	Info	Informations de version

Populaires

bluehood