mirror of
https://github.com/mukul975/Anthropic-Cybersecurity-Skills.git
synced 2026-06-12 06:04:56 +03:00
mukul975
93 lines
5.2 KiB
Markdown
93 lines
5.2 KiB
Markdown
# API Reference: BLE Attack Detection Agent
|
|
|
|
## Overview
|
|
|
|
Scans, enumerates, and analyzes Bluetooth Low Energy devices for security vulnerabilities including weak pairing, replay attack susceptibility, insecure GATT permissions, advertising spoofing, and Man-in-the-Middle indicators. Combines Ubertooth/nRF hardware sniffing with bleak-based GATT enumeration and crackle-based encryption analysis. For authorized wireless security testing only.
|
|
|
|
## Dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| bleak | >=0.21 | Cross-platform asyncio BLE GATT client for scanning and enumeration |
|
|
| tshark | (system) | Command-line Wireshark for BLE packet extraction and field analysis |
|
|
| ubertooth-btle | (system) | Ubertooth One CLI for passive BLE sniffing and packet capture |
|
|
| crackle | (system) | BLE Legacy Pairing encryption cracker for LTK recovery |
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
# Scan for BLE devices in range
|
|
python agent.py --mode scan --scan-duration 15 --output scan_report.json
|
|
|
|
# Enumerate GATT services on a target device
|
|
python agent.py --mode enumerate --target AA:BB:CC:DD:EE:FF --output gatt_report.json
|
|
|
|
# Test replay vulnerability on a specific characteristic
|
|
python agent.py --mode replay --target AA:BB:CC:DD:EE:FF \
|
|
--char-uuid 0000fff1-0000-1000-8000-00805f9b34fb \
|
|
--replay-payload 0102030405 --output replay_report.json
|
|
|
|
# Monitor for BLE advertising spoofing
|
|
python agent.py --mode monitor --scan-duration 60 \
|
|
--known-devices known.json --output monitor_report.json
|
|
|
|
# Analyze a BLE packet capture
|
|
python agent.py --mode analyze --pcap capture.pcapng --output pcap_report.json
|
|
|
|
# Full assessment with Ubertooth capture
|
|
python agent.py --mode full --target AA:BB:CC:DD:EE:FF \
|
|
--ubertooth-capture 120 --pcap-format ppi \
|
|
--char-uuid 0000fff1-0000-1000-8000-00805f9b34fb \
|
|
--replay-payload 0102030405 --output full_report.json
|
|
```
|
|
|
|
## Arguments
|
|
|
|
| Argument | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `--mode` | No | Operating mode: `scan`, `enumerate`, `replay`, `monitor`, `analyze`, `full` (default: `scan`) |
|
|
| `--target` | Conditional | Target BLE device address (required for enumerate/replay modes) |
|
|
| `--scan-duration` | No | BLE scan duration in seconds (default: 10) |
|
|
| `--char-uuid` | Conditional | GATT characteristic UUID for replay testing |
|
|
| `--replay-payload` | Conditional | Hex-encoded payload for replay test |
|
|
| `--pcap` | Conditional | Path to BLE pcap/pcapng file for analysis mode |
|
|
| `--ubertooth-capture` | No | Capture with Ubertooth for N seconds; 0 to disable (default: 0) |
|
|
| `--pcap-format` | No | Ubertooth capture format: `pcapng`, `ppi`, `le` (default: `pcapng`) |
|
|
| `--known-devices` | No | JSON file mapping known device addresses to names for spoofing detection |
|
|
| `--output` | No | Output report file path (default: `ble_security_report.json`) |
|
|
|
|
## Key Functions
|
|
|
|
### `scan_ble_devices(scan_duration)`
|
|
Discovers BLE devices using bleak BleakScanner. Returns device address, name, RSSI, service UUIDs, manufacturer data, service data, and TX power for each device found.
|
|
|
|
### `enumerate_gatt_services(target_address, timeout)`
|
|
Connects to a BLE peripheral and enumerates all GATT services, characteristics, and descriptors. Reads characteristic values when readable. Flags writable characteristics, write-without-response properties, and characteristics containing sensitive keyword patterns.
|
|
|
|
### `test_replay_vulnerability(target_address, char_uuid, test_payload_hex, read_after)`
|
|
Writes a captured/test payload to a characteristic, then replays the same payload to detect if the device accepts stale commands without freshness validation. Reads state before and after to confirm replay effect.
|
|
|
|
### `detect_advertising_spoofing(scan_duration, known_devices)`
|
|
Monitors BLE advertising in real-time to detect spoofing indicators: same device name from multiple addresses (cloned device), known device names from unknown addresses (impersonation), and abnormal RSSI fluctuations (relay attack).
|
|
|
|
### `analyze_pcap_for_ble_attacks(pcap_path)`
|
|
Analyzes BLE packet captures using tshark and crackle. Detects Just Works pairing, Legacy Pairing without Secure Connections, excessive connection attempts, and attempts LTK recovery with crackle.
|
|
|
|
### `run_ubertooth_capture(output_path, target_address, duration, pcap_format)`
|
|
Starts a passive BLE capture using Ubertooth One in either promiscuous or follow mode. Supports pcapng, PPI (crackle-compatible), and LE pseudoheader output formats.
|
|
|
|
### `generate_report(scan_results, gatt_profiles, replay_results, spoofing_findings, pcap_findings, output_path)`
|
|
Aggregates all findings into a JSON report with severity breakdown and full device/GATT data.
|
|
|
|
## Threat Detection Coverage
|
|
|
|
| Threat | Detection Method | Finding ID |
|
|
|--------|-----------------|------------|
|
|
| Insecure GATT Permissions | GATT enumeration, property analysis | BLE-GATT-001/002/003 |
|
|
| Replay Attack | Payload write + re-write + state comparison | BLE-REPLAY-001 |
|
|
| Device Spoofing | Multi-address name monitoring | BLE-SPOOF-001/002/003 |
|
|
| Just Works Pairing | PCAP SMP opcode analysis | BLE-PAIR-001 |
|
|
| Legacy Pairing (No SC) | PCAP auth_req flag analysis | BLE-PAIR-002 |
|
|
| Weak Encryption | crackle LTK recovery | BLE-CRACK-001 |
|
|
| Connection Flooding | PCAP connection event counting | BLE-PCAP-002 |
|