nrvirtdisplay

Project primer

nrvirtdisplay — NinjaRemote virtual display driver (review primer)

Windows Indirect Display Driver (IDD) in C++: a **user-mode UMDF2 driver on the WDK IddCx
framework** that presents a synthetic display adapter + virtual monitor(s) to Windows, so
ncpeer can drive headless machines and add monitors for remote sessions. It is a DLL loaded by
the UMDF host process, not a .sys.

Architecture (durable map)

• Driver logic: DriverEntry + the WDF/IddCx callbacks (device add, power, adapter init, mode

negotiation, swap-chain assign/unassign) and DDI registration.

• Per-monitor frame consumer: a dedicated thread acquires/releases DXGI surfaces (the swap

chain) via a D3D11/DXGI device.

• Adapter/device and per-monitor context objects are raw-pointer wrappers whose lifetime is

owned by WDF object lifetimes.

• Chromium-style LOG/CHECK (fatal checks HARD-KILL the host) + WPP/ETW tracing (debug).
• Build: MSVC, x86/x64/ARM64, Spectre mitigations + PREfast on; INF + signed catalog packages.

What matters most when reviewing here (durable risk areas)

• IddCx DDI contract correctness. Every callback must return correct NTSTATUS and fill

output structures exactly as the framework expects — errors leave the display subsystem
inconsistent or degrade it silently.

• Swap-chain / surface lifetime. DXGI surfaces must be released promptly and in order;

hold/double-release → GPU leaks or hangs. On D3D device loss, delete the swap-chain so IddCx
retries — otherwise the pipeline stalls.

• Concurrency on context pointers. Swap-chain arrival racing device cleanup risks

use-after-free; WDF object lifetime is the only guard — check callback-context races.

• System stability. User-mode, but a host-process crash makes the virtual display vanish;

avoid uncaught exceptions / unhandled WDF errors.

• Driver signing. Any binary/INF change requires the full HSM + WHQL re-sign across all

arches; a catalog mismatch breaks install under Secure Boot / DSE.

Security-sensitive zones

The INF permits kernel-mode clients to open the UMDF device — treat buffers crossing the IddCx
boundary as untrusted; OS-sized output arrays must not be over-written (OOB). Don't log
sensitive handles/LUIDs at production trace levels.

Compatibility surfaces (contracts that must not silently break)

• Minimum Windows baseline — newer APIs need version guards or a baseline + INF/WHQL bump.
• All three arches (x86/x64/ARM64) built + signed + WHQL-submitted together.
• The IddCx interface version must match the target Windows build (a bump ⇒ re-verify DDI + WHQL).
• The INF hardware/device ID + driver-package layout (dll/inf/cat triad) — ncpeer's installer

addresses the driver by these; renaming/restructuring breaks install on existing deployments.

Conventions & gotchas

• WDF device interfaces are per-DEVICE-lifetime. A registered device interface

(WdfDeviceCreateDeviceInterface) lasts the WDFDEVICE's whole life and is only toggled via
WdfDeviceSetDeviceInterfaceState, never deleted; a set-once "created" flag that is never
cleared is normal, not a leak. Keep it distinct from the per-monitor / swap-chain objects,
which DO have real create/destroy pairs (and those are the actual lifetime risk here).

• Debug vs release differ in exception model and the pinned IddCx minor version — behaviour may

appear in only one configuration.

• Fatal log checks terminate the host process (hard kills, not fallbacks).
• The advertised virtual-monitor count feeds IddCx adapter caps that Windows caches.

_Orientation only — verify current specifics in the code; this describes durable architecture &
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.