How to Receive Notifications When Your AWS Account’s Root Access Keys Are Used

AWS Identity and Access Management (IAM) best practices recommend using IAM users or roles to access your AWS resources, instead of using your root credentials. If you follow this best practice, though, how can you monitor for root activity and take action if such activity occurs? AWS CloudTrail and Amazon CloudWatch provide the solution. In this blog post, I’ll show you how to configure CloudTrail and CloudWatch to notify you when your account’s root access keys have been used to call an AWS service API.

CloudTrail is designed to record API activity for most AWS services in the CloudTrail supported regions. CloudTrail also provides a simple way to integrate with CloudWatch. In turn, CloudWatch integrates with Amazon Simple Notification Services (SNS). You can combine these three services in such a way that SNS will send you an email when CloudTrail detects root access key activity in your AWS account. The following illustration shows the steps in setting up this process.

The first step is to authorize CloudTrail to deliver its logs to CloudWatch. You complete this in the CloudTrail console. In this step you also create or select a CloudWatch Logs log group that will receive your logs from CloudTrail.

In steps 2 through 4, you use the CloudWatch console to create a filter that detects root account usage, specify the parameters under which that usage will trigger an alarm, and provide an email address where you will receive alarm notifications.

In step 5, you test the alarm by taking some AWS action with your root credentials (for example, by running an instance in the Amazon EC2 console). And in step 6, you return to the CloudTrail console, where you use its API Activity History feature to look up your event. In a real scenario, you would use this information to take corrective actions or investigate further.

Before you begin

This post assumes that you have enabled CloudTrail (= “created a trail”) in the region that you are going to use. You enable CloudTrail per region, for all of the services in that region. For the steps, see Creating a Trail in the CloudTrail documentation.

1. Turn on CloudTrail-CloudWatch Logs integration

To turn on the CloudTrail-CloudWatch integration, go to the CloudTrail console and navigate to the Configuration page.

In the CloudWatch Logs (Optional) box, click Configure.

In New or existing log group, type a name for the CloudWatch Logs log group that will receive your API activity log files from CloudTrail.

On the next page, click Allow to give CloudTrail access to your CloudWatch Logs log group.

This completes the CloudTrail-CloudWatch Logs integration step. You can also enable the integration using the create-trail CLI command for CloudTrail, or call the CreateTrail action.

2. Create a metric filter

Now that you have given CloudTrail the permission to work with CloudWatch Logs, you’ll use the CloudWatch console to create a metric filter that defines the condition that you want to monitor. In this case, your filter will detect direct usage of your root account.

1. Open the CloudWatch console.
2. In the navigation pane, click Logs.
3. In the list of log groups, select the check box next to the log group that you created for CloudTrail log events.
4. Click Create Metric Filter.
5. On the Define Logs Metric Filter screen, click Filter Pattern and then type the following:

{ $.userIdentity.type = "Root" && $.userIdentity.invokedBy NOT EXISTS && $.eventType != "AwsServiceEvent" }

6. Be sure you have typed the filter exactly as shown, and then click Assign Metric.

3. Assign a metric

Next, give your filter a name and assign a metric.

1. On the Create Metric Filter and Assign a Metric screen, in the Filter Name box, type RootAccountUsage.
2. Under Metric Details, in the Metric Namespace box, type CloudTrailMetrics.
3. In the Metric Name field, type RootAccountUsageCount.
4. Click Metric Value, and then type 1.

Note: If Metric Value does not appear, click Show advanced metric settings first.

5. When you are finished, click Create Filter.

4. Create an alarm

Now, create and specify thresholds for your alarm, and an email address to which an SNS notification will be sent whenever your alarm is triggered.

1. On the Filters for <Your_Log_Group_Name> page, next to the filter name, click Create Alarm.
2. On the Create Alarm page, provide values for the numbered fields shown in the following annotated screenshot; the table following the screenshot contains the values that I used to create the alarm.
   

   Setting	Value
   1	Root Account Usage
   2	>=1
   3	1
   4	5 Minutes
   5	Sum
   6	Near the Select a notification list box, click New list. The Email list box appears, but first type a unique topic name for the list.
   7	In the Email list box, type the email address to which you want notifications sent. (You will receive an email at this address to confirm that you created this alarm.)

   ---

   You can change these values to fit your requirements, but it’s best to stick with a period of 5 minutes or more, and use the Statistic value of Sum. However, you might want to change the RootAccountUsageCount in 2 to be greater than one, depending on your requirements.

3. When you are finished, click Create Alarm. You will be asked to confirm your email address.

4. In the email that you receive, click Confirm Subscription. In the confirmation dialog, a green arrow appears next to your email address. You’re done with this step and can close the dialog.

Now that you’re set to receive notifications, you’re ready to test your alarm.

5. Test the alarm and receive an SNS notification

To test your alarm, perform some activity with your root account. In my case, after starting with an Amazon EC2 instance, I received the following email.

6. Look up the event and take corrective actions

The notification tells me that my root account access key was used in the US East (N. Virginia) region (us-east-1). To get more information for the event, I can use the CloudTrail API Activity History feature.

In the CloudTrail console, I go to the region where the event happened and see what’s shown in the following screenshot.

I can see that, a few minutes before my SNS notification arrived, my root account key was used to call EC2 RunInstances. When I expand the event, I get even more information.

The CloudTrail log shows the IP address of the caller and the access key (obscured in the screenshot), and you can use these to take further actions—potentially by opening a trouble ticket at your company or by deactivating or deleting the access key for your root account.

By the way, you can also access the CloudTrail API Activity History feature by using the AWS CLI and the CloudTrail API. For more information, see Viewing CloudTrail Events with the AWS CLI and the CloudTrail API Reference. For the latter, I’d suggest starting with the LookupEvents API.

Where to learn more

Here are some valuable resources for managing access keys:

• Managing Access Keys for Your AWS Account
• Best Practices for Managing AWS Access Keys
• IAM Best Practices

For many more metric filters that may be of interest to you, see Creating CloudWatch Alarms for CloudTrail Events: Examples.

You can also use a downloadable CloudFormation template to set up alarms easily for common security scenarios. See Using an AWS CloudFormation Template to Create CloudWatch Alarms.

Give us your feedback!

The CloudTrail team is very interested in learning about the specific APIs and API activities you would like to monitor. If there are filters and alarms that you would like to see that we have not yet documented, please visit the CloudTrail Forum and let us know.

– Tim

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.