usbip-rs/README.md

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 apps). Two fuzzing engines are available: libFuzzer (via cargo-fuzz) and AFL++ (via cargo-afl).

Targets (shared across both engines):

• 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)

libFuzzer (cargo-fuzz)

nix run .#fuzz-cargo                              # List targets
nix run .#fuzz-cargo -- fuzz_urb_hid              # Single process
nix run .#fuzz-cargo -- fuzz_urb_hid --fork=8     # Parallel (overnight)
nix run .#fuzz-clean-cargo -- fuzz_urb_hid        # Prune fixed artifacts

Crash artifacts: lib/fuzz-cargo/artifacts/<target>/.

AFL++ (cargo-afl)

AFL++ runs with persistent mode, LLVM plugins (CmpLog, IJON), and a SymCC concolic companion. The main fuzzer instance runs in the foreground; secondary instances and the SymCC companion run as systemd transient units for proper process management.

nix run .#fuzz-afl                                # List targets
nix run .#fuzz-afl -- fuzz_urb_hid                # Single instance + SymCC
nix run .#fuzz-afl -- fuzz_urb_hid --jobs 8       # 1 main + 7 secondaries + SymCC

# Stop background processes manually (also cleaned up on ctrl+c/exit)
systemctl --user stop fuzz_afl_fuzz_urb_hid.slice

# Prune fixed crashes
nix run .#fuzz-clean-afl -- fuzz_urb_hid

# View aggregate stats across all instances
nix develop .#fuzz-afl -c bash -c 'afl-whatsup lib/fuzz-afl/output/fuzz_urb_hid'

Crashes: lib/fuzz-afl/output/<target>/*/crashes/. SymCC companion log: lib/fuzz-afl/output/<target>/symcc/companion.log.

Corpora are separate between engines; copy manually if desired.

Project structure

├── cli/              CLI binary (usbip-rs)
├── lib/              Library crate (usbip-rs)
│   ├── src/
│   ├── fuzz-cargo/   Fuzz targets (libFuzzer / cargo-fuzz)
│   ├── fuzz-afl/     Fuzz targets (AFL++ / cargo-afl)
│   └── examples/
├── nix/              Nix patches (cargo-afl env-var overrides)
└── flake.nix         Nix build, devShells, fuzzing apps

License

MIT — see LICENSE.