Deploy Device Protection in Golden Images

If you build your own Linux images with Packer, or any other image pipeline, install Device Protection during the build. Every machine created from the image is then protected from its first boot, with no install step at runtime.

Read Deploying on Linux first for the token, the package list, and the reboot behaviour that applies to every method.

Baking the agent in

You can install the package and register it during the build, and nothing has to be deferred to first boot. What does need care is device identity: on Linux it follows /etc/machine-id, so an image that ships a machine ID gives every machine cloned from it the same identity. Clear the file at the end of the build and each machine generates its own on first boot, as described under Two things to get right.

Install during a Packer build

workstation.pkr.hcl

variable "aikido_token" {
  type      = string
  sensitive = true
}

build {
  sources = ["source.amazon-ebs.workstation"]

  provisioner "shell" {
    environment_vars = [
      "AIKIDO_TOKEN=${var.aikido_token}",
    ]
    inline = [
      "curl -fsSLo /tmp/aikido.deb https://github.com/AikidoSec/safechain-internals/releases/latest/download/EndpointProtection-amd64.deb",
      "sudo AIKIDO_TOKEN=\"$AIKIDO_TOKEN\" apt-get install -y /tmp/aikido.deb",
      "rm -f /tmp/aikido.deb",
      "systemctl is-enabled aikido-endpoint-protection",
      "sudo truncate -s 0 /etc/machine-id",
    ]
  }
}

Pass the token in from your secret store rather than a .pkrvars.hcl file, for example PKR_VAR_aikido_token=$(...) packer build .. Marking the variable sensitive keeps it out of Packer's output.

The systemctl is-enabled line fails the build if the service did not get enabled, which is the check you want: a broken image is much more expensive to find later. Truncating /etc/machine-id comes last, so every machine built from the image gets its own device identity.

Two things to get right

Give every machine its own machine ID. Machines that boot with the same /etc/machine-id share a single entry in your device list, so you lose visibility on all but one of them. Truncate the file as the last step of the build, which is what image pipelines do anyway, and systemd writes a fresh ID on first boot:

sudo truncate -s 0 /etc/machine-id

Remove the build machine from your device list. The instance Packer builds on registers itself during the install, and it disappears when the build finishes. Delete that entry so it does not sit in your list as an inactive device. See Removing a device.

One image, one user group

The token selects the Aikido user group the device joins, so a baked image belongs to one user group. If one image has to serve several groups, keep the token out of it and stage only the package file:

workstation.pkr.hcl

provisioner "shell" {
  inline = [
    "sudo mkdir -p /var/cache/aikido",
    "sudo curl -fsSLo /var/cache/aikido/EndpointProtection-amd64.deb https://github.com/AikidoSec/safechain-internals/releases/latest/download/EndpointProtection-amd64.deb",
  ]
}

Then install from the staged file on first boot, with the token of the group that machine belongs to:

user-data

#cloud-config
runcmd:
  - AIKIDO_TOKEN=<your-token> apt-get install -y /var/cache/aikido/EndpointProtection-amd64.deb

First boot then needs no network access to GitHub. See cloud-init for the rest of that document, including how to fetch the token from a secret store instead of writing it in the user data.

Keep images current

Images pin whatever version was current at build time, so an old image keeps producing machines on an old agent. Rebuild on your normal image cadence. For machines already running from an older image, install the newer package over the existing one, which keeps the device's registration and needs no token. See Upgrading.

Verify the image

Boot one machine from the finished image and check:

cat /etc/machine-id
systemctl is-active aikido-endpoint-protection
aikido-doctor version

Boot a second machine from the same image and confirm the two machine IDs differ, and that both appear in your device list with an Active status.

Troubleshooting

Problem	Fix
The package installs but the device never appears in the dashboard	AIKIDO_TOKEN was not set for the install command. Configuration management tools do not forward your local environment to the host, so set the variable on the task itself, then install the package again
apt or dnf looks for the package in your repositories instead of installing the file	Pass a path, not a name: apt install ./EndpointProtection-amd64.deb. The leading ./ is what makes the package manager treat it as a local file
The install fails on a Red Hat-family host	Match the build to the major version: use the el9 package on version 9 and the el10 package on version 10
The service is not running	Run systemctl status aikido-endpoint-protection, then sudo aikido-doctor diagnostics to send us the details
Node.js or uv still reject the Aikido certificate	Installing sets NODE_EXTRA_CA_CERTS and UV_SYSTEM_CERTS system-wide, and running shells do not pick them up. Open a new login shell or reboot the device
The token shows up in run output or logs	Use your tool's redaction: no_log in Ansible, sensitive true in Chef, Sensitive() in Puppet
Several machines share one entry in the device list	They booted with the same /etc/machine-id. Device identity on Linux follows that file, so clear it in the image you clone from and let systemd write a fresh one on first boot
No tray icon appears	Expected on GNOME outside Ubuntu, and cosmetic. See Tray Icon Support on Linux