# Deploy Device Protection with AWS Systems Manager

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](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/user-groups-for-aikido-endpoint) 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](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/miscellaneous-aikido-endpoint/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.

{% hint style="warning" %}
The install command contains the user group token. Anyone who can view the association, its command history, its S3 output, or the AWS CloudTrail log bucket can read the token. Restrict IAM access to State Manager, Run Command, and the CloudTrail bucket accordingly.
{% endhint %}

## Set up the association

{% stepper %}
{% step %}
### Copy the install command

1. Go to [Devices](https://app.aikido.dev/endpoint-protection/devices) in the Aikido app.
2. Click **Connect Device**.
3. Choose **Manual install**.
4. Select the [user group](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/user-groups-for-aikido-endpoint) 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](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/device-protection-mdm-guides/linux/install-device-protection-for-linux).
{% endstep %}

{% step %}
### 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.
{% endstep %}

{% step %}
### Create the association

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

{% tabs %}
{% tab title="Windows" %}
| 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%` |

{% code title="commands" %}
```powershell
if (Get-Service -Name EndpointProtection -ErrorAction SilentlyContinue) { exit 0 }
# paste the install command from the Aikido app on the next line
```
{% endcode %}
{% endtab %}

{% tab title="Linux" %}
| Field | Value |
| --- | --- |
| **Name** | `AikidoDeviceProtection-linux-developers` |
| **Document** | `AWS-RunShellScript` |
| **Parameters** | **commands**: the script below |
| **Targets** | **Specify instance tags**, key `AikidoDeviceProtection`, value `linux-developers` |
| **Specify schedule** | **On Schedule**, rate of every 1 day |
| **Rate control** | **Concurrency** `10%`, **Error threshold** `10%` |

{% code title="commands" %}
```bash
if aikidoctl --simple >/dev/null 2>&1; then exit 0; fi

# paste the install command from the Aikido app on this line

# fail the run if the agent is missing or its service is not running
aikidoctl --simple || exit 1
systemctl is-active --quiet aikido-endpoint-protection || exit 1
```
{% endcode %}

Paste the install command on the empty line between the guard and the checks, not at the end. The last two lines make the association report **Failed** when the agent did not install or its service is not running.

For servers, create a second association with the value `linux-servers` and the `--headless` install command.
{% endtab %}
{% endtabs %}

Optionally, set **Output options** to write command output to S3. The output can contain the token, so protect the bucket.
{% endstep %}

{% step %}
### 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](https://app.aikido.dev/endpoint-protection/devices).

{% code title="aikido-applocker.ps1" %}
```powershell
$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 }
```
{% endcode %}

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.

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}
### 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](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/device-protection-mdm-guides/linux/linux-rollout-reference#when-protection-becomes-active).

Reboot nodes in a maintenance window.
{% endstep %}
{% endstepper %}

## 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.

{% tabs %}
{% tab title="Windows" %}
```powershell
Get-Service -Name EndpointProtection
```
{% endtab %}

{% tab title="Linux" %}
```bash
aikidoctl --simple
systemctl is-active aikido-endpoint-protection
```
{% endtab %}
{% endtabs %}

3. Go to [Devices](https://app.aikido.dev/endpoint-protection/devices) in the Aikido app. Each device appears in the list with an **Active** status.

## Troubleshooting

| Problem | What to check |
| --- | --- |
| A node is missing from the targets | Follow the AWS guide [Troubleshooting managed node availability](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-troubleshooting-managed-nodes.html). |
| The association status is **Failed** | Open the command output for the node and read the error. |
| The device doesn't appear in the Aikido app | Reboot the node and check that it has internet access. |

### Windows


| 問題 | 対処法 |
| ------- | --- |
| スクリプトの実行後、デバイスがダッシュボードに表示されない | デバイスを再起動してください。エージェントは次回の起動時に登録が完了します |
| MDM コンソールでスクリプトがエラーで終了する | テストホスト上でスクリプトを SYSTEM として手動で実行し、エラーの詳細を確認してください。また、デバイスがインストーラーをダウンロードするためにインターネットにアクセスできることを確認してください |
| エージェントサービスが実行されていない | デバイスを再起動してください。それでもサービスが存在しない場合は、インストールスクリプトを再実行してください |
| スクリプトが実行ポリシーによってブロックされる | MDM 経由で実行されるスクリプトは SYSTEM として実行されるため、ユーザーレベルの実行ポリシーによる制限を受けません。MDM がスクリプトの実行を制限する追加のポリシーを適用していないことを確認してください |
| インストール後、デバイスが非アクティブと表示される | エージェントを完全に有効化するには再起動が必要です。再起動後にもう一度確認してください |

### Linux


| 問題                                                                                  | 対処法                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| パッケージはインストールされるが、デバイスがダッシュボードに表示されない                       | インストールコマンドに `AIKIDO_TOKEN` が設定されていませんでした。構成管理ツールはローカル環境をホストに転送しないため、タスク自体に変数を設定してから、パッケージを再度インストールしてください                                    |
| `apt` または `dnf` がファイルをインストールせず、リポジトリ内でパッケージを探してしまう | 名前ではなくパスを指定してください: `apt install ./EndpointProtection-amd64.deb`。先頭の `./` によって、パッケージマネージャーはそれをローカルファイルとして扱います                                                                                              |
| Red Hat 系のホストでインストールが失敗する                                               | ビルドをメジャーバージョンに合わせてください。バージョン 9 では `el9` パッケージを、バージョン 10 では `el10` パッケージを使用します                                                                                                                                   |
| サービスが実行されていない                                                               | `systemctl status aikido-endpoint-protection` を実行し、次に `sudo aikidoctl diagnostics` を実行して詳細を送信してください                                                                                                                                 |
| Node.js または uv が依然として Aikido 証明書を拒否する                                        | インストール時に `NODE_EXTRA_CA_CERTS` と `UV_SYSTEM_CERTS` がシステム全体に設定されますが、実行中のシェルにはこれらが反映されません。新しいログインシェルを開くか、デバイスを再起動してください                                                                                    |
| トークンが実行出力やログに表示される                                                 | ツールのマスキング機能を使用してください: Ansible では `no_log`、Chef では `sensitive true`、Puppet では `Sensitive()`                                                                                                                                               |
| 複数のマシンがデバイス一覧で 1 つのエントリを共有している                                      | それらのマシンは同じ `/etc/machine-id` で起動しています。Linux のデバイス ID はこのファイルに基づくため、クローン元のイメージでこのファイルをクリアし、初回起動時に systemd に新しいものを書き込ませてください                                                                |
| トレイアイコンが表示されない                                                                     | Ubuntu 以外の GNOME では想定どおりの動作であり、見た目上の問題にすぎません。[Tray Icon Support on Linux](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/device-protection-mdm-guides/linux/install-device-protection-for-linux/tray-icon-support-on-linux) を参照してください |

## Related

{% content-ref url="linux/linux-rollout-reference.md" %}
[linux-rollout-reference.md](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/device-protection-mdm-guides/linux/linux-rollout-reference)
{% endcontent-ref %}

{% content-ref url="windows/deploy-aikido-endpoint-with-sccm.md" %}
[deploy-aikido-endpoint-with-sccm.md](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/device-protection-mdm-guides/windows/deploy-aikido-endpoint-with-sccm)
{% endcontent-ref %}

{% content-ref url="../user-groups-for-aikido-endpoint.md" %}
[user-groups-for-aikido-endpoint.md](https://help.aikido.dev/docs/docs-ja/aikido-device-protection/deploying-aikido-endpoint/user-groups-for-aikido-endpoint)
{% endcontent-ref %}