10. Agents: what they are and how they are managed

This chapter explains the Lawliet agent: what it does on each operating system, how it talks to the server, how you see it in the console, and how it is upgraded. The chapters that follow give the install procedures:

10.1 What the agent is#

The agent is a small compiled program that runs on each monitored host. One agent per host. It enrols once with the server, then sends a heartbeat every 15 seconds. The heartbeat carries the host's health and collects any work the server has for it.

The agent version in this release is 2.1.9.s.

The watchdog checks that the agent is running and starts it again when it is not. It also restores the agent program from a known-good local copy if the program file is deleted or changed.

The compiled agent needs no Python, no package manager and no internet access. The only thing a host must reach is the Lawliet server. This is what makes the agent suitable for an air-gapped site. A Python version of the agent exists as a fallback, used only when the server has no compiled agent for the host's CPU, or when you ask for it (--python). The Python fallback needs python3 and access to a Python package mirror.

10.2 What the agent does#

The agent reports which modules it supports on that host as Capabilities (FIM, FIM real-time, FIM attribution, DLP). The server sends DLP or FIM work only to hosts that report the capability.

10.3 How the agent talks to the server#

• Direction. Always from the host to the server. The server never opens a connection to an agent. Open one port from the hosts to the server: 443/tcp in HTTPS mode (or the port the server was installed on), 8000/tcp in plain-HTTP lab mode.
• Encryption. HTTPS. The agent checks the server certificate. For a server with a self-signed certificate, the installer is given the certificate file (--ca-cert or -CaCert) and the agent trusts exactly that certificate.
• Identity. At enrolment the server gives the agent its own token. The token is stored on the host (/etc/lawliet/agent.conf on Linux, C:\ProgramData\Lawliet\agent.conf on Windows) and is not the enrolment secret.
• Commands. Every command the server sends is signed. The agent refuses a command that is unsigned, altered, more than 10 minutes old or more than 60 seconds in the future. This is why host clocks matter (see 10.6).

How a host gets enrolled#

A host can enrol in one of three ways. The console shows all three under Environment > Hosts > Install agent.

Windows domains have a fourth way, the Windows MSI for Group Policy. It is an offline package made for Group Policy; see chapter 12.

The enrolment secret is shown by ./lawliet token on the server. After an agent enrols and saves its own token, it removes the secret from its configuration file.

10.4 The Environment page#

Environment > Hosts is the fleet list.

Required permission: View agents.

What you see:

• Tiles: Total agents, Online, Offline, Error, Updating. Online counts only hosts that sent a heartbeat recently.
• Host clocks strip: the fleet's clock status and the host furthest from the server's time.
• Filter box (name, host, IP, platform) and status buttons: All, Online, Offline, Error, Updating.
• Table columns: Host, Platform / OS, IP address, Status, CPU, Memory, Disk, Capabilities, Last heartbeat, Clock, Version.
• Under the host name, a chip shows the domain membership: standalone, member <domain> or DC <domain>.
• A red banner at the top when some agents still talk to the server over plain HTTP while HTTPS is on. It lists the hosts and offers Show the HTTPS install command. Reinstall those hosts over HTTPS.

The page refreshes every 15 seconds.

The agent drawer#

Click a row to open the agent's drawer. It shows:

Agent status values#

CPU, Memory and Disk come from the last heartbeat. When that sample is old, the meter is grey and marked old.

10.5 Agent configuration on the host#

The installer writes the configuration. Change it only when support asks you to.

Settings in config.env:

Reinstalling the agent on the same host keeps agent.conf, so the host keeps its identity and history.

Procedure: change a setting in config.env#

Risk: a wrong server address or certificate path cuts the host off from the server. Rollback: put the previous value back and restart the agent.

1. If self-protection is on, turn it off first (16.2); otherwise the watchdog may restore the files.
2. As root (Administrator on Windows), edit the settings file for the platform (table above). Keep a copy of the original.
3. Restart the agent: sudo systemctl restart lawliet-agent (Linux), sudo launchctl kickstart -k system/com.lawliet.agent (macOS), Stop-ScheduledTask -TaskName LawlietAgent; Start-ScheduledTask -TaskName LawlietAgent (Windows).
4. What you see: the host shows online under Environment > Hosts within a minute, with a fresh Last heartbeat. If it goes offline, read the agent log (table above) and undo the change.
5. Turn self-protection on again.

10.6 Host clocks#

Each heartbeat carries the host's time, so the server knows how far each host's clock is from its own. The Clock column shows a chip such as clock +7m 12s.

Fix the clock with NTP on the host, then check the Clock chip:

1. Run the command for the platform below (as root or Administrator).
2. What you see: within a heartbeat or two the chip returns to ok. If it does not, point the host at your organisation's time source and run the command again.

sudo timedatectl set-ntp true        # Linux (or point chrony at your time server)

w32tm /resync                        # Windows

10.7 Removing a host from the console#

Removing the record in the console does not uninstall the agent. Uninstall it on the host first (chapters 11 and 12), otherwise the host enrols again.

Required permissions: Manage agents and Delete agents to remove or delete; Manage agents alone to revoke the token. Four-eyes: yes (critical action "Delete an agent") for Remove and Delete it and its records; no for Keep the records: revoke its token, which runs at once.

1. Open Environment > Hosts and click the host.
2. In the drawer, under Remove agent, click Remove agent.
3. The console shows what records the agent still has.
   • "It has no records. Remove it?" -> click Remove.
   • "It still has N records: ..." -> choose:
     • Delete it and its records - removes the agent and its FIM events, DLP incidents, scans and forensic records. This cannot be undone. It is written to the audit trail with the row counts.
     • Keep the records: revoke its token - the agent can no longer report, the records stay. You see "Token revoked. The records are kept; a reinstall on this host enrols as this agent again."
4. For a removal or deletion with dual control on, the console says "Sent for approval. Removing an agent needs a second signature; run it from Approvals once signed." A second administrator approves it under Approvals > Waiting for me. You then run it from Approvals > My requests > Execute now (see chapter 15).

What you see: "Agent removed." and the host leaves the list.

If it fails: a 409 message lists the tables that still hold records. Choose one of the two options above.

When to use what:

10.8 Agent versions and upgrades#

Environment > Agent versions shows what the fleet runs and the signed releases it can move to.

Required permissions: Manage agents to view; Publish agent releases to import, register, publish and roll out. Four-eyes: yes for Publish, single-host upgrade and rollout (critical action "Publish an agent release").

Upgrades are off by default. They need two server settings in .env:

After changing .env, run sudo ./lawliet start (a restart does not re-read .env). The page shows a banner when either is missing: "The agent upgrade channel is off" or "No release public key is configured".

Procedure: upgrade agents on an air-gapped site#

Risk: an agent upgrade replaces the program on each host. Rollback: each agent keeps its previous program and restores it if the new one does not report in; to go back across the fleet, roll out the older release (the API's force option allows a downgrade).

1. Update the server to the new bundle (chapter 4). The bundle carries the signed compiled agents.
2. Open Environment > Agent versions and click Import bundled agents. Each agent binary's signature is checked against the release key. Each becomes a draft release. What you see: a "Bundled agents" result listing what was imported and what was skipped, with the reason.
3. In the release catalogue, click Publish on the release. With dual control on, a second administrator approves it, and you run it from Approvals.
4. Check Upgrade candidates. Each host shows ready or the reason it cannot move (already current, offline, mid-upgrade, below the minimum version).
5. Click Roll out 10. At most ten eligible hosts get the upgrade. The result lists every host it skipped and why. To upgrade a single host, use Upgrade to <version> on its row.
6. Watch Upgrade history. States: pending, downloading, verifying, applying, succeeded, rejected, failed, rolled_back.
7. Repeat Roll out 10 until every host is current.

If it fails:

Procedure: register a release by hand#

Use this only for a build that did not come inside a server bundle (for example a release the vendor sent separately). Bundled builds are imported with Import bundled agents instead.

Permission: Publish agent releases. Four-eyes: no to register a draft (a draft reaches no host); yes to publish it.

1. Open Environment > Agent versions and press Register a release (disabled with "The upgrade channel is disabled on this deployment" until AGENT_AUTO_UPGRADE_ENABLED is on).

2. Fill the form:

   Field	What to enter
   Version	For example 2.1.0
   Platform	The operating system the build is for
   Build	Python script (every architecture) or Compiled binary (then Architecture)
   Host it on this server	Tick for air-gapped sites; you upload the file after registering. Untick to give a Download URL (HTTPS) instead
   SHA-256	The file's digest, 64 hexadecimal characters
   Release signature	The base64 Ed25519 signature over the digest, made offline with the release private key
   Minimum version to upgrade from	Optional. Hosts below it step through an intermediate version
   Channel	stable, or canary to keep it out of the stable selection while you try it on a few hosts
   Release notes	What changed

3. Press Register as draft.

4. With Host it on this server, press Upload artefact on the new row and choose the file. The server checks it against the SHA-256.

5. Continue with Publish and the rollout (steps 3-7 above).

If it fails: the form or the notice names the problem, for example a digest or signature that does not verify against the release public key.

Procedure: upgrade one host, stop a rollout, retire a release#

1. One host: in Upgrade candidates, press Upgrade to <version> on a row marked ready. Four-eyes: yes.
2. Stop a rollout: press Unpublish on the release. No new host is sent it; upgrades already running finish. Publish makes it available again (four-eyes).
3. Retire a release: press Delete on an unpublished release and confirm "Delete release <version>? Upgrade history is kept." This cannot be undone; register or import it again if needed.

Upgrade agents to the new version before you replace the server certificate: an agent 2.1.9.s learns the server's trust key with its first heartbeat and only then can follow a certificate change by itself (chapter 16).

Re-running an installer on a host is also an upgrade: it replaces the program in place and keeps the host's identity. If anything fails, the installer puts the previous program back.

10.9 If a host does not appear or goes offline#

Work through the checks in this order; stop at the first one that fails and apply its fix. What you see when it is fixed: the host is online in Environment > Hosts.

The installers check the server before installing anything and print one plain verdict:

More detail: Agents reference.