This repository contains a production-ready CloudFormation template that deploys a comprehensive security auditing and observability suite. It configures an Organizational CloudTrail with KMS encryption, dedicated S3 storage, and an automated alerting pipeline that sends enriched security notifications to Slack/Atlassian webhooks and email.
The solution implements the following components:
- Audit Logging: An Organizational CloudTrail that captures management events across all regions and accounts within the AWS Organization.
- Security Storage: Encrypted S3 buckets with automated lifecycle policies and dedicated access logging for audit integrity.
- Encryption: A Customer Managed Key (CMK) in KMS for trail encryption, ensuring compliance with AWS Security Hub best practices.
- Observability & Alerting:
- Metric Filters: Scans CloudWatch Logs for 12+ specific security patterns (Unauthorized API calls, Root usage, etc.).
- Alarms: Triggers SNS notifications when security thresholds are met.
- Lambda Integration: Python-based Lambda functions catch EventBridge triggers, process log context, and deliver formatted alerts to Slack/Teams via webhooks.
- Centralized Dashboard: A CloudWatch Dashboard for visual auditing of root usage, backup failures, and IAM changes.
The following events are monitored via CloudWatch Metric Filters and EventBridge Rules. When a threshold is met, the system triggers an SNS notification and updates the central dashboard.
| Event / Alarm Name | Description | Compliance / Standard |
|---|---|---|
| RootAccountUsage | Detects any usage of the AWS Root account (logins or API calls). | CIS 3.3 (Root Usage) |
| UnauthorizedAPICalls | Monitors for multiple AccessDenied or UnauthorizedOperation errors. |
CIS 3.1 (Auth Failures) |
| ConsoleSigninWithoutMFA | Alerts when an IAM user signs into the console without Multi-Factor Authentication. | CIS 3.2 (MFA Usage) |
| DisableOrDeleteCMK | Alerts if a Customer Master Key (KMS) is disabled or scheduled for deletion. | CIS 3.7 (KMS Integrity) |
| CloudTrailChanges | Detects attempts to stop, update, or delete the audit logging trail. | CIS 3.5 (Logging Config) |
| IAMPolicyChanges | Monitors for modifications to IAM policies, roles, or permissions. | CIS 3.4 (IAM Integrity) |
| AWSConfigChanges | Detects changes to AWS Config recorders or delivery channels. | CIS 3.9 (Config Changes) |
| NetworkGatewayChanges | Monitors changes to Internet Gateways, VGWs, and Customer Gateways. | CIS 3.12 (Network Arch) |
| SecurityGroupChanges | Alerts when Security Group rules are modified or deleted. | CIS 3.10 (VPC Security) |
| VPCRouteChanges | Detects changes to VPC Route Tables (potential traffic redirection). | CIS 3.13 (Routing) |
| NewIAMUserCreated | Alerts security teams whenever a new IAM user is provisioned. | Internal Governance |
| NewElevatedAccess | Detects users assuming SSO roles with "-Elevated_" in the name. | Privileged Access Mgmt |
| AWSBackupJobFailed | Alerts immediately if an AWS Backup job fails to complete. | Data Resilience |
| AWSBackupJobIssues | Detects backups that completed but had issues (e.g., VSS errors). | Data Integrity |
| BackupCopyFailed | Monitors for failures in cross-region/cross-account backup copies. | Disaster Recovery |
| Parameter | Description | Default Value |
|---|---|---|
| S3BucketName | Name of the S3 bucket that will host all CloudTrail logs. | s3-cloudtrail-logs |
| AccessLoggingS3BucketName | Name of the S3 bucket that will host all access logs for the CloudTrail bucket. | s3-cloudtrail-logs-access-log |
| CloudTrailName | Name of CloudTrail trail. | Organization-CloudTrail |
| IAMRoleForCloudTrailName | Name of the IAM role needed by CloudTrail to write to CloudWatch. | iam-org-cloudtrail |
| CloudWatchLogGroupName | Name of the CloudWatch LogGroup for CloudTrail logs. | aws-cloudwatch-cloudtrail-logs |
| SNSTopicName | Name of the SNS topic used by Lambda functions to send alerts to Slack channels. | aws-sns-cloudtrail-logs |
| CloudTrailSNSSubscription | Slack/Atlassian webhook for notifications. | https://some.notification/... |
| SNSTopicNameForCloudWatch | Name of the SNS topic used by CloudWatch Alarms to send alerts to an email address. | aws-snstopic-cloudtrail-logs-for-cloudwatch |
| LambdaSNSTopicExceptions | Name of the SNS topic for Lambda function exceptions. | aws-snstopic-cloudtrail-lambda-exceptions |
| LambdaExceptionsSNSSubscription | Slack/Atlassian webhook for Lambda function exceptions. | https://some.exception/... |
| CloudTrailSNSSubscriptionForCloudWatch | Email address for security compliance notifications. | something@something.com |
| KMSKeyAlias | Alias of the Customer managed KMS key to encrypt CloudTrail logs in S3. | kms-org-cloudtrail |
| AWSRootAccountID | ID of the root account where CloudTrail is configured. | 123456789123 |
| AWSOrgID | ID of the AWS Organization. | o-abcdefghiz |
| CloudTrailCloudWatchDashboardName | Name of the CloudWatch Dashboard for CloudTrail alerts. | dashboard-cloudtrail-alerts |
| CloudWatchDashboardUrl | Url of the shared CloudWatch Dashboard. | https://cloudwatch.amazonaws.com/... |
- The stack must be deployed in the Management Account of your AWS Organization.
aws cloudformation deploy \
--template-file aws-cloudtrail-observability.yaml \
--stack-name security-observability-stack \
--parameter-overrides \
AWSRootAccountID="123456789012" \
AWSOrgID="o-yourorgid" \
CloudTrailSNSSubscription="[https://your.webhook.url](https://your.webhook.url)" \
[...]
--capabilities CAPABILITY_NAMED_IAM- Upload: Log into the Management Account, navigate to CloudFormation, and upload the aws-cloudtrail-observability.yaml file.
- Parameters: Fill in the required fields. You must customize, at a minimum, parameters like
AWSRootAccountID,AWSOrgID,S3BucketName,AccessLoggingS3BucketName,CloudTrailName,CloudWatchDashboardUrl, and the topics subscriptions to match your environment. - IAM Acknowledge: On the final review page, you must check the box: "I acknowledge that AWS CloudFormation might create IAM resources with custom names."
- Deploy: Click Submit.
The dashboard provides a "single pane of glass" view for security events. You can access it via the URL provided in the CloudWatchDashboardUrl parameter or by navigating to CloudWatch > Dashboards in the AWS Console.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.