usb-rea 0.2.1__tar.gz

usb_rea-0.2.1/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.venv
+dist
+drafts
+**/__pycache__
+.pytest_cache
+*.pcap
+*.pcapng

usb_rea-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: tshark + lua for the generated Wireshark dissector tests
+        if: matrix.python == '3.12'
+        run: sudo apt-get update -q && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -q tshark lua5.4
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

usb_rea-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+# Publishes to PyPI via Trusted Publishing (no token stored) when a GitHub release is published.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - run: pip install build twine && python -m build && twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: {name: dist, path: dist}
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/usb-rea
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: {name: dist, path: dist}
+      - uses: pypa/gh-action-pypi-publish@release/v1

usb_rea-0.2.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.pcap
+*.pcapng
+!tests/data/**
+drafts/

usb_rea-0.2.1/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## Unreleased
+
+## v0.2.1 — 2026-10-16
+- multi-packet transactions: actions that send several packets (e.g. write + apply) are inferred as one command; the driver sends all packets in order
+- cross-packet checksums (a later packet carrying a checksum of an earlier one)
+- fix: `mcp` is now a core dependency, so a plain `pip install usb-rea` gives a working `usb-rea mcp`
+
+- MCP tools: richer descriptions (side effects, privileges, when-to-use) and `pydantic.Field` parameter
+  descriptions so Glama TDQS can score the schema; analysis tools accept the same `labels` string/file
+  as the CLI for marker-free captures
+
+## v0.2.0 — 2026-10-15
+Wireshark dissector generator, HID descriptor decoding, wider inference, marker-free captures.
+
+- `usb-rea dissector` (MCP tool `wireshark_dissector`): generate a Wireshark Lua dissector for the inferred protocol —
+  command names in the Info column, decoded values, counters, lookup labels, checksum verification with expert info;
+  tested against real tshark 4.4 in CI. `usb-rea demo` now writes `<device>.lua` too
+- synthetic captures: submission and completion now share one URB id and use proper usbmon data flags,
+  so Wireshark pairs requests with responses (GET DESCRIPTOR responses and VID/PID are decoded)
+- `--labels`: analyse plain Wireshark/USBPcap captures without markers by splitting traffic at the pauses between clicks
+- inference: 32-bit LE/BE linear values and packed bitfields (contiguous bits beside non-zero const bits,
+  including 12-bit spans across two LE bytes); synthetic `dial` device + encode round-trip tests
+- HID report descriptor decoder (`usb-rea hid`, MCP tool `hid_descriptor`): items, reports, bit-exact fields,
+  report IDs, Push/Pop, extended usages, payload decoding; checked against the HID 1.11 boot mouse/keyboard descriptors
+- reports include a HID section and tag each inferred command with its HID report when the capture has GET_DESCRIPTOR 0x22
+- Dockerfile and glama.json so the MCP server can be listed on Glama
+- `usb-rea demo --device dial` (32-bit value + bitfield demo); README capability table, MCP tool list and roadmap
+  updated for 32-bit/bitfield inference and `hid_descriptor`
+- registry metadata: `server.json` (official MCP Registry, `mcp-name` marker in README) and `smithery.yaml`
+- listed on Glama (score badge in README); MCP install snippets now use the git URL so they work before the PyPI release
+
+## v0.1.0 — 2026-10-14
+First public release.
+
+- pcap/pcapng parser for Linux usbmon (DLT 189/220) and Windows USBPcap (DLT 249), pure Python
+- action markers (`usb-rea mark`) and per-action diffing with background-traffic filtering
+- inference: constants, command ids, linear 8/16-bit LE/BE values, multi-value actions, lookup tables,
+  rolling counters, sum/xor/CRC8/CRC16 checksums; leave-one-out guard against coincidental fits
+- Markdown evidence report: every claim linked to Wireshark frame numbers
+- standalone pyusb driver generator (bulk/interrupt and control/HID SET_REPORT)
+- confirmed-only replay, CLI, MCP server (capture, mark, diff, report, scaffold, replay)
+- validation: synthetic devices, liquidctl Kraken X, rivalcfg Rival 100, public Wireshark captures

usb_rea-0.2.1/Dockerfile

@@ -0,0 +1,21 @@
+# Stdio MCP server for Glama / local Docker use.
+# Build: docker build -t usb-rea .
+# Run:   docker run --rm -i usb-rea          (analysis of capture files)
+# Live capture/replay needs host USB access: add --privileged -v /dev/bus/usb:/dev/bus/usb
+FROM python:3.12-slim-bookworm
+
+# libusb is needed by pyusb for replay/scaffolded drivers; analysis works without it
+RUN apt-get update && apt-get install -y --no-install-recommends libusb-1.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_DISABLE_PIP_VERSION_CHECK=1
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[mcp]"
+
+RUN useradd --create-home --uid 1000 app
+USER app
+WORKDIR /home/app
+
+ENTRYPOINT ["usb-rea", "mcp"]

usb_rea-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emir Mrkaljević
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usb_rea-0.2.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: usb-rea
+Version: 0.2.1
+Summary: Reverse Engineer any USB gadget: capture, diff, infer, and generate open drivers with evidence
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=1.2
+Requires-Dist: pyusb>=1.2
+Provides-Extra: dev
+Requires-Dist: mcp<3,>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# usb-rea — Reverse Engineer any USB gadget
+
+<!-- mcp-name: io.github.emirmrkaljevic/usb-rea -->
+
+[![ci](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml/badge.svg)](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-MIT-blue) [![usb-rea MCP server](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea/badges/score.svg)](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea)
+
+![usb-rea demo: capture labelled clicks, get the protocol and a working driver](docs/demo.gif)
+
+Got a USB device that only ships a Windows vendor app (case LCD, RGB controller, mouse, "smart" lamp)? Click around in the vendor app while **usb-rea** captures the USB traffic (usbmon on Linux, USBPcap on Windows), diffs the packets per action, infers the protocol, and writes an open-source Python/libusb driver — with every conclusion linked to the exact packets that prove it.
+
+> Status: alpha (v0.2.0). Validated on synthetic devices, on protocols documented by liquidctl and rivalcfg, and on public Wireshark captures — see [docs/VALIDATION.md](docs/VALIDATION.md). Not yet tested on a physical gadget: your captures are welcome.
+
+## Try it in 10 seconds (no hardware needed)
+```bash
+pip install git+https://github.com/emirmrkaljevic/usb-rea
+usb-rea demo --device fan
+```
+```
+fan    100%  0x5a | counter (+1 per message) | 0x10 | u16be round(value * 1 + 0) | 0x00 | u16le crc16_modbus(bytes[0:6])
+color  100%  0x5a | counter (+1 per message) | 0x20 | round(value * 1 + 0) | round(value[1] * 1 + 0) | round(value[2] * 1 + 0) | u16le crc16_modbus(bytes[0:6])
+mode   100%  0x5a | counter (+1 per message) | 0x30 | lookup 1→0x11, 2→0x22, 3→0x47 | 0x00 | 0x00 | u16le crc16_modbus(bytes[0:6])
+```
+It writes a synthetic capture of a fan controller, recovers the protocol, and writes `report.md` (every claim linked to Wireshark frame numbers) and a working pyusb driver that encodes values it never saw.
+
+`--device lamp` (default) is a simple 8-bit device; `--device dial` shows 32-bit values and packed bitfields:
+```
+position     100%  0xa5 | 0x01 | u32le round(value * 1 + 0) | sum8(bytes[0:6])
+level        100%  0xa5 | 0x02 | bits[0:4] = round(value * 1 + 0) | 0x00 | sum8(bytes[0:4])
+```
+
+## What it can infer
+| Role | Example |
+|---|---|
+| constant header / command id | `5a`, `10` vs `20` vs `30` |
+| linear values, 8-, 16- or 32-bit LE/BE, several per action | `fan 2650` → `0a 5a`; `color 255 24 0`; `position 50000` → `50 c3 00 00` |
+| packed bitfields (bits beside constant flag bits, incl. 12-bit spans over two bytes) | `level 7` → `b7` = flags `b0` + bits[0:4] |
+| lookup tables (non-linear choices) | DPI 250→`08`, 500→`07` … |
+| rolling counters | sequence byte +1 per message |
+| checksums | sum8, xor8, neg/inv sum8, sum16, CRC8, CRC8/MAXIM, CRC16 CCITT-FALSE/XMODEM/MODBUS/KERMIT |
+
+Linear fits must survive leave-one-out cross-checks; otherwise usb-rea falls back to an honest lookup table and says so.
+
+## Real device workflow (Linux)
+```bash
+sudo modprobe usbmon
+usb-rea capture start -o lamp.pcapng
+usb-rea mark -m lamp.pcapng.actions.json "brightness 0%"    # then click it in the vendor app
+usb-rea mark -m lamp.pcapng.actions.json "brightness 50%"   # ...repeat for 3+ values per setting
+usb-rea capture stop
+usb-rea report lamp.pcapng -o report.md
+usb-rea scaffold lamp.pcapng -o lamp_driver.py
+usb-rea dissector lamp.pcapng -o lamp.lua      # Wireshark dissector for the same protocol
+```
+Captured on Windows with USBPcap/Wireshark and no markers? Click each action with a short pause in between, then just list them in order — usb-rea splits the traffic at the pauses:
+```bash
+usb-rea report lamp.pcapng --labels "brightness 0%; brightness 50%; brightness 100%; power off; power on"
+usb-rea scaffold lamp.pcapng --labels labels.txt -o lamp_driver.py   # one label per line
+```
+(Markers, if you have them, are a JSON list of `{"label", "start", "end"}` epoch timestamps.)
+
+## MCP server
+`pip install "usb-rea[mcp] @ git+https://github.com/emirmrkaljevic/usb-rea"` then add `usb-rea mcp` as a stdio server. Tools: `capture_start`, `capture_stop`, `mark_action`, `diff_actions`, `report`, `scaffold_driver`, `hid_descriptor` (decode a HID report descriptor / report payloads), `wireshark_dissector`, `replay_packet` (refuses unless the human confirmed). Analysis tools accept the same `labels` argument as the CLI for marker-free captures.
+
+With [uv](https://docs.astral.sh/uv/) no install step is needed:
+```json
+{"mcpServers": {"usb-rea": {"command": "uvx", "args": ["--from", "usb-rea[mcp] @ git+https://github.com/emirmrkaljevic/usb-rea", "usb-rea", "mcp"]}}}
+```
+Once usb-rea is on PyPI, `--from "usb-rea[mcp]"` is enough. The server is also listed on [Glama](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea), which builds it from the repo's `Dockerfile` and checks that it starts and lists its tools.
+
+## How it works
+1. `usb-rea capture start` — record traffic (usbmon / USBPcap)
+2. `usb-rea mark "brightness 50%"` — label each action you take in the vendor app
+3. `usb-rea diff` — which bytes change per action, value correlation, checksums, counters
+4. `usb-rea infer` — message templates + evidence report
+5. `usb-rea scaffold` — generate a pyusb driver and replay tests
+6. `usb-rea dissector` — write a Wireshark Lua dissector for the inferred protocol
+7. `usb-rea replay` — send packets to the device (only with explicit confirmation)
+8. `usb-rea hid` — decode a HID report descriptor from a capture (GET_DESCRIPTOR 0x22) or from hex, and decode report payloads
+9. `usb-rea mcp` — the same tools as an MCP server for AI agents
+
+### Wireshark dissector
+`usb-rea dissector capture.pcapng -o lamp.lua` turns the inferred protocol into a Wireshark Lua plugin, so you can keep
+capturing and read the traffic as commands instead of hex:
+```bash
+wireshark -X lua_script:lamp.lua capture.pcapng
+tshark -X lua_script:lamp.lua -r capture.pcapng -Y 'usbrea.command == "brightness"'
+```
+Each matching packet gets a `usbrea` tree with the command name, decoded values (`usbrea.brightness.value`), counters,
+lookup labels, and a checksum check (`usbrea.checksum_ok`, with an expert warning on mismatch); the Info column reads
+`brightness 50`. It works for bulk, interrupt and control/HID SET_REPORT transfers, from usbmon or USBPcap, and needs no
+bit library (Wireshark 3.x and 4.x). `-n NAME` changes the filter prefix. CI runs every generated dissector through tshark.
+
+### HID devices
+Most RGB keyboards, mice, headsets and LCD gadgets are HID with a vendor-defined page. If the capture includes the
+report descriptor (start capturing, then replug the device), the report gets a section with every report's ID, size and
+fields, and each inferred command is tagged with the HID report it travels in. Without a capture:
+
+```sh
+usb-rea hid /sys/class/hidraw/hidraw0/device/report_descriptor --items
+usb-rea hid capture.pcapng --decode "10ff0d1d000000" --type Output
+```
+
+## Roadmap
+- [x] pcap/pcapng parser (usbmon + USBPcap)
+- [x] action markers and per-action diffing
+- [x] checksum detection (sum8, xor8, neg/inv sum8, CRC8, CRC16 variants)
+- [x] evidence-backed protocol report
+- [x] driver scaffolding (pyusb, bulk/interrupt + control/HID SET_REPORT)
+- [x] confirmed replay
+- [x] MCP server
+- [x] rolling counters, multi-byte (16/32-bit LE/BE) values, lookup tables, multi-value actions
+- [x] packed bitfields
+- [x] validation against documented protocols (liquidctl, rivalcfg)
+- [x] HID report descriptor decoding (`usb-rea hid`), with captured commands mapped to their HID reports
+- [ ] emulated-device CI (dummy_hcd + configfs HID; script in `scripts/gadget_e2e.sh`)
+- [ ] real-hardware case studies
+- [x] multi-packet transactions (write + apply), including checksums over earlier packets
+- [ ] state machines (request/response handshakes)
+
+## Legal
+Reverse engineering for interoperability is permitted (EU Directive 2009/24/EC Art. 6, US DMCA §1201(f)). usb-rea only analyzes traffic of devices you own and never redistributes vendor code.
+
+## License
+MIT

usb_rea-0.2.1/README.md

@@ -0,0 +1,124 @@
+# usb-rea — Reverse Engineer any USB gadget
+
+<!-- mcp-name: io.github.emirmrkaljevic/usb-rea -->
+
+[![ci](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml/badge.svg)](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-MIT-blue) [![usb-rea MCP server](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea/badges/score.svg)](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea)
+
+![usb-rea demo: capture labelled clicks, get the protocol and a working driver](docs/demo.gif)
+
+Got a USB device that only ships a Windows vendor app (case LCD, RGB controller, mouse, "smart" lamp)? Click around in the vendor app while **usb-rea** captures the USB traffic (usbmon on Linux, USBPcap on Windows), diffs the packets per action, infers the protocol, and writes an open-source Python/libusb driver — with every conclusion linked to the exact packets that prove it.
+
+> Status: alpha (v0.2.0). Validated on synthetic devices, on protocols documented by liquidctl and rivalcfg, and on public Wireshark captures — see [docs/VALIDATION.md](docs/VALIDATION.md). Not yet tested on a physical gadget: your captures are welcome.
+
+## Try it in 10 seconds (no hardware needed)
+```bash
+pip install git+https://github.com/emirmrkaljevic/usb-rea
+usb-rea demo --device fan
+```
+```
+fan    100%  0x5a | counter (+1 per message) | 0x10 | u16be round(value * 1 + 0) | 0x00 | u16le crc16_modbus(bytes[0:6])
+color  100%  0x5a | counter (+1 per message) | 0x20 | round(value * 1 + 0) | round(value[1] * 1 + 0) | round(value[2] * 1 + 0) | u16le crc16_modbus(bytes[0:6])
+mode   100%  0x5a | counter (+1 per message) | 0x30 | lookup 1→0x11, 2→0x22, 3→0x47 | 0x00 | 0x00 | u16le crc16_modbus(bytes[0:6])
+```
+It writes a synthetic capture of a fan controller, recovers the protocol, and writes `report.md` (every claim linked to Wireshark frame numbers) and a working pyusb driver that encodes values it never saw.
+
+`--device lamp` (default) is a simple 8-bit device; `--device dial` shows 32-bit values and packed bitfields:
+```
+position     100%  0xa5 | 0x01 | u32le round(value * 1 + 0) | sum8(bytes[0:6])
+level        100%  0xa5 | 0x02 | bits[0:4] = round(value * 1 + 0) | 0x00 | sum8(bytes[0:4])
+```
+
+## What it can infer
+| Role | Example |
+|---|---|
+| constant header / command id | `5a`, `10` vs `20` vs `30` |
+| linear values, 8-, 16- or 32-bit LE/BE, several per action | `fan 2650` → `0a 5a`; `color 255 24 0`; `position 50000` → `50 c3 00 00` |
+| packed bitfields (bits beside constant flag bits, incl. 12-bit spans over two bytes) | `level 7` → `b7` = flags `b0` + bits[0:4] |
+| lookup tables (non-linear choices) | DPI 250→`08`, 500→`07` … |
+| rolling counters | sequence byte +1 per message |
+| checksums | sum8, xor8, neg/inv sum8, sum16, CRC8, CRC8/MAXIM, CRC16 CCITT-FALSE/XMODEM/MODBUS/KERMIT |
+
+Linear fits must survive leave-one-out cross-checks; otherwise usb-rea falls back to an honest lookup table and says so.
+
+## Real device workflow (Linux)
+```bash
+sudo modprobe usbmon
+usb-rea capture start -o lamp.pcapng
+usb-rea mark -m lamp.pcapng.actions.json "brightness 0%"    # then click it in the vendor app
+usb-rea mark -m lamp.pcapng.actions.json "brightness 50%"   # ...repeat for 3+ values per setting
+usb-rea capture stop
+usb-rea report lamp.pcapng -o report.md
+usb-rea scaffold lamp.pcapng -o lamp_driver.py
+usb-rea dissector lamp.pcapng -o lamp.lua      # Wireshark dissector for the same protocol
+```
+Captured on Windows with USBPcap/Wireshark and no markers? Click each action with a short pause in between, then just list them in order — usb-rea splits the traffic at the pauses:
+```bash
+usb-rea report lamp.pcapng --labels "brightness 0%; brightness 50%; brightness 100%; power off; power on"
+usb-rea scaffold lamp.pcapng --labels labels.txt -o lamp_driver.py   # one label per line
+```
+(Markers, if you have them, are a JSON list of `{"label", "start", "end"}` epoch timestamps.)
+
+## MCP server
+`pip install "usb-rea[mcp] @ git+https://github.com/emirmrkaljevic/usb-rea"` then add `usb-rea mcp` as a stdio server. Tools: `capture_start`, `capture_stop`, `mark_action`, `diff_actions`, `report`, `scaffold_driver`, `hid_descriptor` (decode a HID report descriptor / report payloads), `wireshark_dissector`, `replay_packet` (refuses unless the human confirmed). Analysis tools accept the same `labels` argument as the CLI for marker-free captures.
+
+With [uv](https://docs.astral.sh/uv/) no install step is needed:
+```json
+{"mcpServers": {"usb-rea": {"command": "uvx", "args": ["--from", "usb-rea[mcp] @ git+https://github.com/emirmrkaljevic/usb-rea", "usb-rea", "mcp"]}}}
+```
+Once usb-rea is on PyPI, `--from "usb-rea[mcp]"` is enough. The server is also listed on [Glama](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea), which builds it from the repo's `Dockerfile` and checks that it starts and lists its tools.
+
+## How it works
+1. `usb-rea capture start` — record traffic (usbmon / USBPcap)
+2. `usb-rea mark "brightness 50%"` — label each action you take in the vendor app
+3. `usb-rea diff` — which bytes change per action, value correlation, checksums, counters
+4. `usb-rea infer` — message templates + evidence report
+5. `usb-rea scaffold` — generate a pyusb driver and replay tests
+6. `usb-rea dissector` — write a Wireshark Lua dissector for the inferred protocol
+7. `usb-rea replay` — send packets to the device (only with explicit confirmation)
+8. `usb-rea hid` — decode a HID report descriptor from a capture (GET_DESCRIPTOR 0x22) or from hex, and decode report payloads
+9. `usb-rea mcp` — the same tools as an MCP server for AI agents
+
+### Wireshark dissector
+`usb-rea dissector capture.pcapng -o lamp.lua` turns the inferred protocol into a Wireshark Lua plugin, so you can keep
+capturing and read the traffic as commands instead of hex:
+```bash
+wireshark -X lua_script:lamp.lua capture.pcapng
+tshark -X lua_script:lamp.lua -r capture.pcapng -Y 'usbrea.command == "brightness"'
+```
+Each matching packet gets a `usbrea` tree with the command name, decoded values (`usbrea.brightness.value`), counters,
+lookup labels, and a checksum check (`usbrea.checksum_ok`, with an expert warning on mismatch); the Info column reads
+`brightness 50`. It works for bulk, interrupt and control/HID SET_REPORT transfers, from usbmon or USBPcap, and needs no
+bit library (Wireshark 3.x and 4.x). `-n NAME` changes the filter prefix. CI runs every generated dissector through tshark.
+
+### HID devices
+Most RGB keyboards, mice, headsets and LCD gadgets are HID with a vendor-defined page. If the capture includes the
+report descriptor (start capturing, then replug the device), the report gets a section with every report's ID, size and
+fields, and each inferred command is tagged with the HID report it travels in. Without a capture:
+
+```sh
+usb-rea hid /sys/class/hidraw/hidraw0/device/report_descriptor --items
+usb-rea hid capture.pcapng --decode "10ff0d1d000000" --type Output
+```
+
+## Roadmap
+- [x] pcap/pcapng parser (usbmon + USBPcap)
+- [x] action markers and per-action diffing
+- [x] checksum detection (sum8, xor8, neg/inv sum8, CRC8, CRC16 variants)
+- [x] evidence-backed protocol report
+- [x] driver scaffolding (pyusb, bulk/interrupt + control/HID SET_REPORT)
+- [x] confirmed replay
+- [x] MCP server
+- [x] rolling counters, multi-byte (16/32-bit LE/BE) values, lookup tables, multi-value actions
+- [x] packed bitfields
+- [x] validation against documented protocols (liquidctl, rivalcfg)
+- [x] HID report descriptor decoding (`usb-rea hid`), with captured commands mapped to their HID reports
+- [ ] emulated-device CI (dummy_hcd + configfs HID; script in `scripts/gadget_e2e.sh`)
+- [ ] real-hardware case studies
+- [x] multi-packet transactions (write + apply), including checksums over earlier packets
+- [ ] state machines (request/response handshakes)
+
+## Legal
+Reverse engineering for interoperability is permitted (EU Directive 2009/24/EC Art. 6, US DMCA §1201(f)). usb-rea only analyzes traffic of devices you own and never redistributes vendor code.
+
+## License
+MIT

usb_rea-0.2.1/docs/VALIDATION.md

@@ -0,0 +1,22 @@
+# Validation
+
+usb-rea is validated without anyone's hardware in four ways. All of them run in CI (`pytest`).
+
+| Suite | What it proves | File |
+|---|---|---|
+| Synthetic lamp | constant header, command byte, scaled value, sum8, over bulk and HID SET_REPORT | `tests/test_infer.py` |
+| Synthetic fan controller | rolling counter, 16-bit big-endian value, 3-value RGB, lookup table, CRC16/MODBUS | `tests/test_infer_advanced.py` |
+| liquidctl Kraken X (1e71:170e) | recovers `02 4d <channel> 00 <duty>` exactly as liquidctl's `kraken2.py` builds it | `tests/test_validation.py` |
+| rivalcfg Rival 100 (1038:1702) | recovers non-linear DPI/polling lookup tables and RGB color as in rivalcfg's `rival100.py` | `tests/test_validation.py` |
+| CRC catalogue | CRC8/CRC16 variants match the standard `123456789` check values | `tests/test_checksums.py` |
+| Wireshark dissector | generated Lua plugin labels every command in tshark 4.4, values match, checksums verify, a corrupted checksum is flagged; Lua checksum helpers match the Python ones | `tests/test_dissector.py` |
+| Real captures | parser handles public usbmon/USBPcap captures (downloaded on demand) | `tests/test_public_pcaps.py` |
+
+The driver generated from each capture is also executed against a mocked pyusb device and must emit
+byte-identical packets for values that were **never captured**.
+
+## Not yet covered
+* Emulated USB gadget (dummy_hcd + raw-gadget). It needs a kernel with `CONFIG_USB_DUMMY_HCD` and
+  `CONFIG_USB_RAW_GADGET`; the development box runs a sandboxed kernel without them. Script planned in
+  `scripts/gadget_e2e.sh` for anyone with a normal Linux machine.
+* Real hardware. Captures + action labels from users are very welcome (open an issue).

usb_rea-0.2.1/docs/demo.tape

@@ -0,0 +1,18 @@
+# Regenerate with: vhs docs/demo.tape
+Output docs/demo.gif
+Set FontSize 15
+Set Width 1100
+Set Height 640
+Set Theme "Dracula"
+Set TypingSpeed 45ms
+Hide
+Type `export PATH=$PWD/.venv/bin:$PATH PS1='$ ' && cd $(mktemp -d) && clear` Enter
+Show
+Type "# a fan controller with a Windows-only app: capture + click labels -> protocol + driver" Enter
+Sleep 600ms
+Type "usb-rea demo --device fan -o fan" Enter
+Sleep 2500ms
+Type "sed -n '/^## .fan/,/^Evidence/p' fan/report.md" Enter
+Sleep 3500ms
+Type `python -c 'import fan.fan_driver as d; print(d.encode(d.FAN, [3100], seq=7).hex(" "))'` Enter
+Sleep 3500ms

usb_rea-0.2.1/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["emirmrkaljevic"]
+}

usb_rea-0.2.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usb-rea"
+version = "0.2.1"
+description = "Reverse Engineer any USB gadget: capture, diff, infer, and generate open drivers with evidence"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["pyusb>=1.2", "mcp>=1.2,<3"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mcp>=1.2,<3"]
+mcp = ["mcp>=1.2,<3"]
+
+[project.scripts]
+usb-rea = "usb_rea.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usb_rea"]

usb_rea-0.2.1/scripts/gadget_e2e.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Emulated-device end-to-end test (EXPERIMENTAL, not run in CI yet).
+#
+# Needs a normal Linux kernel with dummy_hcd, libcomposite (usb_f_hid) and usbmon, plus root.
+# Creates a virtual HID "lamp" on dummy_hcd via configfs, captures real kernel USB traffic with
+# usbmon while writing lamp commands to it, runs usb-rea on the capture, and checks that the
+# device side received exactly what the generated driver would send.
+set -euo pipefail
+[[ $EUID -eq 0 ]] || { echo "run as root"; exit 1; }
+command -v dumpcap >/dev/null || { echo "need dumpcap (apt install tshark)"; exit 1; }
+modprobe dummy_hcd libcomposite usbmon
+
+G=/sys/kernel/config/usb_gadget/usbrea_lamp
+cleanup() {
+  [[ -n "${CAP_PID:-}" ]] && kill "$CAP_PID" 2>/dev/null || true
+  if [[ -d $G ]]; then
+    echo "" > $G/UDC 2>/dev/null || true
+    rm -f $G/configs/c.1/hid.usb0; rmdir $G/configs/c.1/strings/0x409 $G/configs/c.1 \
+      $G/functions/hid.usb0 $G/strings/0x409 $G 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+mkdir -p $G && cd $G
+echo 0x1234 > idVendor; echo 0xabcd > idProduct
+mkdir -p strings/0x409; echo usb-rea > strings/0x409/manufacturer; echo "Fake Lamp" > strings/0x409/product
+mkdir -p functions/hid.usb0
+echo 0 > functions/hid.usb0/protocol; echo 0 > functions/hid.usb0/subclass; echo 5 > functions/hid.usb0/report_length
+# vendor-defined report: 5 bytes in, 5 bytes out
+printf '\x06\x00\xff\x09\x01\xa1\x01\x15\x00\x26\xff\x00\x75\x08\x95\x05\x09\x01\x81\x02\x95\x05\x09\x01\x91\x02\xc0' \
+  > functions/hid.usb0/report_desc
+mkdir -p configs/c.1/strings/0x409; echo lamp > configs/c.1/strings/0x409/configuration
+ln -s functions/hid.usb0 configs/c.1/
+UDC=$(ls /sys/class/udc | grep dummy | head -1); echo "$UDC" > UDC
+sleep 1
+cd - >/dev/null
+
+BUS=$(for d in /sys/bus/usb/devices/*; do [[ -f $d/idVendor && $(cat $d/idVendor) == 1234 ]] && cat $d/busnum; done | head -1)
+HIDRAW=/dev/$(ls /sys/class/hidraw | while read h; do grep -q 1234 /sys/class/hidraw/$h/device/uevent 2>/dev/null && echo $h; done | head -1)
+OUT=$(mktemp -d)
+dumpcap -q -i usbmon$BUS -w $OUT/lamp.pcapng & CAP_PID=$!
+sleep 1
+cat /dev/hidg0 > $OUT/device_side.bin & READER=$!
+
+python3 - "$HIDRAW" "$OUT" <<'PY'
+import json, sys, time
+from usb_rea.synth import encode
+hidraw, out = sys.argv[1], sys.argv[2]
+marks = []
+with open(hidraw, "wb", buffering=0) as f:
+    for label in ["brightness 0%", "brightness 30%", "brightness 60%", "brightness 100%",
+                  "hue 0", "hue 90", "hue 300"]:
+        name, val = label.split()[0], float(label.split()[1].rstrip("%"))
+        start = time.time(); time.sleep(0.2)
+        f.write(b"\x00" + encode(name, val))   # report id 0 + payload
+        time.sleep(0.3); marks.append({"label": label, "start": start, "end": time.time()})
+json.dump(marks, open(f"{out}/lamp.pcapng.actions.json", "w"))
+PY
+sleep 1; kill $CAP_PID; CAP_PID=; kill $READER || true
+usb-rea report $OUT/lamp.pcapng -o $OUT/report.md
+python3 - "$OUT" <<'PY'
+import sys
+from usb_rea.pipeline import analyze
+from usb_rea.synth import encode
+p = analyze(f"{sys.argv[1]}/lamp.pcapng")
+c = {c.name: c for c in p.commands}
+assert c["brightness"].encode(45) == encode("brightness", 45), c["brightness"].fields
+assert c["hue"].encode(200) == encode("hue", 200)
+print("gadget e2e OK:", sys.argv[1])
+PY

usb_rea-0.2.1/server.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.emirmrkaljevic/usb-rea",
+  "description": "Reverse engineer USB gadgets: capture traffic, infer the protocol, generate a pyusb driver.",
+  "repository": {
+    "url": "https://github.com/emirmrkaljevic/usb-rea",
+    "source": "github"
+  },
+  "version": "0.2.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "usb-rea",
+      "version": "0.2.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeHint": "uvx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp"
+        }
+      ]
+    }
+  ]
+}

usb_rea-0.2.1/smithery.yaml

@@ -0,0 +1,8 @@
+# Smithery configuration: https://smithery.ai/docs/config#smitheryyaml
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties: {}
+  commandFunction: |-
+    (config) => ({command: "uvx", args: ["--from", "usb-rea[mcp]", "usb-rea", "mcp"]})

usb_rea-0.2.1/src/usb_rea/__init__.py

@@ -0,0 +1,2 @@
+"""usb-rea: Reverse Engineer any USB gadget."""
+__version__ = "0.2.1"