Limiting Agent Access in an AWS Account

AWS DevOps Agent uses IAM roles to discover and describe AWS resources during incident investigations and preventative evaluations. You can control the level of access the agent has by configuring IAM policies attached to these roles. The application topology doesn't show everything the agent has access to—IAM policies are the only way to truly limit what AWS service APIs and resources the agent can access.

Understanding IAM roles for AWS DevOps Agent

AWS DevOps Agent uses IAM roles to access resources in two types of accounts:

For either type of account, you can restrict which AWS services the agent can access, limit access to specific resources within those services, and control which regions the agent can operate in.

Understanding permission guardrails

AWS DevOps Agent applies a permission guardrail to every session it creates when accessing your AWS resources. This guardrail acts as a ceiling — it defines the maximum set of permissions the agent can ever use, regardless of what permissions you grant on the IAM role.

How it works

When the agent assumes your IAM role, it passes a session policy that limits the effective permissions for that session. The effective permissions are the intersection of:

A permission must be present in both layers to take effect. If you add a permission to your role that is not included in the guardrail, the agent cannot use it.

Default permissions

The AIDevOpsAgentAccessPolicy managed policy provides the default set of read-only permissions the agent uses for investigations. These permissions are included in the guardrail, so they work without additional configuration.

Extending permissions beyond the default

AWS DevOps Agent supports a curated set of additional permissions beyond the default managed policy. These permissions are included in the guardrail but are not enabled by default. To use them, add the specific permissions to your role as an inline policy.

For example, to allow the agent to read objects from your S3 buckets during investigations, add an inline policy to your role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::my-application-bucket",
        "arn:aws:s3:::my-application-bucket/*"
      ]
    }
  ]
}

Because s3:GetObject and s3:ListBucket are included in the guardrail, this inline policy takes effect. You can scope the Resource to specific buckets to follow the principle of least privilege.

Supported additional permissions

The following permissions are included in the guardrail and can be enabled by adding them to your role as an inline policy. These are not granted by default — you must explicitly opt in.

Permissions blocked by the guardrail

If you add a permission to your role that is not in the guardrail, the agent cannot use it. This is by design — the guardrail prevents the agent from performing actions outside its intended scope, even if the role would otherwise allow them.

For example, write operations like s3:PutObject, ec2:TerminateInstances, or dynamodb:DeleteItem are not included in the guardrail. Even if your role grants these permissions, the agent cannot perform these actions.

Summary

This model ensures that the agent operates within a well-defined security boundary while giving you flexibility to extend its capabilities for your specific use case.

Choosing your resource boundaries

When limiting resource access, you need to include enough permissions for the agent to successfully investigate application incidents. This includes:

Supporting infrastructure may include:

If you restrict access too narrowly, the agent may not be able to identify root causes that originate in supporting infrastructure outside your defined boundaries.

Restricting service access

You can limit which AWS services the agent can access by modifying the IAM policies attached to the agent's roles. When creating custom policies, follow these best practices:

Example policy restricting to specific services:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:DescribeAlarms",
        "logs:GetLogEvents",
        "logs:FilterLogEvents",
        "ec2:DescribeInstances",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration"
      ],
      "Resource": "*"
    }
  ]
}

Restricting resource access

To limit the agent to specific resources within a service, use resource-level permissions in your IAM policies. This allows you to grant access only to resources that match specific patterns.

Using resource ARN patterns:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration"
      ],
      "Resource": "arn:aws:lambda:*:*:function:production-*"
    }
  ]
}

This example limits the agent to accessing only Lambda functions with names that begin with "production-".

Using tag-based restrictions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/Environment": "production"
        }
      }
    }
  ]
}

This example limits the agent to accessing only EC2 instances tagged with Environment=production.

Restricting regional access

To limit which AWS regions the agent can access, use the aws:RequestedRegion condition key in your IAM policies:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "lambda:Get*",
        "cloudwatch:Get*"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestedRegion": [
            "us-east-1",
            "us-west-2"
          ]
        }
      }
    }
  ]
}

This example limits the agent to accessing resources only in the us-east-1 and us-west-2 regions.

Creating custom IAM policies

When you create an Agent Space or add secondary accounts, you have the option to create a custom IAM role using a policy template. This allows you to implement the principle of least privilege.

When creating an Agent Space

From the DevOps Agent console in the AWS Management Console...

When editing an Agent Space

From the DevOps Agent console in the AWS Management Console...

Custom policy best practices