# usb-rea

> Python CLI and stdio MCP server for inferring the USB protocol of a device whose only control software is a vendor app. While the user clicks through the app, it captures traffic with usbmon or USBPcap, takes a label for each action, diffs the packets per action and infers message layouts: constant bytes, rolling counters, scaled 8- to 32-bit values, lookup tables, packed bit fields and sum, XOR or CRC checksums. It also decodes device replies, handshakes with session tokens and image streams sent to device screens, links each inferred field to Wireshark frame numbers in a report, and generates a pyusb driver and a Wireshark Lua dissector.

- Type: Integration
- Targets: Protocol
- Category: Independent MCP integrations
- Relationship: Independent agent integration
- Sources reviewed: 2026-11-02
- Added to the catalog: 2026-11-04
- Original resource: <https://github.com/emirmrkaljevic/usb-rea>
- Primary source: <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/README.md>
- Catalog page: <https://awesomerea.org/resources/usb-rea/>
- Record JSON: <https://awesomerea.org/resources/usb-rea/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/usb-rea/index.md)

## Requirements & limits

- **Prerequisites:** Python 3.10+, with pyusb and the MCP SDK as dependencies; version 0.7.7 (released 2026-11-01) is on PyPI. Live capture needs Linux usbmon with dumpcap or tshark, or USBPcap on Windows; offline analysis reads pcap or pcapng files whose actions are marked with timestamps or listed in order with a pause between clicks. The user supplies the device and its vendor app, and the README says the tool only analyzes traffic of devices the user owns.
- **Limits:** The README marks the project alpha and lists limits per feature, among them one-byte modes, unsigned 32-bit readings, handshake tokens that must be copied verbatim and image streams of at least three frames. Sending packets to hardware through the replay command or MCP tool requires explicit confirmation.
- **Testing evidence:** CI runs pytest on Python 3.10, 3.12 and 3.13, including tshark checks of the generated dissectors. docs/VALIDATION.md uses synthetic devices, captures synthesized from liquidctl's Kraken X and Hydro H100i Platinum drivers and rivalcfg's Rival 100 driver as ground truth, and two Wireshark sample captures downloaded on demand; one user-shared ASUS TUF Gaming LC III LCD capture is stored trimmed, with its image data zeroed. Emulated-gadget tests and real-hardware case studies remain open roadmap items.
- **License:** MIT per LICENSE and pyproject.toml.
- **Attribution:** The README expands the name as “Reverse Engineer any USB gadget”.

## Primary sources

1. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/README.md>
2. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/docs/VALIDATION.md>
3. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/docs/case-study-hydro-platinum.md>
4. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/tests/data/SOURCES.md>
5. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/.github/workflows/ci.yml>
6. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/src/usb_rea/capture.py>
7. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/src/usb_rea/replay.py>
8. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/pyproject.toml>
9. <https://github.com/emirmrkaljevic/usb-rea/blob/3b77ccbe3b2c87e344a507937ac3c4a1b2a35eb1/LICENSE>
10. <https://github.com/emirmrkaljevic/usb-rea/releases/tag/v0.7.7>
11. <https://pypi.org/project/usb-rea/0.7.7/>

## More in Agents and MCP

- [IDA NO MCP](https://awesomerea.org/resources/ida-no-mcp/index.md) · Integration
- [ida-mcp-rs](https://awesomerea.org/resources/ida-mcp-rs/index.md) · Integration
- [ida-multi-mcp](https://awesomerea.org/resources/ida-multi-mcp/index.md) · Integration
- [x64dbg MCP (x64dbgMCP)](https://awesomerea.org/resources/x64dbgmcp/index.md) · Integration
- [IDASQL](https://awesomerea.org/resources/idasql/index.md) · Integration
- [Exoproc](https://awesomerea.org/resources/exoproc/index.md) · Integration

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.