AWS incident-manager medium security documentation change

Service: incident-manager · 2025-06-13 · Security-related medium

File: incident-manager/latest/userguide/incident-creation.md

Summary

Added detailed IAM permissions requirements for manually starting incidents including security conditions using aws:CalledViaFirst to restrict cross-account risks

Security assessment

The change explicitly documents security controls using IAM conditions to prevent cross-account calls through Forward Access Sessions (FAS). The aws:CalledViaFirst condition restricts StartEngagement and CreateOpsItem actions to only be called via Incident Manager, mitigating potential privilege escalation risks.

Diff

diff --git a/incident-manager/latest/userguide/incident-creation.md b/incident-manager/latest/userguide/incident-creation.md
index 75cc69092..df54aa2f5 100644
--- a//incident-manager/latest/userguide/incident-creation.md
+++ b//incident-manager/latest/userguide/incident-creation.md
@@ -219,0 +220,75 @@ Responders can manually track an incident using the Incident Manager console by
+### Required IAM permissions for manually starting incidents
+
+To manually start incidents, users need permissions to access the Incident Manager console, view response plans, and start incidents. When a user starts an incident, Incident Manager uses [forward access sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html) (FAS) to make the `StartEngagement` call as part of `StartIncident`.
+
+The following IAM policy provides the necessary permissions for manually starting incidents, viewing the response plans that incidents can be created with, and viewing and editing incidents after they are created.
+    
+    
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "ssm-incidents:StartIncident",
+                    "ssm-incidents:GetResponsePlan",
+                    "ssm-incidents:ListResponsePlans",
+                    "ssm-incidents:TagResource",
+                    "ssm-incidents:GetIncidentRecord",
+                    "ssm-incidents:ListIncidentRecords",
+                    "ssm-incidents:UpdateIncidentRecord"
+                ],
+                "Resource": "*"
+            },
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "ssm-contacts:StartEngagement"
+                ],
+                "Resource": "*",
+                "Condition": {
+                    "StringEquals": {
+                        "aws:CalledViaFirst": "ssm-incidents.amazonaws.com"
+                    }
+                }
+            },
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "ssm:CreateOpsItem"
+                ],
+                "Resource": "*",
+                "Condition": {
+                    "StringEquals": {
+                        "aws:CalledViaFirst": "ssm-incidents.amazonaws.com"
+                    }
+                }
+            }
+        ]
+    }
+
+This policy includes the following permissions:
+
+  * [ssm-incidents:StartIncident](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_StartIncident.html) \- Allows users to manually start an incident using the console or API. This creates a new incident record from a response plan.
+
+  * [ssm-incidents:GetResponsePlan](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_GetResponsePlan.html) \- Allows users to retrieve information about a specific response plan.
+
+  * [ssm-incidents:ListResponsePlans](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_ListResponsePlans.html) \- Allows users to list all response plans in their account.
+
+  * [ssm-incidents:TagResource](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_TagResource.html) \- Allows adding tags to Incident Manager resources, including incidents and response plans.
+
+  * [ssm-incidents:GetIncidentRecord](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_GetIncidentRecord.html) \- Allows users to retrieve detailed information about a specific incident.
+
+  * [ssm-incidents:ListIncidentRecords](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_ListIncidentRecords.html) \- Allows users to list all incidents in their account.
+
+  * [ssm-incidents:UpdateIncidentRecord](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_UpdateIncidentRecord.html) \- Allows users to update the details of an existing incident.
+
+  * [ssm-contacts:StartEngagement](https://docs.aws.amazon.com/incident-manager/latest/APIReference/API_SSMContacts_StartEngagement.html) (with condition) - Allows Incident Manager to start engagements with contacts. The condition ensures this can only be called via Incident Manager.
+
+  * [ssm:CreateOpsItem](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateOpsItem.html) (with condition) - Allows Incident Manager to create an OpsItem in OpsCenter. The condition ensures this can only be called via Incident Manager.
+
+
+
+
+The [aws:CalledViaFirst](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-calledviafirst) condition key ensures that certain permissions (like `StartEngagement`) can only be used when the request comes through the Incident Manager service. This approach uses FAS instead of service-linked roles, which prevents potential cross-account calls that could pose security risks.
+