16. Agent security

This chapter covers the controls that protect the agents themselves: self-protection, uninstall codes, the recovery key, agent tokens and the enrolment secret, and how agents follow a change of the server certificate.

16.1 How agents are protected by default#

Without any setting:

• The agent talks only to the server, over HTTPS, and checks the server certificate.
• Every command from the server is signed with the agent's own token. The agent refuses unsigned, altered, replayed, too old (over 10 minutes) or future-dated (over 60 seconds) commands.
• An upgrade is installed only if the vendor's signature and the file's SHA-256 verify. An older release cannot be pushed to weaken a host.
• The agent's token and settings are readable by root (Linux) or SYSTEM and Administrators (Windows) only.
• The watchdog keeps the agent running.

When the server runs HTTPS but some agents still talk to it over plain HTTP, Environment > Hosts shows a red banner: their tokens crossed the network unencrypted, and the token also signs the commands they run. Reinstall those hosts over HTTPS (Show the HTTPS install command) and remove the old enrolment.

16.2 Self-protection#

When self-protection is on for a host:

• the agent reports the hashes of its own program files every heartbeat; a file the server never released reads as tampering and raises a critical review item, with an Isolate this host action (four-eyes);
• the watchdog and the agent keep each other running and restore the program from the local known-good copy if it is deleted or changed;
• uninstalling needs a code issued in the console after a second signature (16.3), or the recovery key (16.4);
• a protected agent that goes silent without a shutdown notice raises an alert.

A host's own administrator can still remove any software. Self-protection makes it hard, repairs itself and alerts you; it is not a kernel driver.

Procedure: turn self-protection on#

Required permission: Manage agents. Four-eyes: no (it only adds protection).

1. Environment > Hosts, click the host.
2. In the drawer, under Self-protection, click Turn on.
3. What you see: "Saved. It takes effect when the agent next checks in and confirms it." The state shows Turning on - waiting for the agent to confirm, then On once the agent has saved it (normally within one heartbeat, 15 seconds).

If it stays "Turning on": the host is offline, or its agent is older than 1.5.9 and never reports protection. Check the host's status and version.

Tamper state in the drawer is ok, tampered or unknown (not protected or never checked). With protection on and tampering found, the panel shows "Tampering detected on this host. The agent repairs itself; investigate."

Procedure: turn self-protection off#

Required permission: Manage agents. Four-eyes: yes (critical action "Delete an agent"), because once off reaches the host, the agent can be removed with no code.

1. In the host's drawer, Self-protection > Turn off.
2. "Sent for approval. Turning protection off needs a second signature." Have it approved and execute it from Approvals > My requests > Execute now.
3. The state shows Turning off - waiting for the agent to confirm, then Off.

Risk: the host can then be uninstalled by any local administrator without a code. Rollback: Turn on again.

16.3 Uninstall codes#

A code authorises removing one protected agent. It is signed by the server, bound to that host, valid for one hour, and checked by the agent with no network.

Required permission: Delete agents. Four-eyes: yes.

1. In the host's drawer, under Self-protection (shown when protection is on), click Issue uninstall code.

2. "Sent for approval. Once someone else signs it, issue the code from Approvals." Have it approved; then Approvals > My requests > Execute now.

3. The code is shown once: "Code to uninstall this host (valid 1 hour, this host only)". Copy it.

4. Use it on the host within the hour:

   Platform	Command (as root / Administrator)
   Linux	sudo bash install_linux.sh --uninstall --code <code>
   macOS	sudo bash install_macos.sh --uninstall --code <code>
   Windows (script install)	powershell -NoProfile -ExecutionPolicy Bypass -File .\install_windows.ps1 -Uninstall -Code '<code>'
   Windows (MSI install)	put the code in a file and use msiexec /x {<product code>} LAWLIET_UNINSTALL_CODE_FILE=<file> /qn (chapter 12.7)

5. Remove the host in the console (chapter 10.7).

If it fails: "a valid host authorization code is required" - the code expired, is for another host, or was mistyped. Issue a new one. A host whose address changed since it last reported may not match the code: let it report once, then issue the code.

Command lines can be recorded by process auditing (Windows event 4688, Sysmon, Linux audit). Issue the code just before use; it expires after an hour. On Windows MSI installs, prefer the code file.

Issue stop code is also offered. In this release no host-side command accepts a stop code. To stop a protected agent, turn protection off (16.2) or uninstall it with an uninstall code.

16.4 The recovery key#

Each installation has one recovery key. It authorises removing any agent of this server, for example when the server is gone. It can be shown once; after that only its hash remains.

There is no console button for it in this release. An administrator reveals it through the API, once, right after installation, and stores it offline (a safe, a sealed envelope):

POST /api/v1/agents/protection/recovery-key/reveal

The call needs a signed-in administrator's session. If you need help making the call, contact [email protected]. A second call answers "The recovery key was already revealed. It cannot be shown again."

Never put it into a transform, a GPO or a script.

Procedure: remove a protected agent with the recovery key#

Use this only when an uninstall code cannot be issued (for example the server is gone). Risk: the key authorises removing any agent of this installation; anyone who sees it can. Rollback: reinstall the agent.

1. Fetch the key from where it is stored offline.

2. On the host, as root or Administrator, run the uninstall with the key:

   Platform	Command
   Linux	sudo bash install_linux.sh --uninstall --recovery-key <key>
   macOS	sudo bash install_macos.sh --uninstall --recovery-key <key>
   Windows	powershell -NoProfile -ExecutionPolicy Bypass -File .\install_windows.ps1 -Uninstall -RecoveryKey '<key>'

3. What you see: the installer removes the services and files, as in an ordinary uninstall (11.6, 12.9).

4. Clear the shell history on the host, and return the key to safe storage. If it may have been seen, treat it as exposed and tell support.

16.5 Agent tokens#

Each agent has its own token, issued at enrolment. It is not the enrolment secret.

After a revoke, a running agent that still knows the enrolment secret enrols again as the same agent within one heartbeat. A host enrolled from an offline package cannot re-enrol as that agent with its code, but could enrol as a new agent while the code is valid: also revoke the code.

16.6 The enrolment secret and enrolment codes#

The enrolment secret lets any host with the copy-paste command enrol.

sudo ./lawliet token            # show the secret and the install commands
sudo ./lawliet token --rotate   # replace the secret (asks first, restarts the backend)

Rotating does not affect enrolled agents; they use their own tokens. Only new installs need the new value. Rotate it after a rollout, and whenever it may have leaked.

Enrolment codes (offline packages and Group Policy rollouts) expire (at most 30 days) and enrol at most the chosen number of hosts. Every code made, downloaded, used and revoked is in the audit trail under enrolment_code.

Procedure: revoke an enrolment code#

Permission: Deploy agents remotely. Four-eyes: no (revoking takes risk away). Risk: none to enrolled hosts. Rollback: none; make a new package if more hosts must enrol.

1. Open Environment > Hosts > Install agent > Offline package.
2. Under Enrolment codes, find the code by its label, target, uses (for example 12/50), expiry and status.
3. Press Revoke and confirm "Revoke "<label>"? No further host can enrol with it, and its package is removed from the server. Hosts already enrolled are not affected."
4. What you see: the status becomes revoked.

Codes are never deleted; expired, exhausted and revoked codes stay in the list as a record.

16.7 When the server certificate changes#

An agent trusts exactly the certificate it was installed with. When the server certificate is replaced (./lawliet tls, ./lawliet tls repair, ./lawliet tls on), agents 2.1.9.s follow it without a step on the host:

1. The new certificate is staged: every heartbeat reply announces it, signed with this installation's trust key. The agent checks the signature and adds the certificate to its trusted file (the old one stays).

2. The command waits until the enrolled agents hold it, then the server switches:

   Option	Meaning
   --ack P	Switch when P percent of agents hold it (default 100)
   --timeout S	Wait at most S seconds (default 600), with progress every 10 seconds
   --force	Switch now, even if not every agent holds it

3. After the switch each agent checks the new certificate alone and removes the old one.

If not every agent holds it in time, nothing switches. The command lists the hosts that do not have it and offers: run it again to keep waiting, add --force, or withdraw it with sudo ./lawliet tls cancel.

Risk: agents that do not hold the new certificate stop reporting after the switch. Rollback: before the switch, sudo ./lawliet tls cancel; after it, refresh those hosts by hand (below).

By hand (agents older than 2.1.9.s, agents offline the whole time, macOS):

1. On the server: sudo ./lawliet tls --export. Copy lawliet-server.pem to the host.
2. On the host:

   Platform	Command
   Linux	sudo bash install.sh --refresh-ca --ca-cert /path/to/lawliet-server.pem
   Windows	powershell -ExecutionPolicy Bypass -File install.ps1 -RefreshCa -CaCert C:\path\to\lawliet-server.pem
   macOS	copy the file over /etc/lawliet/server-ca.pem, then sudo launchctl kickstart -k system/com.lawliet.agent

The refresh first checks the server with the new certificate and changes nothing if that fails. The agent keeps its identity; nothing is re-enrolled.

Upgrade agents to 2.1.9.s before replacing the certificate. The certificate commands are in chapter 6.

16.8 Removing every agent at the end of an engagement#

For an engagement licence, Settings > Platform shows Decommission all agents.

Required permission: Delete agents. Four-eyes: yes.

1. Export the evidence bundles and reports you need first.
2. Click Decommission all agents, enter a Reason, for the audit trail, and click Remove the agents.
3. After approval and execution: "Sent to N agents. Each removes itself at its next check-in."

Each agent stops, deletes itself from its host and is revoked. The records stay. It cannot be undone: a host would need reinstalling to report again.

16.9 Reporting a security problem#

Report a suspected vulnerability in the agent or the server as described on the security disclosure page. For any other help, contact [email protected].

More detail: agents reference, command security and upgrade channel.