nrvusb

Project primer

nrvusb — NinjaRemote virtual-USB driver (review primer)

Virtual-USB driver used by ncpeer for USB redirection in remote sessions (Windows).
Early-stage: the main branch is near-empty and active driver code lives on feature
branches, so treat the layout as still forming and read the PR's target branch.

What matters most when reviewing here (durable risk areas)

• Driver-model correctness. A USB driver sits at a privileged/kernel boundary —

IOCTL/buffer validation, IRP handling, and object lifetime/teardown bugs can crash or
compromise the whole system. Untrusted input crossing into privileged code is the top risk.

• System stability. Faults here are BSOD / device-stack-corruption class, not app

crashes — hold changes to a high correctness bar.

• Cross-Windows-version compatibility and driver signing (WHQL/attestation):

changes to the driver package/INF or the signing pipeline are high-impact.

• Resource lifetime. Handles, memory, and device objects must be released on every

error and teardown path.

Security-sensitive zones

The kernel/user boundary and any IOCTL / shared-buffer interface exposed to user mode.

Compatibility surfaces (contracts that must not silently break)

• The interface ncpeer uses to drive the virtual USB device.
• Driver package / INF / device IDs and signing requirements.

Conventions & gotchas

• WDK/driver conventions apply, not app C++ — verify against the driver model actually used.
• WDF device interfaces are per-DEVICE-lifetime, not per-handle. WdfDeviceCreateDeviceInterface

registers an interface for the WDFDEVICE's whole life; it is never "deleted", only toggled via
WdfDeviceSetDeviceInterfaceState. So a set-once "which interfaces exist" flag/bitmap that is
never cleared is NORMAL, and returning STATUS_DEVICE_BUSY / "already created" on a repeat
create is an intended idempotency guard — not a lockout. Keep this device-lifetime registration
distinct from the transient per-file-handle objects (VHID module, I/O queues) that ARE created
and torn down per open/close: they live on different lifecycles, so a file-cleanup path that
frees the per-handle object correctly does NOT touch the device-interface flag.

• Because main is currently thin, confirm which branch a PR targets and read that

branch's real layout rather than assuming.

_Orientation only — verify current specifics in the code; this describes durable driver
risk areas, not a snapshot._

Ecosystem map

NinjaRemote / NinjaOne project ecosystem (relationship map)

How the monitored repos relate — so a change in one repo is reviewed with its blast
radius in mind (a change upstream of ncpeer can break ncpeer even if it looks local).
Orientation only; verify specifics in code.

NinjaRemote product

• ncpeer — the remote-desktop client/agent (streamer host + player viewer). The hub.
• ncrp — the server/relay component NinjaRemote peers connect through; ncpeer ⇄ ncrp

speak the NCRP wire protocol (protocol/format changes must stay compatible across
client and server versions).

• ncinstaller — installs the ncpeer player onto end machines.
• qclauncher — bootstraps/launches an ncpeer quick-connect session.

Cloud-side relays of the ninja-remote system (AWS-hosted, Python/Go)

• websocket-switch — generic WebSocket pairing relay: two clients join with signed

URLs, it pairs them and forwards frames verbatim. Signed join URLs are minted by the
Ninja backend — the signature scheme is a backend⇄relay contract, and the frame
semantics are a peer⇄peer contract.

• file-transfer-service — the same pairing idea over plain HTTP for file transfer:

a signed upload leg streams to a signed download leg through memory (never stored).
Two parallel implementations (Python ftsv2/ + Go fts_go/) must stay behaviorally
identical; the URL/signature scheme is shared-family with websocket-switch.
NinjaRemote file-transfer features ride on these relays when peers can't go direct.

Pulled INTO ncpeer (and sometimes nmsnj) — upstream of the products

• nccommon — shared C++ library; a submodule of BOTH ncpeer and nmsnj. An API/ABI

or behaviour change here affects both consumers.

• nr-i18n — localization resources; a submodule of ncpeer.
• nrvirtdisplay — Windows virtual-display driver used by ncpeer.
• nrvusb — virtual-USB driver used by ncpeer.
• ncpeer_vcpkg — the pinned/patched dependency set (vcpkg fork) that **ncpeer and nmsnj

build against**. A dependency bump changes what those products link (security/ABI/build).

• ncpeer_qt6win7 — patched Qt6 (QtBase) for legacy-OS support, delivered to the clients

through the ncpeer_vcpkg overlay.

Largely independent

• nmsnj — network-management delegate (talks to the Ninja Backend over WAMP/RPC);

shares nccommon and ncpeer_vcpkg with ncpeer.

• ninjaflow — packet-capture library + agent (a distinct network-telemetry product, NOT

part of the remote-desktop family). Runs as a child process of the NinjaRMM agent (the
parent owns install/upgrade/policy/launch); NinjaFlow owns the CLI contract, config schema,
credential precedence, DB schema/migrations, and exit-code meanings the parent consumes —
those are cross-process contracts. Submits telemetry to the Ninja Backend. Shares no code with
ncpeer/nmsnj; adjacent to nmsnj only in domain (network), not in implementation.

• desktop-companion — internal companion app; mostly standalone.
• spaceship — AppSec SBOM-ingestion backend (Python/Flask). A distinct security product,

not part of any product's build. It consumes the SBOMs the other products' pipelines emit
(Ninja-Remote/ncpeer, NMS/nmsnj, NinjaFlow all appear in its scope maps), scans them for CVEs
and files Jira issues — a downstream *security-scanning* relationship, not a code dependency.
Shares no code with the others; has its own DB/schema and a toolbox submodule.

• ssh-pam-ninja — SSH one-time-password PAM gatekeeper (Linux C). A standalone

authentication component: its pam_ninja.so gates SSH reverse-tunnel access into
Ninja infrastructure with a time-based OTP. Shares no code with the other repos; its
blast radius is operational (who can SSH-tunnel into hosts), not code-level. The client OTP
generators and the module must agree on the OTP scheme + shared secret.

Review implications

• Reviewing nccommon / nr-i18n / nrvirtdisplay / nrvusb / ncpeer_vcpkg / ncpeer_qt6win7:

these are *upstream* of ncpeer (and nccommon/vcpkg also of nmsnj) — weigh the consumer
side: API/ABI compatibility, build impact, and cross-platform reach.

• Reviewing ncpeer or ncrp: the NCRP wire protocol between them is a cross-version

contract.