Agent Tamper Protection

Tamper protection makes the Hermes agent hard to stop or uninstall on the machines you manage, and tells you when someone tries. While it is on, a local administrator cannot simply stop or delete the agent service, the agent's files are protected, and the only sanctioned local uninstall needs a single-use code that Athena issues for that one machine. Tamper attempts, uses of a code, and an agent that disappears right after either one show up on the Alerts board and in the audit log. Everything runs on your own server, so it works on an air-gapped network.

Turning it on#

1. Open Settings → Agents → Configuration.
2. In the Tamper Protection section, tick Enable tamper protection.
3. Click Save at the bottom of the page.

The change is pushed straight away to every connected agent. Agents that are offline pick it up the next time they connect, because the setting is sent on every connect. Each agent applies its protections once per change, so saving the page again does not re-run them.

To turn it off, clear the box and save. Each agent then removes its protections and goes back to its normal state (see the table below).

The setting is stored as Agent:TamperProtectionEnabled in the server's appsettings.json (see Configuration).

What it does on each OS#

Limits#

Tamper protection is a deterrent and an alarm, not a lock. Someone with full control of a machine can still remove the agent. For example, a Windows administrator can take back ownership of the install folder, disable the service in the registry, or run commands as SYSTEM. A Linux or macOS root user can clear the immutable flags. When that happens, the self-check and the Agent removed unexpectedly alert are what make the attempt visible.

How tampering is detected#

Agents report these events to Athena:

• Protection removed. While tamper protection is on, the agent checks every 5 minutes and each time it connects that its protections are still in place. On Windows it checks the service permissions. On Linux it checks the systemd drop-in and the immutable flags. On macOS it checks the immutable flags. If something was removed or changed, the agent reports it and applies the protections again. The Windows install-folder permissions are not part of this check. This check is paused for 10 minutes after a valid uninstall code is used, so it does not fight a sanctioned uninstall.
• Uninstall refused. Someone ran the uninstall command from an elevated prompt or as root, but it refused to run because the code was missing, invalid, expired or already used.
• Uninstall authorised. A valid uninstall code was accepted and the uninstall is going ahead.

If the agent is offline when an event happens, the event is queued on the machine. It is sent the next time the agent connects.

Uninstall codes#

An uninstall code authorises one uninstall of the agent on one machine. Each code:

• is signed by your Athena server's certificate authority. The agent checks it offline against the CA certificate it already trusts, so the machine does not need to reach the server to accept it. No reusable secret is stored on the endpoint.
• is valid only for the agent it was issued for. A code issued for another machine is refused.
• can be used once. The agent keeps a record of the codes it has accepted and refuses a code it has already seen.
• expires, by default 60 minutes after it is issued. The machine checks the expiry against its own clock.

You only need a code while tamper protection is on. With protection off, the uninstall command runs without one.

Issuing a code in the console#

1. Open the agent's Agent Details page.
2. In the header, click the shield icon ("Issue a single-use uninstall code for this agent (needed only while tamper protection is on)"). It sits next to the revoke icon.
3. Confirm with Issue code. The dialog warns that whoever holds the code can uninstall the agent on that machine until it expires.
4. The code is shown once, with its expiry time. Copy it with the copy icon. When you close the dialog, it cannot be shown again. Issue a new one if you lose it.

Issuing a code requires the agents.revoke permission, which only the built-in Admin role has. Without it, the shield icon is hidden. The icon is also hidden on a revoked agent. Every issued code is audited. The code itself is never written to the audit log; it is identified by its last four characters only.

Uninstalling a protected agent#

The sanctioned local uninstall is the uninstall command of the HermesCLI, which every agent places next to itself. Run it from an elevated (Administrator) prompt on Windows, or as root on Linux and macOS:

hermescli uninstall --code <CODE> [--purge]

hermescli is on the PATH on every OS (see HermesCLI on PATH). You can also call the CLI by its full path:

The command checks whether the machine is protected by looking at the protections themselves. If they are in place, it removes them first, then removes the agent. Before it removes anything, it prints the list of what it will remove.

What is removed#

If the agent's Agent:DataPath is set in the install folder's appsettings.json, that folder is used as the data folder. The hermescli PATH entry (Windows) or the /usr/local/bin/hermescli link (Linux, macOS) is removed as well.

On Windows the removal runs as SYSTEM through a one-time scheduled task, because the protected service cannot be stopped by Administrators. The command returns straight away and prints "The service is being stopped and removed as SYSTEM; the files above are gone within ~15 seconds."

How Athena learns about it#

The command hands the event (authorised or refused) to the running agent service, and waits up to 5 seconds for the agent to send it to Athena. It prints "Athena notified (…)" when the event was sent. If the agent is not running or not connected, it prints "Athena not notified yet …" and continues. The event then stays queued in the data folder unless --purge removes it. An uninstall on an unprotected machine without a code is not a tamper event and is not reported.

Messages and exit codes#

Any non-zero exit code other than 1 means nothing was removed.

An agent enrolled with more than one server accepts a code issued by any of them.

Alerts#

Tamper events raise alerts on the Alerts board, tied to the agent. They count in the agent's alert badge and can be filtered by agent like any other alert. One alert is kept per agent and condition: a repeat event updates the existing open alert (its count and last-seen time) instead of adding a new row.

Agent removed unexpectedly is raised only for an agent that has just reported a tamper event or a code use, so a normal reboot or shutdown never raises it. It fires when the agent's last heartbeat falls within 15 minutes of the event and the agent has then been offline for at least 10 minutes. A machine that reboots and comes back within those 10 minutes does not raise it. After a valid code it is only a Warning, because a sanctioned uninstall looks the same. The watch for this alert is kept in memory, so if the Athena server restarts during that window, the alert is not raised. The tamper alert itself is not affected. Removing the agent from Athena also ends the watch.

Audit events#

These event types appear in the audit log:

Configuration#

These keys go in the server's appsettings.json, or in environment variables using __ for : (for example Tamper__UninstallCodeTtlMinutes=30). See Configuration.

REST API#

Codes can also be issued over the REST API (see API Reference and API Tokens). The response uses Athena's usual envelope, with the result in data.

curl -k -X POST -H "Authorization: Bearer <token>" \
  "https://<server>:8443/api/agents/<agent-id>/uninstall-code?ttlMinutes=30"

PowerShell#

The Athena PowerShell module has New-AthenaAgentUninstallCode. It asks for confirmation unless you pass -Force. The returned Code is sensitive.

Get-AthenaAgent -Hostname "LAB-PC" | New-AthenaAgentUninstallCode -TtlMinutes 30

Troubleshooting#

Related#

• Agent CLI (HermesCLI): the local command-line tool that runs the uninstall.
• Remote Helper & HermesCLI Binaries: how the CLI reaches each agent.
• Retiring & Removing Agents: revoking and removing agents from Athena.
• Monitoring & Alerts: the Alerts board.
• Audit Event Types Reference: all audit events.
• Permission Model & Role Bundles: who holds agents.revoke.