usbip-rs

Implements a userspace server-side server for the usbip protocol, and a tool for the client-side to set up the socket and hand it off to the kernel. In usbip terminology, the "server"/"host" is the side that has the physical device being shared, and the "client" is the side the device is being shared to.

This project is based on https://github.com/jiegec/usbip, with significant changes and additions.

Why?

Implementing the server side in userspace instead of the kernel's usbip_host driver reduces the attack surface considerably. The kernel is not exposed directly to potentially untrusted network input. The userspace server talks to the USB device via /dev/bus/usb/..., and can validate the client's traffic before passing it on to the real USB device. It also makes it possible to implement strong sandboxing via seccomp and namespaces for the server side. The client side is of course still all in the kernel, since making the USB devices visible to the client kernel's drivers is the whole point. But for my use case, the server side is trusted and client side is untrusted, so securing the host side is critical.

There are a few other userspace usbip server implementations around, but as far as I could tell, none of them support isochronous mode. Isochronous is needed for e.g. USB audio devices and webcams. This project does, though my testing so far is limited to playback on USB audio devices which work well.

This implementation also allows for reversing the connection flow. In standard usbip, the server side listens for connections, and the client side connects to it to access the device. usbip-rs supports having the client listen and the server initiating the connection, which maps much better to my needs.

usbip-rs also supports using vsock instead of TCP as the transport, making the "ip" in "usbip" not really true. This is useful when sharing a device to a virtual machine on the same hardware.

Building

With Nix

nix build

With Cargo

Requires libusb and libudev (Linux) system dependencies.

cargo build --release

The CLI binary is at target/release/usbip-rs.

Usage

The CLI has four top-level commands: client, host, test_hid, and test_uac. Transport addresses use the format vsock:<port>, vsock:<cid>:<port>, tcp:<port>, tcp:<host>:<port>, or fc-vsock:<path>:<port>.

Pass through a real USB device

On the client machine (needs vhci_hcd kernel module):

usbip-rs client listen tcp:3240

On the host machine (where the USB device is plugged in):

usbip-rs host connect tcp:<client-ip>:3240 1-2

The device argument is a bus ID (e.g. 1-2) or device path (e.g. /dev/bus/usb/001/002).

Test with a simulated HID keyboard

# Client side
usbip-rs client listen vsock:5000

# Host side (simulated keyboard, no real device needed)
usbip-rs test_hid connect vsock:5000

Test with a simulated UAC1 loopback audio device (not working)

# Client side
usbip-rs client listen tcp:3240

# Host side (simulated USB audio device, no real device needed)
usbip-rs test_uac connect tcp:3240

The UAC1 loopback device advertises 48kHz 16-bit stereo playback and capture. Audio sent to the playback endpoint is looped back to the capture endpoint.

Fuzzing

Fuzz targets exercise the host-side codepaths that process untrusted client data. Requires nightly Rust (provided by the nix app).

# List available fuzz targets
nix run .#fuzz-usbip

# Run a single fuzz target
nix run .#fuzz-usbip -- fuzz_urb_hid

# Run with 8 parallel processes, auto-restart on crash (for overnight runs)
nix run .#fuzz-usbip -- fuzz_urb_hid --fork=8

# Re-check saved crash artifacts and delete the ones that no longer reproduce
nix run .#fuzz-clean-usbip -- fuzz_urb_hid

Targets:

• fuzz_parse_command — protocol deserialization
• fuzz_handle_client — full connection lifecycle (negotiation + URB loop)
• fuzz_urb_hid — URB loop with HID keyboard device
• fuzz_urb_uac — URB loop with UAC1 audio device (isochronous)
• fuzz_urb_cdc — URB loop with CDC ACM serial device (bulk)

Crash artifacts are saved to lib/fuzz/artifacts/<target>/.

Project structure

├── cli/          CLI binary (usbip-rs)
├── lib/          Library crate (usbip-rs)
│   ├── src/
│   ├── fuzz/     Fuzz targets (cargo-fuzz)
│   └── examples/
└── flake.nix     Nix build

License

MIT — see LICENSE.