How to Receive Alerts When Your IAM Configuration Changes

Note: This post has been updated to support the recently launched managed policies.

As an AWS administrator, you want to know when your security configuration changes. Though some changes are expected, you may want to review unexpected changes or changes made by a privileged user. Fortunately, a newly released combination of AWS CloudTrail, Amazon CloudWatch Logs, Amazon CloudWatch, and Amazon SNS will help make sure no changes to your AWS Identity and Access Management (IAM) configuration are made without you being alerted. In this blog post, we walk through how to set up CloudWatch alarms on IAM configuration changes. 

Before getting started, make sure you have done the following:

1. You must have CloudTrail turned on in each of your regions. CloudTrail creates a record of what’s happening in your account and is an essential part of securing your account.
2. You must already have an SNS topic configured to receive CloudWatch alarms. Refer to the topic by its Amazon Resource Name (ARN) (for example, arn:aws:sns:us-east-1:012345678912:emailalerts). A list of your topics and their ARNs is available from the SNS console.
3. CloudTrail must have access to an IAM role in your account to be able to send CloudTrail events to your CloudWatch Logs. Make sure you note the log group to which your CloudTrail events are being sent. The default log group is “CloudTrail/DefaultLogGroup.”

Here’s a quick overview of how AWS usage ends up triggering a CloudWatch alarm. The users of your AWS account make calls to IAM (and other AWS services), and a record of these calls is included in your CloudTrail logs (these records are called “events”). CloudTrail then assumes the IAM role you created (see #3 above), which allows CloudTrail to publish events to your CloudWatch logs. CloudWatch allows you to run a filter on these events and generate a CloudWatch metric on any matches. It’s up to you to define when these metrics trigger an alarm, but when enough events occur in a specified time period, you will receive an alert either via an SNS topic or email.

The following diagram illustrates the process:

Use CloudWatch filter patterns

Before you configure an alarm, you have to decide what will trigger the alarm. This section includes three filter patterns and explains the IAM use cases to which they apply. More filter patterns—for example, for console sign-in failures, network access control list (ACL) changes, and security group configuration changes—are available in the CloudWatch documentation.

Monitor all calls to IAM

To monitor all calls to IAM, you can use the following CloudWatch filter pattern:

{ ($.eventSource = "iam.amazonaws.com") }

This filter pattern matches any CloudTrail events for calls to the IAM service. All calls to IAM have a CloudTrail eventSource of iam.amazonaws.com, so any IAM API calls will match this pattern. You will find this simple filter pattern useful if you have minimal IAM activity in your account or to test this blog post.

Important: The blank spaces in filter patterns are for clarity. Also, note the use of outer curly brackets and inner parentheses.

Monitor changes to IAM

If you are interested only in changes to your IAM account, use the following filter pattern:

{ ( ($.eventSource = "iam.amazonaws.com") && (($.eventName = "Add*") || ($.eventName = "Attach*") || ($.eventName = "Change*") || ($.eventName = "Create*") || ($.eventName = "Deactivate*") || ($.eventName = "Delete*") || ($.eventName = "Detach*") || ($.eventName = "Enable*") || ($.eventName = "Put*") || ($.eventName = "Remove*") || ($.eventName = "Set*") || ($.eventName = "Update*") || ($.eventName = "Upload*")) ) }

This filter pattern will only match events from the IAM service that begin with “Add,” “Change,” “Create,” “Deactivate,” “Delete,” “Enable,” “Put,” “Remove,” “Update,” or “Upload.” For more information about why we’re interested in APIs matching these patterns, see the IAM API Reference.

Monitor changes to authentication and authorization configuration

If you’re interested in changes to your AWS authentication (security credentials) and authorization (policy) configuration, use the following filter pattern:

{ ( ($.eventSource = "iam.amazonaws.com") && (($.eventName = "Put*Policy") || ($.eventName = "Attach*") || ($.eventName = "Detach*") || ($.eventName = "Create*") || ($.eventName = "Update*") || ($.eventName = "Upload*") || ($.eventName = "Delete*") || ($.eventName = "Remove*") || ($.eventName = "Set*")) ) }

This filter pattern matches calls to IAM that modify policy or create, update, upload, and delete IAM elements.

Create a CloudWatch metric based on IAM API activity

Now, we can set up a CloudWatch metric based on the configuration changes we wish to monitor, and then build a CloudWatch alarm based on that metric:

1. In the CloudWatch console, click Logs and then select the check box for your CloudTrail log group. (If you are unclear, review your configuration for prerequisite #3 at the beginning of this blog post.)
2. Click Create Metric Filter.
3. On the Define Logs Metric Filter screen, click Filter Pattern and enter one of the filter patterns shown above.
4. Click Test Pattern to see how many of your CloudTrail events will be matched, and then click Show test results to see which events matched. If you’ve only recently enabled your CloudTrail events or you don’t have recent IAM activity, the events may not be available for a few minutes.
5. When your pattern meets your requirements, click Assign Metric. On the Create Metric Filter and Assign a Metric screen, in the Filter Name box, type a name for the filter, such as IAMAuthnAuthzActivity.
6. Under Metric Details, in the Metric Namespace box, type a namespace, such as CloudTrailMetrics.
7. In the Metric Name box, type a name for the metric, such as IAMAuthnAuthzActivity.
8. Click Show advanced metric settings.
9. Click Metric Value, and then type 1. This means that each CloudTrail event that matches this filter will contribute a metric of one unit. This is important for configuring the alarm later.
10. Click Create Filter.

The following image shows what the metric configuration looks like in the CloudWatch console for the “Monitor changes to authentication and authorization configuration” filter pattern mentioned previously in this post:

Create a CloudWatch alarm for IAM changes

After you complete the previous steps, you should see your newly created CloudWatch metric (in our example, we’ve used IAMAuthnAuthzActivity). You can now treat this as any other CloudWatch alarm, so follow these steps to receive a notification when IAM changes are made:

1. Select Create Alarm (if you are proceeding directly from the previous procedure), or select your newly created metric, and then click Next in the Create Alarm interface.
2. Give the alarm a name such as IAMAuthnAuthzActivityAlarm.
3. Set the alarm to trigger when your metric is >= 1 for 1 consecutive period.
4. Select your notification channel, configured in prerequisite #2 at the beginning of this blog post.
5. Set the period to 5 Minutes and the statistic to Sum.

The following screen shot shows how the alarm appears in the CloudWatch console:

Sample alarm

When the alarm is triggered, you’ll see an SNS message or email with the following details:

Alarm Details:

- Name:                       IAMAuthnAuthzActivityAlarm

- State Change:               INSUFFICIENT_DATA -> ALARM

- Reason for State Change:    Threshold Crossed: 1 datapoint (1.0) was greater than or equal to the threshold (1.0).

- Timestamp:                  Monday 26 January, 2015 21:50:52 UTC

- AWS Account:                123456789012

Threshold:

- The alarm is in the ALARM state when the metric is GreaterThanOrEqualToThreshold 1.0 for 300 seconds.

This is your cue to review your CloudTrail logs and figure out who made changes to your account.

Ideally, all unexpected changes could be prevented, but monitoring IAM security configuration changes allows you another layer of defense against the unexpected. Create an alarm for IAM events that are important to you, and have a response plan ready for such unexpected situations.

If you have questions or feedback about this or any other IAM topic, please visit the IAM forum.

– Will