ECS (Fargate)

Overview

Deploy the ARMO ptrace agent to your Amazon ECS services running on Fargate launch type to enable runtime security monitoring. Unlike the EC2 deployment which uses eBPF at the kernel level, the ptrace agent uses ptrace-based process tracing — since Fargate does not allow kernel-level access.

The ARMO ptrace agent runs as a sidecar container injected into each Fargate task definition. Instrumentation is per-service — each service or task definition that needs monitoring must be patched individually using the armoctl CLI tool.

Prerequisites

• The armoctl CLI tool installed and configured with the following credentials:

  Flag	Env Var	Description
  --customer-guid	ARMO_CUSTOMER_GUID	ARMO customer GUID (required)
  --access-key	ARMO_ACCESS_KEY	ARMO API access key (required)
  --api-url	ARMO_API_URL	ARMO platform URL (required, default: cloud.armosec.io)

  All three are required for the ptrace agent to authenticate with the ARMO Platform. See the armoctl guide for how to provide them via flags, environment variables, or config file.

Collecting Required Credentials

Account ID (Customer GUID)

Your Account ID uniquely identifies your organization within the ARMO Platform. To find it:

1. Log in to the ARMO Platform
2. Look at the top-right corner of the page where your account name is displayed
3. Click on your account name to open the dropdown menu
4. Find your Account ID in this menu - it will be a long alphanumeric string
5. Click the copy icon next to it to copy it to your clipboard

Agent Access Key

The Agent Access Key is an authentication token that allows the ptrace agent to authenticate with the ARMO Platform. To obtain this key:

1. Navigate to Agent Access Keys in the ARMO Platform
2. You'll see a list of existing keys if any have been created previously
3. Either:
   • Copy an existing key if you want to reuse it, or
   • Click "Create New Key" to generate a fresh key for this deployment
4. Store this key securely - you'll need it during the installation process

• An active ECS cluster running on Fargate launch type with platform version 1.4.0 or later (required for pidMode: "task")
• AWS CLI installed (optional, useful for verification and rollback commands)
• IAM permissions to describe, register, and update ECS task definitions and services

🚧

The URLs used in this guide (cloud.armosec.io for the platform and https://api.armosec.io for the API) are for the default ARMO environment. Verify what are the correct URLs for you before proceeding.

Installation

The armoctl CLI provides two commands for instrumenting Fargate task definitions:

• armoctl ecs patch — Takes a task definition JSON (from a file, stdin, or ARN), injects the ARMO ptrace sidecar, and outputs the patched version. Can optionally register the patched definition with AWS.
• armoctl ecs instrument — Fetches the current task definition from a running ECS service, patches it with the ptrace sidecar, and optionally deploys the update.

Both commands output the patched task definition JSON to stdout. Without --register or --deploy, no changes are made to AWS — you can inspect the output before applying it.

Examples

Patch a task definition from a file

If you have a task definition JSON file, patch it and review the output:

# Patch and print the result to stdout
armoctl ecs patch <TASK_DEF_FILE>

Save the patched output to a new file:

armoctl ecs patch <TASK_DEF_FILE> > patched-task-def.json

Patch and register the new revision with AWS in one step:

armoctl ecs patch <TASK_DEF_FILE> --register

If you don't have the task definition as a file, you can export it from AWS first:

Bash

aws ecs describe-task-definition \
  --task-definition <TASK_DEF_FAMILY_OR_ARN> \
  --query 'taskDefinition' > my-task-def.json

Patch from stdin

Pipe a task definition directly from another command:

aws ecs describe-task-definition \
  --task-definition <TASK_DEF_FAMILY_OR_ARN> \
  --query 'taskDefinition' \
  | armoctl ecs patch -

Patch from an ARN

Fetch a task definition directly from AWS by its ARN (requires AWS credentials):

armoctl ecs patch arn:aws:ecs:<REGION>:<ACCOUNT_ID>:task-definition/<FAMILY>:<REVISION>

Patch specific containers only

If your task definition has multiple containers and you only want to instrument some of them, use the --container flag:

armoctl ecs patch <TASK_DEF_FILE> --container <CONTAINER_NAME> --container <CONTAINER_NAME>

Containers not listed in --container will not be instrumented. By default (without --container), all containers are patched.

Instrument a running service

Use armoctl ecs instrument to fetch the task definition from a live ECS service and patch it:

# Patch and print the result to stdout (no changes made to AWS)
armoctl ecs instrument \
  --cluster <CLUSTER_NAME> \
  --service <SERVICE_NAME>

Patch and deploy in one step:

armoctl ecs instrument \
  --cluster <CLUSTER_NAME> \
  --service <SERVICE_NAME> \
  --deploy

When --deploy is used, armoctl registers the new task definition revision with AWS and updates the service to use it. ECS will then perform a rolling deployment of the new tasks.

Command Reference

armoctl ecs patch

armoctl ecs patch <taskdef> [flags]

The <taskdef> argument can be a file path, an ARN (starting with arn:), or - for stdin.

armoctl ecs instrument

armoctl ecs instrument [flags]

Verification

After deploying a patched task definition, verify the deployment:

# Check that the service is running with the new task definition
aws ecs describe-services \
  --cluster <YOUR_CLUSTER_NAME> \
  --services <YOUR_SERVICE_NAME> \
  --region <YOUR_AWS_REGION>

Confirm that:

• The service shows status: ACTIVE
• The taskDefinition ARN matches the newly registered revision
• Running tasks are using the updated task definition

In the ARMO Platform:

• Your cluster should appear in the Accounts page
• Agent health status shows as connected
• Security findings begin appearing within a few minutes

Troubleshooting

Sidecar container not starting

Check the task's stopped reason in the ECS console or with:

aws ecs describe-tasks \
  --cluster <YOUR_CLUSTER_NAME> \
  --tasks <TASK_ID> \
  --region <YOUR_AWS_REGION>

Common causes:

• The sidecar image cannot be pulled — verify ECR access permissions in the task execution role
• Insufficient task memory — the sidecar requires additional memory; increase the task's total memory allocation

pidMode error or ptrace not working

Fargate requires platform version 1.4.0 or later for pidMode: "task". Check your service's platform version:

aws ecs describe-services \
  --cluster <YOUR_CLUSTER_NAME> \
  --services <YOUR_SERVICE_NAME> \
  --query 'services[0].platformVersion'

If the platform version is older than 1.4.0, update your service or task definition to use LATEST or 1.4.0.

Application containers failing after patching

If application containers fail to start after patching, check:

• Whether the container's command was correctly wrapped — review the patched task definition JSON output
• That pidMode is set to "task" — required for ptrace to work across containers

Agent not reporting to ARMO

Verify that the customer-guid, access-key, and api-url values are correct. The sidecar container needs outbound network access to communicate with the ARMO backend.

Reverting to the original task definition

List all revisions for your task definition family to find the pre-patch version:

aws ecs list-task-definitions \
  --family-prefix <TASK_DEF_FAMILY> \
  --sort DESC \
  --region <YOUR_AWS_REGION>

Then update the service to use the previous revision:

aws ecs update-service \
  --cluster <YOUR_CLUSTER_NAME> \
  --service <YOUR_SERVICE_NAME> \
  --task-definition <ORIGINAL_TASK_DEF_ARN> \
  --region <YOUR_AWS_REGION>

Updating the Agent

To update the ARMO ptrace agent to a newer version, re-run the patch or instrument command with the --agent-image flag pointing to the new image:

armoctl ecs instrument \
  --cluster <YOUR_CLUSTER_NAME> \
  --service <YOUR_SERVICE_NAME> \
  --agent-image <NEW_AGENT_IMAGE> \
  --deploy

Or patch from a file, register, and update the service manually:

armoctl ecs patch <TASK_DEF_FILE> \
  --agent-image <NEW_AGENT_IMAGE> \
  --register

# Then update the service to use the new revision
aws ecs update-service \
  --cluster <YOUR_CLUSTER_NAME> \
  --service <YOUR_SERVICE_NAME> \
  --task-definition <NEW_TASK_DEF_ARN> \
  --region <YOUR_AWS_REGION>

Uninstalling

To remove the ARMO ptrace agent from a Fargate service, update the service to use the original (unpatched) task definition revision:

# Find the pre-patch revision
aws ecs list-task-definitions \
  --family-prefix <TASK_DEF_FAMILY> \
  --sort DESC \
  --region <YOUR_AWS_REGION>

# Roll back to the original revision
aws ecs update-service \
  --cluster <YOUR_CLUSTER_NAME> \
  --service <YOUR_SERVICE_NAME> \
  --task-definition <ORIGINAL_TASK_DEF_ARN> \
  --region <YOUR_AWS_REGION>

You can also deregister the patched task definition revisions if they are no longer needed:

aws ecs deregister-task-definition \
  --task-definition <PATCHED_TASK_DEF_ARN> \
  --region <YOUR_AWS_REGION>

Next Steps

• Configure security policies and detection rules in the ARMO Platform
• Set up alert notifications (Slack, PagerDuty, email)
• Review and tune initial security findings
• Connect additional ECS clusters or Kubernetes clusters