How do I monitor IAM events and set up event notifications with AWS CloudFormation?
Last updated: 2020-11-18
I want to monitor AWS Identity and Access Management (IAM) activity with AWS CloudFormation. For example, I want to receive an email notification whenever a certain IAM event occurs.
Short description
You can use the AWS CloudFormation template in the following resolution to monitor IAM events and set up notifications with Amazon CloudWatch Events.
Consider the following:
- You must deploy the template in the US East (N. Virginia) - us-east-1 AWS Region.
- You can modify the AWS::SNS::Topic resource to include additional email addresses.
- You can edit the AWS::Events::Rule resource to add or remove additional API calls.
Resolution
The following template includes the AWS::Events::Rule resource that contains the EventPattern property. You can use the EventPattern property to give different event sources and API calls the ability to add or restrict specific events for your use case. Each API call has different parameters and information in the events. It isn't possible to create one-size-fits-all events rule. The following sample template provides only two rules that group together many different API calls. However, you can use as many rules as you need to create emails or notifications for different API calls. You can customize and define which API calls to monitor and define customized emails and information for each call.
1. Copy the following JSON or YAML version of the template, and then update it with the values for your environment.
JSON:
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "Monitor IAM events with CloudWatch Events rules with AWS CloudFormation. This Stack must be deployed in 'us-east-1' (IAM).",
"Parameters": {
"EmailList": {
"Type": "String",
"Description": "Email to notify!",
"AllowedPattern": "[a-zA-Z0-9]+@[a-zA-Z0-9]+\\.[a-zA-Z]+",
"Default": "mail@company.com"
},
"SNSTopicName": {
"Type": "String",
"Description": "Name for the notification topic.",
"AllowedPattern": "[a-zA-Z0-9_-]+",
"Default": "iam-monitoring-topic"
},
"MonitorStatus": {
"Type": "String",
"Description": "Enable / Disable monitor.",
"AllowedValues": [
"ENABLED",
"DISABLED"
],
"Default": "ENABLED"
}
},
"Resources": {
"SNSMonitoringTopic": {
"Type": "AWS::SNS::Topic",
"Properties": {
"Subscription": [
{
"Endpoint": {
"Ref": "EmailList"
},
"Protocol": "email"
}
],
"TopicName": {
"Fn::Sub": "${AWS::StackName}-${SNSTopicName}"
}
}
},
"SNSMonitoringTopicTopicPolicy": {
"Type": "AWS::SNS::TopicPolicy",
"Properties": {
"Topics": [
{
"Ref": "SNSMonitoringTopic"
}
],
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SnsIAMTopicPolicy",
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": [
"sns:Publish"
],
"Resource": {
"Ref": "SNSMonitoringTopic"
}
},
{
"Sid": "AllowAccessToTopicOwner",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"sns:GetTopicAttributes",
"sns:SetTopicAttributes",
"sns:AddPermission",
"sns:RemovePermission",
"sns:DeleteTopic",
"sns:Subscribe",
"sns:ListSubscriptionsByTopic",
"sns:Publish",
"sns:Receive"
],
"Resource": {
"Ref": "SNSMonitoringTopic"
},
"Condition": {
"StringEquals": {
"AWS:SourceOwner": {
"Ref": "AWS::AccountId"
}
}
}
}
]
}
}
},
"EventRulePolicyMonitor": {
"Type": "AWS::Events::Rule",
"Properties": {
"Name": {
"Fn::Sub": "${AWS::StackName}-policy-monitor"
},
"Description": "This CloudWatch Event Rule will capture IAM API Calls and events related to creation and deletion of policies.\n",
"State": {
"Ref": "MonitorStatus"
},
"EventPattern": {
"source": [
"aws.iam"
],
"detail-type": [
"AWS API Call via CloudTrail"
],
"detail": {
"eventSource": [
"iam.amazonaws.com"
],
"eventName": [
"CreatePolicy",
"DeletePolicy",
"PutGroupPolicy",
"DeleteGroupPolicy",
"PutRolePolicy",
"DeleteRolePolicy",
"PutUserPolicy",
"DeleteUserPolicy",
"CreatePolicyVersion",
"DeletePolicyVersion",
"AttachRolePolicy",
"DetachRolePolicy",
"AttachUserPolicy",
"DetachUserPolicy",
"AttachGroupPolicy",
"DetachGroupPolicy"
]
}
},
"Targets": [
{
"Arn": {
"Ref": "SNSMonitoringTopic"
},
"Id": "iam-policy-monitor",
"InputTransformer": {
"InputPathsMap": {
"eventName": "$.detail.eventName",
"policyName": "$.detail.requestParameters.policyName",
"policyArn": "$.detail.requestParameters.policyArn",
"eventTime": "$.detail.eventTime",
"userIdentity": "$.detail.userIdentity.arn",
"sourceIPAddress": "$.detail.sourceIPAddress"
},
"InputTemplate": "\"API Call '<eventName>' was issued on policy '<policyName><policyArn>'. This occurred at '<eventTime>' and was initiated by '<userIdentity>' from IP '<sourceIPAddress>'. Please review the details here: https://console.aws.amazon.com/iam/home?region=us-east-1#/policies/<policyArn>$jsonEditor?section=attached_entities .\"\n"
}
}
]
}
},
"EventRulePrincipalsMonitor": {
"Type": "AWS::Events::Rule",
"Properties": {
"Name": {
"Fn::Sub": "${AWS::StackName}-principals-monitor"
},
"Description": "This CloudWatch Event Rule will capture IAM API Calls and events related to creation and deletion of users, groups and roles.",
"State": {
"Ref": "MonitorStatus"
},
"EventPattern": {
"source": [
"aws.iam"
],
"detail-type": [
"AWS API Call via CloudTrail"
],
"detail": {
"eventSource": [
"iam.amazonaws.com"
],
"eventName": [
"CreateUser",
"CreateGroup",
"CreateRole",
"UpdateUser",
"UpdateGroup",
"UpdateRole",
"DeleteUser",
"DeleteGroup",
"DeleteRole"
]
}
},
"Targets": [
{
"Arn": {
"Ref": "SNSMonitoringTopic"
},
"Id": "iam-user-monitor",
"InputTransformer": {
"InputPathsMap": {
"eventName": "$.detail.eventName",
"userName": "$.detail.requestParameters.userName",
"roleName": "$.detail.requestParameters.roleName",
"groupName": "$.detail.requestParameters.groupName",
"eventTime": "$.detail.eventTime",
"userIdentity": "$.detail.userIdentity.arn",
"sourceIPAddress": "$.detail.sourceIPAddress"
},
"InputTemplate": "\"API Call '<eventName>' was issued on '<userName><roleName><groupName>'. This occurred at '<eventTime>' and was initiated by '<userIdentity>' from IP '<sourceIPAddress>'. \"\n"
}
}
]
}
}
}
}
YAML:
AWSTemplateFormatVersion: 2010-09-09
Description: >
- Monitor IAM events with CloudWatch Events rules with AWS CloudFormation.
- This Stack must be deployed in 'us-east-1' (IAM).
Parameters:
EmailList:
Type: String
Description: "Email to notify!"
AllowedPattern: '[a-zA-Z0-9]+@[a-zA-Z0-9]+\.[a-zA-Z]+'
Default: "mail@company.com"
SNSTopicName:
Type: String
Description: "Name for the notification topic."
AllowedPattern: '[a-zA-Z0-9_-]+'
Default: "iam-monitoring-topic"
MonitorStatus:
Type: String
Description: "Enable / Disable monitor."
AllowedValues:
- ENABLED
- DISABLED
Default: ENABLED
Resources:
SNSMonitoringTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint: !Ref EmailList
Protocol: email
TopicName: !Sub ${AWS::StackName}-${SNSTopicName}
SNSMonitoringTopicTopicPolicy:
Type: AWS::SNS::TopicPolicy
Properties:
Topics:
- !Ref SNSMonitoringTopic
PolicyDocument:
Version: '2012-10-17'
Statement:
- Sid: SnsIAMTopicPolicy
Effect: Allow
Principal:
Service: events.amazonaws.com
Action: [ 'sns:Publish' ]
Resource: !Ref SNSMonitoringTopic
- Sid: AllowAccessToTopicOwner
Effect: Allow
Principal:
AWS: '*'
Action: [ 'sns:GetTopicAttributes',
'sns:SetTopicAttributes',
'sns:AddPermission',
'sns:RemovePermission',
'sns:DeleteTopic',
'sns:Subscribe',
'sns:ListSubscriptionsByTopic',
'sns:Publish',
'sns:Receive' ]
Resource: !Ref SNSMonitoringTopic
Condition:
StringEquals:
'AWS:SourceOwner': !Ref 'AWS::AccountId'
EventRulePolicyMonitor:
Type: AWS::Events::Rule
Properties:
Name: !Sub ${AWS::StackName}-policy-monitor
Description: >
This CloudWatch Event Rule will capture IAM API Calls and
events related to creation and deletion of policies.
State: !Ref MonitorStatus
EventPattern:
source:
- aws.iam
detail-type:
- AWS API Call via CloudTrail
detail:
eventSource:
- iam.amazonaws.com
eventName:
- CreatePolicy
- DeletePolicy
- PutGroupPolicy
- DeleteGroupPolicy
- PutRolePolicy
- DeleteRolePolicy
- PutUserPolicy
- DeleteUserPolicy
- CreatePolicyVersion
- DeletePolicyVersion
- AttachRolePolicy
- DetachRolePolicy
- AttachUserPolicy
- DetachUserPolicy
- AttachGroupPolicy
- DetachGroupPolicy
Targets:
- Arn:
Ref: SNSMonitoringTopic
Id: iam-policy-monitor
InputTransformer:
InputPathsMap:
eventName: $.detail.eventName
policyName: $.detail.requestParameters.policyName
policyArn: $.detail.requestParameters.policyArn
eventTime: $.detail.eventTime
userIdentity: $.detail.userIdentity.arn
sourceIPAddress: $.detail.sourceIPAddress
InputTemplate: >
"API Call '<eventName>' was issued on policy '<policyName><policyArn>'. This occurred at '<eventTime>' and was initiated by '<userIdentity>' from IP '<sourceIPAddress>'. Please review the details here: https://console.aws.amazon.com/iam/home?region=us-east-1#/policies/<policyArn>$jsonEditor?section=attached_entities ."
EventRulePrincipalsMonitor:
Type: AWS::Events::Rule
Properties:
Name: !Sub ${AWS::StackName}-principals-monitor
Description: >
This CloudWatch Event Rule will capture IAM API Calls and
events related to creation and deletion of users, groups
and roles.
State: !Ref MonitorStatus
EventPattern:
source:
- aws.iam
detail-type:
- AWS API Call via CloudTrail
detail:
eventSource:
- iam.amazonaws.com
eventName:
- CreateUser
- CreateGroup
- CreateRole
- UpdateUser
- UpdateGroup
- UpdateRole
- DeleteUser
- DeleteGroup
- DeleteRole
Targets:
- Arn:
Ref: SNSMonitoringTopic
Id: iam-user-monitor
InputTransformer:
InputPathsMap:
eventName: $.detail.eventName
userName: $.detail.requestParameters.userName
roleName: $.detail.requestParameters.roleName
groupName: $.detail.requestParameters.groupName
eventTime: $.detail.eventTime
userIdentity: $.detail.userIdentity.arn
sourceIPAddress: $.detail.sourceIPAddress
InputTemplate: >
"API Call '<eventName>' was issued on '<userName><roleName><groupName>'. This occurred at '<eventTime>' and was initiated by '<userIdentity>' from IP '<sourceIPAddress>'. "2. Deploy your template using either the AWS CloudFormation console or the AWS Command Line Interface (AWS CLI):
AWS CloudFormation console
1. Download the template.
2. Open the AWS CloudFormation console.
3. From the AWS Region selector in the navigation bar, choose us-east-1.
4. Choose Create stack, and then choose With new resources (standard).
5. In the Specify template section, choose Upload a template file.
6. Choose Choose file, select the template that you downloaded in step 1, and then choose Next.
7. In the Stack name section, for Stack name, enter a name for your stack.
8. In the Parameters section, for EmailList, enter the email address where you want to receive notifications.
9. For MonitorStatus, choose ENABLED.
10. For SNSTopicName, leave the default name, or choose your own name for an Amazon Simple Notification Service (Amazon SNS) topic.
11. Complete the rest of the steps in the setup wizard, and then choose Create stack.
12. Check your inbox (using the email address that you entered in step 8) for a confirmation email, and then follow the email instructions to confirm your subscription.
AWS CLI
Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent AWS CLI version.
1. Download the template, and then name the template sample-event-rule-iam-sns.yaml.
2. Set up the AWS CLI.
3. Open a command line in your operating system, and go to the folder where your template is located.
4. Run the following command:
aws cloudformation --region=us-east-1 \
create-stack \
--stack-name iam-sample-monitor \
--template-body file://sample-event-rule-iam-sns.yaml \
--parameters \
ParameterKey=EmailList,ParameterValue="mail@company.com"Note: Replace mail@company.com with the email that you want to receive notifications.
5. Check your inbox (using the email address that you entered in step 4) for a confirmation email, and then follow the email instructions to confirm your subscription.
Test the monitoring notification
1. Open the IAM console.
3. Check your email for a notification about the event. You will receive an email similar to the following:
API Call 'CreatePolicy' was issued on policy 'test-policy'.
This occurred at '2020-11-13T00:00:00Z' and was initiated by 'arn:aws:sts::123456789012:assumed-role/your-role' from IP 'X.Y.Z.T'.
Please review the details here: https://console.aws.amazon.com/iam/home?region=us-east-1#/policies/$jsonEditor?section=attached_entities.Related information
Did this article help?
Do you need billing or technical support?