0.21.0

[mickem]

NSClient Fleet launches: central management for your agents, plus checks that only read what you allow

0.21.0 is the agent release that goes with the first release of NSClient
Fleet, a new, separate product: one server that holds the configuration for
a whole estate of NSClient++ agents, hands each host the part that applies to
it, and shows you what every host is actually running. Agents enroll
themselves and report what they are, so the server builds the inventory
instead of consuming one; groups select hosts by those reported tags, and
bundles of configuration and scripts attach to groups. This release brings
the agent side to feature parity with the server: encrypted bundles the server
cannot read, a way to leave a fleet, and an nscp test prompt that survives a
configuration push. Fleet is entirely optional; NSClient++ works exactly as it
always has without it.

The other theme is reading less. check_logfile, check_files, check_wmi,
check_pdh, check_registry_* and check_eventlog read whatever their
argument names, with the agent's privileges, which is a general read primitive
wherever a caller may choose the argument. Each of them now has an access mode
and an allow list, off by default. Two WEB roles complete the picture:
restricted runs the checks you define but passes no arguments, and
metrics scrapes and does nothing else. And the nscp test prompt got a
round of usability work: aligned listings, a desc that shows defaults and
what an alias runs, filter keyword lists, single-quoted paths and
case-insensitive completion.

✨ Highlights

• 🚀 NSClient Fleet is out. A server that enrolls your agents, builds the
  inventory from what they report, and delivers configuration and scripts per
  host as signed bundles, pulled by the agent over mTLS with no inbound port.
  Read the launch announcement
  and the Fleet documentation; this
  release is the agent side of it.
• 🛡️ Access modes for the checks whose argument decides what is read.
  check_logfile, check_files, check_single_file, check_disk_write,
  check_wmi, check_pdh, check_registry_key, check_registry_value and
  check_eventlog each gained a mode setting and an allow list. The default,
  any, is exactly the previous behaviour; predefined limits a caller to the
  names you configured; allowed matches an allow list. Nothing changes on
  upgrade. (feature: add access control gates for data-reading checks #1516)
• 🔒 Two WEB roles that cannot be widened. restricted holds
  queries.execute.noargs, the REST equivalent of NRPE's
  allow arguments = false: it runs the checks the agent defines and refuses
  any query-string parameter. metrics reads the two metrics endpoints and
  nothing else. The bundled monitoring role finally holds the grant the
  metrics endpoints actually check, so a monitoring user is no longer answered
  403 there. (feature: add queries.execute.noargs grant for argument-less query execution #1517, feature: add metrics role and fix monitoring role grants #1520)
• 🔐 Encrypted fleet bundles. A bundle sealed in the fleet server's browser
  is opened by the agent with a key you hand it out of band, at enrollment
  (nscp enroll --bundle-key, FLEET_BUNDLE_KEY on the MSI) or later. The key
  and the optional "sealed bundles only" posture live in the enrollment
  manifest, never in the settings store, so the server cannot plant or switch
  them. (Fleet: encrypted bundles, unenroll, and an nscp test prompt that survives a config push #1521)
• 🚪 nscp enroll --unenroll leaves the fleet. It removes the include,
  the identity and keys, and the fleet directory, and reports each step.
  (Fleet: encrypted bundles, unenroll, and an nscp test prompt that survives a config push #1521)
• 💥 nscp test no longer crashes after a fleet configuration push. A
  settings reload replaced the object the prompt's completion held a pointer
  to; the next completion refresh dereferenced freed memory. The crash file the
  agent writes now names the faulting module instead of printing a pointer.
  (Fleet: encrypted bundles, unenroll, and an nscp test prompt that survives a config push #1521)
• 🖥️ A better nscp test prompt. Padded tables instead of tabs in every
  listing, desc with parameter defaults, the bare-call command line and what
  an alias runs, a keywords verb listing a check's filter keywords, alias
  as a shorter aliases, Tab completion that corrects load check to
  load Check…, single quotes that take paths literally, exec that passes
  --options to a module, and a settings dump that lists only what is
  configured with passwords masked. (nscp test prompt: aligned listings, richer desc, keywords, alias, case-insensitive completion, single quotes #1522)
• 🔎 Three follow-up fixes to the access gates from review, including a
  path written with the other separator walking out of an allowed directory,
  a link the path resolver skipped, and a reload window during which every
  gate stood open. Ship the release with those in, not the first cut.
• 📦 Packaging. Each Windows install no longer strands an 8 MB copy of
  nscp.exe under %WINDIR%\Installer, the WinGet manifests carry the
  metadata the upstream validator wants again, and the Debian source package
  drops a Unicode-licensed file so it passes Lintian. (Replace Unicode-licensed ConvertUTF with DFSG-free implementation #1518)

🔍 Detailed changes

🚀 NSClient Fleet

Until now a large estate of agents was configured either by pointing each one
at an ini file on a web server or by pushing settings over the REST API from
whatever orchestration you already run. Both still work. Neither keeps track
of the estate: the only inventory is the one you maintain by hand.

Fleet turns that around. A host enrolls with a one-time token, a few MSI
properties or one nscp enroll command, and appears in the inventory with its
OS, version, drives and detected roles as tags the agent reported. Groups
select hosts by tag, bundles of INI fragments and scripts attach to groups,
and each host pulls the bundles that apply to it, verifies their signatures,
renders them into a fleet.ini its own nsclient.ini includes, and reports
back what it applied. The server never pushes and never needs a port opened on
a monitored host. Status is derived from what hosts report: in sync, out of
sync, offline, lost, and whether local settings outrank what the server sends.
It is one static binary and a SQLite file, on Linux or Windows or as a
container, in its own repository.

To learn more, start with the
launch announcement,
then the Fleet documentation for running
it in Docker, installing it on Linux or Windows, and the deployment reference.
The agent-side walkthrough is
Central management with NSClient Fleet.
What this release adds on the agent side is below.

🛡️ Restricting what a check may read

The checks in the table take an argument that decides what data is read,
and the agent reads it with its own privileges. Where callers choose the
argument, NRPE with allow arguments = true or a REST user not on the
restricted role, an unrestricted file= is a general file-read primitive.
Each module gained a mode setting and an allow list:

Check	Section	Mode setting	Allow list
check_logfile	[/settings/logfile]	file access	allowed files
check_wmi	[/settings/wmi]	query access	allowed classes, allowed namespaces
check_pdh	[/settings/system/windows]	counter access	allowed counters
check_files, check_single_file, check_disk_write	[/settings/disk]	file access	allowed files
check_registry_key, check_registry_value	[/settings/system/windows]	registry access	allowed registry keys
check_eventlog	[/settings/eventlog]	log access	allowed logs

The modes are any (the default, and what every earlier release did),
predefined (the secure option: only names you configured in the module's own
sections, such as [/settings/logfile/files] or the counters already in
[/settings/system/windows/counters]) and allowed (only what matches the
list; experimental, since it has to parse what the caller sent). Registry and
event-log entries are hierarchical and match whole name segments. Configured
names resolve in every mode, so you can name your checks first and tighten
the mode afterwards.

Once a mode is set, some arguments tighten with it: a check_wmi namespace=
may no longer leave root\cimv2 unless allowed namespaces says so and its
target= must name a configured target, check_registry_* refuses
computer=, and check_eventlog's default channels go through the gate like
any other. Review of the gates before release closed a path written with the
other separator walking out of an allowed directory, a symbolic link the path
resolver did not follow, a NUL byte, a remote host in the path, and a window
during a settings reload in which every gate stood open; allowed mode judges
a WMI query by its class rather than its text. Alongside this, check_files
on Windows no longer follows file symbolic links, as the Linux scanner never
did, and * and ? in a path allow list no longer cross a directory
separator (C:/logs/**.log for the subtree). See
Restricting what a check may read.

🔒 WEBServer — roles that cannot be widened

restricted holds queries.execute.noargs instead of queries.execute: the
caller may run the checks the agent defines, and a request carrying any
query-string parameter is refused with 403 Arguments are not allowed for this user. Neither grant implies the other. Give such a caller the checks that
need arguments as aliases, so the arguments live in your configuration:

[/settings/WEB/server/users/monitor]
role = restricted

[/settings/check helpers/alias]
check_root_disk = check_drivesize drive=/ warning=free<10% critical=free<5%

Every query parameter counts, including a session token passed the legacy way
as ?TOKEN=, so a restricted client authenticates with a header.

metrics is for a Prometheus scraper: metrics.list and openmetrics.list,
no queries.execute. The bundled monitoring role granted metrics.get, a
privilege nothing checks, so a monitoring user got 403 on both metrics
endpoints; it now grants the two real ones. Roles already written to
nsclient.ini are never rewritten, so an existing monitoring line keeps its
inert grant until you update it or assign metrics instead.

🔐 Fleet — encrypted bundles and unenrolling

A bundle the operator seals in the fleet server's browser (format: enc-v1)
used to be refused by the agent as an unreadable archive. The agent now opens
it. The envelope is AES-256-GCM with the bundle's name and version bound in as
additional data, so a server that re-labels an old sealed bundle gets a
refusal; the published checksum and signature cover the envelope, so download
verification is unchanged and decryption is a step after it. The plaintext
exists on disk only while it is unpacked; the cache keeps the envelope.

The key reaches the host out of band, never from the server:

Where	How
At enrollment	nscp enroll --bundle-key <key> (repeatable while rotating), or FLEET_BUNDLE_KEY=<key> on the MSI
On an enrolled host	nscp enroll --update-bundle-keys --bundle-key <key>, or re-run the MSI with only FLEET_BUNDLE_KEY
Sealed bundles only	nscp enroll --require-encrypted-bundles, or FLEET_REQUIRE_ENCRYPTED_BUNDLES=1

Both the keys and the requirement are stored in the enrollment manifest
beside the host's private key, not in nsclient.ini: the fleet-managed
configuration is an include of the settings store, so anything kept there
could be planted by the very server the bundles are sealed against. A bundle
sealed with a key the host lacks is refused and the state report names the
missing key's fingerprint, which is what the server shows on its key page.

nscp enroll --unenroll removes the [/includes] fleet entry, the manifest
and the fleet directory, in that order, and says what it removed; a service
restart stops the sync. It is a local act, so remove the host on the server as
well. Enrollment also resolves the manifest path from [/settings/fleet]
state file on every path now; a host that sets that key used to enroll into
a file the service never read. See
Central management with NSClient Fleet,
new in this release as a guide. (#1519, #1521)

🖥️ The nscp test prompt

A fleet configuration push, or any settings reload, killed the prompt: the
reload re-entered the module and replaced the client object the completion
hooks held a raw pointer to. Fixed, and the crash record the agent writes now
names the faulting module (it printed a pointer). On top of that:

Verb	Now
queries, aliases, list, plugins	Padded tables, one line per entry; list really lists both kinds
desc <query>	Parameter defaults, the command as it runs bare (show-default), and for an alias the command it runs plus that command's parameters
keywords <query>	The filter keywords and functions of a check with their descriptions, from the running agent
alias	Same as aliases
settings	Only what the configuration sets, with passwords masked
exec <module> --opt	Options reach the module as nscp <module> --opt sends them, instead of --opt being taken for the command
load check<Tab>	Completes and corrects the case: CheckDisk, CheckSystem, …
'C:\Program Files\x'	Single quotes take their content literally; "..." keeps its backslash escapes, and filter=core='total' typed bare still reaches the check as written

A PDH enumeration race seen through exec CheckSystem --list inside the
prompt is fixed as well: when the counter list grows between the sizing call
and the fetch, the agent grows the buffer and retries instead of reporting
PDH_MORE_DATA as a failure. (#1522)

🐛 Bug fixes

• check_logfile files= works: the comma-separated form was parsed before
  the check read its arguments and had been ignored since it was added; it is
  one list with file= now, and every name goes through file access.
• check_installed_software on Debian and Ubuntu takes install dates from
  dpkg-query (db-fsys:Last-Modified, dpkg 1.19.3 or later) instead of
  dpkg's internal database, and returns UNKNOWN when a package's file list
  cannot be read for a reason other than a missing file. (fix(CheckSystemUnix): take the dpkg install date from dpkg-query #1485)
• The nscp test fallback on Linux appended a tab and ... to every line of
  multi-line output; it now prints the record as written, as Windows did.
• Enrolling with a bundle key that has = padding in the middle is refused
  with a message that says so, and the MSI names the property that is
  actually missing when only FLEET_REQUIRE_ENCRYPTED_BUNDLES is given on an
  unenrolled host.

📦 Packaging

• The MSI's Add/Remove Programs icon was nscp.exe itself, so Windows
  Installer extracted an isolated 8 MB copy of the agent into
  %WINDIR%\Installer on every install. It is a real icon now.
• The WinGet manifests declare the VC runtime dependency, the real licence,
  the published moniker, ReleaseNotes, Documentations, locale, scope and
  installer switches again, date a manually re-published manifest by its
  release rather than the day the workflow ran, and keep the useful part of
  the release notes instead of cutting a table in half.
• The vendored replxx used by the prompt no longer carries Unicode, Inc.'s
  ConvertUTF, whose licence is not DFSG-free; the Debian source package
  passes Lintian again. (Replace Unicode-licensed ConvertUTF with DFSG-free implementation #1518)

⚠️ Upgrade notes

• Nothing changes by itself. Every access mode defaults to any, no user
  is assigned to the new WEB roles, and roles already written to
  nsclient.ini are not rewritten. Set a mode, or update a monitoring role
  line, only when you want the new behaviour.
• check_files on Windows skips file symbolic links. If you relied on
  them being counted, point the check at the link targets. Path allow-list
  wildcards no longer cross directory separators; use ** for a subtree.
• check_logfile with both file= and files= reads the union from
  this release on. Nothing to do unless you relied on files= being dropped.
• check_installed_software on a dpkg older than 1.19.3 leaves
  install_date unset, so an expression on it no longer matches there.
• Encrypted fleet bundles need the key on every host before the server
  starts serving sealed bundles; a host without it refuses them and names the
  missing key's fingerprint in its state report. There is no key escrow on
  the server.

Security notices for this release:
Access modes for the checks whose argument decides what is read,
WEB: a metrics role, and a corrected metrics grant on the monitoring role,
Fleet: encrypted bundles are opened by the agent, not the server and
Sensitive settings are redacted in the nscp test settings dump.
The full list of behaviour changes is on the
upgrading page.

Full Changelog: 0.20.0...0.21.0

---

This discussion was created from the release 0.21.0.