Skip to main content

# usbrply

Convert a .pcap file (captured USB packets) to Python or C code that replays the captured USB commands.

Supported packet sources are: * Linux Wireshark (via usbmon) * Windows Wireshark (via USBPcap)

Supported output formats are: * libusb Python (primary) * (libusb C: fixme) * (Linux Kernel C: fixme) * JSON

Example applications: * Rapidly reverse engineer and re-implement USB protocols * Record a proprietary Windows programming sequence and replay on an embedded Linux device * Snoop USB-serial packets

Questions? Please reach out on github or join #usbrply on Freenode IRC

# Installation Its currenlty only tested under Ubuntu Linux, but probably works under Windows. If someone sends instructions I’ll add them here

` # Do one of these # Easier to setup, but slower sudo pip install python-pcapng # Much faster, but no longer maintained sudo apt-get install -y python-libpcap git clone https://github.com/JohnDMcMaster/usbrply.git cd usbrply sudo python setup.py install `

# Sample workflows

Sample workflow for capturing Windows traffic and replaying traffic in Python: * Install Wireshark. Make sure you install the USBPcap library * Start Wireshark * Connect USB device to computer * Start catpure * Start your application, do your thing, etc to generate packets * Close application * Stop capture * Save capture. Save in pcap-ng format (either should work) * Close Wireshark * Run: “usbrply –device-hi -p my.pcapng >replay.py” * Linux: run “python replay.py” * Verify expected device behavior. Did an LED blink? Did you get expected data back?

Sample workflow for capturing Windows VM traffic from Linux host and replaying traffic in Python: * Example: program a Xilinx dev board under Linux without knowing anything about the JTAG adapter USB protocol * Linux: Install Wireshark * Linux: Enable usbmon so Wireshark can capture USB (sudo modprobe usbmon, see http://wiki.wireshark.org/CaptureSetup/USB) * Linux: Boot Windows VM (ie through VMWare) * Linux: Start Wireshark. Make sure you have USB permissions (ie you may need to sudo) * Connect USB device to computer * Linux: use lsusb to determine which device bus is on. Try to choose a bus (port) with no other devices * Linux: start catpure on bus from above * Linux: attach USB device to Windows guest * Windows: start your application, do your thing, etc to generate packets * Linux: stop capture * Linux: save capture. Save in pcap-ng format (either should work) * Linux: run: “usbrply –device-hi -p my.pcapng >replay.py” * Linux: detatch USB device from Windows guest * Linux: run “python replay.py” * Verify expected device behavior. Did an LED blink? Did you get expected data back?

You may need to filter out USB devices. There are two ways to do this: * –device-hi: use the last device enumerated. This works well in most cases, including FX2 renumeration * –device DEVICE: manually specify the USB device used. Get this from lsusb output or Wireshark view

Other useful switches: * –rel-pkt: intended to easier allow diffing two outputs. Ex: what changed in trace for LED on vs LED off? * –no-packet-numbers: alternative to above * –fx2: decode common FX2 commands (ex: CPU reset) * –range RANGE: only decode a specific packet range. Use along with Wireshark GUI or refine a previous decode * see –help for more

# JSON output

use -j switch to output a parsing intermediate representation that should resemble original USB requests along with associated metadata. This can be used in more advanced applications, such as if you need to decode a complicated protocol or convert USB output to higher level API calls. An example can be found here: https://github.com/ProgHQ/bpmicro/blob/master/scrape.py This example first aggregates USB packets into application specific packets, and then decodes these into API calls

# USB serial decoder

usbrply-serial supported adapters:
  • FT2232C: data rx/tx

TODO: write doc

Metadata

Release files for usbrply 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for usbrply 2.0.1
File Size Uploaded Provenance Actions
usbrply-2.0.1.tar.gz 27.4 kB Without provenance Details for usbrply-2.0.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for usbrply 2.0.1
File Interpreter ABI Platform Actions
usbrply-2.0.1-py3.8.egg Legacy Egg format - - Details for usbrply-2.0.1-py3.8.egg
usbrply-2.0.1-py3-none-any.whl Python 3 none any Details for usbrply-2.0.1-py3-none-any.whl

Total release size: 129.3 kB

Release files / usbrply-2.0.1.tar.gz

Download URL usbrply-2.0.1.tar.gz
Size 27.4 kB
Tags Source
SHA-256 checksum
How to use checksums
30005c807d7f577d5fc378e0c0944e32b00fffe9a21feaa6055ebb5c6041f479
BLAKE2b-256 checksum
How to use checksums
264295ffb99e25a52adc0539e74fd2a1b423e70a3652e7fcfd8610f1f0557d93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.8.2

Release files / usbrply-2.0.1-py3.8.egg

Download URL usbrply-2.0.1-py3.8.egg
Size 68.2 kB
Tags Egg
SHA-256 checksum
How to use checksums
5cdbd0a3311ec2ad1bf8982b31df6ce936a9ea0f3a3856feeb52b6d73ed2829a
BLAKE2b-256 checksum
How to use checksums
a5979d65f48965eab91464606d5f0a5fe8b4c1970329dc90f8b68d0f6fd9e1a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.8.2

Release files / usbrply-2.0.1-py3-none-any.whl

Download URL usbrply-2.0.1-py3-none-any.whl
Size 33.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6adedaf6fbbc18bef876512a3e8b881b41fc8b4b3663cfa4ea8acca4f8147cda
BLAKE2b-256 checksum
How to use checksums
27d14f0976398d64fb3c1cc30cf6624ebf70175f9642940277d9387b85727de0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.8.2

Security for usbrply 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page