Skip to content
Garrison AI

Linux systems

The Garrison agent is a single program that runs as a system service. It connects out to the appliance over TLS on port 8080, so the system needs no inbound port and no SSH access from the appliance.

Requirements

Section titled “Requirements”
  • Linux with systemd, on x86-64 or ARM64 (Ubuntu, Debian, RHEL and derivatives, Arch, DGX OS).
  • sudo on the system, once, for the installation.
  • The system can reach https://<appliance>:8080.

Install

Section titled “Install”

  1. In the console, open Systems and click Add system.

  2. Choose Linux. The console shows a one-line command with a short-lived install token:

    Add a system: the one-line install command

  3. Choose how long the token stays valid: 15 minutes, 1 hour (default) or 1 day. One token can enrol several systems until it expires.

  4. Run the command on the system:

    Terminal window
    curl -fsSLk --pinnedpubkey 'sha256//<appliance-key-pin>' https://<appliance>:8080/api/agent/install.sh \
      | sudo bash -s -- --token <install-token> --install-ca

The system appears in Systems as online within a few seconds.

What the command does

Section titled “What the command does”
  • Checks it is talking to your appliance. --pinnedpubkey makes curl accept only the appliance’s own key, so a machine in the middle cannot hand out a different installer, even before the appliance’s certificate is trusted.
  • Installs the agent in /opt/vclocal/ and the garrison-agent systemd service.
  • With --install-ca, adds the appliance’s CA to the system’s trusted certificates, so later connections are verified normally.
  • Registers the system. The install token is exchanged for the system’s own credential, stored in a root-only file (/opt/vclocal/agent.env, mode 600), never on the command line.

The install token can only enrol new systems. It cannot take over a system that is already enrolled, and it expires.

After enrolment

Section titled “After enrolment”

Open the system from Systems to:

  • Tag it: Crown jewel (alerts on it rank higher), Hunt target (included in hunts), Scan allowed (authorized for attack-surface scans), Internet facing, Netflow capture, or your own tags such as #prod. Tags scope chats, hunts and scheduled jobs.
  • Assign a role: see System roles. The Log collector role sends the system’s logs and metrics to Observe.
  • Ask Garry about it, or open a terminal (owners only; every session is audited).

A system’s details: roles and tags

Machines cloned from one image

Section titled “Machines cloned from one image”

Machines built from the same image often share a machine ID (DGX OS does). Garrison registers each one as its own system and, when the name is taken, adds a short suffix (web-01-3f2a).

Remove

Section titled “Remove”

Delete the system in the console (this revokes its credential at once), then remove the agent: see Uninstall.