AWS IAM medium security documentation change

Service: IAM · 2025-06-19 · Security-related medium

File: IAM/latest/UserGuide/access-analyzer-eventbridge.md

Summary

Added documentation for internal access findings events and error handling patterns

Security assessment

Added detailed documentation about internal access findings events and error patterns in EventBridge integration. This directly relates to security monitoring capabilities by documenting how to detect intra-account access patterns and analysis errors (ACCESS_DENIED/INTERNAL_ERROR), which helps identify potential security misconfigurations.

Diff

diff --git a/IAM/latest/UserGuide/access-analyzer-eventbridge.md b/IAM/latest/UserGuide/access-analyzer-eventbridge.md
index b14a0acf2..36ef20801 100644
--- a//IAM/latest/UserGuide/access-analyzer-eventbridge.md
+++ b//IAM/latest/UserGuide/access-analyzer-eventbridge.md
@@ -5 +5 @@
-Findings eventsAccess preview eventsEvent notification frequencyExample external access findings eventsExample unused access findings related eventsExample access preview eventsCreating an event rule using the console
+Findings eventsAccess preview eventsEvent notification frequencyExample external access findings eventsExample internal access findings eventsExample unused access findings related eventsExample access preview eventsCreating an event rule using the console
@@ -93,0 +94,75 @@ IAM Access Analyzer also sends events to EventBridge for error findings. An erro
+## Example internal access findings events
+
+The following is an example IAM Access Analyzer internal access finding event sent to EventBridge. The `id` listed is the ID for the event in EventBridge. To learn more, see [Events and Event Patterns in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html).
+
+In the `detail` object, the values for the `accountId` and `principalOwnerAccount` attributes refer to the account of the principal reported in the finding. The `isDeleted` attribute indicates whether the event was from the finding being deleted. The `id` is the finding ID. The `resource` is the ARN of the analyzer that generated the finding.
+    
+    
+    {
+        "version": "0",
+        "id": "b45c3678-c278-b593-6121-c155259ce1b5",
+        "detail-type": "Internal Access Finding",
+        "source": "aws.access-analyzer",
+        "account": "111122223333",
+        "time": "2025-04-08T19:42:49Z",
+        "region": "us-east-1",
+        "resources": [
+            "arn:aws:access-analyzer:us-east-1:111122223333:analyzer/testAnalyzer"
+        ],
+        "detail": {
+            "accessType": "INTRA_ACCOUNT",
+            "action": [
+                "s3:GetObject"
+            ],
+            "analyzedAt": "2025-04-08T03:18:43.509465073Z", 
+            "condition": {},
+            "createdAt": "2025-04-07T21:33:49.914099224Z",
+            "id": "11111111-2222-4444-aaaa-333333333333",
+            "isDeleted": false,
+            "findingType": "InternalAccess",
+            "principal": {
+                "AWS": "arn:aws:iam::111122223333:role/MyRole_6"
+            },
+            "principalOwnerAccount": "111122223333",
+            "principalType": "IAM_ROLE",
+            "resource": "arn:aws:s3:::critical-data",
+            "resourceControlPolicyRestrictionType": "NOT_APPLICABLE",
+            "accountId": "111122223333",
+            "resourceType": "AWS::S3::Bucket",
+            "serviceControlPolicyRestrictionType": "NOT_APPLICABLE",
+            "status": "ACTIVE",
+            "updatedAt": "2025-04-08T03:22:12.654688231Z",
+            "version": "1.0"
+        }
+    }
+
+IAM Access Analyzer also sends events to EventBridge for error findings. An error finding is a finding generated when IAM Access Analyzer can't analyze the resource. Events for error findings include an `error` attribute as shown in the following example.
+    
+    
+    {
+        "version": "0",
+        "id": "5a94b99b-e87d-a6a7-58c7-f47871532860",
+        "detail-type": "Internal Access Finding",
+        "source": "aws.access-analyzer-test",
+        "account": "444455556666",
+        "time": "2025-05-07T11:57:54Z",
+        "region": "us-west-2",
+        "resources": ["arn:aws:access-analyzer-beta:us-west-2:444455556666:analyzer/example-analyzer"],
+        "detail": {
+            "analyzedAt": "2025-03-24T19:58:52.512329448Z",
+            "createdAt": "2025-03-22T03:30:46.920200692Z",
+            "id": "ef573afd-12a5-4095-87a6-bf2f25109895",
+            "isDeleted": false,
+            "findingType": "InternalAccess",
+            "resource": "arn:aws:s3:::test-entity-88",
+            "accountId": "111122223333",
+            "resourceControlPolicyRestrictionType": "NOT_APPLICABLE",
+            "resourceType": "AWS::S3::Bucket",
+            "serviceControlPolicyRestrictionType": "NOT_APPLICABLE",
+            "error": "ACCESS_DENIED", // can be INTERNAL_ERROR and ACCESS_DENIED
+            "status": "ACTIVE",
+            "updatedAt": "2025-03-24T20:09:39.176075014Z",
+            "version": "1.0"
+        }
+    }
+
@@ -270 +345 @@ The following procedure describes how to create an event rule using the console.
-       * To create a rule based on an external access or unused access findings event, use the following pattern example:
+       * To create a rule based on an external access, internal access, or unused access findings event, use the following pattern example:
@@ -277,0 +353 @@ The following procedure describes how to create an event rule using the console.
+                "Internal Access Finding",
@@ -292,0 +369,11 @@ The following procedure describes how to create an event rule using the console.
+       * To create a rule based only on an internal access findings event, use the following pattern example:
+            
+                        {
+              "source": [
+                "aws.access-analyzer"
+              ],
+              "detail-type": [
+                "Internal Access Finding"
+              ]
+            }
+