AWS CDK Root Account Use Alarm

A serverless AWS CDK stack that sets up an Amazon EventBridge alarm to detect root account logins and sends notifications via Amazon SNS, with optional CloudTrail integration for monitoring.

Overview

This project provides two CDK stack variations to monitor root account usage:

• RootAccountUseAlarmStack: Deploys an EventBridge alarm using an existing CloudTrail trail.
• RootAccountUseAlarmWithCloudTrailStack: Includes a dedicated CloudTrail trail for root account management events alongside the alarm.

Notifications are sent via Amazon SNS when root account logins are detected, enhancing account security.

Table of Contents

• Features
• Prerequisites
• Installation
• Deployment
• Cleanup
• Additional Resources

Features

• Root Account Monitoring: Detects root account logins using Amazon EventBridge.
• Flexible Deployment: Supports existing CloudTrail trails or creates a new one.
• Notification System: Sends alerts via Amazon SNS.
• CDK-Based: Infrastructure defined and deployed using AWS Cloud Development Kit (CDK).
• Security Focused: Helps enforce best practices by alerting on unauthorized root usage.

Prerequisites

• AWS CLI: Installed and configured with appropriate credentials.
• Node.js: Required for AWS CDK (version 14 or higher recommended).
• Python: Version 3.8 or higher (for virtual environment setup).
• AWS Account: With permissions to create EventBridge rules, CloudTrail trails, and SNS topics.

Installation

1. Clone the repository:

   git clone https://github.com/username/repo.git
   cd aws-cdk-root-account-use-alarm

2. Create and activate a virtual environment:
   • MacOS/Linux:

     python3 -m venv .venv
     source .venv/bin/activate

   • Windows:

     py -3 -m venv .venv
     .venv\Scripts\activate.bat

3. Install dependencies:

   pip install -r requirements.txt

Deployment

1. Synthesize the CloudFormation template:

   cdk synth

2. Deploy one of the following stacks based on your needs:
   • Option 1: With CloudTrail Trail (if no existing trail or want a dedicated one):

     cdk deploy RootAccountUseAlarmWithCloudTrailStack --parameters email=<your-email> --profile <your-profile>

   • Option 2: With Existing Trail:

     cdk deploy RootAccountUseAlarmStack --parameters email=<your-email> --profile <your-profile>

   • Notes:
     • Replace <your-email> with the email address to receive SNS notifications.
     • Replace <your-profile> with your AWS CLI profile name.

Cleanup

To remove the stack and its resources from your AWS account:

cdk destroy --profile <your-profile>

• Replace <your-profile> with your AWS CLI profile name.
• This command deletes all resources created by the deployed stack.

Additional Resources

• AWS CDK Documentation
• AWS CloudTrail Documentation
• Amazon SNS Documentation
• Amazon EventBridge Documentation