cynthion-reverse-engineer

Reverse-engineer proprietary USB device protocols from Cynthion captures and generate replay and Facedancer emulation scripts.

2|Updated May 13, 2026
One-click install
npx skills add https://github.com/curtisgalloway/public-skills --skill cynthion-reverse-engineer-curtisgalloway
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cynthion-reverse-engineer
Source: https://github.com/curtisgalloway/public-skills/tree/main/plugins/hardware-lab/skills/cynthion-reverse-engineer
Command: npx skills add https://github.com/curtisgalloway/public-skills --skill cynthion-reverse-engineer-curtisgalloway

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires libusb1, facedancer, and includes scripts (resource) components.

What problem does it solve? Understanding the undocumented protocol of a proprietary USB device requires tedious manual comparison of packet captures. This Skill orchestrates a structured seven-step workflow that turns raw Cynthion/Packetry captures into a command-structure hypothesis, a runnable replay script, a Facedancer device clone, and a protocol reference document. ## Core Features & Use Cases - Byte-level capture diffing: Compare two labeled captures with diff_transactions.py to classify each byte offset as constant, monotonic counter, varying, or missing per endpoint. - Command inference: Run infer_commands.py across multiple labeled captures to identify opcodes, counters, and constants, producing a JSON protocol hypothesis. - Code generation: Generate a libusb1 replay script, a Facedancer 3.x device-emulation clone (Linux only), and a Markdown protocol document from the hypothesis. - Use Case: You have a proprietary USB gadget and want to build an emulator. Capture idle and button-press sessions, diff them, infer the opcode layout, then generate a Facedancer clone script that mimics the device's descriptors and endpoints. ## Quick Start Ask the agent to reverse engineer the protocol of your USB device using the Cynthion captures you have recorded, starting with at least two labeled sessions.

Frequently Asked Questions about cynthion-reverse-engineer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reverse engineer a USB device protocol with Cynthion?▼

Capture at least two labeled sessions of the device doing different actions, decode them with cynthion-pcap-decode, then run diff_transactions.py and infer_commands.py to classify bytes and identify opcodes. The workflow ends with generated replay, clone, and protocol documentation scripts.

How many USB captures are needed for opcode inference?▼

Two captures is the minimum, but three to five labeled sessions are recommended. With only two captures, a byte differing by exactly 1 is misclassified as a monotonic counter even when it is actually an opcode.

Does Facedancer device emulation work on macOS or Windows?▼

No. Facedancer 3.x device emulation is Linux-only; macOS support is limited and unreliable, and Windows is unsupported. The generated clone script must be run on Linux with BACKEND=cynthion set as an environment variable.

What is the difference between cynthion-pcap-decode and cynthion-reverse-engineer?▼

cynthion-pcap-decode decodes a single pcap into transfers and is a required dependency. cynthion-reverse-engineer orchestrates the full multi-capture workflow: diffing, opcode inference, replay generation, Facedancer cloning, and protocol documentation.

Why does command inference fail on some USB devices?▼

The inference assumes fixed-length frames and groups transactions by dominant payload length. Devices using variable-length framing, length prefixes, TLV encoding, or encryption produce sparse or misleading command tables and require manual analysis.

What Python packages are needed to run the generated replay script?▼

The generated replay script requires libusb1 (install with pip install libusb1), with pyusb as a partial fallback. The analysis scripts themselves use only the Python standard library, and the Facedancer clone requires the facedancer package on Linux.