AWS Cloud Operations & Migrations Blog

Monitor and Notify on AWS Account Root User Activity

Are you aware when someone uses your AWS account credentials to perform some activity? Are you notified in time?

When you first create an AWS account, you begin only with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the root user and is accessed by signing in with the email address and password that you used to create the account.

An AWS account root user has full access to all your resources for all AWS services, including billing information. It is critical to prevent root user access from getting into the wrong hands and to be aware whenever root user activity occurs in your AWS account. For more information about AWS recommendations, see IAM Best Practices. Some of the key recommendations include:

  • Enabling multi factor authentication (MFA)
  • Setting complex passwords
  • Avoiding creating access key for root
  • Creating an admin level IAM user to perform any high privilege activities

However, there are certain actions that can only be performed by the root user. To be certain that all root user activity is authorized and expected, it is important to monitor root API calls to a given AWS account and to notify when this type of activity is detected. This notification gives you the ability to take any necessary steps when an illegitimate root API activity is detected or it can simply be used as a record for any future auditing needs.

In this post, I walk through a solution that monitors and notifies on root API activity for an AWS account.


The diagram below describes the solution at a high level.

  1. An Amazon CloudWatch Events rule detects any AWS account root user API events.
  2. It triggers an AWS Lambda function.
  3. The Lambda function then processes the root API event. It also publishes a message to an Amazon SNS topic, where the subject contains the AWS account ID or AWS account alias where the root API call was detected and the type of API activity.
  4. The SNS topic then sends notifications to its email subscribers about this event.

I walk through deploying the AWS CloudFormation stack that creates these resources and then validates that root user activity is detected and notified. It helps if you know about CloudWatch Events rulesLambda, and SNS.


Deployment steps

  1. In the CloudFormation console, choose Create Stack. Use the RootAPIMonitor.json CloudFormation JSON template. Choose Next.
  2. Create the stack in the region in which to monitor root API activity, as well as the us-east-1 region. Root API login is a global event and logged in us-east-1. I recommend deploying in all AWS regions.
  3. Enter the following parameter details and choose Next:
    • SNSTopicName: A unique name for the SNS topic to be created.
    • SNSSubscriptions: An email address to subscribe to the SNS topic. . I recommend sending these notifications to a distribution list rather than an individual.
    • LambdaTimeout: The Lambda function timeout value in seconds. The default is 30 seconds.
    • LambdaS3Bucket: Name of the S3 bucket where the Lambda function zip file is stored.
    • LambdaS3Key: Name of the Lambda function zip file. This is the full path to the S3 object, with the prefix. For example, “/dir1/dir2/”.
  4. Select Capabilities Acknowledgement and choose Create. This field gives permission to the stack to create IAM roles and policies. These roles and policies are used by the Lambda function to perform certain actions such as publishing messages to the SNS topic, listing the account alias, and so on.
  5. After the CloudFormation stack completes, check for an SNS subscription email sent to the email provided for SNSSubscriptions. Open the SubscribeURL link to complete the subscription.
  6. After the SNS topic is subscribed, the subscriber starts receiving email notification when root API activity is detected.

The CloudFormation template created three main AWS resources for this solution:

CloudWatch Events rule

The rule catches a console login event and all other API events by a root user, and triggers the Lambda function (set as a target) when such events are detected.

Lambda function

The function collects the necessary information about the root API event and publishes it to the SNS topic. The function parses the name of the event and the AWS account alias where this root API event occurred and puts them in the subject field for the message that it publishes to the SNS topic.

Code for getting the name of the event:

def lambda_handler(event, context):
		eventname = event['detail']['eventName']

Code for getting the AWS account alias:

response = client.list_account_aliases()
	logger.debug("List account alias response --- %s" %response)
		if not response['AccountAliases']:
			accntAlias = (boto3.client('sts').get_caller_identity()['Account'])"Account alias is not defined. Account ID is %s" %accntAliase)
			accntAliase = response['AccountAliases'][0]"Account alias is : %s" %accntAliase)
	except ClientError as e:
		logger.error("Client error occurred")

Code for publishing to the SNS topic:

		#Sending the notification...
		snspublish = snsclient.publish(
						TargetArn= snsARN,
						Subject=(("Root API call-\"%s\" detected in Account-\"%s\"" %(eventname,accntAliase))[:100]),

SNS topic

The topic sends the email notification published by the Lambda function.

Solution validation

Now that you have the solution deployed and ready, test and validate. First, sign in to your AWS account using your access credentials. This console login activity by a root user should send an email notification in near real time.

Next, validate if other root API events are also detected and notified on. For example, you can create an EBS volume using the root credentials and confirm that you receive an email notification in near real time.

Some AWS services—such as Auto Scaling, Elastic Load Balancing, and Trusted Advisor—use root to access resources in your AWS account, instead of an IAM role. When this happens, you see the service name in the invokedBy field of the userIdentity JSON statement. This event is legitimate and can be ignored.


In this post, I showed you how to monitor and notify on root API activity for an AWS account. This framework can be extended to monitor and notify on other IAM user activity, giving you the ability to monitor highly privileged users in near real time.

For more information, I recommend the following whitepapers:

About the Author

Sudhanshu Malhotra is a Solutions Architect at AWS Professional Services. Sudhanshu enjoys working with our customers and helping them deliver complex solutions in AWS in the area of DevOps, Infrastructure-as-Code and Config Management. In his spare time, Sudhanshu enjoys spending time with his family, hiking and tinkering with cars.