Deploy Device Protection with AWS Systems Manager

Deploy Aikido Device Protection to Windows and Linux machines managed by AWS Systems Manager with a State Manager association that runs the install command.

Use AWS Systems Manager (SSM) State Manager to install Aikido Device Protection on your Windows and Linux managed nodes. An association runs the install command on every node with a given tag, including nodes you tag later.

Prerequisites

• Managed nodes. Each node runs SSM Agent and has permissions, either through an instance profile with the AmazonSSMManagedInstanceCore policy or through Default Host Management Configuration (needs IMDSv2 and SSM Agent 3.2.582.0 or later). Machines that aren't EC2 instances need a hybrid activation.
• Permissions to create State Manager associations and to run commands with Run Command.
• The install command for each operating system and user group you roll out to. You copy it from the Aikido app in the first step.
• A tag on the target nodes. Use the key AikidoDeviceProtection with one value per operating system, user group, and Linux flavor, for example windows-developers, linux-developers, and linux-servers. A node carries one value only.
• A supported operating system. For Linux distributions, see Supported ecosystems.

How it works

A State Manager association runs a script on every targeted node once when you create it, and then on a schedule. The script starts with a guard, so a node that already has the agent exits immediately. A node that gets the tag later runs the association right away.

Each install command carries the token of one user group. Create one association per tag value, so one per operating system, user group, and Linux flavor.

Set up the association

1. 1

   Copy the install command

   1. Go to Devices in the Aikido app.
   2. Click Connect Device.
   3. Choose Manual install.
   4. Select the user group the machines should join.
   5. Copy the PowerShell install command for Windows or the Linux install command for Linux.

   For Linux servers and VMs, append --headless to the Linux install command. Leave it off for desktops. See Install Device Protection for Linux.

2. 2

   Test on one node with Run Command

   1. In the Systems Manager console, go to Run Command → Run command.
   2. Select AWS-RunPowerShellScript for Windows or AWS-RunShellScript for Linux.
   3. In Command parameters, paste the script from the next step.
   4. In Targets, choose manual selection and pick one node.
   5. Run the command and check the output for errors.
3. 3

   Create the association

   In the Systems Manager console, go to State Manager → Create association and enter the values for your operating system.

   WindowsLinux

   Field	Value
   Name	AikidoDeviceProtection-windows-developers
   Document	AWS-RunPowerShellScript
   Parameters	commands: the script below
   Targets	Specify instance tags, key AikidoDeviceProtection, value windows-developers
   Specify schedule	On Schedule, rate of every 1 day
   Rate control	Concurrency 10%, Error threshold 10%

   if (Get-Service -Name EndpointProtection -ErrorAction SilentlyContinue) { exit 0 }
   # paste the install command from the Aikido app on the next line

   Optionally, set Output options to write command output to S3. The output can contain the token, so protect the bucket.

4. 4

   Block uninstall on Windows (optional)

   Create a second association that stops users from launching the Aikido uninstaller with an AppLocker rule. It targets a separate tag, so it never runs before the install.

   1. Create an association with the document AWS-RunPowerShellScript and the targets Specify instance tags, key AikidoLockdown, value true.
   2. Set commands to the following script. It turns on the Application Identity service that AppLocker needs to enforce rules, then adds an AppLocker rule that blocks the uninstaller.
   3. Add the tag AikidoLockdown=true to a node only after it has rebooted and shows Active in the Aikido device list.

   $ErrorActionPreference = "Stop"
   sc.exe config appidsvc start= auto
   Start-Service -Name AppIDSvc
   $tmp = "$env:TEMP\aikido-applocker.xml"
   Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AikidoSec/safechain-internals/refs/heads/main/docs/aikido-applocker-deny.xml" -OutFile $tmp
   Set-AppLockerPolicy -XmlPolicy $tmp -Merge
   Remove-Item $tmp -Force
   if ((Get-Service -Name AppIDSvc).Status -ne "Running") { exit 1 }

   The first line stops the script at the first error and the last line fails the run if the Application Identity service is not running, so the association reports Failed instead of a silent success.

   If end users are local administrators, AppLocker rules can be bypassed. Combine this policy with App Control for Business (WDAC) and removal of local admin rights for stronger enforcement.

5. 5

   Reboot or start a new login shell

   The association doesn't reboot nodes. Protection becomes active at these points:

   • Windows: the agent fully activates on the next boot.
   • Linux: protection becomes active in a new login shell or after a reboot. See When protection becomes active.

   Reboot nodes in a maintenance window.

Verify the rollout

1. In the Systems Manager console, go to State Manager, open the association, and check its execution history.
2. Check the agent on a node. You can run these with Run Command.

Get-Service -Name EndpointProtection

aikidoctl --simple
systemctl is-active aikido-endpoint-protection

3. Go to Devices in the Aikido app. Each device appears in the list with an Active status.

Troubleshooting

Windows

Linux

Related