Deploy Device Protection with Chef

Use a Chef cookbook to install Device Protection on the Linux machines your Chef Infra Client already manages. The recipe below picks the right package per platform, installs it with your user group token, and keeps the service running on every converge.

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

Cookbook layout

cookbooks/aikido_device_protection/
├── attributes/default.rb
├── metadata.rb
└── recipes/default.rb

Set up the cookbook

1

Add the attributes

cookbooks/aikido_device_protection/attributes/default.rb

default['aikido']['release_url'] =
  'https://github.com/AikidoSec/safechain-internals/releases/latest/download'

# Reboot after installing. See "Handle the reboot" below.
default['aikido']['reboot'] = false

2

Store the token in an encrypted data bag

Create a data bag item holding the token for the user group these nodes belong to:

knife data bag create aikido device_protection --secret-file /path/to/encrypted_data_bag_secret

data_bag_item decrypts it on the node using the secret at Chef::Config[:encrypted_data_bag_secret]. If you use Chef Vault instead, swap the lookup for chef_vault_item('aikido', 'device_protection')['token'].

3

Add the recipe

cookbooks/aikido_device_protection/recipes/default.rb

arch = node['kernel']['machine'] == 'aarch64' ? 'arm64' : 'amd64'

case node['platform_family']
when 'debian'
  package_file    = "EndpointProtection-#{arch}.deb"
  install_command = 'apt-get install -y'
  installed_check = "dpkg-query -W -f='${db:Status-Status}' aikido-endpoint-protection 2>/dev/null | grep -qx installed"
when 'rhel'
  package_file    = "EndpointProtection-#{arch}.el#{node['platform_version'].to_i}.rpm"
  install_command = 'dnf install -y'
  installed_check = 'rpm -q aikido-endpoint-protection'
else
  raise "Aikido Device Protection does not support #{node['platform_family']}"
end

package_path = "/var/cache/aikido/#{package_file}"

directory '/var/cache/aikido' do
  owner 'root'
  group 'root'
  mode '0700'
end

remote_file package_path do
  source "#{node['aikido']['release_url']}/#{package_file}"
  owner 'root'
  mode '0600'
  not_if installed_check
end

execute 'install aikido-endpoint-protection' do
  command "#{install_command} #{package_path}"
  environment 'AIKIDO_TOKEN' => data_bag_item('aikido', 'device_protection')['token']
  sensitive true
  not_if installed_check
  notifies :request_reboot, 'reboot[activate aikido-endpoint-protection]', :delayed
end

service 'aikido-endpoint-protection' do
  action [:enable, :start]
end

reboot 'activate aikido-endpoint-protection' do
  action :nothing
  reason 'Activate Aikido Device Protection'
  delay_mins 5
  only_if { node['aikido']['reboot'] }
end

4

Add it to the run list

Put the recipe in the run list of the nodes you want protected, through a role, an environment, or a Policyfile:

run_list 'recipe[aikido_device_protection]'

The next converge on each node installs the agent. Roll out gradually by adding the recipe to one role first.

Why an execute resource and not package

Chef's package, dpkg_package, and rpm_package resources have no environment property, so there is no way to hand AIKIDO_TOKEN to the install through them. The package reads that variable while it installs, so the install has to run as an execute resource with environment set.

sensitive true keeps the token out of the run log and the report handler output. Leave it on.

Keep converges idempotent

not_if installed_check guards both the download and the install, so a node that already runs the agent does nothing on later converges. The token is only needed on first install, and upgrades keep the device's registration.

On the Debian family the check is dpkg-query, not dpkg -s. dpkg -s also succeeds for a package that was removed but not purged, so a node where someone ran apt remove aikido-endpoint-protection would look installed to Chef and never be converged back.

To upgrade the fleet, remove the guard or point release_url at a specific package you have mirrored, and let the execute resource install over the existing version.

Handle the reboot

Installing sets the Aikido CA environment variables system-wide, and running shells only pick them up after a new login shell or a reboot. node['aikido']['reboot'] is off by default so a converge never restarts a machine someone is working on. Set it to true for unattended machines, or ask users to log out and back in.

Verify the rollout

On a converged node:

systemctl is-active aikido-endpoint-protection
aikido-doctor version

The device then 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