Reverse engineer USB gadgets: capture traffic, infer the protocol, generate a pyusb driver.
io.github.emirmrkaljevic/usb-rea (MCP Server)
This MCP server focuses on reverse engineering USB gadgets. It captures USB traffic, infers the underlying protocol behavior, and uses those findings to generate a pyusb-based driver.
🛠️ Key Features
Reverse engineering USB gadgets
Capturing USB traffic
Inferring the protocol
Generating a pyusb driver
🚀 Use Cases
Analyzing and documenting behavior of USB gadgets
Developing a driver for a gadget after protocol inference
Creating a protocol model from observed USB traffic
⚡ Developer Benefits
Produces a pyusb driver based on inferred protocol details
Provides an implementation path from captured traffic to usable driver code
⚠️ Limitations
Available server data does not specify supported platforms, transport details, or tooling beyond capture/inference/driver generation
If you find this useful, you can support me by getting a SkinToScan pack, my other project. It's a one-time purchase that directly funds my open-source work.
usb-rea reads a USB capture (pcap or pcapng, from usbmon or USBPcap) and does the step after Wireshark: it infers the command and protocol structure from labelled actions, then writes a Markdown report and a standalone pyusb driver. I built it for gadgets that only ship a Windows vendor app, such as a case LCD, an RGB controller, a mouse or a "smart" lamp. No hardware is needed to try it.
usb-rea demo: capture labelled clicks, get the protocol and a working driver
From captures of the NZXT Kraken X (1e71:170e) fan command, it recovers 02 4d <channel> 00 <duty> byte for byte, as liquidctl's kraken2.py sends it, and the generated driver emits identical packets for duty values it never saw. The same holds for the SteelSeries Rival 100 DPI, polling and RGB tables from rivalcfg. Those checks run in CI; details are in validation.
Install
sh
pip install usb-rea
Example
sh
usb-rea demo --device fan
code
mode 100% 0x5a | counter (+1 per message) | 0x30 | lookup 1→0x11, 2→0x22, 3→0x47 | 0x00 | 0x00 | u16le crc16_modbus(bytes[0:6])
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 | RGB bytes | u16le crc16_modbus(bytes[0:6])
color only sent while mode 3: the driver sets it first
It writes a synthetic capture of a fan controller, recovers the protocol and the replies, and writes report.md (every claim linked to Wireshark frame numbers) plus a working pyusb driver. --device lamp is a simpler 8-bit device; --device lcd is a pump cap screen; --device dial shows 32-bit values and packed bitfields.
On a real device, label each click in the vendor app, then infer:
Captured on Windows with USBPcap and no markers? List the actions in order and usb-rea splits the traffic at the pauses. The full CLI, including markers, replies, handshakes, image streams and HID, is in usage.
Before you capture, usb-rea lookup 1e71:170e (or the ID 1e71:170e form from lsusb) checks a VID:PID against devices whose protocol an open-source project already implements. The offline table is in known devices.
Limitations
Status: alpha (v0.7.14, on PyPI). It is validated on synthetic devices, on protocols documented by liquidctl and rivalcfg, on public Wireshark captures, and on a real AIO cooler LCD capture a user shared. Linear fits must survive leave-one-out cross-checks; otherwise usb-rea falls back to a lookup table and says so. A matching USB ID alone does not prove your unit speaks the same protocol.
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.
Have a Windows-only device? Open a device request with a capture and I will run it and publish the result.