ncpeer

Project primer

ncpeer — NinjaRemote Peer (review primer)

Cross-platform remote-desktop agent in C++/Qt (qmake + vcpkg). Ships two roles that share
one core runtime and speak a custom encrypted binary transport: a streamer
(host/agent, runs elevated / as a service) and a player (viewer). Targets Windows,
Linux, macOS, Android, iOS.

Architecture (durable map)

• common/ — transport framing + crypto (per-channel nonces, AEAD), IP/ACL, shared types.
• core/ — the business logic: a set of workers, each on its own QThread, talking via

Qt signals/slots. Subsystems: session/channel routing, screen capture + encode, audio,
input injection, reliable bulk/file transfer, TCP tunnelling, TLS bridge, HTTP.

• core/desktop/, core/codecs/, core/audio/ — per-OS capture/input, video codecs

(VP8/9, H.264 incl. hardware), audio I/O + Opus. Platform-specific code is the norm here.

• app/ — process scaffolding, the Glob settings container, IPC (UDP + local socket),

crash handling.

• ncstreamer/, ncplayer/, *-mob*/ — the role entry points/UI (desktop + mobile).
• filetransfer/, drivers/ (virtual display), qml/, guicommon/.

What matters most here (durable risk areas)

• Cross-platform correctness. Capture, input injection, and audio have separate per-OS

implementations; a fix on one OS can regress another, and an unguarded platform API breaks
another OS's build. Platform code must be #ifdef/Q_OS_*- or .pri-guarded.

• Transport & crypto integrity. Any change to wire framing, field layout, channel

numbering, or nonce handling is protocol- and security-critical: nonce reuse or a skipped
MAC silently voids the guarantee; wire changes need version negotiation (see below).

• Input-injection privilege boundary. Injection runs elevated on the target; coordinate-

mapping and confirmation-gating bugs have direct safety/security impact.

• Real-time concurrency. Capture/encode/input/congestion callbacks cross threads; guard

shared frame/queue state and guard worker shutdown against in-flight callbacks.

• Session / shared-memory lifecycle. Shared memory + system mutexes coordinate

streamer/launcher/agent restarts; stale handles or missed cleanup lock processes out.

Security-sensitive zones

Crypto primitives + transport auth; the TLS bridge (cert-validation bypass is high-risk);
input injection (remote-control surface); IP/ACL access control; the confirm-to-connect flow.

Compatibility surfaces (must not silently break)

• Wire protocol — framing, channel enum, and serialized struct field order (QDataStream).

Streamer and player run at different versions in the field: gate any change on the protocol
version fields; never remove/reorder a serialized field without negotiation.

• ninjarmm:// URL scheme — the player's public invocation interface (backend/launcher).
• **NC_* environment variables** — a documented operator/CI interface.
• IPC (UDP / local socket) — used by the installer and QC launcher to start/stop sessions.
• Glob settings keys — persisted + cross-process; renames break upgrades.

Conventions & gotchas

• Worker start/stop is ordered and fenced — adding a dependency can deadlock startup.
• NC_IGNORE_SSL_ERROR is dev-only but operator-settable; never widen its scope.
• Qt6 is the target — the project has migrated off Qt5. Any remaining Qt5 / _qt5

code is a historical artifact; do NOT flag a change for breaking a Qt5 build or for
dropping Qt5 support. Removing dual-Qt scaffolding is fine.

• Mobile lacks some desktop features (virtual display, printer redirect, full IPC revival) —

don't assume parity.

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