Deploying on Linux

On Linux, Device Protection ships as a plain .deb or .rpm package, so any tool that can copy a file and run a package manager can install it. If your MDM manages Linux devices, push the install command through it as a script. Otherwise, use the configuration management or provisioning tool you already run.

This page covers what every method needs. The guides below cover the tool-specific parts.

Which method to use

Situation	Use
Existing fleet, agent checks in on a schedule	Chef or Puppet
Existing fleet, you push over SSH	Ansible
New cloud instances	cloud-init or Terraform
Machines built from an image you control	Packer and golden images
Container images for CI or build jobs	Device Protection in Containers

Device Protection secures the machines your developers work on. To scan servers for vulnerable packages instead, use VM Scanning.

What you need

• A user group token. Go to Device Protection, click Connect Device, choose Manual install, and select the user group the devices should join. The token is part of the install command shown there.
• systemd and root access on every target host. See Supported Ecosystems for the distributions and versions we support.

The packages

All packages live under https://github.com/AikidoSec/safechain-internals/releases/latest/download/.

Distribution family	Package
Debian, Ubuntu	EndpointProtection-amd64.deb, EndpointProtection-arm64.deb
RHEL, Rocky Linux, CentOS 9	EndpointProtection-amd64.el9.rpm, EndpointProtection-arm64.el9.rpm
RHEL, Rocky Linux, CentOS 10	EndpointProtection-amd64.el10.rpm, EndpointProtection-arm64.el10.rpm

Pick the architecture from uname -m: x86_64 means amd64, aarch64 means arm64. On Red Hat-family hosts, match the el suffix to the major version.

latest always resolves to the newest release, so your automation installs whatever is current whenever it does download. To decide yourself which version the fleet gets, copy the package to your own artifact repository or package mirror and point your automation at that copy.

How the token reaches the package

The package reads the AIKIDO_TOKEN environment variable while it installs, and that is the only moment it needs it. Registration and configuration survive upgrades, so a later run that installs a newer package does not need the token again.

Your tool has to set the variable in the environment of the process that runs apt or dnf on the host. Setting it in your own shell, or in the CI job that starts the run, does nothing.

Pick the flavor for the host

There are three flavors, and the package installs the desktop one unless you say otherwise. Set the flavor's variables in the environment of the process that runs apt or dnf, next to AIKIDO_TOKEN.

• Desktop. A laptop or workstation somebody works on.

  • Nothing to set.
  • The install pulls in GTK and WebKit as recommended packages and the user gets a tray icon.
• Server or VM. A build server, a CI runner, a Docker or Kubernetes host, a cloud VM developers only SSH into.

  • Set AIKIDO_HEADLESS=1.
  • Skip recommended packages so the tray and the desktop libraries stay off the host: --no-install-recommends on the Debian family, --setopt=install_weak_deps=False on the Red Hat family.
• Container image. The agent running inside a container, installed while the image is built.

  • Set AIKIDO_CONTAINER=1 and AIKIDO_CI_CD=1, because packages up to 1.8.2 read only the older name.
  • Skip recommended packages the same way, and add the container entrypoint. See Device Protection in Containers.
  • This one goes on the image, not on the Docker or Kubernetes host that runs it. That host is a server.

Protection is the same on a desktop and on a server, and so is the reboot. The container flavor also switches the datapath, which is why it has its own page.

Map your groups to Aikido user groups

Each token belongs to one user group, so you can hand different hosts different tokens: one per Ansible inventory group, Chef role, or Hiera scope. Devices land in the matching Aikido user group, which gives you separate installation policies per group and lets you roll out to a pilot group first.

Keep the token out of your repository

The token is a credential. Store it with the secret handling your tool already has, and turn on its redaction so the token stays out of run logs.

Tool	Store it in	Redact with
Ansible	Ansible Vault	no_log: true
Chef	Encrypted data bag or Chef Vault	sensitive true
Puppet	Hiera eyaml	Sensitive()
Terraform	A secret manager, ideally read by the machine at boot	sensitive = true

Make the install idempotent

Guard the download and install so repeat runs do nothing. Any of these work as a check:

dpkg-query -W -f='${db:Status-Status}' aikido-endpoint-protection 2>/dev/null | grep -qx installed   # Debian family
rpm -q aikido-endpoint-protection    # Red Hat family
aikido-doctor --simple               # either, prints the installed version

On the Debian family, use the dpkg-query form rather than dpkg -s. dpkg -s also succeeds for a package that was removed but not purged, which is the state apt remove leaves behind. A guard built on it would report the agent as installed on a machine someone uninstalled it from, and your tool would never put it back.

Plan for the reboot

Installing sets NODE_EXTRA_CA_CERTS and UV_SYSTEM_CERTS system-wide so Node.js and uv trust the Aikido CA. Shells and services that were already running do not see them, so protection is only complete after a new login shell or a reboot.

Rebooting a workstation from an automation run is disruptive. On a fleet of developer machines, tell users to log out and back in, or schedule the reboot. On machines nobody is sitting at, reboot as part of the run.

Verify a rollout

On a test host:

systemctl status aikido-endpoint-protection
aikido-doctor version

The device then appears in your device list with an Active status. To confirm that blocking works, follow How to test if Device Protection is working.

Guides

Deploy Device Protection with AnsibleDeploy Device Protection with ChefDeploy Device Protection with PuppetDeploy Device Protection with TerraformDeploy Device Protection with cloud-initDeploy Device Protection in Golden Images

Installing on a single machine instead? See Install Device Protection for Linux.

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