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.
# 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
# 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
# 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
# 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
# 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
# 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 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 |
# 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
# 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 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 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;"
# 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
| 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 |
# 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
# 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
# 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 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
# 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
| 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
# 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
# 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
| 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 |
# 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
# 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
# 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
# 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
