Agent Server Trust (CA Pinning)

Every Hermes agent checks that it is talking to your Athena server before it sends a registration token, inventory, or accepts a command. It does that by pinning your server's Root CA: once an agent holds that CA, it accepts the agent-port (8444) certificate only if it was issued by that exact CA. This page explains how the CA gets onto an agent, how to supply it when you install from the release MSI or Linux tarball, what the agent refuses, and how to fix an agent that will not connect. It all works offline, on an air-gapped network.

What the agent checks#

The pinned CA is stored per server, as servers\<name>\ca.crt in the agent's data folder (<name> is the server entry's name, primary for a normal install):

When the agent connects to the agent port (8444), it decides like this:

In every case, a certificate issued for a different host name than the one in the server URL is refused. Revocation is not checked against the Athena CA, because it publishes no revocation list and agents may be offline.

When an agent registers, the server's answer includes its CA. If no CA is pinned yet, the agent saves it. If one is pinned and the answer carries a different CA, the agent refuses the answer and saves nothing (see When the CA changes).

Getting your server's CA certificate#

The Root CA certificate is public (it holds no key), and the server hands it out without signing in:

curl -k -o athena-root-ca.crt "https://<server>:8443/api/pki/ca/download?format=pem"

Fetch it once from a machine you trust and copy the file to where you install, rather than downloading it on each endpoint with certificate checks off. With PowerShell, Save-AthenaCACertificate does the same (see Certificates & PKI).

Which install methods pin the CA for you#

Silent MSI install with the CA#

From an elevated prompt:

msiexec /i Hermes.Agent-<version>-windows-x64.msi /quiet ^
  SERVER_URL="https://<server>:8444" ^
  REGISTRATION_TOKEN="<registration-token>" ^
  CA_CERT="C:\path\athena-root-ca.crt"

During the install, before the service first starts, the MSI runs HermesCLI to write the server entry into the agent's appsettings.json, save the CA as servers\<SERVER_NAME>\ca.crt and set ValidateServerCertificate to true. So the very first connection is already checked against your CA. If CA_CERT is not a CA certificate, the install fails and rolls back instead of leaving an agent that trusts the wrong thing.

Linux tarball install with the CA#

The release tarball includes install.sh. Extract it and run, as root:

sudo ./install.sh --server https://<server>:8444 --token <registration-token> --ca-cert ./athena-root-ca.crt

The script installs to /opt/hermes, saves the CA as /var/lib/hermes/servers/primary/ca.crt and writes the server as primary.

Pinning the CA on an installed agent#

Use HermesCLI from an elevated prompt (or as root) to set or update a server entry and pin its CA, then restart the agent:

hermescli config server add --name primary --url https://<server>:8444 --ca-cert C:\path\athena-root-ca.crt --replace
hermescli service restart

On success the output lists the entry and a line CA: with the CA's thumbprint, followed by "(pinned; server certificate validation on)". Compare that thumbprint with the one shown in Settings → Security → Certificate on your server.

When the CA changes#

The pinned CA is also what the agent uses to check signed agent updates and uninstall codes, so the agent never lets a server swap it:

• A registration answer that carries a different CA is refused, and nothing is saved.
• A server migration in Mint mode keeps the same CA: the new address must present a certificate from the CA the agent already trusts. A migration in Paste mode adds a new server entry, which gets its own pinned CA when it registers.
• If you regenerate your server's CA, agents that pinned the old CA refuse the server's new certificate and stop connecting. Pin the new CA on each one with config server add … --ca-cert … --replace (or reinstall with a one-line installer), and re-enrol them. Prefer Extend over Regenerate: extending keeps the same CA.

Agents installed with validation off#

Older release packages shipped with ValidateServerCertificate set to false, and an agent update replaces only the program, not appsettings.json. You do not need to change those agents: once they are on the versions above, any agent that already registered holds its server's CA and enforces it, whatever its appsettings.json says. Only an agent that has never registered still accepts any certificate on first contact.

Package and update downloads (Windows)#

Windows agents download deployment packages, agent updates and Windows Update files from the web port (8443). That port may legitimately use a certificate from your own PKI or a public CA (see Server TLS Certificate), so for these downloads the agent accepts a certificate that chains to any pinned Athena CA or one the operating system trusts. It never accepts any certificate, and never one issued for another host name. A deployment package is also checked against the SHA-256 the server sends over the pinned agent channel; a package without that hash fails instead of running.

Troubleshooting#

Agent messages appear in the agent log.

Related#

• Certificates & PKI: the Root CA, agent certificates, extend vs. regenerate.
• Agent Enrollment: one-line installers that pin the CA for you.
• Agent CLI (HermesCLI): all config server commands.
• Agent Configuration File: ValidateServerCertificate and the server list.
• Agent Server Migration: moving agents to a new address or server.
• Network Ports & Firewall: ports 8443 and 8444.