terraform-aws-security-alerts

Real-time AWS security event monitoring. Six EventBridge rules watch for 10 high-signal CloudTrail events and fire a Lambda within seconds. The Lambda enriches and routes alerts to SNS → email + Slack via AWS Chatbot.

Architecture

CloudTrail (management events, multi-region)
        │
        ▼
EventBridge (6 rules grouped by source)
        │
        ▼
Lambda: security-alert-formatter
  - Enriches event (account alias, actor, console URL)
  - Assigns severity (CRITICAL / WARNING / INFO)
  - Filters console logins and security group rules
  - Publishes to SNS
  - On failure → SQS Dead Letter Queue
        │
        ├── SNS: security-alerts (CRITICAL / WARNING)
        │       ├── Email subscription
        │       └── AWS Chatbot → Slack #security-critical
        │
        └── SNS: security-alerts-info (INFO)
                ├── Email subscription
                └── AWS Chatbot → Slack #security-info

Events Monitored

Severity	Event	Why It Matters
CRITICAL	CloudTrail StopLogging	Attacker disabling your audit trail
CRITICAL	CloudTrail DeleteTrail	Attacker removing audit trail entirely
CRITICAL	CloudTrail UpdateTrail	Trail scope being silently reduced
CRITICAL	CloudTrail PutEventSelectors	Selectively filtering what gets logged
CRITICAL	IAM CreateUser	Plain IAM user in an Identity Center account = incident
CRITICAL	IAM CreateAccessKey	Legacy access keys not permitted
CRITICAL	Console login without MFA	Credential exposure risk
WARNING	Failed console login	Brute force / credential stuffing
CRITICAL	Security group 0.0.0.0/0 or ::/0	Unintentional internet exposure
INFO	SSO CreateUser	Informational — new Identity Center user added

Improvements Over a Naive Implementation

• Grouped rules: CloudTrail tampering events share one rule (less rule overhead, easier management)
• IPv6 coverage: Security group check also catches ::/0 rules
• AWS Chatbot instead of custom webhook: Native SNS → Slack integration, no webhook URL to rotate
• Severity tiers: CRITICAL/WARNING go to one SNS topic; INFO goes to another (separate Slack channel)
• Dead Letter Queue: Failed Lambda invocations land in SQS; CloudWatch alarm fires if Lambda errors
• Lambda enrichment: Every alert includes account alias, actor ARN, source IP, event time, and a console URL
• Encrypted SNS: Both topics use a customer-managed KMS key
• Remote state: S3 + DynamoDB locking from day one

Prerequisites

• AWS CLI configured with SSO (aws sso login --profile <profile>)
• Terraform >= 1.6
• Make
• Slack workspace with AWS Chatbot OAuth completed (one-time manual step — see HOW-TO-USE.md)
• CloudTrail trail already enabled (or set create_cloudtrail = true)

Inputs

Variable	Description	Default
aws_region	Deployment region	us-east-1
account_name	Human-readable name in alert messages	required
alert_email	Email for SNS subscriptions	required
slack_workspace_id	Slack workspace ID for Chatbot	required
slack_channel_id	Slack channel for CRITICAL/WARNING alerts	required
slack_channel_id_info	Slack channel for INFO alerts	same as above
create_cloudtrail	Create a new trail if one doesn't exist	false
cloudtrail_name	Name of existing or new trail	management-events

Outputs

Output	Description
sns_topic_arn	CRITICAL/WARNING SNS topic ARN
sns_topic_arn_info	INFO SNS topic ARN
lambda_function_name	Alert formatter function name
lambda_dlq_url	Dead Letter Queue URL
eventbridge_rule_arns	Map of all rule ARNs

Required IAM Permissions (deployer)

The identity running terraform apply needs:

cloudtrail:* (if create_cloudtrail = true)
events:*
lambda:*
iam:CreateRole, iam:PutRolePolicy, iam:AttachRolePolicy, iam:PassRole
sns:*
sqs:*
kms:*
chatbot:*
logs:*
s3:* (on the state bucket and trail log bucket)
dynamodb:* (on the lock table)

Project Structure

terraform-aws-security-alerts/
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf
├── backend.tf
├── terraform.tfvars.example
├── Makefile
├── .gitignore
├── .env.example
└── modules/
    ├── cloudtrail/     Trail creation (conditional)
    ├── eventbridge/    6 EventBridge rules
    ├── lambda/         Alert formatter + DLQ + IAM + CloudWatch alarm
    └── notifications/  SNS topics + email + AWS Chatbot