Monitor IAM root user activity - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAdditional information

Monitor IAM root user activity

Created by Mostefa Brougui (AWS)

Code repository: aws-iam-root-user-activity-monitor

Environment: PoC or pilot

Technologies: Security, identity, compliance; Management & governance

Workload: All other workloads

AWS services: Amazon EventBridge; AWS Lambda; Amazon SNS; AWS Identity and Access Management

Summary

Every Amazon Web Services (AWS) account has a root user. As a security best practice for AWS Identity and Access Management (IAM), we recommend that you use the root user to complete the tasks that only the root user can perform. For the complete list, see Tasks that require root user credentials in the AWS Account Management Reference Guide. Because the root user has full access to all of your AWS resources and billing information, we recommend that you don’t use this account and monitor it for any activity, which might indicate that the root user credentials have been compromised.

Using this pattern, you set up an event-driven architecture that monitors the IAM root user. This pattern sets up a hub-and-spoke solution that monitors multiple AWS accounts, the spoke accounts, and centralizes management and reporting in a single account, the hub account.

When the IAM root user credentials are used, Amazon CloudWatch and AWS CloudTrail record the activity in the log and trail, respectively. In the spoke account, an Amazon EventBridge rule sends the event to the central event bus in the hub account. In the hub account, an EventBridge rule sends the event to an AWS Lambda function. The function uses an Amazon Simple Notification Service (Amazon SNS) topic that notifies you of the root user activity.

In this pattern, you use an AWS CloudFormation template to deploy the monitoring and event-handling services in the spoke accounts. You use a HashiCorp Terraform template to deploy the event-management and notification services in the hub account.

Prerequisites and limitations

Prerequisites

  1. Permissions to deploy AWS resources in your AWS environment.

  2. Permissions to deploy CloudFormation stack sets. For more information, see Prerequisites for stack set operations (CloudFormation documentation).

  3. Terraform installed and ready to use. For more information, see Get Started – AWS (Terraform documentation).

  4. An existing trail in each spoke account. For more information, see Getting started with AWS CloudTrail (CloudTrail documentation).

  5. The trail is configured to send events to CloudWatch Logs. For more information, see Sending events to CloudWatch Logs (CloudTrail documentation).

  6. Your hub and spoke accounts must be managed by AWS Organizations.

Architecture

The following diagram illustrates the building blocks of the implementation.

An event in a spoke account creating an email notification in a hub account

  1. When the IAM root user credentials are used, CloudWatch and CloudTrail record the activity in the log and trail, respectively.

  2. In the spoke account, an EventBridge rule sends the event to the central event bus in the hub account.

  3. In the hub account, an EventBridge rule sends the event to a Lambda function.

  4. The Lambda function uses an Amazon SNS topic that notifies you of the root user activity.

Tools

AWS services

  • AWS CloudFormation helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and Regions.

  • AWS CloudTrail helps you audit the governance, compliance, and operational risk of your AWS account.

  • Amazon CloudWatch Logs helps you centralize the logs from all your systems, applications, and AWS services so you can monitor them and archive them securely.

  • Amazon EventBridge is a serverless event bus service that helps you connect your applications with real-time data from a variety of sources. For example, AWS Lambda functions, HTTP invocation endpoints using API destinations, or event buses in other AWS accounts.

  • AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.

  • AWS Lambda is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use.

  • Amazon Simple Notification Service (Amazon SNS) helps you coordinate and manage the exchange of messages between publishers and clients, including web servers and email addresses.

Other tools and services

  • Terraform is a CLI application for provisioning and managing cloud infrastructure and resources by using code, in the form of configuration files.

Code repository

The source code and templates for this pattern are available in a GitHub repository. This pattern provides two templates:

  • A Terraform template containing the resources you deploy in the hub account

  • A CloudFormation template you deploy as a stack set instance in the spoke accounts

The repository has the following overall structure.

.
 |__README.md
 |__spoke-stackset.yaml
 |__hub.tf
 |__root-activity-monitor-module
     |__main.tf  # contains Terraform code to deploy resources in the Hub account
     |__iam      # contains IAM policies JSON files
         |__ lambda-assume-policy.json          # contains trust policy of the IAM role used by the Lambda function
         |__ lambda-policy.json                 # contains the IAM policy attached to the IAM role used by the Lambda function
     |__outputs  # contains Lambda function zip code

The Epics section provides step-by-step instructions for deploying the templates.

Epics

TaskDescriptionSkills required

Clone the sample code repository.

  1. Open the AWS IAM Root User Activity Monitor repository.

  2. On the Code tab, above the file list, choose Code, and then copy the HTTPS URL.

  3. In a command-line interface, change your working directory to the location where you want to store the sample files.

  4. Enter the following command:

    git clone <repoURL>
General AWS

Update the Terraform template.

  1. Retrieve your organization ID. For instructions, see Viewing the details of an organization from the management account (AWS Organizations documentation).

  2. In the cloned repository, open hub.tf.

  3. Update the following with the appropriate values for your environment:

    • OrganizationId – Add your organization ID.

    • SNSTopicName – Add a name for the Amazon SNS topic.

    • SNSSubscriptions – Add the email to which Amazon SNS notifications should be sent.

    • Region – Add the AWS Region code where you are deploying the resources. For example, eu-west-1.

    • Tags – Add your tags. For more information, see Tagging AWS resources (AWS General Reference).

  4. Save and close the hub.tf file.

General AWS

Deploy the resources to the AWS hub account.

  1. In the Terraform command-line interface, navigate to the root folder of the cloned repository, and then enter the following command.

    terraform init && terraform plan

  2. Review the output and confirm you want to create the resources described.

  3. Enter the following command.

    terraform apply

  4. When prompted, confirm the deployment by entering yes.

General AWS
TaskDescriptionSkills required

Deploy the CloudFormation template.

  1. Sign in to the AWS Management Console, and open the CloudFormation console.

  2. From the navigation pane, choose StackSets.

  3. At the top of the StackSets page, choose Create StackSet.

  4. Under Permissions, choose Service-managed permissions. CloudFormation automatically configures the permissions required to deploy to the target accounts managed by AWS Organizations.

  5. Under Prerequisite - Prepare template, choose Template is ready.

  6. Under Specify Template, choose Upload a template file.

  7. Choose Choose file, and then in the cloned repository, select spoke-stackset.yaml.

  8. Choose Next.

  9. On the Specify StackSet details page, enter a name for the stack set.

  10. Under Parameters, enter the account ID of the hub account, and then choose Next.

  11. On the Configure StackSet options page, under Tags, add your tags.

  12. Under Execution configuration, choose Inactive, and then choose  Next.

  13. On the Set deployment options page, specify the organizational units and Regions where you want to deploy the stack set, then choose Next.

  14. On the Review page, select I acknowledge that AWS CloudFormation might create IAM resources, and then choose Submit. CloudFormation starts deploying your stack set.

For more information and instructions, see Create a stack set (CloudFormation documentation).

General AWS
TaskDescriptionSkills required

Use the root user credentials.

  1. Sign into a spoke account or the hub account by using the root user credentials.

  2. Confirm that the email account you specified receives the Amazon SNS notification.

General AWS

Related resources

Additional information

Amazon GuardDuty is a continuous security monitoring service that analyzes and processes logs to identify unexpected and potentially unauthorized activity in your AWS environment. As an alternative to this solution, if you have enabled GuardDuty, it can alert you when the root user credentials have been used. The GuardDuty finding is Policy:IAMUser/RootCredentialUsage, and the default severity is Low. For more information, see Managing Amazon GuardDuty findings.