Bluetooth privacy is often thought to hinge on MAC address randomization, but in practice, passive observations reveal much more. Bluehood is a Python tool that passively scans BLE and Classic Bluetooth devices around you, classifies them by vendor and service UUIDs, and tracks presence patterns over time through a web dashboard. It’s an educational demonstration of how much metadata can be inferred passively — daily routines, visitor patterns, and even device correlations — despite Bluetooth’s privacy measures.
Passive Bluetooth scanning and presence pattern analysis
Bluehood targets Linux hosts with BlueZ installed and a Bluetooth adapter capable of BLE Central role scanning (Bluetooth 4.0+). It passively listens to Bluetooth advertisements and classic device inquiries without actively connecting to devices. The core functionality includes classifying devices by vendor and BLE service UUIDs, recording signal strength (RSSI) history, and building presence timelines up to 30 days.
The tool offers a web dashboard showing presence heatmaps, device grouping, and activity timelines, making it easier to visualize how devices appear and reappear over time. It also supports push notifications via ntfy.sh and optional authentication for the dashboard.
Under the hood, Bluehood uses the BlueZ Linux Bluetooth stack for low-level access. Deployment is supported via Docker (privileged mode with host networking to access Bluetooth sockets) or manual installation with pip. Because raw Bluetooth socket access requires elevated privileges, the tool either runs as root, is granted Linux capabilities, or is run as a systemd service.
The architecture is straightforward: a scanner component captures Bluetooth packets, a processing layer filters out noise and random addresses, then correlates devices using BLE service UUIDs and RSSI patterns to mitigate the limitations of MAC address randomization.
How Bluehood filters randomized MACs and correlates devices
MAC address randomization is Bluetooth’s main privacy defense, but it’s not foolproof. Bluehood’s distinguishing feature is its ability to correlate devices even when their MAC addresses change frequently. It does this by analyzing the BLE service UUIDs broadcast, which often remain stable, and signal strength patterns over time.
This approach reveals the limits of MAC randomization as a privacy measure. Devices that attempt to hide their identity by cycling MAC addresses can still be tracked by their unique BLE fingerprints and presence patterns. For example, a device’s daily routine, movement patterns, and even relationships to other devices nearby emerge from the data collected.
The tradeoff here is that passive scanning and correlation require careful filtering to avoid false positives. Signal strength can fluctuate due to environment and interference, and some devices randomize service UUIDs or use minimal advertising data. Bluehood’s code balances sensitivity and accuracy, but it’s an educational tool rather than a hardened production scanner.
The codebase is Python 3, relying on BlueZ DBus interfaces and raw Bluetooth sockets. It’s surprisingly clean for an alpha-stage project, with clear separation between scanning, data processing, and web dashboard layers. The use of Docker for deployment simplifies setup but requires privileged networking due to the nature of Bluetooth sockets.
Quick start with Docker on Linux
Bluehood is Linux-only due to its reliance on BlueZ for Bluetooth stack access. To run it, you must have BlueZ installed and running on your host. The Docker image itself doesn’t include BlueZ, so the host must provide it.
Here’s the exact Quick Start setup from the README:
# 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
Then create or download the provided docker-compose.yml file and start the container:
docker compose up -d
Your Bluetooth adapter must support BLE Central role (Bluetooth 4.0+). You can check this with bluetoothctl show and look for central in the supported roles.
If your adapter lacks this, Bluehood will exit with an error.
For manual installation:
# Arch Linux
sudo pacman -S bluez bluez-utils python-pip
# 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 scanning requires elevated privileges. Options include running as root, setting Linux capabilities on the Python binary, or running as a systemd service.
Who benefits from Bluehood and its limitations
Bluehood is a solid educational tool for security researchers, privacy advocates, and Bluetooth developers interested in understanding the metadata leakage possible from passive Bluetooth scanning. It clearly demonstrates that MAC address randomization alone is insufficient for privacy in Bluetooth environments.
However, it’s not a polished production-grade scanner. The reliance on Linux and BlueZ limits cross-platform use. The need for privileged access complicates deployment in shared environments. Signal strength-based correlation can produce false positives or miss devices that randomize service UUIDs aggressively.
Still, the codebase is approachable and well-structured, offering a useful starting point for anyone looking to explore Bluetooth presence pattern analysis. Its web dashboard and notification features add practical value for monitoring device activity over time.
If you want to understand the real-world implications of Bluetooth privacy weaknesses or build on a passive scanning foundation, Bluehood is worth exploring.
→ GitHub Repo: dannymcc/bluehood ⭐ 976 · Python