Bluehood

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

AVERTISSEMENT : Logiciel Alpha

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

Captures d'écran

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

Settings Page de configuration à onglets — Alertes, Opérations, Groupes et Sécurité

About Page Intel avec informations sur le projet et 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 à tout moment : téléphones, voitures, téléviseurs, écouteurs, prothèses auditives, véhicules de livraison, etc. Bluehood démontre à quel point il est simple de détecter passivement ces appareils et d'observer les schémas de leur présence.

Avec suffisamment de données, vous pourriez potentiellement :

Comprendre à quelle heure quelqu'un promène généralement son chien
Détecter quand un visiteur arrive dans une maison
Identifier des schémas dans les routines quotidiennes en fonction de 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 pour 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 :

Scanne en continu les appareils Bluetooth à proximité (BLE et Classic)
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, objets connectés portables, IoT, véhicules, etc.)
Suit les schémas de présence dans le temps avec des cartes thermiques horaires/quotidiennes
Filtre le bruit des adresses MAC randomisées (appareils à rotation de confidentialité)
Analyse les corrélations entre appareils pour trouver les appareils qui apparaissent ensemble
Envoie des notifications push lorsque les appareils surveillés arrivent ou partent
Fournit un tableau de bord web pour la surveillance et l'analyse

Fonctionnalités

Scan

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

Gestion des appareils

Marquer les appareils comme « Surveillés » pour suivre les appareils personnels
Organiser les appareils en groupes personnalisés
Donner un nom personnalisé aux appareils (le nom annoncé reste visible à côté)
Remplacer la classification détectée de tout appareil
Ajouter des notes/tags personnalisés à tout appareil
Détection du type d'appareil (téléphones, audio, objets connectés portables, IoT, véhicules, etc.)

Analytique

Visualisation de la chronologie de présence sur 30 jours
Graphique de l'historique de la force du signal (RSSI) avec données sur 7 jours
Cartes thermiques d'activité horaire et quotidienne montrant quand les appareils sont actifs
Analyse des schémas (« Jours de semaine, soirées 17h-21h »)
Analyse du temps de séjour montrant le temps total que les appareils passent à portée
Détection de corrélation entre appareils pour trouver les appareils qui apparaissent ensemble (co-présence plus arrivée/départ synchronisés)
Liaison par rotation de MAC (« Probablement le même appareil ») — relie heuristiquement les identifiants randomisés qui se relaient dans le temps, partagent une force de signal similaire et émettent à une cadence similaire
Zones de proximité (immédiate, proche, éloignée, distante) basées sur la force du signal
Recherche par MAC, fabricant ou nom
Recherche par plage de dates pour les requêtes historiques

Notifications (via ntfy)

Notifications push vers votre téléphone/bureau via ntfy.sh ou un serveur ntfy auto-hébergé
Notifier lorsque de nouveaux appareils sont détectés
Notifier lorsque les appareils surveillés reviennent
Notifier lorsque les appareils surveillés partent
Seuils configurables pour l'arrivée/départ

Opérations

Point de contrôle Heartbeat — POST périodique du statut vers un service de surveillance de disponibilité (par ex., Uptime Kuma, Healthchecks.io)
Rotation du stockage — élaguer automatiquement les observations plus anciennes qu'un nombre configurable de jours ; éventuellement restreindre l'élagage aux appareils obsolètes entiers vus moins d'un nombre minimum de fois (les appareils surveillés ne sont jamais élagués)
Les deux 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 obscurcir les MAC et les noms pour un partage sécurisé
Raccourcis clavier pour les utilisateurs avancés (appuyez sur ? pour les afficher)
Export CSV des données détaillées des appareils (MAC, fabricant, identifiant, type, type BT, classe d'appareil, indicateurs surveillé/ignoré, première/dernière vue, observations, groupe, UUID de service et notes) — exporte l'ensemble filtré complet, pas seulement la page actuelle
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 de Linux. BlueZ doit être installé et en cours d'exécution 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 comme : 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'image Docker est disponible sur GitHub Container Registry :

ghcr.io/dannymcc/bluehood:latest

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

Exigences Docker

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

Remarque : Les adaptateurs plus anciens (Bluetooth 2.x/3.x) ne prennent pas en charge le scan BLE. Si votre adaptateur ne prend pas en charge le rôle BLE Central, 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 requis pour le scan BLE.

Variables d'environnement Docker

Exigences de 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 prennent pas en charge le scan BLE et ne fonctionneront pas.

Si votre adaptateur ne prend pas en charge le rôle BLE Central, Bluehood se fermera avec :

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 pris en charge.

Installation manuelle (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 .

Permissions Bluetooth

Le scan Bluetooth nécessite des privilèges élevés. Choisissez l'une des options :

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

Accorder les capacités à Python :

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

Utiliser le service systemd (recommandé pour un fonctionnement continu) :

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.

# 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

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

Remarque : Au premier lancement, macOS vous demandera d'autoriser l'accès Bluetooth. Vous devez accorder cette permission pour que le scan fonctionne.

Utilisation

# 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

Tableau de bord Web

Le tableau de bord fournit :

Liste des appareils avec icônes de type, fabricant, MAC, nom, observations, dernière vue
Filtres d'appareils par type (téléphones, audio, IoT, etc.) et statut de surveillance
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 et Sécurité (lien direct via hash, par ex. /settings#operations)
Modale de détails de l'appareil avec :
- Empreintes de service BLE
- Cartes thermiques d'activité horaire/quotidienne
- Chronologie de présence sur 30 jours
- Graphique de l'historique de la force du signal (RSSI)
- Analyse des schémas
- Statistiques de temps de séjour
- Liste des appareils corrélés
- Liste des appareils probablement identiques (rotation de MAC)
- Indicateur de zone de proximité
- Champ de notes de l'opérateur
- Attribution de groupe

Raccourcis clavier

Mode capture d'écran

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

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

Notifications Push

Bluehood peut envoyer des notifications push via ntfy, un service de notification gratuit et open-source. Vous pouvez utiliser le serveur public ntfy.sh ou votre propre instance auto-hébergée.

Créez un sujet sur ntfy.sh (par ex., bluehood-myname-alerts), ou sur votre propre serveur ntfy
Abonnez-vous au sujet sur votre téléphone à l'aide de l'application ntfy
Dans les paramètres de Bluehood, saisissez l'URL du serveur (par défaut https://ntfy.sh), le nom de votre sujet et un jeton d'accès si votre serveur en exige un, puis activez les notifications
Configurez les événements qui déclenchent les notifications :
- Nouvel appareil détecté
- Retour d'un appareil surveillé (après avoir été absent)
- Départ d'un appareil surveillé (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 des variables d'environnement :

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

Remarque : Les paramètres de heartbeat et d'élagage peuvent être configurés depuis l'interface web (Paramètres > Opérations) ou via des variables d'environnement. Les valeurs de l'interface graphique sont prioritaires 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 (Heart Rate = objet connecté portable, A2DP = audio, etc.)
Schémas de nom d'appareil - « iPhone », « Galaxy », « AirPods », etc.
Recherche de fabricant par OUI - 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 administré localement)
Les masque de la liste principale des appareils (inutiles pour le suivi)
Affiche un compteur des appareils randomisés masqués

Analyse des 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 de semaine, Week-ends
Fréquence : Constant, Quotidien, Régulier, Occasionnel, Rare

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

Corrélation entre appareils

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

Des appareils appartenant à la même personne (téléphone + montre connectée)
Des personnes qui voyagent ensemble
Des 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
Éloignée (-60 à -70 dBm) : Plus loin, pièces adjacentes
Distante (< -70 dBm) : Lointaine, à la limite de la portée de détection

Analyse du temps de séjour

Suit combien de temps 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 l'option CLI --metrics-port.

# Via environment variable
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 à grafana/bluehood-dashboard.json. Importez-le via l'interface Grafana (Dashboards > Import) ou 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}"

Dépannage

Aucun appareil trouvé

Assurez-vous que votre adaptateur prend en charge 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 permission refusée

Problèmes Docker

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

BlueZ n'est pas installé ou ne fonctionne pas sur l'hôte. Correction :

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

Contribution

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

Contributeurs

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

Licence

Licence MIT - Voir LICENSE pour plus de détails.

Avertissement

Cet outil est destiné à des fins éducatives uniquement. Soyez attentif aux lois sur la vie privée dans votre juridiction lors de la surveillance d'appareils Bluetooth. L'auteur n'est pas responsable de toute mauvaise utilisation de ce logiciel.

Créé par Danny McClelland

`PUID`	`1000`	UID pour l'utilisateur du conteneur — à définir pour correspondre à votre utilisateur hôte (`id -u`) lors de l'utilisation de montages bind
`PGID`	`1000`	GID pour l'utilisateur du conteneur — à définir pour correspondre à votre groupe hôte (`id -g`) lors de l'utilisation de montages bind
`TZ`	UTC	Fuseau horaire du conteneur (par ex., `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	Adaptateur Bluetooth pour le scan BLE (par ex., `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	identique à `BLUEHOOD_ADAPTER`	Adaptateur séparé pour le scan Bluetooth classic (par ex., `hci1`). Lorsqu'il est défini sur un adaptateur différent, les scans BLE et classic s'exécutent simultanément.
`BLUEHOOD_DATA_DIR`	`/data`	Répertoire de stockage de la base de données
`BLUEHOOD_PORT`	`8080`	Port du tableau de bord web. Le conteneur utilise le réseau de l'hôte, donc modifiez ceci (plutôt qu'un mappage de port) si 8080 est occupé
`BLUEHOOD_NTFY_SERVER`	`https://ntfy.sh`	URL de base du serveur ntfy pour les notifications push ; pointez-le vers une instance auto-hébergée. La valeur enregistrée dans la page Paramètres est prioritaire
`BLUEHOOD_METRICS_PORT`	désactivé	Port des métriques Prometheus (par ex., `9199`)
`BLUEHOOD_HEARTBEAT_URL`	désactivé	URL pour POSTer les points de contrôle heartbeat (par ex., une URL push healthchecks.io ou uptime-kuma)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	Secondes entre les points de contrôle heartbeat
`BLUEHOOD_PRUNE_DAYS`	`0` (désactivé)	Supprimer automatiquement les observations plus anciennes que N jours pour libérer du stockage
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0` (désactivé)	Lorsque >0, élaguer les appareils obsolètes entiers (plus anciens que `BLUEHOOD_PRUNE_DAYS` et avec moins de N observations totales) au lieu de simplement supprimer les anciennes lignes d'observation ; les appareils surveillés ne sont jamais élagués

`/`	Focus sur la barre de recherche
`r`	Rafraîchir la liste des appareils
`c`	Basculer la vue compacte
`w`	Basculer la surveillance sur l'appareil sélectionné
`Esc`	Fermer la modale
`?`	Afficher les raccourcis clavier

`bluehood_scans_total`	Counter	Total des cycles de scan terminés
`bluehood_scan_errors_total`	Counter	Erreurs de scan (label : `scan_type`)
`bluehood_sightings_total`	Counter	Total des 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