Overview
Blue Hydra is a Bluetooth device discovery and classification tool designed for identifying both discoverable and non-discoverable Bluetooth devices. It supports standard Bluetooth adapters and integrates with Ubertooth hardware for enhanced detection capabilities. The tool is essential for wireless security assessments and Bluetooth reconnaissance operations.
Installation
Linux (Debian/Ubuntu)
# Install dependencies
sudo apt-get update
sudo apt-get install -y bluez libbluetooth-dev python3-pip git
# Clone Blue Hydra repository
git clone https://github.com/sandialabs/blue-hydra.git
cd blue-hydra
# Install Python dependencies
sudo pip3 install -r requirements.txt
# Make scripts executable
chmod +x blue_hydra.py
Linux (Fedora/RHEL)
# Install dependencies
sudo dnf install -y bluez-libs-devel python3-pip git
# Clone and install
git clone https://github.com/sandialabs/blue-hydra.git
cd blue-hydra
sudo pip3 install -r requirements.txt
Ubertooth Setup
# Install Ubertooth tools
sudo apt-get install -y ubertooth libusb-1.0-0-dev
# Verify Ubertooth hardware detection
ubertooth-one -v
# Update Ubertooth firmware if needed
ubertooth-dfu -d
Basic Scanning
Simple Bluetooth Discovery
# Scan for discoverable devices (basic adapter)
sudo python3 blue_hydra.py -i hci0
# Scan with verbose output
sudo python3 blue_hydra.py -i hci0 -v
# Scan for specific time duration (seconds)
sudo python3 blue_hydra.py -i hci0 -t 60
# Scan with timeout
sudo python3 blue_hydra.py -i hci0 --timeout 120
Ubertooth Integration
# Scan using Ubertooth hardware
sudo python3 blue_hydra.py -i ubertooth
# Ubertooth passive scan (non-discoverable detection)
sudo python3 blue_hydra.py -i ubertooth -p
# Combine standard and Ubertooth scanning
sudo python3 blue_hydra.py -i hci0 -i ubertooth
Extended Scanning Modes
# Aggressive scanning with inquiry extensions
sudo python3 blue_hydra.py -i hci0 --aggressive
# Low-energy (BLE) scanning
sudo python3 blue_hydra.py -i hci0 --ble
# Dual scan (classic + BLE)
sudo python3 blue_hydra.py -i hci0 --dual-scan
# Background continuous monitoring
sudo python3 blue_hydra.py -i hci0 --continuous
Device Classification
| Device Type | Description | Typical Use |
|---|
| Phone | Mobile devices running iOS/Android | Communication |
| Laptop | Computers and tablets | Computing |
| Headphones | Audio devices and earbuds | Entertainment |
| Speaker | Standalone audio output devices | Entertainment |
| Watch | Wearable smartwatches | Wearables |
| Keyboard | Input devices | Peripherals |
| Mouse | Pointing devices | Peripherals |
| Car | Vehicle Bluetooth systems | Transportation |
| Fitness | Fitness trackers and bands | Health |
| Medical | Medical monitoring devices | Healthcare |
| Gaming | Gaming consoles and controllers | Gaming |
| Unknown | Unclassified devices | Research |
Filtering by Classification
# Scan and filter phone devices only
sudo python3 blue_hydra.py -i hci0 --filter-type phone
# Multiple device type filters
sudo python3 blue_hydra.py -i hci0 --filter-type phone,laptop,headphones
# Exclude specific device types
sudo python3 blue_hydra.py -i hci0 --exclude-type unknown
# Show all with classification confidence
sudo python3 blue_hydra.py -i hci0 -v --show-confidence
Database Storage
# Use SQLite database (default)
sudo python3 blue_hydra.py -i hci0 --db sqlite:///blue_hydra.db
# Use PostgreSQL database
sudo python3 blue_hydra.py -i hci0 --db postgresql://user:pass@localhost/blue_hydra
# Specify custom SQLite location
sudo python3 blue_hydra.py -i hci0 --db sqlite:////tmp/devices.db
Export Data
# Export to JSON format
sudo python3 blue_hydra.py -i hci0 --export json --output results.json
# Export to CSV format
sudo python3 blue_hydra.py -i hci0 --export csv --output results.csv
# Export specific fields only
sudo python3 blue_hydra.py -i hci0 --export csv --fields address,name,rssi,class --output devices.csv
# Export to PCAP format (compatible with Wireshark)
sudo python3 blue_hydra.py -i ubertooth --export pcap --output capture.pcap
Query Database
# Query stored devices
sqlite3 blue_hydra.db "SELECT address, name, rssi FROM devices ORDER BY rssi DESC LIMIT 20;"
# Find devices by classification
sqlite3 blue_hydra.db "SELECT address, name, device_type FROM devices WHERE device_type = 'phone';"
# Count devices by type
sqlite3 blue_hydra.db "SELECT device_type, COUNT(*) FROM devices GROUP BY device_type;"
# Find recently discovered devices
sqlite3 blue_hydra.db "SELECT address, name, last_seen FROM devices ORDER BY last_seen DESC LIMIT 10;"
Web Interface
Starting Web Server
# Start web interface on default port (8080)
sudo python3 blue_hydra.py -i hci0 --web
# Use custom port
sudo python3 blue_hydra.py -i hci0 --web --port 9000
# Allow remote connections
sudo python3 blue_hydra.py -i hci0 --web --bind 0.0.0.0
# Access web interface
# Open browser: http://localhost:8080
Web Dashboard Features
| Feature | Function |
|---|
| Device List | Real-time display of discovered devices |
| Map View | Geographic visualization if GPS enabled |
| Signal Strength | RSSI chart and trending |
| Classification | Device type distribution charts |
| Timeline | Discovery history and activity timeline |
| Export | Download data in multiple formats |
Filtering by Device Type
Advanced Filtering
# Scan only devices with specific RSSI range
sudo python3 blue_hydra.py -i hci0 --min-rssi -80 --max-rssi -30
# Find devices by name pattern
sudo python3 blue_hydra.py -i hci0 --name-filter "iPhone*"
# Filter by manufacturer
sudo python3 blue_hydra.py -i hci0 --manufacturer apple
# Combine multiple filters
sudo python3 blue_hydra.py -i hci0 --filter-type phone --manufacturer apple --min-rssi -70
# Exclude blacklisted devices
sudo python3 blue_hydra.py -i hci0 --blacklist-file blacklist.txt
Blacklist Management
# Create blacklist file
echo "AA:BB:CC:DD:EE:FF" > blacklist.txt
echo "11:22:33:44:55:66" >> blacklist.txt
# Scan excluding blacklisted devices
sudo python3 blue_hydra.py -i hci0 --blacklist-file blacklist.txt
# Create whitelist (scan only these)
echo "XX:XX:XX:XX:XX:XX" > whitelist.txt
sudo python3 blue_hydra.py -i hci0 --whitelist-file whitelist.txt
Monitoring Mode
Continuous Background Monitoring
# Start continuous monitoring
sudo python3 blue_hydra.py -i hci0 --monitor
# Monitor with logging
sudo python3 blue_hydra.py -i hci0 --monitor --log-file blue_hydra.log
# Monitor with email alerts
sudo python3 blue_hydra.py -i hci0 --monitor --alert-email alert@example.com
# Background daemon mode
sudo python3 blue_hydra.py -i hci0 --daemon --pid-file /var/run/blue_hydra.pid
Alert Configuration
# Alert on new device discovery
sudo python3 blue_hydra.py -i hci0 --monitor --alert-new-device
# Alert on specific device type
sudo python3 blue_hydra.py -i hci0 --monitor --alert-type phone
# Alert on signal strength change
sudo python3 blue_hydra.py -i hci0 --monitor --alert-rssi-change 20
# Custom webhook notifications
sudo python3 blue_hydra.py -i hci0 --monitor --webhook http://localhost:5000/alert
Console Output
# Standard output
sudo python3 blue_hydra.py -i hci0
# Verbose output with detailed info
sudo python3 blue_hydra.py -i hci0 -v
# Very verbose (debug level)
sudo python3 blue_hydra.py -i hci0 -vv
# Quiet mode (errors only)
sudo python3 blue_hydra.py -i hci0 -q
Export Options
| Format | Command | Use Case |
|---|
| JSON | --export json | Data parsing and integration |
| CSV | --export csv | Spreadsheet analysis |
| PCAP | --export pcap | Wireshark analysis |
| XML | --export xml | Enterprise tools |
| HTML | --export html | Reporting |
| PDF | --export pdf | Documentation |
# JSON output with pretty printing
sudo python3 blue_hydra.py -i hci0 --export json --pretty --output results.json
# CSV with custom delimiter
sudo python3 blue_hydra.py -i hci0 --export csv --delimiter ";" --output results.csv
# HTML report generation
sudo python3 blue_hydra.py -i hci0 --export html --template report.html --output report.html
# Multiple simultaneous exports
sudo python3 blue_hydra.py -i hci0 --export json --export csv --export pdf
Advanced Operations
# Calculate approximate distance from RSSI
# Formula: distance = 10^((RSSI - TxPower) / (10 * N))
# Where TxPower is typically -40 to -50 dBm, N is propagation constant
# Scan with distance calculation
sudo python3 blue_hydra.py -i hci0 --calc-distance
# Set custom TX power for distance estimation
sudo python3 blue_hydra.py -i hci0 --tx-power -45 --calc-distance
Service Discovery
# Discover Bluetooth services on found devices
sudo python3 blue_hydra.py -i hci0 --discover-services
# Service discovery for specific device
sudo python3 blue_hydra.py -i hci0 --discover-services --target AA:BB:CC:DD:EE:FF
# Deep service enumeration
sudo python3 blue_hydra.py -i hci0 --deep-discovery
# Adjust inquiry duration (1.28 seconds per unit)
sudo python3 blue_hydra.py -i hci0 --inquiry-length 16
# Set scan window and interval (BLE)
sudo python3 blue_hydra.py -i hci0 --ble-window 50 --ble-interval 100
# Use multiple threads for scanning
sudo python3 blue_hydra.py -i hci0 --threads 4
# Optimize for speed vs accuracy
sudo python3 blue_hydra.py -i hci0 --speed-optimized
Troubleshooting
Common Issues
| Problem | Solution |
|---|
| Permission Denied | Run with sudo or add user to bluetooth group |
| Device Not Found | Check adapter with hciconfig; enable scan mode |
| No Ubertooth Detection | Verify USB connection; check ubertooth-one -v |
| Web Interface Inaccessible | Check firewall; verify port binding |
| High CPU Usage | Reduce inquiry length or thread count |
Debug Commands
# Check Bluetooth adapter status
hciconfig
# List all Bluetooth devices
hciconfig -a
# Check Ubertooth device connection
ubertooth-one -v
# Monitor Bluetooth events
sudo hcidump -i hci0
# View system logs
sudo journalctl -u bluetooth -f
Security Considerations
Responsible Scanning
# Respect privacy: limit scan duration
sudo python3 blue_hydra.py -i hci0 --timeout 60
# Non-intrusive discovery (passive scanning)
sudo python3 blue_hydra.py -i ubertooth --passive
# Log all activities for audit
sudo python3 blue_hydra.py -i hci0 --audit-log audit.log
Data Protection
# Encrypt database
sudo python3 blue_hydra.py -i hci0 --db-encrypt
# Set database permissions
chmod 600 blue_hydra.db
# Secure export with encryption
sudo python3 blue_hydra.py -i hci0 --export json --encrypt --output results.json.enc
Integration Examples
# Export for analysis in Bluetooth scanner apps
sudo python3 blue_hydra.py -i hci0 --export pcap | tcpdump -r -
# Pipe to JSON parser
sudo python3 blue_hydra.py -i hci0 --export json | jq '.devices[] | select(.rssi < -50)'
# Feed into ELK stack
sudo python3 blue_hydra.py -i hci0 --export json --webhook http://localhost:5000/elk
# Integration with SecurityOnion
sudo python3 blue_hydra.py -i ubertooth --export pcap --output capture.pcap
Resources
