Skip to main content

Agents

The agent runs on each machine you want to scan. It connects out to the server, so the machine needs no open ports and, once installed, no internet access.

Enroll a machine​

  1. In the dashboard, open Agents → Enroll a machine, check the address agents will use to reach the server, and click Create token. On the server's command line, deaconguard token create --server-url https://SERVER:8443 does the same.

  2. Run the command the dialog shows on the machine to scan:

    curl -fsSL https://get.deaconguard.io | DEACONGUARD_TOKEN=deaconguard1.… sh -

    The dialog's command pins the same version as the server.

  3. The machine appears on the Agents and Hosts pages. Scan it from the dashboard or with deaconguard scan HOST_ID on the server.

The enrollment token​

  • A token enrolls one machine, within 24 hours. Unused tokens can be revoked on the Agents page.
  • It contains the server's address and its certificate fingerprint, so the agent knows exactly which server to trust.
  • Run like this, the token ends up in the shell history. Once used it is worthless. To keep it out of the history anyway, run the command without DEACONGUARD_TOKEN=…, and paste the token when the script asks for it.
  • On a machine that already has DeaconGuard installed, sudo deaconguard setup agent asks for the token.

Automation​

For cloud-init, Ansible or golden images, give the token without a prompt:

# from the environment
curl -fsSL https://get.deaconguard.io | DEACONGUARD_TOKEN="$TOKEN" sh -

# from a file, readable by root only
curl -fsSL https://get.deaconguard.io | sh -s -- --agent --token-file /run/secrets/deaconguard-token

--force enrolls a machine again even if it is already enrolled.

Status and logs​

deaconguard agent status              # where it is enrolled
journalctl -u deaconguard-agent       # what it did

The agent checks in with the server every 25 seconds. The dashboard shows an agent as offline when it hasn't checked in for 90 seconds; scans you start for it wait up to an hour for it to reconnect.

Removing an agent​

Remove the host in the dashboard. That revokes the agent's credential at once, and the agent service stops. The credential is stored on the machine in /etc/deaconguard/agent.json, readable by root only.