The friendly BLE scanner that makes Bluetooth security fun
Bleep is your go-to tool for discovering, monitoring, and security testing Bluetooth Low Energy devices. Passive scanning, deep device analysis, and security audits — all with a clean interface that doesn't take itself too seriously.
"BLE" + "beep" = Bleep! Your Bluetooth detective in the wild.
- Zero-interaction discovery - No pairing or connection required
- Real-time device discovery with live RSSI tracking
- Movement detection based on signal strength variations
- Distance estimation with proximity categories
- Vendor identification via MAC OUI lookup
- Comprehensive characteristic reading - Reads all accessible characteristics
- Standard service decoding - Auto-decodes Battery, Heart Rate, Environmental Sensors, Device Info, etc.
- Multi-format parsing - Supports uint8/16/32/64, int8/16/32/64, float32/64, strings, IP addresses
- Manufacturer-specific decoders - Apple, Samsung, HP printer data extraction
- Raw packet logging - Full hex/decimal data streams
- Connection testing - Attempts connections without authentication
- Permission enumeration - Tests read/write/notify capabilities
- Authentication detection - Identifies "Just Works" pairing and auth requirements
- Vulnerability reporting - Highlights characteristics accessible without auth
- Safe testing - Read-only by default, avoids destructive operations
- Automatic device typing - Detects AirTags, fitness trackers, printers, IoT sensors
- Beacon detection - Identifies non-connectable beacon-only devices
- Battery monitoring - Extracts battery levels when available
- Network info extraction - Pulls IP addresses from HP printers and other networked devices
- 3-state filters - Normal / Only Show / Exclude by device type
- Device-specific logs - Click any device to see only its packets
- Real-time updates - Live streaming with auto-scroll
- Stable device list - Devices stay in discovery order
- Python 3.8 or higher
- macOS (CoreBluetooth), Linux (BlueZ), or Windows (WinRT)
- Bluetooth adapter with BLE support
# Clone the repository
git clone https://github.com/domcritchlow/bleep.git
cd bleep
# Install dependencies
pip install -r requirements.txt
# Run Bleep
python server.pyOpen your browser and navigate to:
http://localhost:5005
- Start Scanning - Click the "Start" button
- View Devices - Devices appear in the left panel as discovered
- Click a Device - Filter logs to show only that device's packets
- Stop Scanning - Click "Stop" when done
- Discover a device (must be connectable, not beacon-only)
- Click 🔐 Audit button on the device card
- Review the security findings:
- ✅ Characteristics readable without authentication
⚠️ Characteristics writable without authentication- 🔐 Characteristics requiring authentication
- Pairing method detection
- Click 🔬 Deep Scan on any connectable device
- The scanner will:
- Read ALL readable characteristics
- Subscribe to all notifications for 30 seconds
- Decode standard services automatically
- Display comprehensive device information
Use the top bar filters to show/hide device types:
- First click: Normal (show all)
- Second click: Only (show ONLY this type)
- Third click: Exclude (hide this type)
bleep/
├── src/
│ └── bleep/
│ ├── __init__.py # Package initialization
│ ├── config_loader.py # Configuration management
│ ├── decoders.py # Data decoding utilities
│ └── device_detector.py # Device type detection
├── config/
│ ├── app_config.json # Application settings
│ ├── oui_vendors.json # MAC vendor mappings
│ ├── company_ids.json # Bluetooth company IDs
│ ├── standard_services.json # GATT service definitions
│ └── device_detection.json # Device detection rules
├── templates/
│ └── index.html # Web UI
├── docs/
│ └── API.md # API documentation (coming soon)
├── tests/
│ └── test_decoders.py # Unit tests (coming soon)
├── server.py # Main application entry point
├── requirements.txt # Python dependencies
├── README.md # This file
├── LICENSE # MIT License
└── .gitignore # Git ignore rules
All configuration files are in JSON format and located in the config/ directory.
Edit config/app_config.json to customize:
{
"server": {
"host": "0.0.0.0",
"port": 5005,
"debug": false
},
"scanner": {
"rssi_history_size": 10,
"movement_threshold": 5,
"max_log_entries": 1000
},
"security": {
"connection_timeout_seconds": 10,
"deep_scan_duration_seconds": 30
}
}Edit config/oui_vendors.json:
{
"mappings": {
"AA:BB:CC": "Your Company Name"
}
}Edit config/device_detection.json to add new device type patterns.
This tool is designed for:
- ✅ Testing your own devices
- ✅ Security research in controlled environments
- ✅ Educational purposes
- ✅ Authorized penetration testing
DO NOT use this tool for:
- ❌ Unauthorized access to devices
- ❌ Violating privacy or laws
- ❌ Malicious activities
- Read-only by default - Write operations are disabled
- No pairing popup avoidance - Respects OS security prompts
- Clear warnings - Indicates which operations may trigger pairing
- Non-destructive - Designed to observe, not modify
# Install development dependencies
pip install pytest pytest-asyncio
# Run tests
pytest tests/This project follows PEP 8 guidelines. Format code with:
pip install black flake8
black src/
flake8 src/See CONTRIBUTING.md for contribution guidelines.
- API Documentation - API reference (coming soon)
- Configuration Guide - Detailed configuration options (coming soon)
- Decoder Reference - Available decoders (coming soon)
- macOS pairing popups: Some devices (e.g., Garmin watches) may trigger OS pairing prompts during security audits
- Connection timeouts: Devices may disconnect during deep scans if they have strict security policies
- Initial release of Bleep! 🎉
- Passive BLE scanning
- Security audit functionality
- Deep scan feature
- Configuration-based decoders
- Comprehensive device detection
- Fun, friendly interface
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with Bleak - Python BLE library (the name inspiration!)
- UI powered by Flask and Socket.IO
- Bluetooth SIG for GATT specifications
Made with 💙 for Bluetooth tinkerers and security researchers