untether-bt 0.7.0__py3-none-any.whl

untether_bt/__init__.py

@@ -0,0 +1,153 @@
+"""untether-bt — a Bluetooth Swiss-army-knife for reverse engineering, troubleshooting, and engineering.
+
+First-class Bluetooth **Classic (RFCOMM/SPP)** support — reachable from any host or from Home
+Assistant via the companion ``untether_spp`` ESP32 bridge — plus the protocol primitives the
+BLE-only ecosystem leaves to you. Includes: the framing/codec engine, the SPP bridge client, the
+advertisement decoder, and the full reverse-engineering pipeline: the live ADB/UIAutomator driver
+(drive the vendor app, mark each action) → btsnoop capture → HCI/ATT extraction → UI-action↔
+wire-byte correlation. jadx/Frida wrappers and SDP/GATT-over-bleak follow.
+"""
+
+from __future__ import annotations
+
+from .advertising import (
+    ADStructure,
+    flags,
+    local_name,
+    manufacturer_data,
+    parse_ad,
+    service_data,
+    service_uuids16,
+)
+from .android import AdbError, AdbRunner, AndroidDriver, extract_btsnoop_from_zip
+from .apk import (
+    ApkAnalysis,
+    Finding,
+    analyze_apk,
+    analyze_tree,
+    decompile_apk,
+    pull_apk,
+)
+from .frida import FridaSession, hook_script_path, parse_hook_message
+from .gatt import GattClient, normalize_uuid
+from .numbers import (
+    company_name,
+    describe_uuid,
+    gatt_name,
+    sdp_service_name,
+    uuid16_to_128,
+    uuid128_to_16,
+)
+from .sdp import (
+    find_rfcomm_channels,
+    parse_data_element,
+    parse_records,
+    parse_ssa_response,
+    rfcomm_channel,
+    spp_channel,
+)
+from .uiauto import UiNode, find_node, parse_ui_dump
+from .btsnoop import (
+    Btsnoop,
+    BtsnoopRecord,
+    decompress_btsnooz,
+    is_btsnooz,
+    load_btsnoop,
+    make_record,
+    parse_btsnoop,
+    write_btsnoop,
+)
+from .capture import Capture, Correlation, Mark, Recorder, WireEvent, correlate
+from .framing import (
+    DIVOOM_NEWMODE,
+    DIVOOM_STUFFED,
+    Frame,
+    Framing,
+    Stuffing,
+    crc_sum16,
+)
+from .hci import AttPdu, HciPacket, L2capPayload, att_pdus, hci_packets, l2cap_payloads
+from .spp import AsyncSppBridge, SppBridge
+from .connection import SppConnection
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "__version__",
+    # framing
+    "Framing",
+    "Frame",
+    "Stuffing",
+    "crc_sum16",
+    "DIVOOM_NEWMODE",
+    "DIVOOM_STUFFED",
+    # spp
+    "SppBridge",
+    "AsyncSppBridge",
+    "SppConnection",
+    # advertising
+    "ADStructure",
+    "parse_ad",
+    "manufacturer_data",
+    "service_data",
+    "service_uuids16",
+    "local_name",
+    "flags",
+    # capture / reverse-engineering
+    "Btsnoop",
+    "BtsnoopRecord",
+    "parse_btsnoop",
+    "write_btsnoop",
+    "make_record",
+    "decompress_btsnooz",
+    "is_btsnooz",
+    "load_btsnoop",
+    "HciPacket",
+    "L2capPayload",
+    "AttPdu",
+    "hci_packets",
+    "l2cap_payloads",
+    "att_pdus",
+    "Capture",
+    "WireEvent",
+    "Mark",
+    "Correlation",
+    "Recorder",
+    "correlate",
+    # android live driver (RE pipeline)
+    "AndroidDriver",
+    "AdbRunner",
+    "AdbError",
+    "extract_btsnoop_from_zip",
+    "UiNode",
+    "parse_ui_dump",
+    "find_node",
+    # static analysis (jadx)
+    "ApkAnalysis",
+    "Finding",
+    "analyze_tree",
+    "analyze_apk",
+    "decompile_apk",
+    "pull_apk",
+    # dynamic instrumentation (frida)
+    "FridaSession",
+    "parse_hook_message",
+    "hook_script_path",
+    # assigned numbers
+    "uuid16_to_128",
+    "uuid128_to_16",
+    "company_name",
+    "gatt_name",
+    "sdp_service_name",
+    "describe_uuid",
+    # sdp
+    "parse_data_element",
+    "parse_records",
+    "parse_ssa_response",
+    "rfcomm_channel",
+    "find_rfcomm_channels",
+    "spp_channel",
+    # gatt (over bleak)
+    "GattClient",
+    "normalize_uuid",
+]

untether_bt/advertising.py

@@ -0,0 +1,104 @@
+"""BLE advertisement parsing — the passive-broadcast layer.
+
+Many BLE sensors never accept a connection; they broadcast their state in the advertisement's
+manufacturer- or service-data. This module parses the AD structure list per the Core Specification
+Supplement (each element is ``[length][AD type][data]``, where ``length`` counts the type byte but
+not itself), and pulls out the fields you actually reverse-engineer against.
+
+Note the endianness traps the spec calls out: the 16-bit Company Identifier (in manufacturer data)
+and 16-bit Service-Data UUIDs are **little-endian**.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# AD type codes (Assigned Numbers / CSS)
+AD_FLAGS = 0x01
+AD_UUID16_INCOMPLETE = 0x02
+AD_UUID16_COMPLETE = 0x03
+AD_NAME_SHORT = 0x08
+AD_NAME_COMPLETE = 0x09
+AD_TX_POWER = 0x0A
+AD_SERVICE_DATA_16 = 0x16
+AD_SERVICE_DATA_32 = 0x20
+AD_SERVICE_DATA_128 = 0x21
+AD_MANUFACTURER = 0xFF
+
+
+@dataclass(frozen=True)
+class ADStructure:
+    type: int
+    data: bytes
+
+
+def parse_ad(payload: bytes) -> list[ADStructure]:
+    """Parse a raw advertisement (or scan-response) payload into AD structures.
+
+    Tolerant of the trailing zero-padding controllers add, and of truncation.
+    """
+    out: list[ADStructure] = []
+    i, n = 0, len(payload)
+    while i < n:
+        length = payload[i]
+        if length == 0:
+            break  # padding
+        if i + 1 + length > n:
+            break  # truncated
+        out.append(ADStructure(payload[i + 1], payload[i + 2 : i + 1 + length]))
+        i += 1 + length
+    return out
+
+
+def _structs(ad: bytes | list[ADStructure]) -> list[ADStructure]:
+    return parse_ad(ad) if isinstance(ad, (bytes, bytearray)) else ad
+
+
+def manufacturer_data(ad: bytes | list[ADStructure]) -> tuple[int, bytes] | None:
+    """Return ``(company_id, data)`` from the Manufacturer Specific Data (0xFF), or None.
+
+    ``company_id`` is decoded little-endian per spec.
+    """
+    for s in _structs(ad):
+        if s.type == AD_MANUFACTURER and len(s.data) >= 2:
+            return int.from_bytes(s.data[:2], "little"), s.data[2:]
+    return None
+
+
+def service_data(ad: bytes | list[ADStructure]) -> dict[int, bytes]:
+    """Map 16-bit Service-Data UUID -> its data bytes (UUID decoded little-endian)."""
+    out: dict[int, bytes] = {}
+    for s in _structs(ad):
+        if s.type == AD_SERVICE_DATA_16 and len(s.data) >= 2:
+            out[int.from_bytes(s.data[:2], "little")] = s.data[2:]
+    return out
+
+
+def service_uuids16(ad: bytes | list[ADStructure]) -> list[int]:
+    """All advertised 16-bit service UUIDs (complete + incomplete lists), little-endian."""
+    out: list[int] = []
+    for s in _structs(ad):
+        if s.type in (AD_UUID16_INCOMPLETE, AD_UUID16_COMPLETE):
+            for j in range(0, len(s.data) - 1, 2):
+                out.append(int.from_bytes(s.data[j : j + 2], "little"))
+    return out
+
+
+def local_name(ad: bytes | list[ADStructure]) -> str | None:
+    """The advertised local name (complete preferred over shortened)."""
+    short = None
+    for s in _structs(ad):
+        if s.type == AD_NAME_COMPLETE:
+            return s.data.decode("utf-8", "replace")
+        if s.type == AD_NAME_SHORT and short is None:
+            short = s.data.decode("utf-8", "replace")
+    return short
+
+
+def flags(ad: bytes | list[ADStructure]) -> int | None:
+    """The Flags byte (0x01), if present. bit0 LE Limited Disc, bit1 LE General Disc,
+    bit2 BR/EDR Not Supported."""
+    for s in _structs(ad):
+        if s.type == AD_FLAGS and s.data:
+            return s.data[0]
+    return None

untether_bt/android.py

@@ -0,0 +1,159 @@
+"""Drive an Android device over ADB to reverse-engineer its Bluetooth app.
+
+The live half of the RE loop: enable HCI snoop, drive the vendor app by accessibility label while
+**marking** each UI action, then pull the capture and (with :func:`untether_bt.capture.correlate`)
+see exactly which wire bytes each action produced.
+
+The driver runs adb through an injectable runner, so the pure logic is fully unit-tested and the
+real device path is a thin shell. Capture is pulled via ``adb bugreport`` (works unrooted) or a
+direct path (rooted).
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import tempfile
+import zipfile
+from typing import Protocol
+
+from .capture import Recorder
+from .uiauto import UiNode, find_node, parse_ui_dump
+
+_UI_REMOTE = "/sdcard/untether_ui.xml"
+_DEFAULT_SNOOP_PATH = "/data/misc/bluetooth/logs/btsnoop_hci.log"
+
+
+class AdbError(RuntimeError):
+    pass
+
+
+class Runner(Protocol):
+    def run(self, *args: str) -> str: ...
+    def run_bytes(self, *args: str) -> bytes: ...
+    def shell(self, *args: str) -> str: ...
+
+
+class AdbRunner:
+    """Default runner: shells out to the ``adb`` binary (optionally targeting a serial)."""
+
+    def __init__(self, serial: str | None = None, adb_path: str = "adb", timeout: float = 90.0):
+        self._base = [adb_path] + (["-s", serial] if serial else [])
+        self._timeout = timeout
+
+    def _exec(self, args: tuple[str, ...], *, text: bool):
+        import subprocess
+
+        p = subprocess.run(  # noqa: S603
+            [*self._base, *args], capture_output=True, timeout=self._timeout
+        )
+        if p.returncode != 0:
+            raise AdbError(f"adb {' '.join(args)} failed: {p.stderr.decode('utf-8', 'replace')[:300]}")
+        return p.stdout.decode("utf-8", "replace") if text else p.stdout
+
+    def run(self, *args: str) -> str:
+        return self._exec(args, text=True)
+
+    def run_bytes(self, *args: str) -> bytes:
+        return self._exec(args, text=False)
+
+    def shell(self, *args: str) -> str:
+        return self.run("shell", *args)
+
+
+def extract_btsnoop_from_zip(zip_path: str) -> bytes:
+    """Pull the btsnoop_hci.log out of an ``adb bugreport`` zip."""
+    with zipfile.ZipFile(zip_path) as z:
+        names = z.namelist()
+        cands = [n for n in names if "btsnoop" in n.lower()]
+        if not cands:
+            raise AdbError("no btsnoop log found in bugreport zip")
+        # prefer the real uncompressed btsnoop_hci.log, then largest
+        cands.sort(key=lambda n: (not n.endswith("btsnoop_hci.log"), -z.getinfo(n).file_size))
+        return z.read(cands[0])
+
+
+class AndroidDriver:
+    """High-level ADB driver for app-driven Bluetooth reverse engineering."""
+
+    def __init__(self, serial: str | None = None, runner: Runner | None = None):
+        self.adb: Runner = runner if runner is not None else AdbRunner(serial)
+
+    # ---- device ----
+    def devices(self) -> list[str]:
+        out = self.adb.run("devices")
+        return [
+            line.split("\t", 1)[0]
+            for line in out.splitlines()[1:]
+            if "\tdevice" in line
+        ]
+
+    def launch(self, package: str) -> None:
+        self.adb.shell("monkey", "-p", package, "-c", "android.intent.category.LAUNCHER", "1")
+
+    # ---- UI (accessibility-hierarchy driven) ----
+    def dump_ui(self) -> list[UiNode]:
+        self.adb.shell("uiautomator", "dump", _UI_REMOTE)
+        raw = self.adb.run_bytes("exec-out", "cat", _UI_REMOTE)
+        return parse_ui_dump(raw.decode("utf-8", "replace"))
+
+    def tap_xy(self, x: int, y: int) -> None:
+        self.adb.shell("input", "tap", str(x), str(y))
+
+    def tap(self, label: str, *, fields: tuple[str, ...] = ("text", "desc", "resource_id")) -> UiNode:
+        """Find a node by accessibility label and tap its center. Raises if not found."""
+        node = find_node(self.dump_ui(), label, fields=fields)
+        if node is None or node.center is None:
+            raise AdbError(f"no tappable node matching {label!r}")
+        self.tap_xy(*node.center)
+        return node
+
+    def text(self, value: str) -> None:
+        self.adb.shell("input", "text", value.replace(" ", "%s"))
+
+    def key(self, code: int) -> None:
+        self.adb.shell("input", "keyevent", str(code))
+
+    def back(self) -> None:
+        self.key(4)
+
+    def home(self) -> None:
+        self.key(3)
+
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, ms: int = 300) -> None:
+        self.adb.shell("input", "swipe", str(x1), str(y1), str(x2), str(y2), str(ms))
+
+    # ---- HCI snoop capture ----
+    def enable_hci_snoop(self, *, restart_bt: bool = True) -> None:
+        """Turn on Bluetooth HCI snoop logging.
+
+        Note: on many builds the durable switch is the Developer Options toggle
+        ("Enable Bluetooth HCI snoop log"); this sets the setting and (by default) restarts the
+        Bluetooth stack so it takes effect. If captures come back empty, flip the toggle by hand.
+        """
+        self.adb.shell("settings", "put", "global", "bluetooth_hci_log", "1")
+        if restart_bt:
+            self.adb.shell("svc", "bluetooth", "disable")
+            self.adb.shell("svc", "bluetooth", "enable")
+
+    def pull_btsnoop(self) -> bytes:
+        """Pull the current capture via ``adb bugreport`` (works unrooted). Returns btsnoop bytes."""
+        with tempfile.TemporaryDirectory() as d:
+            self.adb.run("bugreport", d)
+            zips = glob.glob(os.path.join(d, "*.zip"))
+            if not zips:
+                raise AdbError("adb bugreport produced no zip")
+            zips.sort(key=os.path.getmtime, reverse=True)
+            return extract_btsnoop_from_zip(zips[0])
+
+    def pull_btsnoop_path(self, path: str = _DEFAULT_SNOOP_PATH, *, su: bool = False) -> bytes:
+        """Pull the capture directly from its path (rooted devices)."""
+        args = ("exec-out", "su", "0", "cat", path) if su else ("exec-out", "cat", path)
+        return self.adb.run_bytes(*args)
+
+    # ---- the harness helper ----
+    def tap_and_mark(self, label: str, recorder: Recorder, **kw: object) -> UiNode:
+        """Tap a labelled node and timestamp the action into ``recorder`` for later correlation."""
+        node = self.tap(label, **kw)  # type: ignore[arg-type]
+        recorder.mark(label)
+        return node

untether_bt/apk.py

@@ -0,0 +1,149 @@
+"""Static analysis of a vendor app — decompile with jadx, then map the Bluetooth surface.
+
+This is Phase-0/1 of the methodology automated: get the APK (off a connected device or a local
+file), decompile it, and answer the questions that steer everything downstream — **is this app BLE
+GATT or Bluetooth Classic SPP?**, which **UUIDs**/characteristics does it touch, and **where** are
+the command-building / write call sites.
+
+``analyze_tree`` is pure (point it at any decompiled source tree); ``decompile_apk`` / ``pull_apk``
+are thin wrappers around ``jadx`` and ``adb``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .android import AdbRunner, Runner
+
+# --- signal patterns ---
+_UUID128 = re.compile(
+    r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"
+)
+_SPP_UUID = re.compile(r"0000110[0-9a-fA-F]-0000-1000-8000-00805f9b34fb", re.IGNORECASE)
+
+# kind -> regex. Order matters only for readability; every line is checked against all.
+_SIGNALS: dict[str, re.Pattern[str]] = {
+    "ble_write": re.compile(r"writeCharacteristic|writeDescriptor|\.setValue\("),
+    "ble_notify": re.compile(r"setCharacteristicNotification|onCharacteristicChanged"),
+    "ble_gatt": re.compile(r"BluetoothGatt|connectGatt|BluetoothLeScanner|BluetoothGattCharacteristic"),
+    "rfcomm": re.compile(r"createRfcommSocket|createInsecureRfcommSocket|BluetoothSocket"),
+    "byte_builder": re.compile(r"new byte\[\]\s*\{"),
+}
+_BLE_KINDS = {"ble_write", "ble_notify", "ble_gatt"}
+_CLASSIC_KINDS = {"rfcomm"}
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    file: str   # path relative to the analyzed root
+    line: int
+    snippet: str
+
+
+@dataclass
+class ApkAnalysis:
+    transport: str = "unknown"           # "ble" | "classic-spp" | "both" | "unknown"
+    gatt_uuids: list[str] = field(default_factory=list)
+    has_spp_uuid: bool = False
+    findings: list[Finding] = field(default_factory=list)
+
+    def by_kind(self) -> Counter[str]:
+        return Counter(f.kind for f in self.findings)
+
+    def summary(self) -> str:
+        counts = self.by_kind()
+        lines = [f"transport: {self.transport}"]
+        if self.has_spp_uuid:
+            lines.append("Serial Port (SPP) service UUID present (00001101)")
+        if self.gatt_uuids:
+            lines.append(f"{len(self.gatt_uuids)} distinct 128-bit UUID(s): " + ", ".join(self.gatt_uuids[:6]))
+        lines += [f"  {k}: {counts[k]}" for k in sorted(counts)]
+        return "\n".join(lines)
+
+
+def analyze_tree(root: str | Path, *, max_snippet: int = 160) -> ApkAnalysis:
+    """Walk a decompiled source tree (.java) and map its Bluetooth surface."""
+    root = Path(root)
+    findings: list[Finding] = []
+    uuids: set[str] = set()
+    has_spp = False
+    kinds_seen: set[str] = set()
+    for path in root.rglob("*.java"):
+        try:
+            text = path.read_text("utf-8", "replace")
+        except OSError:
+            continue
+        rel = str(path.relative_to(root))
+        for i, line in enumerate(text.splitlines(), 1):
+            for u in _UUID128.findall(line):
+                uuids.add(u.lower())
+            if _SPP_UUID.search(line):
+                has_spp = True
+            for kind, pat in _SIGNALS.items():
+                if pat.search(line):
+                    kinds_seen.add(kind)
+                    findings.append(Finding(kind, rel, i, line.strip()[:max_snippet]))
+
+    ble = bool(kinds_seen & _BLE_KINDS)
+    classic = has_spp or bool(kinds_seen & _CLASSIC_KINDS)
+    transport = (
+        "both" if ble and classic
+        else "ble" if ble
+        else "classic-spp" if classic
+        else "unknown"
+    )
+    return ApkAnalysis(
+        transport=transport,
+        gatt_uuids=sorted(uuids),
+        has_spp_uuid=has_spp,
+        findings=findings,
+    )
+
+
+def decompile_apk(apk_path: str | Path, out_dir: str | Path, *, jadx: str = "jadx") -> Path:
+    """Run ``jadx -d <out_dir> <apk>`` and return the output directory."""
+    import subprocess
+
+    out = Path(out_dir)
+    p = subprocess.run(  # noqa: S603
+        [jadx, "-d", str(out), str(apk_path)], capture_output=True, text=True
+    )
+    # jadx returns non-zero on partial-decompile warnings but still produces usable sources.
+    if not any(out.rglob("*.java")):
+        raise RuntimeError(f"jadx produced no sources: {p.stderr[:300]}")
+    return out
+
+
+def pull_apk(package: str, dest: str | Path, *, runner: Runner | None = None) -> Path:
+    """Pull an installed app's base APK off a connected device via adb."""
+    adb = runner if runner is not None else AdbRunner()
+    paths = adb.run("shell", "pm", "path", package)
+    base = None
+    for line in paths.splitlines():
+        line = line.strip()
+        if line.startswith("package:") and line.endswith("base.apk"):
+            base = line[len("package:") :]
+            break
+    if base is None:  # no explicit base.apk (single non-split) — take the first
+        for line in paths.splitlines():
+            if line.startswith("package:"):
+                base = line.strip()[len("package:") :]
+                break
+    if base is None:
+        raise RuntimeError(f"package {package} not found on device")
+    dest = Path(dest)
+    adb.run("pull", base, str(dest))
+    return dest
+
+
+def analyze_apk(apk_path: str | Path, *, jadx: str = "jadx") -> ApkAnalysis:
+    """Decompile an APK (to a temp dir) and analyze it."""
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as d:
+        out = decompile_apk(apk_path, d, jadx=jadx)
+        return analyze_tree(out)

untether_bt/bluez.py

@@ -0,0 +1,34 @@
+"""Live SDP browsing on Linux via BlueZ (optional, needs pybluez).
+
+The only first-class way to *issue* a Classic SDP query from Python is a Classic-capable host stack.
+On Linux/BlueZ that's pybluez (``pip install untether-bt[bluez]``; Linux only). This is a thin
+wrapper that returns the dynamic RFCOMM/SPP channel — so you don't hardcode it. (On other hosts,
+recover the channel from a capture via ``Capture.sdp_records()`` + ``sdp.spp_channel``, or let the
+``untether_spp`` ESP32 bridge SDP-discover it on-device with ``channel: 0``.)
+"""
+
+from __future__ import annotations
+
+SPP_CLASS = "1101"
+
+
+def browse_services(mac: str) -> list[dict]:
+    """All advertised services for a device (raw pybluez records)."""
+    import bluetooth  # pybluez — Linux only
+
+    return bluetooth.find_service(address=mac)
+
+
+def _is_spp(svc: dict) -> bool:
+    classes = svc.get("service-classes") or []
+    return any(SPP_CLASS in str(c).upper() for c in classes)
+
+
+def spp_channel(mac: str) -> int | None:
+    """The RFCOMM channel of the device's Serial Port service (falls back to any RFCOMM port)."""
+    services = browse_services(mac)
+    rfcomm = [s for s in services if s.get("protocol") == "RFCOMM" and s.get("port")]
+    for s in rfcomm:
+        if _is_spp(s):
+            return int(s["port"])
+    return int(rfcomm[0]["port"]) if rfcomm else None