AWS imagebuilder documentation change

Service: imagebuilder · 2025-11-16 · Documentation low

File: imagebuilder/latest/userguide/security-iam.md

Summary

Added documentation for IAM permissions required by custom workflow step actions, specifically RegisterImage with details about EC2 permissions and tag merging behavior

Security assessment

The change adds documentation about required IAM permissions for custom workflows but does not indicate a security vulnerability fix. It provides security guidance for proper permission configuration when using specific features, which qualifies as security documentation enhancement rather than addressing a specific security issue.

Diff

diff --git a/imagebuilder/latest/userguide/security-iam.md b/imagebuilder/latest/userguide/security-iam.md
index 412971ca7..25b501645 100644
--- a//imagebuilder/latest/userguide/security-iam.md
+++ b//imagebuilder/latest/userguide/security-iam.md
@@ -5 +5 @@
-AudienceAuthenticating with identitiesResource-Based Policies
+AudienceAuthenticating with identitiesCustom workflow permissionsResource-Based Policies
@@ -20,0 +21,2 @@ AudienceAuthenticating with identitiesResource-Based Policies
+  * IAM permissions for custom workflows
+
@@ -48,0 +51,76 @@ For detailed information about how to provide authentication for people and proc
+## IAM permissions for custom workflows
+
+When using custom workflows with specific step actions like [RegisterImage](./wfdoc-step-actions.html#wfdoc-step-action-register-image), additional IAM permissions may be required beyond the standard Image Builder managed policies. This section describes the additional permissions needed for custom workflow step actions.
+
+### RegisterImage step action permissions
+
+The `RegisterImage` step action requires specific Amazon EC2 permissions to register AMIs and optionally retrieve snapshot tags. When using the `includeSnapshotTags` parameter, additional permissions are needed to describe snapshots.
+
+**Required permissions for RegisterImage step action:**
+
+For all resources, allow the following actions:
+
+  * `ec2:RegisterImage`
+
+  * `ec2:DescribeSnapshots`
+
+
+
+    
+    
+    {
+        "Version": "2012-10-17",		 	 	 
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "ec2:RegisterImage",
+                    "ec2:DescribeSnapshots"
+                ],
+                "Resource": "*"
+            },
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "ec2:CreateTags"
+                ],
+                "Resource": "arn:aws:ec2:*::image/*",
+                "Condition": {
+                    "StringEquals": {
+                        "ec2:CreateAction": "RegisterImage"
+                    }
+                }
+            }
+        ]
+    }
+
+**Permission details:**
+
+  * `ec2:RegisterImage` \- Required to register new AMIs from snapshots
+
+  * `ec2:DescribeSnapshots` \- Required when using `includeSnapshotTags: true` to retrieve snapshot tags for merging with AMI tags
+
+  * `ec2:CreateTags` \- Required to apply tags to the registered AMI, including both Image Builder default tags and merged snapshot tags
+
+
+
+
+###### Note
+
+The `ec2:DescribeSnapshots` permission is only used when the `includeSnapshotTags` parameter is set to `true`. If you don't use this feature, you can omit this permission.
+
+**Tag merging behavior:**
+
+When `includeSnapshotTags` is enabled, the RegisterImage step action will:
+
+  * Retrieve tags from the first snapshot specified in the block device mapping
+
+  * Exclude any AWS reserved tags (those with keys starting with "aws:")
+
+  * Merge snapshot tags with Image Builder's default AMI registration tags
+
+  * Give precedence to Image Builder tags when tag keys conflict
+
+
+
+