NetLock RMMNetLock RMM Docs
IV — Administration

Endpoint protection

Endpoint protection: devices installed with a trust anchor execute only definitions a registered phone signed and remote actions a registered phone approved. Setup in the NetLock app, the anchor as installation parameter, protection levels, signing definitions, approving actions and work sessions, screen control from the Relay App and the NetLock app, what happens when the server cannot check a device, device states, the public API, the operating rules, and Android devices.

Endpoint protection

With endpoint protection, an anchored device runs a definition (the policy, its jobs and sensors, App Hub apps, software deployments) only after a phone you registered has signed it. The server and the Console store and transport the definitions, but they cannot sign them. A change made in the Console reaches anchored devices once somebody with a registered phone has reviewed and confirmed it.

The same applies to remote actions. A remote shell, a file transfer, a screen control session, a tunnel or an agent uninstall on an anchored device needs a grant the phone signs for exactly that action on exactly those devices, or a work session that covers a class of actions on a device list for a few hours. A.13.4 describes the definitions, A.13.9 the grants and work sessions, A.13.10 screen control from the Relay App and the NetLock app, A.13.11 Android phones and tablets.

Note: Endpoint protection is opt-in per device. A device installed without an anchor is not affected by signatures. Without a trust line, the Console shows only the settings page of endpoint protection.

A.13.1 Concept in short

  • A trust line lists the signer phones and the recovery key. Every change to it is a new keychain version, signed by an existing signer with the keychain role or by the recovery key. Normally an installation has exactly one trust line.
  • The anchor is a 64-character value that identifies the trust line. It is the only value a device needs, and the device receives it at installation time. With it the device knows which keys may sign what.
  • A signer is a phone running the NetLock app with a key in its hardware keystore. The key signs only after the fingerprint or face check. The keychain lists each key with its roles: definitions (sign policies, jobs, sensors and the other definitions), grants (approve remote actions and work sessions) and keychain (add, remove or re-role signers). The recovery key is created once during setup, shown as QR code and text, and signs keychain documents only; it restores access when every phone is lost.
  • A definition is one version of a policy, job, sensor, automation, App Hub app, software deployment or NetMesh link. The phone signs it, and an anchored device runs it only with a valid signature.
  • The Console never shows an anchor as something to copy. The anchor comes out of the app that created it. The Console only displays which anchors devices report back, so you can compare the first characters after a rollout.

A.13.2 Setup in the NetLock app

Setup happens entirely on the phone, with the NetLock app for Android. The account needs the permission ztep_signer_own to register a phone and settings_endpoint_protection_manage to upload the trust line.

  1. Open Endpoint protection in the app and choose Set up. Give the trust line a label (the installation or company name is a good choice).
  2. The app creates the signer key in the phone's keystore and registers it with the Console. Keep the phone's screen lock on; the key does not sign without it.
  3. The app shows the recovery key once, as QR code and as text. Print it or store it in a password safe that is not reachable from the server. It is not shown again.
  4. Choose the protection level: Productive (default) requires a grant for everything that can take over a device (scripts and remote shells, writing files, system changes, screen control, backstage and elevation, tunnels and NetMesh links, application and agent uninstalls, sensor live tests) and allows work sessions of up to eight hours on up to 500 devices; Strict requires a grant for every class, including power actions, patch runs, reading files, the BitLocker key resync and audio calls, and allows no work sessions. The protection level is part of the keychain and can be changed later with a new keychain version.
  5. The app creates the trust line and shows the anchor in groups of four characters and offers Copy and Share. The copied value is the plain 64-character string the installer expects.
  6. The app uploads the trust line to the Console. The Console then lists the trust line under Settings → Endpoint protection.

To add a second phone, start on that phone: it registers its key, shows the key as QR code, and an existing keychain signer scans it and signs the next keychain version. The Console transports the new version to the devices with their next policy sync.

A.13.3 Anchoring devices

A device is anchored by the installer, in the modes clean and fix only:

NetLock_RMM_Agent_Installer clean ... --ztep-anchor 3f9a0c…e71b

GPO, Intune and scripted rollouts pass the parameter. The installer writes ztep/anchor.json next to the agent, readable only by SYSTEM and administrators (root on Linux and macOS). The agent update path never touches the file: an anchored device stays anchored through agent updates, an unanchored device never becomes anchored by itself.

Devices that were installed earlier are anchored by reinstalling them with the parameter or by running the installer in fix mode with it. Devices cannot be anchored remotely.

From the app. The anchor page of the NetLock app shows the installation commands per platform with the anchor already in them (PowerShell and command prompt for Windows, a shell one-liner for Linux and macOS), the repair commands for devices that are already installed, the files the anchor is stored in, and the bare parameter for your own script, GPO or Intune. The commands are the ones of the Agent installers page with --ztep-anchor appended. The app builds the commands on the phone.

The page needs the permission agent_installers_enabled next to the endpoint protection permission, and the location must have been opened once on the Agent installers page so its installers exist. The page also carries a fixed warning: never hand out the anchor through the Console, in a policy, a job, a script or a remote shell.

The installer writes the anchor into two files, one for the Comm agent and one for the Remote agent, readable only by administrators or root:

  • Windows: C:\ProgramData\0x101 Cyber Security\NetLock RMM\Comm Agent\ztep\anchor.json and C:\ProgramData\0x101 Cyber Security\NetLock RMM\Remote Agent\ztep\anchor.json
  • Linux: /var/0x101 Cyber Security/NetLock RMM/Comm Agent/ztep/anchor.json and /var/0x101 Cyber Security/NetLock RMM/Remote Agent/ztep/anchor.json
  • macOS: /Library/Application Support/0x101 Cyber Security/NetLock RMM/Comm Agent/ztep/anchor.json and /Library/Application Support/0x101 Cyber Security/NetLock RMM/Remote Agent/ztep/anchor.json

The repair command for an installed device is the installer in fix mode with the path of the Comm agent's server_config.json of the platform (…\Comm Agent\server_config.json below the same base directory) and the parameter; the app shows it ready to paste for every platform. The device keeps its registration, the installer refreshes the agent files and writes the anchor. Run it from your own deployment tool, a GPO, Intune or a local session, not through the remote shell or a job of the Console.

After the first sync the device reports its anchor, the keychain version it runs and its state. The device details show one line Endpoint protection in the General tab; the settings page counts devices per line and state. When the app uploads a new keychain version, devices anchored to that line receive it with their next contact (online devices right away).

A.13.4 Signing definitions

Once a trust line exists, the Console shows a Signature column in the lists of jobs, sensors, policies, automations, App Hub apps, software deployments and NetMesh links, with three states:

StateMeaning
SignedThe stored content matches the last signature. Anchored devices run it.
Changed since signatureThe definition was saved after it was last signed. Anchored devices keep running the signed version until it is signed again; unanchored devices already run the new one.
UnsignedNever signed. Anchored devices do not run it.

Three ways lead to a signature:

  • Save and sign in the dialogs of jobs, sensors, automations and App Hub apps and on the policy settings page. The definition is saved as usual, then the waiting dialog opens.
  • Sign in the actions column of a list entry.
  • Sign all pending above a list (every unsigned or changed entry of that list) and Sign all on the settings page (every kind at once).

The waiting dialog says Confirm in the NetLock app. The phone receives a push notification. Without push, the app lists open requests while it is in the foreground, and the QR code in the dialog opens the request directly. If the app knows the Console under another address, it asks before it loads the request. The app shows every document of the request with name, kind, version and the script text, one fingerprint signs them all, and the Console dialog closes as soon as the signatures have arrived. The devices receive the new versions with their next sync; the Console triggers that sync for online devices right away.

Who may ask for a signature follows the existing permissions: whoever may edit a job may ask for its signature. Who may sign is decided by the keychain alone. If the account that asks has a registered phone listed in the keychain with the definitions role, the request goes to that phone. Otherwise it goes to every account whose phone is such a signer, and the first signature wins. The dialog names the people it is waiting for.

Signing follows these rules:

  • Jobs and sensors are signed in their template form: variables such as {{field.api_key}} stay references. Changing the script needs a new signature; changing a custom field value does not.
  • A policy document lists the signed versions of its jobs, sensors and apps. Signing a job or sensor therefore re-signs the policies and automations that reference it in the same request: the item comes first, the lists follow, one confirmation on the phone covers them all. A list that was never signed is not pulled in.
  • A definition signed by a key the keychain no longer accepts (removed, revoked or without the definitions role after a keychain change) shows Signer key removed and counts as pending; Sign all pending re-signs it with a current key.
  • Deleting a job, sensor, app, automation, deployment or link marks its signatures as superseded and the policies and automations that listed it as Changed since signature. The delete dialogs of jobs, sensors and automations additionally offer Also revoke the signed versions on the phone: a registered phone signs a revocation, and anchored devices refuse the deleted definition with their next sync instead of waiting for the next policy signature.
  • Editing a script that jobs or sensors embed marks those jobs and sensors as changed.
  • An App Hub app of the source File from the file server is signed with its file name, the SHA-512 of the file, every argument field and the uninstall mode; the app shows them in the request, so the signer can compare the SHA-512 with the hash of a known copy of the installer (Get-FileHash -Algorithm SHA512, sha512sum, shasum -a 512). The device starts the file only when the downloaded bytes have exactly this SHA-512; a different file is refused with file_hash_mismatch.
  • A software deployment hands the app its items as one text, so packages, files, SHA-512 values, parameters and every install, uninstall and detection script are visible before signing; an item changed after signing is refused with payload_hash_mismatch.
  • A request for a definition that is saved again before the phone answered is marked superseded; sign again after the last save.
  • Anchored devices do not run SNMP sensors that discovery creates automatically.

A.13.5 Device states

StateTriggerEffect
Not anchoredno anchor fileRuns every definition.
Anchored, waitinganchor present, no valid keychain received yetThe device enforces with an empty keychain: no signed definition can verify, so the policy is empty (no jobs, sensors or apps). Inventory and sync keep running. An event of type 14 is written once an hour.
Anchored, activethe keychain of the trust line verifiedSigned definitions run, unsigned ones are removed from the policy and reported with event type 14.
Chain breakthe delivered keychain does not continue the trusted chainThe last valid chain stays in force, event type 14 names the reason.

Event type 14, Endpoint protection, carries the reason the agent decided on (missing_authorization, payload_hash_mismatch, not_in_policy, version_rollback, keychain_missing, …). The policy's agent settings have a block Endpoint protection that switches these notifications on and chooses the channels, like the antivirus notifications.

Two reasons are written on every Windows device, anchored or not: script_manifest_mismatch and script_missing. They concern the PowerShell scripts included with NetLock RMM (Windows Update, WSUS, Storage Spaces, DHCP, Terminal Server, Hyper-V and Exchange sensors), which ship as code-signed files under Program Files\0x101 Cyber Security\NetLock RMM\Comm Agent\Scripts. A script that was changed or removed is not started, and the event names the script. Reinstalling the agent (fix) restores the files.

A.13.6 The settings page

Settings → Endpoint protection (/settings/endpoint_protection, permission settings_endpoint_protection_enabled, actions with settings_endpoint_protection_manage) shows:

  • the trust lines: label of the trust line, the anchor prefix as reported by devices (nothing while no device reports it), keychain version, the signers with their roles, devices per state and the number of unsigned definitions with Sign all;
  • the number of devices that are not anchored;
  • my signer devices: the phones registered for the signed-in account, whether the keychain lists them, when they were last used, and Disable. Disabling stops the phone from answering requests for this account; removing it from the keychain is a separate keychain step in the app;
  • the setup hints: the app version that carries the signer, the installer parameter, and the reminder that the anchor is taken from the app only;
  • the active work sessions: the signed-in account's own, every account's with settings_endpoint_protection_manage, each with account, trust line, device count, classes and expiry, and End with signature or End on the console only (see A.13.9).

A.13.7 Operating rules

Endpoint protection is only as strong as the handling of the keys. Follow these rules:

  1. Sign every definition before you anchor devices. Use Sign all on the settings page, then roll the anchor out in steps, starting with a handful of pilot devices. Watch event type 14 on them before you widen the rollout.
  2. Keep the recovery key offline. It is the only way to add a new phone when every registered phone is gone. It must not be stored on the server, in the Console or in a share the server can reach.
  3. Compare the anchor. After the rollout, compare the first characters shown by the devices with the value the app displays. They must match; a difference means the installer received a different value.
  4. Read before you sign. The app shows the script text and the document. A request you did not trigger, or one that lists a device or a change you do not recognise, is rejected on the phone.
  5. Phones are personal. One account, one or more of its own phones. Shared accounts defeat the audit trail; the signed document records which key signed.
  6. Lost or replaced phone: disable the device on the settings page and remove its key from the keychain with another signer or the recovery key. Until the keychain version without the key has reached the devices, the key is still trusted by them.
  7. Several trust lines are possible (a second anchor with its own signers and protection level, for example for a high-security group or a customer who keeps their own phone). The Console lists them side by side; definitions are signed per line.
  8. Leaving endpoint protection means reinstalling the device without the anchor (a clean installation without the parameter) or deleting both anchor files locally as administrator or root. Running the installer in fix mode without the parameter keeps the anchor. Nothing on the server can switch it off remotely.

A.13.8 For the mobile console app

Use the current version of the NetLock app. Requests of the kinds grant and session show the action class, the devices with their names, the tenant and location, the requester, the validity and the details (the script, the user a shell runs as, the target of a tunnel); a session request additionally lists the classes it covers, the device count and the duration.

A.13.9 Approving remote actions and work sessions

On an anchored device the actions of a class the keychain signs need an approval as well. The Console asks a registered phone for a grant: a signed approval of one action class for the listed devices, the requesting account and a limited time. Before you approve, the phone shows the action, the devices, the requester, the validity and the details (script, shell user, tunnel target). Anchored devices refuse anything that differs and write event type 14.

Which classes need a grant follows the protection level of the trust line. Productive protects everything that can take over a device: scripts and remote shells, writing files, system changes (services, tasks, registry writes, clearing event logs), screen control, backstage and elevation, tunnels and NetMesh links, application and agent uninstalls, sensor live tests. Viewing a screen is part of screen control and needs the grant like controlling it. Strict also asks for power actions (restart, shutdown, lock, log off), patch runs, reading files (including the disk usage analyzer), the BitLocker key resync and audio calls, and allows no work sessions.

The Console asks at the point where the action is dispatched. A device without an anchor keeps the usual step-up authentication. So does an anchored device for an action whose class the protection level does not sign. A mixed selection (anchored and unanchored devices in one bulk action) runs the step-up once for the action and asks the phone for the anchored devices. For an interactive tool (remote shell, file browser, task manager, registry editor, disk usage, screen control, backstage) one grant covers the whole dialog. A classic shell command, a patch run, an uninstall or a sensor test is one grant per action.

Before the request goes to the phone, the Console offers three choices: only this action, a work session on this device, or a work session on the group (or on the selection, for a bulk action). The choice is remembered per account.

With a work session the phone signs one reusable document for the chosen devices, the classes the protection level allows a session for and a duration (default 4 hours, at most the keychain limit); until it expires, the Console attaches it to every matching action of the account and asks nothing more. An action on another device or of another class asks again.

The device details show Session active until HH:MM with Extend (a new session for the chosen hours; the Console stops using the old one) and End.

Start work session on the device details and Work session next to the bulk remote shell open the session dialog directly; the Work session button in the top bar of the Console opens the same dialog from any page with a tenant, location and group picker (each entry shows how many anchored devices it covers, and a badge on the button counts your active sessions). In the dialog a signer of the line can also start a session for another user: that account's actions use it, nobody else's.

There are two ways to end a session. End with signature asks the phone for a revocation; the listed devices receive it with their next contact (online devices right away) and stop accepting the session. End on the console only needs no phone: the Console stops attaching the session immediately, but the devices accept it until it expires. The dialog says so.

Whoever may run an action may ask for its grant; who may sign is decided by the keychain (role grants). An account without a registered phone has its requests routed to the signers of the line whose accounts may see the devices' tenants; the waiting dialog names them, the first signature wins. Grant requests expire after five minutes.

A work session lets the Console run matching actions of the account on its devices without a new approval until it expires. Keep work sessions short and scoped, or choose only this action or the protection level Strict. The Relay App cannot sign: a tunnel or a screen control session to an anchored device is approved on a registered phone (the app shows Confirm the approval in the NetLock app while it waits). Screen control from the apps is described in A.13.10.

Public API. Device actions of the public API (run-command, run-script, reboot, shutdown, uninstall-agent, patch-now, patch-uninstall, the file, registry, event log and process actions, sensor tests and discoveries) answer 409 ztep_grant_required for an anchored device whose keychain signs the class of the action. The API has no phone to ask; run such actions from the Console. Actions of classes the protection level leaves unsigned, sync and Wake on LAN keep working through the API.

A.13.10 Screen control from the Relay App and the NetLock app

Screen control is a signed class at both protection levels, so a session from the Relay App or the NetLock app to an anchored device needs a grant as well. Before the session starts, the app asks the server whether the device needs one. The grant is requested for the account that owns the relay key and covers the whole session, pasting files included. An active work session of that account that names the device and screen control covers it without a request, as in the console.

In the NetLock app.

  • When this phone signs grants for the device's trust line, the signing page opens right away in the app, without a push notification: "Screen control on this device needs an approval. Approve the request on this phone." After the fingerprint or face check the session starts.
  • Otherwise the app waits until another phone approves: "Approve the request on another phone." when the account has another registered phone, "Waiting for another person to approve it." when the request went to the approvers of the line.
  • A rejection, a request that nobody approved in time and a device that no phone may approve for are named in the viewer; start again to send a new request.

In the Relay App. The Relay App never signs. The request goes to the phone of the account that owns the key ("Confirm the approval in the NetLock app on your phone."), or to the approvers of the device when that account has no registered phone ("Waiting for an approver of this device to confirm the request in the NetLock app."). Cancel ends the attempt and closes the window. A device for which no phone may approve is reported as "No registered phone can approve screen control on this device."

Relay App versions older than 3.3.0.11 cannot request a screen grant; their sessions to an anchored device are refused.

When the server cannot check a device

When the server cannot check a device, for example while the database is not reachable, the action is refused and nothing is sent to the device. A device is never treated as unanchored because its data could not be read. The refusal says to try again: "The server could not check the device right now. Please try again in a moment." in the console, "The server cannot process the request right now. Please try again in a moment." in the Relay App and the NetLock app, 503 with temporarily_unavailable on the public API and the relay routes.

This applies to screen control, backstage, audio calls and tunnels, to the approval requests of the Relay App and the NetLock app, to the remote actions of the console, to tenant and location deletion, to work sessions and to device actions of the public API. During such an outage:

  • An approval request that is already open stays open and is not sent to the phone a second time.
  • The Relay App and the NetLock app keep asking while they wait for an approval instead of reporting that no phone can approve. They show the message above only when the waiting time runs out during the outage.
  • Ending a work session is stored only after the server has read the sessions it ends; otherwise the app gets an error and can try again.

A.13.11 Android devices

An Android phone or tablet with the NetLock RMM app supports endpoint protection like a desktop agent: the app holds an anchor, receives the keychain of its trust line with every sync and checks grants itself.

The Endpoint Protection card. The app shows a card Endpoint Protection with the state of the phone:

State on the cardMeaning
Off. Screen sessions need no approval from the NetLock App.No anchor; screen sessions need no approval.
Protected · waiting for the trust line …Anchored, no valid keychain yet: every screen session is refused.
Active · trust line …The keychain of the trust line verified; screen sessions need an approval.
Chain break · trust line …The delivered keychain does not continue the trusted chain; the last valid one stays in force.
The protection data cannot be read. …The anchor exists but cannot be read: screen sessions are refused until the enrollment is removed. Protection is never switched off this way.

The trust line is shown by the first 12 characters of its anchor.

Anchoring at enrollment. The anchor of a phone comes only from a code built in the NetLock app, never from the web console. On the anchor page of the NetLock app, the card Android phones builds the enrollment code for the tenant and location chosen above with the anchor of the line, as QR code and as text. The phone scans it in the NetLock RMM app instead of the code of the console's Mobile enrollment dialog; that dialog creates codes without an anchor and says so.

The card carries the same warning as the installation commands: do not pass the codes on through the web console or by e-mail. Anchored enrollment requires NetLock RMM app 3.3.0.11 or later. Update the app on the phone before it scans the code.

If the server refuses such an enrollment, nothing of the code is kept: the anchor it wrote is taken back with it (The protection in this code could not be stored, so the phone was not enrolled. when the anchor itself could not be stored).

Anchoring a phone that is already enrolled. The same card in the NetLock app shows a second code with the anchor alone. On the phone, Scan trust anchor code or Enter trust anchor code (paste the text form) on the Endpoint Protection card takes it; the card then says This phone is now protected by the trust line …. The phone accepts it only while it holds no anchor (This phone is already protected. The protection ends only when the enrollment is removed.) and only once it is enrolled. A trust anchor code is not an enrollment code; the enrollment field refuses it.

Re-enrolling an anchored phone. An enrollment code with the same anchor, or one without an anchor, re-enrolls the phone and keeps its anchor. A code with another anchor is refused as a whole, and nothing changes (This phone is protected by another trust line. Remove the enrollment first.).

Leaving. An anchor cannot be replaced or removed. Removing the enrollment in the app or clearing the app's data ends the anchor together with the enrollment; the phone is then enrolled again like a new device.

New phone. The app's data, the enrollment and the anchor included, is excluded from Android backups and from device-to-device transfer. A phone set up from a backup of another phone, or moved to new hardware, starts without enrollment and must be enrolled again (with an anchored code if it should be protected). It appears as a new device.

What needs a grant. Starting a screen session, for viewing as well as for control (A.7.12). The grant is of the class screen control, as for a desktop: a single approval from the viewer, or a work session whose classes include screen control and whose device list includes the phone. The phone checks the grant before it shows anything to its user, before the consent question; a refusal reaches the viewer at once with the reason and is written as an event of type 14. Locating the phone, letting it ring and sending it a message need no grant.

During a session. Input needs no grant of its own; it belongs to the session. The phone ends the session once the grant has expired or a revocation names it.

Keychain and revocations reach the phone right away where push is available, otherwise with its next sync. A phone in a screen session receives them within a few seconds, even without push; when a revocation names the grant of that session, the session ends at once.

States in the console. The phone reports its anchor, keychain version and state like a desktop agent, and the device lists show the same lock on its icon (see A.13.5).

Limits. The anchor is stored in the app's private storage. The compliance check of the device reports a phone that looks rooted.