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

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

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

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.

root@kitploit:~

# 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 :

1. Exécuter en tant que root (le plus simple) :

   root@kitploit:~

   sudo bluehood
   

2. Accorder les capacités à Python :

   root@kitploit:~

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

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

   root@kitploit:~

   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.

1. Créez un sujet sur ntfy.sh (par ex., bluehood-myname-alerts), ou sur votre propre serveur ntfy
2. Abonnez-vous au sujet sur votre téléphone à l'aide de l'application ntfy
3. 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
4. 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é) :

1. UUID de service BLE - Le plus précis (Heart Rate = objet connecté portable, A2DP = audio, etc.)
2. Schémas de nom d'appareil - « iPhone », « Galaxy », « AirPods », etc.
3. 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