Anthropic-Cybersecurity-Skills/skills/detecting-bluetooth-low-energy-attacks/references/api-reference.md

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

# 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