How aws-solutions/aws-waf-security-automations works
Project type and purpose
• This is a serverless, microservices-based AWS solution (“Security Automations for AWS WAF”).
• It deploys multiple AWS Lambda functions (microservices) that integrate with AWS WAF, CloudFront/ALB, S3, Athena, CloudWatch Events, and third-party IP lists to automate threat detection and blocking.
File structure
• Top-level directories:
• deployment/ – CloudFormation templates, build and test scripts
• source/ – all Lambda microservices, helpers, custom resources, and shared libraries
• Under source/, you have:
• access_handler/ – Lambda for honeypot endpoint access (bad-bot detection)
• custom_resource/ – CloudFormation custom resources (provisioning support)
• helper/ – CFN dependency checks and auxiliary functions
• ip_retention_handler/ – scheduled IP set cleanup
• log_parser/ – processes access logs (S3/Athena) for suspicious traffic
• reputation_lists_parser/ – hourly ingestion of external IP reputation feeds
• timer/ – CloudWatch-triggered “sleep” function to pace resource creation
• lib/ – shared utilities (Boto3 wrappers, logging, metrics, DynamoDB/S3/SNS helpers)
• Configuration and test files show each microservice is packaged with Poetry (pyproject.toml) and covered by pytest.
README insights
• The solution groups protections into rule-group categories (AWS managed rules, manual IP lists, SQLi/XSS, HTTP flood, scanner & probe, IP reputation lists, bad bot honeypot).
• It triggers Lambda functions via CloudWatch Events (timers), S3 events (log arrivals), API Gateway (honeypot), and during CFN deployment (custom resources).
• CloudFormation templates and build scripts in deployment/ build assets, push to S3, then launch the stack.
Main components
• External / AWS services:
• Amazon CloudFront distribution or Application Load Balancer (entry point)
• AWS WAF Web ACL & IP Sets (rule groups, block/allow lists)
• Amazon S3 buckets:
– Access logs bucket (for CloudFront/ALB logs)
– Deployment asset buckets (global/regional)
• Amazon Athena / AWS Glue (for log queries and partitioning)
• Amazon CloudWatch Events / EventBridge (scheduled triggers)
• Third-party IP Reputation feeds (Spamhaus, ET, Tor)
• Microservice Lambdas:
• access_handler
• log_parser
• reputation_lists_parser
• ip_retention_handler
• custom_resource Lambdas (resource_manager, log_group_retention, operation handlers)
• timer function
• Build & deployment:
• Local CLI (Poetry, AWS CLI) → deployment/build-s3-dist.sh → S3 buckets → CloudFormation stack launch
Relationships & interactions
• Client traffic → CloudFront/ALB → inspected by AWS WAF Web ACL (rule groups)
• CloudFront/ALB logs → S3 → S3 event → log_parser Lambda → Analyze via Athena → update WAF IP Sets
• Scheduled CloudWatch Events →
• reputation_lists_parser → fetch external IP lists → update WAF IP Sets
• ip_retention_handler → remove expired IPs from allow/deny sets
• timer → pace custom_resource deployments
• API Gateway (or CloudFront function) → access_handler Lambda → add offending IP to WAF block list (honeypot)
• CloudFormation custom_resource Lambdas run during stack creation to configure buckets, WebACL, partitions, metrics, etc.
• All Lambdas utilize shared lib/ utilities for AWS calls, metrics collection, and CFN responses.
Architectural patterns & design principles
• Microservices: each Lambda focuses on a single domain of protection
• Event-driven: triggers via S3 events, schedules, API calls
• Infrastructure as code: CloudFormation with custom resources
• Shared library for common logic (DRY principle)
• Test-driven: pytest and coverage configurations per microservice
Final recommendations
• Essential AWS resources and Lambdas—avoid omitting any microservice.
• Both runtime flows (traffic, events) and deployment flows (build, deploy, configure).