--- name: cynthion-capture description: Set up and run USB traffic capture with a Cynthion USB analyzer. Covers device verification, loading the analyzer bitstream, hardware wiring, launching Packetry for GUI capture, and headless (no-GUI) capture to .pcap files using the bundled Rust or Python tools. Use when the user asks to capture USB traffic, analyze a USB device, run headless/automated capture, or start a USB capture session with Cynthion. --- # Cynthion USB Capture Cynthion is a USB analysis platform from Great Scott Gadgets. In analyzer mode it acts as a man-in-the-middle between a USB host and a USB device, capturing all traffic to a pcap file or live in the Packetry GUI. ## Trigger phrases - "capture USB traffic with Cynthion" - "start a USB capture session" - "analyze this USB device with Cynthion" - "run packetry" - "load the analyzer bitstream" - "headless capture" - "capture without a GUI" - "rolling capture" / "continuous capture" / "long-running capture" - "rotate capture files" / "split capture into segments" - "index a pcap" / "build a device index" ## Prerequisites ### Hardware - **Cynthion** (r1.4 or later) connected to your machine via its **CONTROL** port (the USB-C port labeled CONTROL — this is how the host talks to the analyzer) - A second USB cable for the **TARGET** side (see wiring below) ### Software Run the `cynthion-setup` skill to install all software prerequisites (`cynthion` CLI, Packetry, and Linux udev rules) and verify device access. Only continue with this skill once `cynthion info` reports `Found Apollo stub interface!`. ## Hardware wiring The board-edge silkscreen labels are **CONTROL**, **AUX**, **TARGET C** and **TARGET A**. The analyzed connection passes through TARGET C and TARGET A: | Port label | Connector | Role in analyzer mode | |---|---|---| | **CONTROL** | USB-C | Connected to the analysis host — the machine running Packetry. Always required. | | **TARGET C** | USB-C | Connected to the **target host** — the USB host whose traffic you want to observe. | | **TARGET A** | USB-A female | Connected to the **target device** — the USB device under test. | Per the [Packetry quick start](https://packetry.readthedocs.io/en/latest/quick_start.html): > "Connect TARGET C to your target host computer." > "You can connect Cynthion's TARGET A port to your target device at this time, > but you may wish to delay this connection until after Packetry is capturing." ``` [Analysis host] ──CONTROL──▶ Cynthion ◀──TARGET C── [target host] ◀──TARGET A── [target device under test] ``` Cynthion sits transparently between TARGET C and TARGET A, intercepting all packets. If you want to observe a device plugged into your own machine, connect that machine to both CONTROL and TARGET C, and the device under test to TARGET A. **Do not swap these.** TARGET A is a USB-A *female* receptacle — the kind a host offers for a device to plug into — so the **device** goes there, not the host. Wiring them backwards produces a capture with zero packets and no error message. **Cable note:** the device under test plugs into TARGET A (USB-A female), so a USB-C device needs a **USB-A male → USB-C** cable. For TARGET C to the target host, use USB-C to USB-C, or USB-C to USB-A if that machine only has USB-A ports. **Plug the device in after starting the capture** if you want enumeration in the file — the vendor docs recommend exactly this. ## Procedure: GUI capture with Packetry ### 1. Load the analyzer bitstream If `cynthion info` shows the device is already running the USB Analyzer bitstream (look for `Bitstream: USB Analyzer` in the output), skip this step. ```bash cynthion run analyzer ``` This flashes the FPGA with the analyzer gateware. The device re-enumerates after a few seconds. Re-run `cynthion info` to confirm. ### 2. Launch Packetry ```bash packetry ``` Packetry is a GTK4 GUI application. On first launch it may take a moment to open. To quickly verify the hardware without starting a full session: ```bash packetry --test-cynthion ``` ### 3. Capture traffic 1. In Packetry, click **Start** (or the record button) to begin capture. 2. Plug in or activate the USB device connected to the TARGET port. 3. Interact with the device to generate traffic. 4. Click **Stop** when done. ### 4. Save the capture File → Save As → choose a `.pcap` filename. Packetry saves captures in standard pcap format, which can be opened in Wireshark with the USB dissector (`usbmon` link type). ## Procedure: Headless capture (no GUI) Use the bundled `cynthion-capture` tool for scripted, automated, or background capture without launching Packetry. It writes standard libpcap files (LINKTYPE\_USB\_2\_0, link type 288) compatible with Wireshark and tshark. Two implementations are provided in `scripts/`: - **Rust** (`scripts/capture-rs/`) — recommended; uses `nusb`, which is cross-platform: IOUSBHost on macOS (no sudo needed), usbfs on Linux (udev rules required for unprivileged access — same rules used by Packetry), WinUSB on Windows. Async bulk-in queue gives better throughput at high traffic rates. - **Python** (`scripts/capture.py`) — simpler to run without a build step; uses `pyusb`, which has the same platform access requirements as the Rust tool. ### Build and install the Rust tool ```bash cd scripts/capture-rs cargo build --release # binary at target/release/cynthion-capture # optionally: cargo install --path . ``` Requires Rust stable (edition 2024). Dependencies: `nusb`, `futures-lite`, `ctrlc`. ### Usage ``` cynthion-capture [OPTIONS] Options: -d, --duration Stop after N seconds (default: run until Ctrl-C) -s, --speed auto|hs|fs|ls (default: auto) -h, --help Show this help ``` Output is gzip-compressed and SOF tokens are dropped at capture time. **Speed modes:** - `auto` — captures all speeds (HS, FS, LS). Use this unless you need to filter. - `hs` — High Speed (480 Mbps) only - `fs` — Full Speed (12 Mbps) only - `ls` — Low Speed (1.5 Mbps) only **Examples:** ```bash # Capture all traffic until Ctrl-C cynthion-capture capture.pcap.gz # Capture 30 seconds of full-speed traffic only cynthion-capture -d 30 -s fs capture-fs.pcap.gz # Capture in background for 60 seconds cynthion-capture -d 60 output.pcap.gz & ``` ### Python alternative ```bash pip install pyusb python3 scripts/capture.py capture.pcap python3 scripts/capture.py -d 30 -s fs capture-fs.pcap ``` SOF tokens are dropped at capture time. To compress the output, pipe through gzip or name the output `.pcap.gz` and use `rolling_capture.py` instead (which always writes compressed segments). Same options as the Rust tool. On Linux without udev rules, prefix with `sudo`. **Optional LED feedback.** The Python capture scripts try to drive Cynthion's status LEDs through the Apollo debug MCU (`scripts/_apollo_leds.py`): a slow pulse once the analyzer is claimed, a fill-up animation while capturing, and all-off on exit. Because the FPGA owns the CONTROL port while the analyzer gateware is running, Apollo (PID `0x615c`) is usually not separately enumerated, in which case the LED calls are silent no-ops. Treat the LEDs as decoration — capture status comes from the scripts' stdout, not the board. ### Speed field encoding (implementation note) The Cynthion analyzer control request uses a 1-byte value: `bits[2:1]=speed, bit[0]=enable`. The speed encoding (confirmed from Packetry source `src/backend/cynthion.rs`) is: | Value | Speed | |---|---| | 0 | HS-only | | 1 | FS-only | | 2 | LS-only | | 3 | **Auto (all speeds)** | `auto` (speed=3) is the correct default for general captures. It also works correctly when the device was already enumerated before capture started. ## Procedure: Rolling capture (long-running sessions) Use `rolling_capture.py` when you need to capture over hours or days — for anomaly hunting, monitoring a process that runs infrequently, or any session where a single large pcap file would be unwieldy. It writes rotating segment files and builds a JSON index for each segment automatically in a background thread after every rotation. ### Requirements Same as the Python headless capture tool: `pyusb`, plus the `cynthion-pcap-decode` skill installed alongside this one (for indexing). ### Usage ```bash # Capture with 5-minute segments (default) until Ctrl-C python3 scripts/rolling_capture.py captures/ # 10-minute segments, custom prefix, stop after 4 hours python3 scripts/rolling_capture.py captures/ --interval 600 --prefix mydevice --duration 14400 # Also rotate when a segment reaches 100 MB python3 scripts/rolling_capture.py captures/ --interval 300 --max-size 100 # Measure clock offset against the target machine at capture start python3 scripts/rolling_capture.py captures/ --target-host user@target-machine # Skip auto-indexing (faster; index the whole directory later) python3 scripts/rolling_capture.py captures/ --no-index python3 scripts/index_pcap.py captures/*.pcap --manifest captures/ ``` ### Output structure ``` captures/ capture_20260520_143000.pcap.gz segment 1 — gzip-compressed pcap (LINKTYPE_USB_2_0) capture_20260520_143000.json segment 1 — device index capture_20260520_143500.pcap.gz segment 2 capture_20260520_143500.json segment 2 ... manifest.json session index of all segments ``` SOF tokens (PID 0xA5) are dropped at capture time before writing. Wireshark and tshark open `.pcap.gz` files natively without any extra flags. ### manifest.json format ```json { "clock_sync": { "target_host": "user@target-machine", "measured_at": 1748000000.0, "offset_s": 0.0123, "uncertainty_s": 0.0031, "rtt_s": 0.0062, "method": "ssh-date" }, "segments": [ { "file": "capture_20260520_143000.pcap", "index": "capture_20260520_143000.json", "start_time": 1748000000.0, "end_time": 1748000300.0, "duration_s": 300.0, "packets": 12345, "bytes": 987654, "devices": [ {"addr": 3, "vid": "0x04e8", "pid": "0x6860"}, {"addr": 7} ] } ] } ``` `clock_sync.offset_s` is `target_clock - capture_clock` at the moment of measurement. A positive value means the target is ahead; subtract `offset_s` from target syslog timestamps (or add it to capture timestamps) to put both on a common timeline. `uncertainty_s` is half the SSH round-trip time — the irreducible error from not knowing exactly when the remote `date` command ran within the round trip. Devices without captured enumeration traffic appear with only `addr`. VID/PID are populated when the tool observes a `GET_DESCRIPTOR(DEVICE)` exchange during the segment. ### Segment JSON index format Each `.json` file contains the same device entries as the manifest, plus transfer counts and first/last-seen timestamps: ```json { "file": "capture_20260520_143000.pcap", "start_time": 1748000000.0, "end_time": 1748000300.0, "duration_s": 300.0, "packets": 12345, "bytes": 987654, "devices": { "3": { "first_seen": 1748000010.5, "last_seen": 1748000290.1, "transfers": 450, "idVendor": "0x04e8", "idProduct": "0x6860", "bDeviceClass": "0x00", "bcdUSB": "0x0200" } } } ``` ### Finding a specific device across segments ```bash # Which segments have traffic for VID 04e8? grep -l '"vid": "0x04e8"' captures/*.json # Quick manifest scan (jq): jq '.segments[] | select(.devices[].vid == "0x04e8") | .file' captures/manifest.json # Decode a specific segment in detail python3 skills/cynthion-pcap-decode/scripts/decode.py \ captures/capture_20260520_143000.pcap \ --filter address=3 --format transcript ``` ### Performance note The Python rolling capture tool reads USB in a single loop. Indexing runs in a background thread to avoid blocking, but the USB read loop is single-threaded. At very high traffic rates (> ~30 MB/s of USB data), use the Rust tool for capture (`capture-rs/`) and run `index_pcap.py` as a post-processing step. ## Procedure: Index an existing pcap file `index_pcap.py` runs standalone on any pcap file captured with Packetry or the headless tools. It extracts per-device statistics and writes a `.json` alongside the pcap. ```bash # Index one file python3 scripts/index_pcap.py capture.pcap # Index all segments in a directory and build a manifest python3 scripts/index_pcap.py captures/*.pcap --manifest captures/ # Print the index to stdout without writing a file python3 scripts/index_pcap.py capture.pcap --stdout ``` Requires: `cynthion-pcap-decode` skill (for decode.py). ## Offline analysis with Wireshark ```bash wireshark capture.pcap ``` Useful Wireshark filters for USB captures: | Filter | What it shows | |---|---| | `usb.transfer_type == 0x01` | Isochronous transfers | | `usb.transfer_type == 0x02` | Bulk transfers | | `usb.transfer_type == 0x03` | Interrupt transfers | | `usb.bmRequestType` | Control transfers (setup packets) | | `usb.data_len > 0` | Packets with payload data | ## Switching back to other modes To load the Facedancer (USB emulation) bitstream instead: ```bash cynthion run facedancer ``` To update firmware and bitstreams to the latest installed version: ```bash cynthion update ``` ## Troubleshooting **`cynthion info` shows no device found** - Check that the CONTROL port cable is connected and is a data cable (not charge-only) - Try a different USB port on the host - On Linux: confirm udev rules are installed (see Prerequisites above) and that you unplugged and replugged the device after installing them **Packetry shows no capture data** - Confirm the analyzer bitstream is loaded (`cynthion info` → `Bitstream: USB Analyzer`) - Check that the TARGET cable is connected to the device under test - Verify the device under test is powered and enumerating **Headless capture: "No Cynthion USB Analyzer found"** - Run `cynthion run analyzer` to load the analyzer bitstream first - On macOS: no sudo needed with the Rust tool (uses IOUSBHost) - On Linux: confirm udev rules grant access, or run with `sudo` **Device enumerates at wrong speed** - Cynthion captures USB 2.0 (HS/FS/LS). USB 3.x SuperSpeed traffic is not captured. - For USB 3.x devices, the device may fall back to USB 2.0 when connected through Cynthion — this is expected.