qclauncher

Project primer

qclauncher — QC Launcher (review primer)

Customer-facing Qt6/C++ desktop app (Windows and macOS) that bootstraps a NinjaRemote
Quick Connect session: it registers/authenticates the device with the NinjaOne backend over
WAMP/WebSocket + TLS, then on backend command fetches, integrity-verifies, installs,
and launches the ncstreamer process (also handles RMM agent install + self-cleanup). qmake.

Architecture (durable map)

• downloader/ — standalone bootstrapper that runs first: fetches the launcher binary

(invitation-code flow), verifies its hash, unpacks, launches it, reports, self-cleans.

• launcher/ — main binary: login/registration, WAMP session, system-tray UI, and the

RPC action handlers the backend calls to start / start-as-user / install-agent /
uninstall; launcher/internal/ process + bootstrap helpers (elevation, run-as-user, IPC).

• wrk/ — WAMP worker (Autobahn over WS+TLS, proxy-aware) + a retrying HTTP worker.
• common/ — run-as/sudo wrapper, zip, retry; fingerprint/, njlog/, shared security lib.

What matters most here (durable risk areas)

• Shell execution on macOS. Some flows shell out (DMG mount/unmount, etc.) with paths

derived from downloads/config — shell-injection and TOCTOU surface; server-supplied
content must never be shell-interpolated.

• Untrusted server-provided arguments. Backend RPC kwargs (including unknown extras) are

written to a session file and passed to ncstreamer — verify nothing is shell-interpolated
and the temp file isn't world-readable/writable.

• Integrity-before-execute. Downloaded binaries are hash-verified before running; the

check must be un-skippable on every error / early-quit path.

• Session-credential file lifecycle. The session hand-off file contains key material and

is deleted on a timer, not immediately — wrong perms, leaks, or a missed timer expose it.

• Privilege escalation. Run-as-user / elevation / sudo paths must elevate only when

needed and never expose credentials in argv or logs.

• WAMP authrole gate. Every RPC handler must validate the caller's authrole — a missing

check on a new handler is high-severity.

Security-sensitive zones

The macOS shell-out paths; credential handling in the start-as-user flow and the sudo wrapper;
bootstrap-arg parsing from an elevated process; proxy credentials.

Compatibility surfaces (must not silently break)

• WAMP RPC interface (start / start-as / install-agent / uninstall): kwarg names +

result/error tuples are a contract with the backend.

• Session hand-off file schema passed to ncstreamer — field changes break the streamer.
• The device/session binary key layout shared with the backend.
• Windows named-event IPC between downloader and launcher.
• Install paths shared across install / run / remove / version-check.
• Downloader parameter-embedding scheme (invitation code / URLs baked into the binary,

with a filename-based fallback) — packaging/signing changes can break param extraction.

Conventions & gotchas

• Singletons for platform utils / session state / tray; workers via a named registry.
• Heavy event-loop + signal/lambda "sync-looking async" — watch for missed loop-quit on error

paths (hangs).

• Elevation state is detected once at startup and cached (drives user- vs system-dir install).
• The macOS shell-outs are intentional (shell-pipeline ops) but a known liability.

_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.