If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dorssel/usbipd-win shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 6d ago
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 83% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dorssel/usbipd-win repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dorssel/usbipd-win.

What it runs against: a local clone of dorssel/usbipd-win — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dorssel/usbipd-win | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dorssel/usbipd-win. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dorssel/usbipd-win.git
#   cd usbipd-win
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dorssel/usbipd-win and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dorssel/usbipd-win(\\.git)?\\b" \\
  && ok "origin remote is dorssel/usbipd-win" \\
  || miss "origin remote is not dorssel/usbipd-win (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dorssel/usbipd-win"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

usbipd-win is a Windows service and CLI tool that shares locally connected USB devices to remote machines (WSL 2, Hyper-V guests, other network clients) using the USBIP protocol. It wraps the VirtualBox USB drivers (VBoxUSB.sys, VBoxUSBMon.sys) to intercept USB traffic and forward it over TCP port 3240 to requesting clients, solving the problem of USB device inaccessibility in virtualized/remote Windows environments. Single monolithic .NET/C# application: Drivers/ folder contains pre-built VirtualBox USB drivers (arm64 and x64 variants with .sys, .inf, .cat files); Installer/ has WiX project files (Product.wxs, Server.wxs, WSL.wxs) defining the MSI package structure; source code likely in src/ or similar (not fully visible in top-60 listing); Directory.Build.props and Directory.Build.targets provide centralized build configuration for all projects.

Windows system administrators and developers who need to attach physical USB devices (scanners, microcontrollers, security keys, etc.) to WSL 2 distributions or Hyper-V VMs running on a different machine; also Windows driver developers building USB-dependent tools that must run in containers or VMs.

Production-ready and actively maintained. The project has a robust CI/CD pipeline (GitHub Actions for build, CodeQL analysis, MegaLinter, REUSE compliance), comprehensive test coverage tracked in Codecov, and a single dedicated maintainer (dorssel) with consistent commits. Used across thousands of installations (visible from GitHub release download counts) with stable, versioned releases managed through WinGet and GitHub Releases.

Low-to-moderate risk. Single-maintainer project creates sustainability risk, but code is stable with strong compliance tooling (CodeQL, REUSE licensing audits). No visible dependency sprawl in the C# codebase (managed via Directory.Packages.props for centralized version control). Main risk: tight coupling to Windows driver API (VBoxUSB drivers) means Windows updates or driver changes could break functionality; also requires administrator privileges and firewall configuration, expanding attack surface.

Active development evident from GitHub Actions workflows: auto-updates for USB device IDs (usbids.yml), WinGet package maintenance (winget.yml), driver updates (update-drivers.yml), and security scanning (CodeQL, DevSkim). The project maintains automated compliance checks (MegaLinter, REUSE) suggesting ongoing quality investment. Specific current work not visible from file list alone, but the build-installer.yml workflow suggests regular CI builds.

git clone https://github.com/dorssel/usbipd-win.git
cd usbipd-win
# Install .NET SDK (required by Directory.Build.props)
dotnet restore
dotnet build
# Or build the installer (requires WiX Toolset):
# msbuild Installer/Installer.wixproj

Daily commands: The application is deployed as a Windows Service. After installation: usbipd list (CLI to enumerate USB devices), usbipd bind --busid=<BUSID> (share a device), or interact via the service running in background. Development: dotnet build to compile, then test via usbipd --help or run the service manually with elevated privileges.

• Drivers/x64/VBoxUSB.sys: The core 64-bit kernel-mode USB filter driver that intercepts and redirects USB traffic; essential to the entire USB sharing mechanism
• Installer/Product.wxs: WiX project file defining the complete MSI installer package structure, service registration, and firewall rule setup
• Directory.Build.props: Centralized .NET project configuration managing dependencies, target framework, and build settings across all C# projects
• .github/workflows/build-installer.yml: CI/CD pipeline automating build, test, and MSI generation; reveals the complete build process and dependencies
• GitVersion.yml: Semantic versioning configuration; controls how release versions are calculated and tagged
• Installer/Server.wxs: WiX component file specifically defining the usbipd service installation, firewall rule (port 3240), and TCP listener setup

CLI commands: likely in src/Program.cs or src/Commands/ (typical structure for .NET CLI apps). Service logic: search for Windows Service host (ServiceController, ServiceBase usage). Driver integration: Drivers/ folder has pre-built binaries and .inf files — modifying would require VirtualBox source or a different USB filter driver. Installer customization: modify Installer/*.wxs files (WiX markup) to add/remove features. Build/version info: edit Directory.Build.props and GitVersion.yml for versioning.

Administrator privileges required: the application must run with elevated privileges to bind USB devices and manage drivers. Driver architecture mismatch: VBoxUSB drivers are pre-built binaries (arm64 and x64); building on non-matching architectures or Windows versions may fail silently. Port 3240 must be open: firewall rules are added during install but third-party firewalls (mentioned in README) may block TCP 3240 without user configuration. Persistence across reboots: the bind operation is persistent (survives reboots) but client attachments are not, which can surprise new users. Windows version constraint: officially supports only Windows 10 x64/ARM64 or Windows Server 2019 v1809+; older versions will fail at driver load time.

• USBIP (USB over IP) — This entire project is a USBIP server; understanding the USBIP protocol (how USB packets are serialized, sent over TCP, and reconstructed on the client) is essential to debugging connectivity or adding new features
• Kernel-mode USB driver and filter drivers — The VBoxUSB.sys kernel driver intercepts USB traffic before the OS; understanding driver architecture, IRPs (I/O Request Packets), and kernel-mode debugging is required to modify the core USB capture mechanism
• Windows Service architecture and ServiceBase — usbipd runs as a Windows Service listening on port 3240 continuously; understanding service lifecycle, start/stop notifications, and error recovery is necessary for service-side bug fixes
• WiX Toolset (Windows Installer XML) — The entire installer is built from .wxs files (Product.wxs, Server.wxs, etc.); understanding WiX is required to modify installation behavior, add new components, or troubleshoot MSI deployment failures
• Device driver INF files and CAT (Catalog) signing — Drivers/*/VBoxUSB.inf and .cat files tell Windows how to install the kernel driver; understanding INF structure and code signing is necessary if you need to modify driver installation or support new hardware
• Administrative privilege elevation and UAC (User Account Control) — The tool requires administrator privileges to bind devices and manage drivers; understanding how to handle privilege escalation, manifest files, and UAC prompts is critical for CLI design and security
• TCP socket server and async I/O patterns — The service listens on TCP port 3240 and must handle multiple concurrent USBIP client connections; understanding async socket patterns, buffering, and protocol state machines is needed for network layer debugging

• dorssel/usbipd — The original Linux/macOS port of this tool; provides USBIP client implementation and shows how the protocol works cross-platform
• VirtualBox/virtualbox — Upstream source of the VBoxUSB.sys kernel driver bundled in Drivers/; understanding VirtualBox's USB filtering is key to modifying this project
• microsoft/WSL — WSL 2 is a primary target client for usbipd-win; the WSL project's USB device support documentation complements this tool
• felixbirkham/win-usb-share — Alternative Windows USB sharing tool; useful for comparing feature sets and architectural decisions
• daynix/usbip-win — Windows USBIP client library that receives USB data from usbipd-win; understanding both client and server is necessary for end-to-end debugging

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CommandHandlersCli_Tests.cs edge cases and error scenarios

The repo has a CommandHandlersCli_Tests.cs file but examining the partial file structure shows limited test coverage. Given this is a CLI tool for USB device sharing, comprehensive tests for command parsing, validation, and error handling are critical. New contributors could add tests for malformed input, permission errors, and device unavailability scenarios that users might encounter.

• [ ] Review existing CommandHandlersCli_Tests.cs to identify untested command handlers
• [ ] Add unit tests for invalid command-line argument combinations (e.g., missing required flags, conflicting options)
• [ ] Add unit tests for error conditions: non-existent devices, permission denied, device already attached/detached
• [ ] Add unit tests for edge cases: empty device lists, special characters in device names, concurrent operations

Add missing unit tests for ClientContext_Tests.cs connection lifecycle

ClientContext_Tests.cs exists but the repo manages USB device connections across networks (to Hyper-V and WSL 2). A new contributor could add comprehensive tests for connection establishment, cleanup, timeout handling, and reconnection scenarios which are critical for reliability.

• [ ] Add tests for successful client connection and disconnection flows
• [ ] Add tests for connection timeout and retry logic
• [ ] Add tests for cleanup when connections are forcefully terminated
• [ ] Add tests for concurrent client connections and resource cleanup
• [ ] Add tests for invalid device binding/unbinding sequences

Add CI workflow for cross-architecture driver validation (x64 and arm64)

The repo contains driver binaries for both Drivers/x64 and Drivers/arm64 platforms (VBoxUSB.sys, VBoxUSBMon.sys), but there's no evidence of a workflow validating driver signatures, catalogs, or architecture-specific configurations. A new contributor could create a GitHub Actions workflow to verify driver integrity, INF file correctness, and architecture matching.

• [ ] Create new workflow file .github/workflows/validate-drivers.yml
• [ ] Add validation step to verify .cat (catalog) file signatures for x64 and arm64
• [ ] Add validation step to verify .inf driver configuration files reference correct architecture binaries
• [ ] Add validation step to ensure both x64 and arm64 versions are present and synchronized
• [ ] Integrate workflow into existing CI pipeline in build-installer.yml documentation

• Add unit tests for the CLI argument parser (likely Program.cs or Commands/*). The test coverage from Codecov suggests gaps in command-line parsing logic, especially for edge cases like invalid --busid values or conflicting flags.: Improves reliability of user-facing commands and is a good way to learn the CLI structure without touching driver code
• Document the USBIP protocol implementation details in README or a PROTOCOL.md file. Currently, the README only explains user-facing commands; there's no guide for developers on how the TCP port 3240 communication works or how to debug client connections.: Helps future contributors and people debugging connectivity issues understand the network layer
• Create or improve integration tests in .github/workflows/ to validate that the installed MSI actually registers the Windows Service correctly and opens port 3240. Currently, build-installer.yml only builds; it doesn't verify the service starts or listens on the correct port.: Catches installer regressions early and demonstrates the full deployment pipeline to new contributors

The usbipd-win repository demonstrates good security practices with CI/CD workflows (CodeQL, linting) and proper licensing (REUSE compliance). The primary security concerns are the inclusion of pre-compiled third-party driver binaries without explicit verification mechanisms and potential exposure through GitHub workflows. The codebase appears to follow security best practices with automated analysis enabled. Recommendations focus on driver verification, credential management in CI/CD, and formal security policy documentation.

• Medium · Third-party Driver Files Included — Drivers/x64/, Drivers/arm64/. The repository includes pre-compiled VBoxUSB driver files (VBoxUSB.sys, VBoxUSBMon.sys) for both x64 and arm64 architectures. While these appear to be from VirtualBox/Oracle, including binary drivers without explicit verification mechanism creates a supply chain risk and makes it difficult to audit the actual code being executed. Fix: Document the exact source, version, and hash of these drivers. Consider implementing a verification step during installation to validate driver signatures and integrity. Document the build process for reproducibility.
• Low · Incomplete README Content — README.md. The README.md file appears truncated in the provided snippet (Codecov badge URL is incomplete). While not a direct security vulnerability, incomplete documentation can lead to misconfigurations. Fix: Ensure documentation is complete and up-to-date with proper security setup instructions.
• Low · Potential Hardcoded Credentials in Configuration Files — .github/codecov.yml, .github/dependabot.yml, Installer/packages.lock.json. The repository contains multiple configuration files (.github/codecov.yml, package.lock.json) that could potentially contain credentials or sensitive tokens if not properly managed. GitHub workflow files are present which may expose secrets if misconfigured. Fix: Audit all configuration files to ensure no credentials, API keys, or tokens are committed. Use GitHub secrets management for sensitive values. Enable secret scanning in GitHub repository settings.
• Low · Missing or Incomplete Security Policy — Repository root. No SECURITY.md or security policy documentation is visible in the file structure, which is important for coordinating responsible vulnerability disclosure. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process and security contact information.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.