AWS devopsagent high security documentation change

Service: devopsagent · 2026-05-13 · Security-related high

File: devopsagent/latest/userguide/aws-devops-agent-security-limiting-agent-access-in-an-aws-account.md

Summary

Added 'Understanding permission guardrails' section explaining session policies that limit agent permissions beyond IAM roles

Security assessment

Introduces mandatory session policies that enforce a security boundary by restricting agent permissions to only those explicitly allowed in the guardrail, preventing privilege escalation even if IAM roles are misconfigured. Specifically blocks write operations like s3:PutObject or ec2:TerminateInstances.

Diff

diff --git a/devopsagent/latest/userguide/aws-devops-agent-security-limiting-agent-access-in-an-aws-account.md b/devopsagent/latest/userguide/aws-devops-agent-security-limiting-agent-access-in-an-aws-account.md
index c2ad5c261..e4bb59f19 100644
--- a//devopsagent/latest/userguide/aws-devops-agent-security-limiting-agent-access-in-an-aws-account.md
+++ b//devopsagent/latest/userguide/aws-devops-agent-security-limiting-agent-access-in-an-aws-account.md
@@ -7 +7 @@
-Understanding IAM roles for AWS DevOps AgentChoosing your resource boundariesRestricting service accessRestricting resource accessRestricting regional accessCreating custom IAM policiesCustom policy best practices
+Understanding IAM roles for AWS DevOps AgentUnderstanding permission guardrailsChoosing your resource boundariesRestricting service accessRestricting resource accessRestricting regional accessCreating custom IAM policiesCustom policy best practices
@@ -25,0 +26,72 @@ For either type of account, you can restrict which AWS services the agent can ac
+## 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) that limits the effective permissions for that session. The effective permissions are the intersection of:
+
+  1. **Your IAM role policies** — The managed policy and any inline policies you attach to the role.
+
+  2. **The permission guardrail** — A session policy applied by AWS DevOps Agent at assume-role time.
+
+
+
+
+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.
+
+Service | Actions | Use case  
+---|---|---  
+Amazon S3 | `s3:GetObject`, `s3:ListBucket` | Read application data, logs, or configuration stored in S3  
+AWS Direct Connect | `directconnect:DescribeConnections`, `directconnect:DescribeDirectConnectGatewayAssociations`, `directconnect:DescribeDirectConnectGateways`, `directconnect:DescribeLags`, `directconnect:DescribeVirtualInterfaces` | Investigate network connectivity issues  
+  
+### 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
+
+Layer | Who controls it | Purpose  
+---|---|---  
+IAM role policies | You | Define what you intend the agent to be able to do  
+Permission guardrail | AWS DevOps Agent | Defines the maximum the agent can ever do  
+Effective permissions | Intersection of both | What the agent can actually do  
+  
+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.
+