Bluehood

Bluetooth Neighborhood – BLE-Geräte in Ihrer Umgebung verfolgen und Verkehrsmuster analysieren.

WARNUNG: Alpha-Software

Dieses Projekt befindet sich in der Frühphase und ist nicht für den Produktionseinsatz bereit. Funktionen können sich ändern, ausfallen oder ohne Vorankündigung entfernt werden. Nutzung auf eigene Gefahr. Erfasste Daten sollten als experimentell betrachtet werden.

Screenshots

Haupt-Dashboard mit Geräteliste, Filterung, Suche und Echtzeitstatistiken

Registerkarten-Konfigurationsseite – Benachrichtigungen, Operationen, Gruppen und Sicherheit

Intel-Seite mit Projektinformationen und Funktionsübersicht

Warum?

Dieses Projekt wurde von der WhisperPair-Sicherheitslücke (CVE-2025-36911) inspiriert, die auf Datenschutzrisiken bei Bluetooth-Geräten aufmerksam machte.

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

Mit genügend Daten könnten Sie möglicherweise:

• Verstehen, wann jemand typischerweise mit dem Hund spazieren geht
• Erkennen, wann ein Besucher ein Haus betritt
• Muster in alltäglichen Routinen basierend auf Gerätepräsenz 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 nahen Bluetooth-Geräten (sowohl BLE als auch Classic)
• Identifiziert Geräte nach Hersteller (MAC-Adresssuche) und BLE-Dienst-UUIDs
• Klassifiziert Geräte in Kategorien (Telefone, Audio, Wearables, IoT, Fahrzeuge usw.)
• Verfolgt Präsenzmuster über die Zeit mit stündlichen/täglichen Heatmaps
• Filtert Rauschen aus randomisierten MAC-Adressen (datenschutzrotierte Geräte)
• Analysiert Gerätekorrelationen, um Geräte zu finden, die zusammen auftauchen
• Sendet Push-Benachrichtigungen, wenn beobachtete Geräte eintreffen oder sich entfernen
• Bietet ein Web-Dashboard zur Überwachung und Analyse

Funktionen

Scannen

• Dual-Mode-Scan: Bluetooth Low Energy (BLE) und Classic Bluetooth
• MAC-Adress-Herstellerabfrage (lokale Datenbank + Online-API-Fallback)
• BLE-Dienst-UUID-Fingerprinting für genaue Geräteklassifizierung
• Classic Bluetooth Geräteklassen-Parsing
• Randomisierte MAC-Filterung (in Hauptansicht versteckt)

Geräteverwaltung

• Geräte als „Beobachtet“ markieren zur Verfolgung persönlicher Geräte
• Geräte in benutzerdefinierten Gruppen organisieren
• Anzeigenamen für bekannte Geräte festlegen
• Benutzerdefinierte Notizen/Tags zu jedem Gerät hinzufügen
• Gerätetyp-Erkennung (Telefone, Audio, Wearables, IoT, Fahrzeuge usw.)

Analysen

• 30-Tage-Präsenzzeitleiste Visualisierung
• Signalstärkeverlauf (RSSI) Diagramm mit 7-Tage-Daten
• Stündliche und tägliche Aktivitäts-Wärmekarten die anzeigen, wann Geräte aktiv sind
• Musteranalyse („Wochentage, Abende 17-21 Uhr“)
• Aufenthaltsdaueranalyse die zeigt, wie lange Geräte insgesamt in Reichweite sind
• Gerätekorrelationserkennung um Geräte zu finden, die zusammen auftauchen
• Nähezonen (unmittelbar, nah, fern, entfernt) basierend auf Signalstärke
• Suche nach MAC, Hersteller oder Name
• Datumsbereichssuche für historische Abfragen

Benachrichtigungen (via ntfy.sh)

• Push-Benachrichtigungen auf Ihr Telefon/Desktop
• Benachrichtigung bei neuen erkannten Geräten
• Benachrichtigung, wenn beobachtete Geräte zurückkehren
• Benachrichtigung, wenn beobachtete Geräte sich entfernen
• Konfigurierbare Schwellenwerte für Ankunft/Abreise

Operationen

• Heartbeat-Check-in – regelmäßiger POST-Status an einen Uptime-Monitoring-Dienst (z.B. Uptime Kuma, Healthchecks.io)
• Speicherrotation – automatisches Löschen von Sichtungen älter als eine konfigurierbare Anzahl von Tagen
• Beides über die Weboberfläche oder Umgebungsvariablen konfigurierbar

Weboberfläche

• Umschalter kompakte/detaillierte Ansicht für verschiedene Anzeigepräferenzen
• Screenshot-Modus um MACs und Namen für sicheres Teilen zu verschleiern
• Tastaturkürzel für Power-User (Taste ? drücken, um anzuzeigen)
• CSV-Export von Gerätedaten
• Gerätegruppen zur Organisation verwandter Geräte
• Optionale Authentifizierung zum Sichern des Zugriffs

Wie?

Schnellstart mit Docker (Empfohlen)

Voraussetzungen – Nur Linux-Hosts

Bluehood kommuniziert über BlueZ, den Linux-Bluetooth-Stack, mit Ihrem Bluetooth-Adapter. BlueZ muss vor dem Starten des Containers auf dem Host installiert und ausgeführt werden – das Docker-Image enthält es nicht selbst.

root@kitploit:~

# Debian / Ubuntu (including 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 erscheint ein 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 wird unter http://localhost:8080 verfügbar sein.

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 ausgeführt (sudo apt install bluez && sudo systemctl enable --now bluetooth)

Hinweis: Ältere Adapter (Bluetooth 2.x/3.x) unterstützen kein BLE-Scannen. Wenn Ihr Adapter keine BLE-Central-Rolle unterstützt, sehen Sie: No Bluetooth adapters with BLE 'central' role found.

Hinweis: Docker läuft im privilegierten Modus mit Host-Netzwerk für Bluetooth-Zugriff. Dies ist für BLE-Scan 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 Ihr Adapter die BLE-Central-Rolle nicht unterstützt, wird Bluehood mit folgendem Fehler beendet:

No Bluetooth adapters with BLE 'central' role found

Sie können die Fähigkeiten Ihres 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-Scan erfordert erhöhte Rechte. Wählen Sie eine Option:

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

   root@kitploit:~

   sudo bluehood
   

2. Python Capabilities verleihen:

   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 unter 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 wird unter http://localhost:8080 verfügbar sein.

Hinweis: Beim ersten Start fordert macOS Sie auf, den Bluetooth-Zugriff zu erlauben. Sie müssen diese Berechtigung erteilen, damit das Scannen funktioniert.

Verwendung

# Start with web dashboard (default port 8080)
bluehood

# Specify a different 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 Typensymbolen, Hersteller, MAC, Name, Sichtungen, zuletzt gesehen
• Gerätefilter nach Typ (Telefone, Audio, IoT usw.) und Beobachtungsstatus
• Suche nach MAC, Hersteller oder Name
• Datumsbereichssuche um Geräte zu finden, die in einem bestimmten Zeitfenster gesehen wurden
• Registerkarten-Konfigurationsseite – Benachrichtigungen, Operationen, Gruppen und Sicherheit (direkt verlinkbar über Hash, z.B. /settings#operations)
• Gerätedetails-Modal mit:
  • BLE-Dienst-Fingerabdrücke
  • Stündliche/tägliche Aktivitäts-Wärmekarten
  • 30-Tage-Präsenzzeitleiste
  • Signalstärkeverlauf (RSSI)-Diagramm
  • Musteranalyse
  • Aufenthaltsdauer-Statistiken
  • Liste korrelierter Geräte
  • Nähezonen-Indikator
  • Notizenfeld für Betreiber
  • Gruppenzuweisung

Tastaturkürzel

Screenshot-Modus

Aktivieren Sie den Screenshot-Modus über die 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)
• Anzeigenamen zeigen nur die ersten 2 Zeichen (z.B. Da********)
• CSV-Exporte respektieren ebenfalls den Screenshot-Modus

Push-Benachrichtigungen

Bluehood kann Push-Benachrichtigungen über ntfy.sh senden, einen kostenlosen Open-Source-Benachrichtigungsdienst.

1. Erstellen Sie ein Thema bei ntfy.sh (z.B. bluehood-myname-alerts)
2. Abonnieren Sie das Thema auf Ihrem Telefon mit der ntfy-App
3. Geben Sie in den Bluehood-Einstellungen Ihren Themennamen ein und aktivieren Sie Benachrichtigungen
4. Konfigurieren Sie, welche Ereignisse Benachrichtigungen auslösen:
   • Neues Gerät erkannt
   • Beobachtetes Gerät kehrt zurück (nach Abwesenheit)
   • Beobachtetes Gerät entfernt sich (für X Minuten nicht gesehen)

Datenspeicherung

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

Überschreiben Sie den Speicherort mit Umgebungsvariablen:

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

Hinweis: Heartbeat- und Bereinigungseinstellungen können über die Weboberfläche (Einstellungen > Operationen) 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-Dienst-UUIDs – Am genauesten (Herzfrequenz = Wearable, A2DP = Audio, usw.)
2. Gerätenamenmuster – „iPhone“, „Galaxy“, „AirPods“, usw.
3. Hersteller-OUI-Suche – Apple, Samsung, Bose, usw.

Randomisierte MACs

Moderne Geräte randomisieren ihre MAC-Adressen aus Datenschutzgründen. Bluehood:

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

Musteranalyse

Bluehood analysiert Sichtungszeitstempel, um Muster zu erkennen:

• Tageszeit: Morgen, Nachmittag, Abend, Nacht
• Wochentag: Werktage, Wochenenden
• Häufigkeit: Ständig, Täglich, Regelmäßig, Gelegentlich, Selten

Beispielmuster: „Täglich, abends (17-21 Uhr)“, „Wochentage, morgens (8-12 Uhr)“

Gerätekorrelation

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

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

Nähezonen

Basierend auf der RSSI-Signalstärke werden Geräte in Nähezonen eingeteilt:

• Unmittelbar (> -50 dBm): Sehr nah, innerhalb weniger Meter
• Nah (-50 bis -60 dBm): In der Nähe, im selben Raum
• Fern (-60 bis -70 dBm): Weiter entfernt, angrenzende Räume
• Entfernt (< -70 dBm): Weit entfernt, an der Grenze der Erkennungsreichweite

Aufenthaltsdaueranalyse

Verfolgt, wie lange Geräte in Reichweite sind, 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 zum Scraping durch Prometheus bereitstellen. Aktivieren Sie dies durch Setzen der Umgebungsvariablen 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 importfertiges Grafana-Dashboard ist unter grafana/bluehood-dashboard.json enthalten. Importieren Sie es über die Grafana-Oberfläche (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

• Stellen Sie sicher, dass Ihr Adapter BLE (Bluetooth 4.0+) mit der Central-Rolle unterstützt – ältere Adapter funktionieren nicht
• Stellen Sie sicher, dass der Bluetooth-Adapter aktiviert ist: bluetoothctl power on
• Überprüfen Sie, ob der Adapter erkannt wird: bluehood --list-adapters
• Führen Sie 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 nicht installiert oder läuft nicht auf dem Host. Behebung:

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

Allgemeine Checkliste:

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

Mitwirken

Beiträge willkommen! Bitte öffnen Sie ein Issue oder einen PR auf GitHub.

Mitwirkende

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

Lizenz

MIT-Lizenz – Einzelheiten finden Sie in der LICENSE-Datei.

Haftungsausschluss

Dieses Werkzeug dient nur zu Bildungszwecken. Beachten Sie die Datenschutzgesetze in Ihrem Zuständigkeitsbereich, wenn Sie Bluetooth-Geräte überwachen. Der Autor übernimmt keine Verantwortung für Missbrauch dieser Software.

Erstellt von Danny McClelland