Bluehood

Bluetooth Neighborhood – Verfolge BLE-Geräte in deiner Umgebung und analysiere Verkehrsmuster.

WARNUNG: Alpha-Software

Dieses Projekt befindet sich in einer frühen Entwicklungsphase und ist nicht für den Produktiveinsatz geeignet. Funktionen können sich ändern, fehlschlagen oder ohne Vorankündigung entfernt werden. Nutzung auf eigenes Risiko. Gesammelte Daten sollten als experimentell betrachtet werden.

Screenshots

Hauptdashboard mit Geräteliste, Filterung, Suche und Echtzeitstatistiken

Tab-basierte Konfigurationsseite – Alerts, Operations, Groups und Security

Intel-Seite mit Projektinformationen und Funktionsübersicht

Warum?

Dieses Projekt wurde durch die WhisperPair-Schwachstelle (CVE-2025-36911) inspiriert, die Datenschutzrisiken bei Bluetooth-Geräten aufgezeigt hat.

Tausende Bluetooth-Geräte umgeben uns ständig: Telefone, Autos, Fernseher, Kopfhörer, Hörgeräte, Lieferfahrzeuge und mehr. Bluehood demonstriert, wie einfach es ist, diese Geräte passiv zu erkennen und Muster in ihrer Anwesenheit zu beobachten.

Mit genügend Daten könnte man potenziell:

• Verstehen, wann jemand typischerweise mit dem Hund spazieren geht
• Erkennen, wann ein Besucher an einem Haus ankommt
• Muster in täglichen Routinen basierend auf der Geräteanwesenheit identifizieren

Diese Metadaten können überraschend persönliche Informationen preisgeben, ohne dass eine aktive Interaktion mit den Geräten erforderlich ist.

Bluehood ist ein Bildungswerkzeug, um das Bewusstsein für Bluetooth-Datenschutz zu schärfen. Es ist ein Wochenendprojekt, aber die Implikationen sind es wert, darüber nachzudenken.

Was?

Bluehood ist ein Bluetooth-Scanner, der:

• Kontinuierlich scannt nach Bluetooth-Geräten in der Nähe (sowohl BLE als auch Classic)
• Geräte identifiziert nach Hersteller (MAC-Adressen-Lookup) und BLE-Service-UUIDs
• Geräte klassifiziert in Kategorien (Telefone, Audio, Wearables, IoT, Fahrzeuge usw.)
• Anwesenheitsmuster verfolgt über die Zeit mit stündlichen/täglichen Heatmaps
• Rauschen herausfiltert von randomisierten MAC-Adressen (datenschutzrotierte Geräte)
• Gerätekorrelationen analysiert, um Geräte zu finden, die zusammen erscheinen
• Push-Benachrichtigungen sendet, wenn überwachte Geräte ankommen oder gehen
• Ein Web-Dashboard bereitstellt für Überwachung und Analyse

Funktionen

Scannen

• Dual-Modus-Scannen: Bluetooth Low Energy (BLE) und Classic Bluetooth
• MAC-Adressen-Hersteller-Lookup (lokale Datenbank + Online-API-Fallback)
• BLE-Service-UUID-Fingerprinting für präzise Geräteklassifizierung
• Classic-Bluetooth-Geräteklassen-Parsing
• Randomisierte MAC-Filterung (in der Hauptansicht ausgeblendet)

Geräteverwaltung

• Geräte als „Watched" markieren, um persönliche Geräte zu verfolgen
• Geräte in benutzerdefinierte Gruppen organisieren
• Geräten einen benutzerdefinierten Namen geben (der beworbene Name bleibt daneben sichtbar)
• Die erkannte Klassifizierung eines Geräts überschreiben
• Benutzerdefinierte Notizen/Tags zu jedem Gerät hinzufügen
• Gerätetyp-Erkennung (Telefone, Audio, Wearables, IoT, Fahrzeuge usw.)

Analysen

• 30-Tage-Anwesenheits-Timeline-Visualisierung
• Signalstärke (RSSI)-Verlauf-Diagramm mit 7-Tage-Daten
• Stündliche und tägliche Aktivitäts-Heatmaps, die zeigen, wann Geräte aktiv sind
• Musteranalyse („Werktags, abends 17:00–21:00 Uhr")
• Aufenthaltsdauer-Analyse, die die Gesamtzeit zeigt, die Geräte in Reichweite verbringen
• Gerätekorrelations-Erkennung, um Geräte zu finden, die zusammen erscheinen (Ko-Präsenz plus synchronisiertes Ankommen/Verlassen)
• MAC-Rotations-Verknüpfung („Wahrscheinlich dasselbe Gerät") – verknüpft heuristisch randomisierte Identifikatoren, die zeitlich übergeben, eine ähnliche Signalstärke teilen und in ähnlicher Kadenz pingen
• Näherungszonen (unmittelbar, nah, fern, entfernt) basierend auf Signalstärke
• Suche nach MAC, Hersteller oder Name
• Datumsbereichssuche für historische Abfragen

Benachrichtigungen (über ntfy)

• Push-Benachrichtigungen auf dein Telefon/Desktop über ntfy.sh oder einen selbst gehosteten ntfy-Server
• Benachrichtigung, wenn neue Geräte erkannt werden
• Benachrichtigung, wenn überwachte Geräte zurückkehren
• Benachrichtigung, wenn überwachte Geräte gehen
• Konfigurierbare Schwellenwerte für Ankunft/Abgang

Betrieb

• Heartbeat-Check-in – regelmäßiges POSTen des Status an einen Uptime-Überwachungsdienst (z. B. Uptime Kuma, Healthchecks.io)
• Speicherrotation – automatisches Bereinigen von Sichtungen, die älter als eine konfigurierbare Anzahl von Tagen sind; optional Beschränkung der Bereinigung auf ganze veraltete Geräte, die weniger als eine Mindestanzahl von Malen gesehen wurden (überwachte Geräte werden nie bereinigt)
• Beides konfigurierbar über die Web-UI oder über Umgebungsvariablen

Web-Oberfläche

• Kompakt-/Detailansicht-Umschaltung für verschiedene Anzeigepräferenzen
• Screenshot-Modus zum Verschleiern von MACs und Namen für sicheres Teilen
• Tastaturkürzel für Power-User (drücke ? zum Anzeigen)
• CSV-Export detaillierter Gerätedaten (MAC, Hersteller, Identifikator, Typ, BT-Typ, Geräteklasse, Watched/Ignored-Flags, erstmals/zuletzt gesehen, Sichtungen, Gruppe, Service-UUIDs und Notizen) – exportiert das gesamte gefilterte Set, nicht nur die aktuelle Seite
• Gerätegruppen zum Organisieren verwandter Geräte
• Optionale Authentifizierung zum Sichern des Zugriffs

Wie?

Schnellstart mit Docker (Empfohlen)

Voraussetzungen – nur Linux-Hosts

Bluehood kommuniziert mit deinem Bluetooth-Adapter über BlueZ, den Linux-Bluetooth-Stack. BlueZ muss auf dem Host installiert und laufen, bevor der Container gestartet wird – das Docker-Image selbst enthält es nicht.

root@kitploit:~

# Debian / Ubuntu (einschließlich Ubuntu Server)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

Ohne BlueZ auf dem Host siehst du einen Fehler wie: 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

Das Docker-Image ist auf der GitHub Container Registry verfügbar:

ghcr.io/dannymcc/bluehood:latest

Das Web-Dashboard ist unter http://localhost:8080 verfügbar

Docker-Anforderungen

• Docker und Docker Compose
• Linux-Host mit einem BLE-fähigen Bluetooth-Adapter (Bluetooth 4.0+), der die Central-Rolle unterstützt
• BlueZ auf dem Host installiert und laufend (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Hinweis: Ältere Adapter (Bluetooth 2.x/3.x) unterstützen kein BLE-Scannen. Wenn dein Adapter die BLE-Central-Rolle nicht unterstützt, siehst du: No Bluetooth adapters with BLE 'central' role found.

Hinweis: Docker läuft im privilegierten Modus mit Host-Netzwerk für den Bluetooth-Zugriff. Dies ist für BLE-Scannen erforderlich.

Docker-Umgebungsvariablen

Bluetooth-Adapter-Anforderungen

Bluehood erfordert einen BLE-fähigen Bluetooth-Adapter (Bluetooth 4.0 oder neuer) mit Central-Rollenunterstützung. Ältere Bluetooth 2.x/3.x-Adapter unterstützen kein BLE-Scannen und funktionieren nicht.

Wenn dein Adapter die BLE-Central-Rolle nicht unterstützt, beendet sich Bluehood mit:

No Bluetooth adapters with BLE 'central' role found

Du kannst die Fähigkeiten deines Adapters mit bluetoothctl show überprüfen und nach central in den unterstützten Rollen suchen.

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

Bluetooth-Berechtigungen

Bluetooth-Scannen erfordert erhöhte Berechtigungen. Wähle eine:

1. Als root ausführen (am einfachsten):

   root@kitploit:~

   sudo bluehood
   

2. Capabilities an Python vergeben:

   root@kitploit:~

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

3. systemd-Dienst verwenden (empfohlen für Dauerbetrieb):

   root@kitploit:~

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

macOS

Bluehood funktioniert nativ auf macOS ohne Docker. macOS verwendet CoreBluetooth anstelle von BlueZ, was automatisch von der bleak-Bibliothek gehandhabt wird.

# 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

Das Web-Dashboard ist unter http://localhost:8080 verfügbar

Hinweis: Beim ersten Start fordert macOS dich auf, den Bluetooth-Zugriff zu erlauben. Du musst diese Berechtigung erteilen, damit das Scannen funktioniert.

Verwendung

# 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

Web-Dashboard

Das Dashboard bietet:

• Geräteliste mit Typsymbolen, Hersteller, MAC, Name, Sichtungen, zuletzt gesehen
• Gerätefilter nach Typ (Telefone, Audio, IoT usw.) und Watched-Status
• Suche nach MAC, Hersteller oder Name
• Datumsbereichssuche, um Geräte zu finden, die in einem bestimmten Zeitfenster gesehen wurden
• Tab-basierte Einstellungsseite – Alerts, Operations, Groups und Security (Direktlink über Hash, z. B. /settings#operations)
• Gerätedetails-Modal mit:
  • BLE-Service-Fingerprints
  • Stündliche/tägliche Aktivitäts-Heatmaps
  • 30-Tage-Anwesenheits-Timeline
  • Signalstärke (RSSI)-Verlaufsdiagramm
  • Musteranalyse
  • Aufenthaltsdauer-Statistiken
  • Liste korrelierter Geräte
  • Liste wahrscheinlich desselben Geräts (MAC-Rotation)
  • Näherungszonen-Anzeige
  • Operator-Notizfeld
  • Gruppenzuweisung

Tastaturkürzel

Screenshot-Modus

Aktiviere den Screenshot-Modus in der Seitenleiste, um sensible Daten vor dem Teilen von Screenshots zu verschleiern:

• MAC-Adressen zeigen nur die ersten 2 Oktette (z. B. AA:BB:XX:XX:XX:XX)
• Freundliche Namen zeigen nur die ersten 2 Zeichen (z. B. Da********)
• CSV-Exporte berücksichtigen ebenfalls den Screenshot-Modus

Push-Benachrichtigungen

Bluehood kann Push-Benachrichtigungen über ntfy senden, einen kostenlosen Open-Source-Benachrichtigungsdienst. Du kannst den öffentlichen ntfy.sh-Server oder deine eigene selbst gehostete Instanz verwenden.

1. Erstelle ein Thema bei ntfy.sh (z. B. bluehood-myname-alerts) oder auf deinem eigenen ntfy-Server
2. Abonniere das Thema auf deinem Telefon mit der ntfy-App
3. Gib in den Bluehood-Einstellungen die Server-URL (Standard https://ntfy.sh), deinen Themennamen und ein Zugriffstoken ein, falls dein Server eines erfordert, und aktiviere dann Benachrichtigungen
4. Konfiguriere, welche Ereignisse Benachrichtigungen auslösen:
   • Neues Gerät erkannt
   • Überwachtes Gerät kehrt zurück (nach Abwesenheit)
   • Überwachtes Gerät geht (X Minuten nicht gesehen)

Datenspeicherung

Daten werden in ~/.local/share/bluehood/bluehood.db (SQLite) gespeichert.

Speicherort mit Umgebungsvariablen überschreiben:

• BLUEHOOD_DATA_DIR – Verzeichnis für Datendateien
• BLUEHOOD_DB_PATH – Direkter Pfad zur Datenbankdatei

Hinweis: Heartbeat- und Bereinigungs-Einstellungen können über die Web-UI (Settings > Operations) oder über Umgebungsvariablen konfiguriert werden. GUI-Werte haben Vorrang vor Umgebungsvariablen.

Wie es funktioniert

Geräteklassifizierung

Bluehood klassifiziert Geräte anhand mehrerer Signale (in Prioritätsreihenfolge):

1. BLE-Service-UUIDs – Am genauesten (Heart Rate = Wearable, A2DP = Audio usw.)
2. Gerätenamen-Muster – „iPhone", „Galaxy", „AirPods" usw.
3. Hersteller-OUI-Lookup – Apple, Samsung, Bose usw.

Randomisierte MACs

Moderne Geräte randomisieren ihre MAC-Adressen zum Schutz der Privatsphäre. Bluehood:

• Erkennt randomisierte MACs (lokal verwaltetes Bit)
• Blendet sie aus der Hauptgeräteliste aus (nicht nützlich für Tracking)
• Zeigt eine Anzahl ausgeblendeter randomisierter Geräte an

Musteranalyse

Bluehood analysiert Sichtungs-Zeitstempel, um Muster zu erkennen:

• Tageszeit: Morgen, Nachmittag, Abend, Nacht
• Wochentag: Werktags, Wochenende
• Häufigkeit: Konstant, Täglich, Regelmäßig, Gelegentlich, Selten

Beispielmuster: „Täglich, abends (17:00–21:00 Uhr)", „Werktags, morgens (8:00–12:00 Uhr)"

Gerätekorrelation

Bluehood erkennt Geräte, die häufig zusammen innerhalb eines konfigurierbaren Zeitfensters erscheinen. Dies kann aufdecken:

• Geräte, die derselben Person gehören (Telefon + Smartwatch)
• Personen, die zusammen reisen
• Geräte, die einen Zeitplan teilen

Näherungszonen

Basierend auf der RSSI-Signalstärke werden Geräte in Näherungszonen klassifiziert:

• Unmittelbar (> -50 dBm): Sehr nah, innerhalb weniger Meter
• Nah (-50 bis -60 dBm): In der Nähe, gleicher Raum
• Fern (-60 bis -70 dBm): Weiter weg, angrenzende Räume
• Entfernt (< -70 dBm): Distant, am Rand der Erkennungsreichweite

Aufenthaltsdauer-Analyse

Verfolgt, wie lange Geräte in Reichweite verbringen, indem Lücken zwischen Sichtungen analysiert werden. Ein konfigurierbarer Lückenschwellenwert (Standard 15 Minuten) bestimmt, wann eine neue „Sitzung" beginnt.

Prometheus-Metriken

Bluehood kann Metriken für Prometheus-Scraping bereitstellen. Aktivieren durch Setzen der Umgebungsvariable BLUEHOOD_METRICS_PORT oder des CLI-Flags --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Metriken werden unter http://host:9199/metrics bereitgestellt.

Verfügbare Metriken

Grafana-Dashboard

Ein importbereites Grafana-Dashboard ist unter grafana/bluehood-dashboard.json enthalten. Importiere es über die Grafana-UI (Dashboards > Import) oder die 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}"

Fehlerbehebung

Keine Geräte gefunden

• Stelle sicher, dass dein Adapter BLE (Bluetooth 4.0+) mit der Central-Rolle unterstützt – ältere Adapter funktionieren nicht
• Stelle sicher, dass der Bluetooth-Adapter aktiviert ist: bluetoothctl power on
• Prüfe, ob der Adapter erkannt wird: bluehood --list-adapters
• Führe mit sudo aus, wenn die Berechtigung verweigert wird

Docker-Probleme

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

BlueZ ist auf dem Host nicht installiert oder läuft nicht. Behebung:

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

Allgemeine Checkliste:

• Stelle sicher, dass BlueZ auf dem Host installiert ist (nicht nur im Container)
• Überprüfe, ob der Bluetooth-Dienst läuft: systemctl status bluetooth
• Bestätige, dass dein Adapter sichtbar ist: bluetoothctl list

Mitwirken

Beiträge willkommen! Bitte öffne ein Issue oder PR auf GitHub.

Mitwirkende

• @martinh2011 (Martin Hüser) – Verbesserungen am MAC-Hersteller-Cache
• @hatedabamboo (Kirill Solovei) – Unterstützung für helles Theme
• @krnltrp – Web-UI-Verbesserungen
• @jacobpretorius (Jacob Pretorius) – CSV-Export-JS-Fix (#14), Klick zum Öffnen der Einstellung (#16)
• @unqualifiedkoala – BLE-Adapter-Anforderungen dokumentiert
• @dazzag24 – macOS-Adressformat-Problem gemeldet
• @floese (W.A.Flozart) – Firefox-Doppelklick-Fix (#29)
• @GeiserX (Sergio Fernández) – Prometheus-Metriken-Exporter (#35), nicht-blockierender Hersteller-DB-Fix (#37), Dual-Adapter-Scannen (#33), robuste Scan-Wiederherstellung mit rfkill (#40)

Lizenz

MIT-Lizenz – Siehe LICENSE für Details.

Haftungsausschluss

Dieses Tool dient nur zu Bildungszwecken. Sei dir der Datenschutzgesetze in deiner Gerichtsbarkeit bewusst, wenn du Bluetooth-Geräte überwachst. Der Autor ist nicht für jeglichen Missbrauch dieser Software verantwortlich.

Erstellt von Danny McClelland