Ctrlk
Changelog NotificationsAPIAikido login
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Deploy Device Protection with cloud-init

cloud-init runs on the first boot of a new machine, which makes it the simplest way to have Device Protection installed before anyone logs in. It works anywhere cloud-init does: AWS, Azure, GCP, OpenStack, Proxmox, and plain libvirt images.

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

The user data document

The agent is not published in a distribution repository, so the packages: module cannot install it. Download the package and install it from runcmd.

user-data
#cloud-config
runcmd:
  - curl -fsSLo /tmp/aikido.deb https://github.com/AikidoSec/safechain-internals/releases/latest/download/EndpointProtection-amd64.deb
  - AIKIDO_TOKEN=<your-token> apt-get install -y /tmp/aikido.deb
  - rm -f /tmp/aikido.deb
user-data
#cloud-config
runcmd:
  - curl -fsSLo /tmp/aikido.rpm https://github.com/AikidoSec/safechain-internals/releases/latest/download/EndpointProtection-amd64.el9.rpm
  - AIKIDO_TOKEN=<your-token> dnf install -y /tmp/aikido.rpm
  - rm -f /tmp/aikido.rpm

Use the el10 package on version 10.

The package enables and starts the aikido-endpoint-protection service itself, so there is nothing to add for that.

One document covers one image family, one architecture, and on Red Hat-family images one major version, because the package name differs for each. Keep a document per image rather than adding detection logic to runcmd.

Keep the token out of the user data

Instance user data is readable from the instance metadata service by anything running on the machine, and cloud-init writes the commands it runs to /var/log/cloud-init-output.log. A literal token in runcmd is therefore readable by any local user.

For anything beyond a quick test, give the machine an identity that can read your secret store and fetch the token at boot:

user-data
#cloud-config
runcmd:
  - curl -fsSLo /tmp/aikido.deb https://github.com/AikidoSec/safechain-internals/releases/latest/download/EndpointProtection-amd64.deb
  - |
    AIKIDO_TOKEN=$(aws ssm get-parameter \
      --name /aikido/device-protection-token \
      --with-decryption \
      --query Parameter.Value \
      --output text)
    export AIKIDO_TOKEN
    apt-get install -y /tmp/aikido.deb
  - rm -f /tmp/aikido.deb

Swap the lookup for your own cloud: az keyvault secret show with a managed identity, or gcloud secrets versions access with a service account.

Know what runs when

runcmd only fires on the first boot. Changing the user data does nothing to machines that are already running, so treat it as image configuration rather than a way to manage a fleet. For machines that already exist, use Ansible, Chef, or Puppet.

runcmd also runs late in the boot, which matters for the Aikido CA environment variables the install sets system-wide. Logins after boot pick them up. Services that started earlier in the same boot, such as a container runtime or a build agent, do not. If the machine runs those, add power_state to the document so it reboots at the end of the first boot:

Verify the rollout

On a new machine:

If the install failed, /var/log/cloud-init-output.log has the package manager output. The device appears 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

Last updated

Was this helpful?