nmsnj

Project primer

nmsnj — NMS Delegate (review primer)

C++/Qt6 network-management agent (Windows service; also deployed on Linux). Discovers and
monitors devices (ICMP/TCP/HTTP/SNMP/NetFlow/Syslog), evaluates conditions, runs CLI/SSH/
Telnet config + agent-deployment tasks, and relays results to the **Ninja Backend over
WAMP/RPC** (Autobahn + WebSocket++/Boost.ASIO + TLS).

Architecture (durable map)

• nmsmanager/ — entry point: bootstrap, WAMP login, Windows-service plumbing.
• nmscore/ — worker base (each worker owns a QThread + event loop), the HTTP job

queue, and the WAMP/RPC layer; nmscore/condition/ condition evaluators;
nmscore/structs/ JSON↔struct serialization.

• wrk/ — the concrete workers (discovery, SNMP, NetFlow, CLI, config backup, deployment,

syslog, ICMP/TCP/ARP/DNS, …); wrk/misc/ protocol clients (SSH/Telnet/SNMP) + DB migrator;
wrk/flow/ flow parser + the encrypted flow DB.

• app/ — platform shims (Windows COM/registry/firewall/minidump/service vs Linux).
• ncossl/ — OpenSSL/TLS (FIPS-capable); ninja-security — credential encryption (DPAPI).

What matters most here (durable risk areas)

• Threading / Qt object affinity. Workers run on their own threads — cross-thread calls

must go via signals/slots or invokeMethod; check the shutdown guard before dereferencing
shared worker pointers.

• Network/IO error paths. SSH/Telnet/SNMP/HTTP/WAMP over flaky networks: finite retries,

a possibly-null WAMP context, independent session-disconnect states — swallowed errors,
unchecked results, and silent hangs are the classic bugs. Clean up on partial failure.

• Session/socket lifetime. Back-pointers span the Boost.ASIO thread and Qt threads;

use-after-free / null-after-check on replies and sessions is the recurring pitfall.

• Credential handling. SNMP community/v3, SSH/Telnet creds flow through config JSON —

never log them; encrypt at rest.

• Encrypted-DB migrations. The flow/config SQLite DBs are SEE-encrypted and use

numbered, append-only migrations; reordering/editing a shipped migration or changing
key derivation corrupts existing DBs silently.

• Cross-platform build. Windows-primary; the Linux path is thinner. Platform APIs (COM,

DPAPI, WMI, registry, service) must be guarded and Linux equivalents not left as stubs.

Security-sensitive zones

Credential storage (DPAPI) + never-log discipline; WAMP auth — **every RPC handler must
validate the caller's authRole** before acting; SEE-encrypted SQLite key handling; backend
TLS (no downgrade / cert-skip); remote deployment (WMI / PowerShell) — injection via
unsanitized target/credential inputs.

Compatibility surfaces (must not silently break)

• WAMP RPC payload shapes the backend expects — field renames/type changes are breaking.
• Config JSON schema (credential / OID / policy / target keys) — a backend-driven

contract for all deployed agents.

• DB migrations — append-only, monotonically numbered, tracked by checksum.
• The differential getConfig(since) protocol — delta semantics must match the backend.

Conventions & gotchas

• Periodic work belongs in the worker's timer callback, not ad-hoc threads.
• Task-completion callbacks fire from a custom deleter (on destruction), not on explicit call.
• The WAMP/WebSocket++ header has strict include-order constraints (noted in-file).
• Release logs carry source context (visible in crash dumps) — mind what is logged.
• The dev-vs-release build flag is not a security gate.

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