A full-featured offensive BLE security framework for scanning, exploitation, and replay with anomaly detection, fingerprint-based attack suggestions, and offline sandbox simulation.
⚠️ WARNING: Ethical Use Required
blexploitis a BLE security testing framework for red teams and researchers.
It must only be used in environments where you have explicit authorization.
Unauthorized use may be illegal and is strictly prohibited.
- Passive BLE scanning with anomaly detection
- GATT enumeration and fingerprinting
- Modular attack framework (replay, brute-force, fake key)
- Simulation engine for safe testing
| Passive Scan Report (HTML) | Fingerprinting Summary |
|---|---|
 |
 |
Most BLE security tools only log packets or trigger proof-of-concept GATT writes.
Blexploit bridges the gap between passive analysis and offensive simulation with a modular, extensible framework:
- Real BLE packet injection (
--write-test,--attack) - Anomaly-based risk detection via Isolation Forest
- GATT-based fingerprinting & UUID enumeration
- Modular plugin-based attack execution
- Auto-generated HTML & JSON reports with recommendations
- Simulated replay of Xiaomi GATT writes
- HTML report generation from passive scan
- UUID-based attack module suggestion in CLI
- Auto-suggested modules based on detected UUIDs
→ Example: UUID0xffd5→replay,brute-pin - Risk scoring from anomaly detection using Isolation Forest
- Log tagging of exploit attempts with risk level, suggestions, and remediation
🔗 HTML Report Example (Coming Soon) 📄 JSON Output Schema (Coming Soon)
Each scan result includes:
- Device info (MAC, Name, Manufacturer)
- Risk level (Low / High via anomaly detection)
- Suggested attack modules (based on UUIDs)
- Mitigation recommendations
Blexploit supports safe testing through simulated attacks and offline sandbox replay, enabling:
- Training and education without real BLE hardware
- Reproducible PoCs and CLI demos
- Integration into CI pipelines
| Feature | Description |
|---|---|
--simulate-fakekey |
Simulates invalid BLE key injection |
--simulate-replay |
Simulates BLE replay attack flow without sending packets |
--sandbox |
Offline replay engine using mock device profiles |
mock_device.py |
Emulates BLE devices like Xiaomi, Tile, WELOCK |
| YAML scripting | Define and replay BLE write sequences for PoCs |
Run a safe simulation (no packets transmitted):
python main.py simulate-fakekeyOffline replay against sandbox profile:
python main.py --sandbox --input-file scripts/xiaomi_unlock.yamlmain.py
│
├── core/
│ ├── passive_scanner.py # BLE advertising scan + anomaly detection
│ ├── fingerprint_store.py # Store and compare device fingerprints
│ ├── ble_write.py # Write to GATT characteristics in live BLE devices
│ └── uuid_scanner.py # Enumerate GATT services/characteristics for a device
│
├── attacks/
│ ├── replay.py # Replay known BLE write payloads (e.g. unlock)
│ ├── brute_pin.py # Brute-force BLE PINs from top100 list
│ └── ... # Additional attack modules (e.g. fakekey)
│
├── logic/
│ ├── anomaly_detector.py # IsolationForest-based BLE anomaly detection
│ └── attack_suggester.py # Map UUIDs to recommended attack modules
│
├── reporting/
│ └── report_generator.py # Generate HTML/JSON reports with risk & attack info
│
└── data/
└── top100_ble_pins.txt # BLE PIN wordlist used in brute-force attacks
git clone https://github.com/schoi1337/blexploit.git
cd blexploitpython3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -r requirements.txtMake sure bluez is installed:
sudo apt install bluetooth libbluetooth-dev bluezEnsure the Bluetooth interface is up:
sudo systemctl start bluetoothRun all BLE operations with root or appropriate permissions.
Install macOS BLE backend:
pip install pyobjc-core pyobjc-framework-CoreBluetooth- Make sure you're using Python ≥ 3.8 (64-bit)
- No extra BLE drivers required.
- Use Bleak's WinRT backend (automatically selected)
- A working BLE adapter (built-in or USB)
- Location/Bluetooth permission enabled (especially on macOS and Windows)
# Scan nearby BLE devices and generate report
python main.py passive-scan --timeout 10 --unsafe
# Read BLE characteristic
python main.py read-gatt --address <MAC> --uuid <UUID>
# Attempt brute-force BLE PIN attack
python main.py attack --type brute-pin --address <MAC> --unsafeTo add a new attack module:
# Example: attacks/custom_jammer.py
def run(args):
print("[*] Sending test packet to", args.address)And register it via CLI:
python main.py attack --type custom-jammer --address <MAC> --unsafeBlexploit is under structured development with the following planned milestones:
- macOS BLE scanning (via CoreBluetooth backend)
- CLI+video replay demo (asciinema or GIF)
- Animated fakekey/replay visualization in terminal
- Public
v1.0.0release tag and changelog - README translations for international security audiences
- Auto-tagging exploit logs for post-triage export (CSV/JSON)
Contributions are welcome! If you have ideas for new attack modules, improvements to fingerprinting, or better simulation flows — feel free to open an issue or submit a pull request. Please see CONTRIBUTING.md for setup instructions and contribution guidelines.
Blexploit is intended strictly for authorized testing and research.
All live attack modules (--attack, --write-test) require:
- The
--unsafeflag - A typed confirmation in the CLI prompt (
yoryesmust be entered manually)
This project is licensed under the MIT license with an added ethical use clause. By using this tool, you agree to use it only in authorized environments.
Do not use against systems you do not own or have explicit permission to test.
The author assumes no responsibility for misuse or damage caused by this tool.
If you're unsure whether your testing is legal — don’t run it.