GATT, profiles and recorded session reconstruction #1364

New issue

Open

opened 2026-10-16 21:04:42 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:42 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3644

Summary

Bluetooth and Bluetooth Low Energy (BLE) represent the primary short-range wireless communication standard for IoT peripherals, wearable health monitors, smart locks, medical sensors, automotive telematics, and consumer hardware. In wireless hardware reverse engineering and security research, analysts record over-the-air or host-controller Bluetooth communications as btsnoop or PCAP/PCAPNG captures.

While REA possesses network PCAP (#3599) and USB capture (#3641) primitives, it currently has no parser for Bluetooth protocols or BLE GATT profiles. Reversing an unknown Bluetooth/BLE peripheral requires:

Parsing the Host Controller Interface (HCI) packet stream (Commands, Events, ACL Data, Synchronous Data);
Reconstructing BLE Advertising and Scan Response data packets (Manufacturer Specific Data, Service UUIDs, Flags);
Parsing the Logical Link Control and Adaptation Protocol (L2CAP) signaling and multiplexed channels;
Reconstructing the Attribute Protocol (ATT) and Generic Attribute Profile (GATT) hierarchy: Services, Characteristics, Descriptors, Read/Write operations, Notifications, and Indications;
Inferring proprietary BLE command-response protocols and state machines.

This feature proposal introduces dedicated Bluetooth and BLE Reverse Engineering to REA, enabling automated ingestion of btsnoop/PCAP captures, reconstruction of the full GATT service database, and inference of proprietary device protocols.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: btsnoop / PCAP Bluetooth Capture |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | HCI Packet Stream Parser  |                                   | BLE Advertising & Pairing |
           | (HCI H4/H5, ACL Data, Evt)|                                   | Packet Reconstructor      |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | L2CAP Multiplexer & Channel Tracker   |
                                     | (Signaling, Security Mgr, ATT 0x0004) |
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | ATT / GATT Attribute Table Recovery   |
                                     | (Primary Services, Chars, Descriptors)|
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Value Transfer Inversion  |                                   | Proprietary BLE Protocol  |
           | (Read, Write, Notify, Ind)|                                   | Inference & State Machine |
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: GATT Profile Dossier,   |
                                     | Inferred Commands & Python Replay     |
                                     +---------------------------------------+

1. Bluetooth Capture Ingestion (btsnoop & PCAP)

Format Ingestion: Support btsnoop format versions 1 and 2 (btsnoop header magic 62 74 73 6e 6f 6f 70 00), Android bugreport btsnoop_hci.log, and PCAP/PCAPNG files with Bluetooth link types (LINKTYPE_BLUETOOTH_HCI_H4 = 187, LINKTYPE_BLUETOOTH_LINUX_MONITOR = 251).
Packet Extraction: Parse packet indicators (HCI Command = 1, ACL Data = 2, SCO Data = 3, HCI Event = 4, ISO Data = 5), timestamps, directions (Host-to-Controller / Controller-to-Host), and channel IDs.

2. BLE Advertising & Pairing Reconstruction

Advertising Reports: Parse HCI_LE_Advertising_Report and extended advertising packets:
- Advertising types: connectable undirected, scannable, non-connectable.
- AdvData / ScanResponse payload carving: Flags, 16-bit/128-bit Service Class UUIDs, Local Name strings, TX Power Level, and Manufacturer Specific Data (e.g. Apple iBeacon / AirTag payloads, Google Fast Pair, Exposure Notification).
Pairing & Security Metadata: Track Security Manager Protocol (SMP) exchanges: Pairing Request/Response, authentication requirements (Just Works, Passkey Entry, Numeric Comparison), and encryption key generation flags.

3. L2CAP & ATT / GATT Service Table Recovery

L2CAP Channel Tracking: Demultiplex L2CAP frames across Fixed Channels: Signaling (0x0001/0x0005), Connectionless (0x0002), Security Manager (0x0006), and Attribute Protocol (0x0004).
GATT Database Reconstruction: Assemble the remote peripheral's attribute table by parsing GATT discovery procedures:
- Primary & Secondary Services: UUID, handle ranges (0x0001 - 0xFFFF).
- Characteristics: Characteristic Declaration handles, properties (Read, Write Without Response, Write, Notify, Indicate), value handles, and characteristic UUIDs.
- Descriptors: Client Characteristic Configuration Descriptors (CCCD - 0x2902), User Description (0x2901), Format (0x2904).
Standard UUID Resolution: Map standard 16-bit UUIDs to SIG specifications (e.g. Heart Rate 0x180D, Battery 0x180F, Device Info 0x180A).

4. Value Transfer Analysis & Proprietary Protocol Inference

Transaction Pairing: Pair ATT Read Requests with Read Responses, and Write Requests with Write Responses.
Notification / Indication Streams: Aggregate asynchronous telemetry emitted by CCCD subscriptions.
Proprietary Framing Inference: Trace repeating binary payloads across custom 128-bit vendor characteristics to identify packet headers, command opcodes, sequence counters, and CRC/checksum tails.
Client Script Synthesis: Synthesize working Python (bleak) or Web Bluetooth client boilerplate scripts replicating the discovered service discovery, authentication, and command-response procedures.

Acceptance Criteria

Introduce analyze_bluetooth_capture in REA CLI and MCP contracts, accepting .pcap, .pcapng, and btsnoop logs.
Ingest synthetic HCI H4 and Linux Monitor test captures without format errors.
Reconstruct a complete GATT database (Services, Characteristics, CCCD descriptors) from synthetic discovery captures.
Extract manufacturer-specific advertising payloads and identify device identities.
Invert proprietary command-response exchanges into structured JSON dossiers and export working bleak replay scripts.

#3599 [Feature] Passive DNS extraction and cybersecurity analysis primitives
#3615 [Feature] Hardware and Embedded Reverse Engineering: ESP32 firmware
#3641 [Feature] USB protocol reverse engineering: descriptors and HID reports

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3644 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary Bluetooth and Bluetooth Low Energy (BLE) represent the primary short-range wireless communication standard for IoT peripherals, wearable health monitors, smart locks, medical sensors, automotive telematics, and consumer hardware. In wireless hardware reverse engineering and security research, analysts record over-the-air or host-controller Bluetooth communications as **btsnoop** or **PCAP/PCAPNG** captures. While REA possesses network PCAP (#3599) and USB capture (#3641) primitives, it currently has no parser for Bluetooth protocols or BLE GATT profiles. Reversing an unknown Bluetooth/BLE peripheral requires: - Parsing the Host Controller Interface (HCI) packet stream (Commands, Events, ACL Data, Synchronous Data); - Reconstructing BLE Advertising and Scan Response data packets (Manufacturer Specific Data, Service UUIDs, Flags); - Parsing the Logical Link Control and Adaptation Protocol (L2CAP) signaling and multiplexed channels; - Reconstructing the Attribute Protocol (ATT) and Generic Attribute Profile (GATT) hierarchy: Services, Characteristics, Descriptors, Read/Write operations, Notifications, and Indications; - Inferring proprietary BLE command-response protocols and state machines. This feature proposal introduces dedicated **Bluetooth and BLE Reverse Engineering** to REA, enabling automated ingestion of btsnoop/PCAP captures, reconstruction of the full GATT service database, and inference of proprietary device protocols. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: btsnoop / PCAP Bluetooth Capture | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | HCI Packet Stream Parser | | BLE Advertising & Pairing | | (HCI H4/H5, ACL Data, Evt)| | Packet Reconstructor | +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | L2CAP Multiplexer & Channel Tracker | | (Signaling, Security Mgr, ATT 0x0004) | +-------------------+-------------------+ | v +---------------------------------------+ | ATT / GATT Attribute Table Recovery | | (Primary Services, Chars, Descriptors)| +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Value Transfer Inversion | | Proprietary BLE Protocol | | (Read, Write, Notify, Ind)| | Inference & State Machine | +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | REA Evidence: GATT Profile Dossier, | | Inferred Commands & Python Replay | +---------------------------------------+ ``` ### 1. Bluetooth Capture Ingestion (btsnoop & PCAP) - **Format Ingestion:** Support btsnoop format versions 1 and 2 (`btsnoop` header magic `62 74 73 6e 6f 6f 70 00`), Android bugreport `btsnoop_hci.log`, and PCAP/PCAPNG files with Bluetooth link types (`LINKTYPE_BLUETOOTH_HCI_H4 = 187`, `LINKTYPE_BLUETOOTH_LINUX_MONITOR = 251`). - **Packet Extraction:** Parse packet indicators (HCI Command = 1, ACL Data = 2, SCO Data = 3, HCI Event = 4, ISO Data = 5), timestamps, directions (Host-to-Controller / Controller-to-Host), and channel IDs. ### 2. BLE Advertising & Pairing Reconstruction - **Advertising Reports:** Parse `HCI_LE_Advertising_Report` and extended advertising packets: - Advertising types: connectable undirected, scannable, non-connectable. - AdvData / ScanResponse payload carving: Flags, 16-bit/128-bit Service Class UUIDs, Local Name strings, TX Power Level, and Manufacturer Specific Data (e.g. Apple iBeacon / AirTag payloads, Google Fast Pair, Exposure Notification). - **Pairing & Security Metadata:** Track Security Manager Protocol (SMP) exchanges: Pairing Request/Response, authentication requirements (Just Works, Passkey Entry, Numeric Comparison), and encryption key generation flags. ### 3. L2CAP & ATT / GATT Service Table Recovery - **L2CAP Channel Tracking:** Demultiplex L2CAP frames across Fixed Channels: Signaling (0x0001/0x0005), Connectionless (0x0002), Security Manager (0x0006), and Attribute Protocol (0x0004). - **GATT Database Reconstruction:** Assemble the remote peripheral's attribute table by parsing GATT discovery procedures: - **Primary & Secondary Services:** UUID, handle ranges (`0x0001` - `0xFFFF`). - **Characteristics:** Characteristic Declaration handles, properties (Read, Write Without Response, Write, Notify, Indicate), value handles, and characteristic UUIDs. - **Descriptors:** Client Characteristic Configuration Descriptors (CCCD - `0x2902`), User Description (`0x2901`), Format (`0x2904`). - **Standard UUID Resolution:** Map standard 16-bit UUIDs to SIG specifications (e.g. Heart Rate `0x180D`, Battery `0x180F`, Device Info `0x180A`). ### 4. Value Transfer Analysis & Proprietary Protocol Inference - **Transaction Pairing:** Pair ATT Read Requests with Read Responses, and Write Requests with Write Responses. - **Notification / Indication Streams:** Aggregate asynchronous telemetry emitted by CCCD subscriptions. - **Proprietary Framing Inference:** Trace repeating binary payloads across custom 128-bit vendor characteristics to identify packet headers, command opcodes, sequence counters, and CRC/checksum tails. - **Client Script Synthesis:** Synthesize working **Python (`bleak`)** or **Web Bluetooth** client boilerplate scripts replicating the discovered service discovery, authentication, and command-response procedures. --- ## Acceptance Criteria 1. Introduce `analyze_bluetooth_capture` in REA CLI and MCP contracts, accepting `.pcap`, `.pcapng`, and `btsnoop` logs. 2. Ingest synthetic HCI H4 and Linux Monitor test captures without format errors. 3. Reconstruct a complete GATT database (Services, Characteristics, CCCD descriptors) from synthetic discovery captures. 4. Extract manufacturer-specific advertising payloads and identify device identities. 5. Invert proprietary command-response exchanges into structured JSON dossiers and export working `bleak` replay scripts. --- ## Related - #3599 [Feature] Passive DNS extraction and cybersecurity analysis primitives - #3615 [Feature] Hardware and Embedded Reverse Engineering: ESP32 firmware - #3641 [Feature] USB protocol reverse engineering: descriptors and HID reports

bsakaguchi referenced this issue

2026-10-17 21:04:21 +00:00

[GH-ISSUE #4636] [Bug] MCP browser scenario validation omits the typed input-error diagnostic #2416

bsakaguchi referenced this issue

2026-10-17 21:10:47 +00:00

[PR #1366] [MERGED] fix(mcp): preserve JavaScript workflow identity validation #2830