Amazon Web Services (AWS)

Connect your AWS account so AgentSOAR can contain threats on EC2 — blocking attacker IPs at network ACLs, isolating instances with a deny-all security group, and powering instances on and off. AgentSOAR authenticates with an IAM access key belonging to a dedicated, least-privilege IAM user.

What this enables

This credential powers three AgentSOAR response capabilities against your AWS account:

CapabilityWhat it doesHow
block_ipBlocks an attacker IP at the network edgeEC2 network ACL (NACL) deny entry
isolateCuts an EC2 instance off from the networkDeny-all security group
powerPowers an EC2 instance on or offStartInstances / StopInstances

Prerequisites

  • An AWS account with the EC2 instances you want AgentSOAR to manage.
  • An account that can create IAM users and policies.
  • The AWS Region where those instances run (e.g. us-east-1).
  • Access to AgentSOAR → Settings → Credentials (/agentsoar/settings/credentials).

How the connection works

AgentSOAR authenticates to AWS with an IAM access key belonging to a dedicated IAM user. The user is granted only the EC2 and networking permissions the integration's actions need. Three values go into the credential form:

ValueWhat it is
Access Key IDThe public identifier of the IAM access key
Secret Access KeyThe matching secret — shown only once, at creation
RegionDefault AWS Region for API calls (e.g. us-east-1)

By the end of this guide you will have all three and a validated credential in AgentSOAR.

Step 1 — Open the IAM console

Sign in to the AWS Management Console with an account that can create IAM users and policies, then open IAM.

Step 2 — Create an IAM policy

The integration needs a narrow set of EC2 permissions. In IAM → Policies → Create policy, switch to the JSON tab and paste:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentSOCEc2Containment",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeNetworkAcls",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSubnets",
        "ec2:DescribeVpcs",
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:CreateNetworkAclEntry",
        "ec2:DeleteNetworkAclEntry",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:ModifyInstanceAttribute",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupEgress"
      ],
      "Resource": "*"
    }
  ]
}

Name it e.g. agentsoc-ec2-containment.

Resource: "*" keeps the guide simple. For least-privilege, scope the statement to the specific account, region, or resource ARNs your workloads use.

Step 3 — Create an IAM user

  1. Go to IAM → Users → Create user.
  2. Name it e.g. agentsoc-soar.
  3. Do not enable console access — this user is for programmatic API access only.

Step 4 — Attach the policy

On the Set permissions step, choose Attach policies directly and select the agentsoc-ec2-containment policy from Step 2. Finish creating the user.

Step 5 — Create an access key

  1. Open the new user and go to the Security credentials tab.
  2. Under Access keys, choose Create access key.
  3. Select the Application running outside AWS use case.
  4. Copy the Access key ID and Secret access key.

The Secret access key is shown only once. Copy it now — if you lose it, you must create a new key. Store it like a password and never commit it to source control.

Step 6 — Choose your Region

Pick the AWS Region where the EC2 instances you want AgentSOAR to manage run — e.g. us-east-1, eu-west-1. This becomes the Region value in the credential form.

Step 7 — Add the credential in AgentSOAR and validate

  1. In AgentSOAR, open Settings → Credentials (/agentsoar/settings/credentials).
  2. Add an AWS credential and enter:
    • Access Key ID — from Step 5.
    • Secret Access Key — from Step 5.
    • Region — from Step 6.
  3. Save. AgentSOAR validates the key with an sts:GetCallerIdentity call.
  4. Once it shows Healthy, the AWS action capabilities are ready to use.

Troubleshooting

ErrorLikely cause and fix
InvalidClientTokenId / SignatureDoesNotMatchThe Access Key ID or Secret Access Key is wrong or was mistyped. Re-copy both from Step 5, or create a fresh access key.
AccessDenied on validationThe IAM user has no permissions, or sts:GetCallerIdentity is blocked by a permission boundary or SCP. GetCallerIdentity needs no explicit permission — check for a restrictive SCP.
AccessDenied when running an actionThe policy from Step 2 isn't attached, or it's missing an action. Confirm the policy is attached to the user.
UnauthorizedOperation for a specific regionThe instances are in a different Region than the one configured. Add a credential for each Region you operate in.

Reference: AWS — Manage access keys for IAM users