Bluehound

A Bluetooth Low Energy (BLE) reconnaissance and anomaly detection framework with real-time visualization.

Originally built for BLE wardriving, now extended into a dual-mode system for device discovery and environment analysis.

---

Features

Sniffer Mode (Wardriving)

• Discovers nearby BLE devices in real-time
• Persistent JSON database across sessions
• RSSI-based distance estimation
• Web-based radar visualization
• Fast continuous scanning

---

Monitor Mode (Anomaly Detection Engine)

Analyzes BLE activity in real-time to detect abnormal behavior across both devices and the environment.

Device-Level Detection

• RSSI spike detection (signal instability)
• Missed scan cycles (intermittent presence)
• Time-based disappearance tracking

Devices are dynamically classified:

• stable
• unstable

---

Environment-Level Detection

• Unstable device ratio
• Device count drop score
• Real-time session analysis

Detects conditions such as:

• BLE flooding
• RF interference
• Sudden signal disruption
• Suspicious device behavior

---

Installation

Install BlueZ (Linux Bluetooth Stack)

Debian / Ubuntu

sudo apt-get update && sudo apt-get install -y bluez

Arch Linux

sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

---

Install Bluehound

git clone https://github.com/nsm-barii/bluehound.git
cd bluehound/src

python3 -m venv venv
source venv/bin/activate

pip install -r ../requirements.txt

---

Usage

Sniffer Mode

sudo venv/bin/python main.py --sniffer

Monitor Mode

sudo venv/bin/python main.py --monitor

---

Live Web Dashboard

Add --web to either mode to launch the real-time dashboard (radar + device table) at http://localhost:8000:

sudo venv/bin/python main.py --monitor --web
sudo venv/bin/python main.py --sniffer --web

---

Optional Flags

--save             # Save scan results
-s <IP>            # Send data to external server (ESP32 / LED system)
--web              # Launch live web dashboard at http://localhost:8000
--window <sec>     # How long each scan listens for advertisements (default: 5)
--interval <sec>   # Wait time between scans; 0 = continuous (default: 0)

Example — 8s scan window with a 3s pause between scans, plus the dashboard:

sudo venv/bin/python main.py --monitor --web --window 8 --interval 3

---

How It Works

Sniffer Mode

• Scans BLE advertisement packets
• Extracts device metadata (MAC, vendor, RSSI, UUIDs)
• Stores results persistently
• Displays devices in a real-time web UI

---

Monitor Mode

• Tracks devices across scan cycles
• Builds a live model of BLE activity
• Uses weighted anomaly detection:

RSSI instability + missed cycles + signal loss → unstable device

---

Real-Time Metrics

• Total devices
• Unstable devices
• Unstable ratio (%)
• Drop score

Example:

Session Devices: 42
Unstable Devices: 8
Unstable Ratio: 19.04%
Drop Score: 0.27

---

Project Structure

src/
├── main.py
├── scanner/
│   └── BLE_Sniffer.py
├── monitor/
│   └── Monitor_Bluetooth.py
├── web/
├── database/
│   └── database.json

---

Use Cases

• BLE wardriving and mapping
• IoT device discovery
• RF environment monitoring
• BLE anomaly detection
• Early-stage BLE intrusion detection research

---

Roadmap

• BLE jamming detection
• Device fingerprinting (behavior + vendor)
• Multi-adapter support
• ESP32 real-time alert integration
• Data export / analytics pipeline

---

Requirements

• Linux (BlueZ required)
• Python 3.7+
• BLE-compatible adapter

---

Disclaimer

This tool is intended for authorized security research and educational use only.
Do not scan or analyze devices without permission.

---

Author

Built by
https://github.com/nsm-barii