WafBuilder¶

Purpose¶

The WafBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create AWS WAF v2 Web ACLs for CloudFront distribution protection. This builder creates comprehensive web application firewalls with AWS Managed Rules, custom rate limiting, and organizational security standards to protect against common web exploits, malicious traffic, DDoS attacks, and automated threats.

Dependencies¶

Required AWS Permissions¶

WAF Management: Create, configure, and manage WAF v2 Web ACLs and rules
CloudWatch Metrics: Create and publish metrics for WAF monitoring and alerting
Parameter Store: Store Web ACL ARNs for cross-stack integration and reference
Resource Tagging: Apply organizational tags to WAF resources for governance
CloudFormation: Manage WAF resource lifecycle and stack dependencies

Foundation Dependencies¶

Environment Configuration: Account and region mappings for multi-environment deployments
Naming Standards: Organizational resource naming conventions following organization patterns
Tagging Strategy: Consistent tagging for cost allocation, security policies, and operational categorization
Cross-Stack Integration: Parameter Store for sharing Web ACL references with CloudFront distributions

Configuration¶

This builder supports both zero-configuration deployment with AWS security best practices, and advanced configuration through the WafConfig model for custom rule overrides and rate limiting.

Zero-Configuration Mode¶

When no configuration is provided, the builder automatically applies:

All AWS Managed Rules with default actions
Rate limiting of 300 requests per 5-minute window per IP
Standard organizational naming and tagging

Advanced Configuration Mode¶

The builder uses the WafConfig model for validation of custom settings and becomes the authoritative source of all WAF configurations.

CDK Configuration Structure¶

The builder's configuration values should be sourced from the cdk.json file. The expected structure is as follows:

{
  "common_ruleset_overrides": {
    "SizeRestrictions_BODY": "allow"
  },
  "ip_reputation_overrides": {
    "AWSManagedIPDDoSList": "allow"
  },
  "bad_inputs_overrides": {
    "Log4JRCE_QUERYSTRING": "allow"
  },
  "sqli_overrides": {
    "SQLi_BODY": "allow"
  },
  "bot_control_overrides": {
    "CategoryArchiver": "allow"
  },
  "rate_limit": 500

}

Configuration Parameters¶

Parameter	Mandatory	Type	Default	Description
common_ruleset_overrides	No	Dict		Rule overrides for AWSManagedRulesCommonRuleSet
ip_reputation_overrides	No	Dict		Rule overrides for AWSManagedRulesAmazonIpReputationList
bad_inputs_overrides	No	Dict		Rule overrides for AWSManagedRulesKnownBadInputsRuleSet
sqli_overrides	No	Dict		Rule overrides for AWSManagedRulesSQLiRuleSet
bot_control_overrides	No	Dict		Rule overrides for AWSManagedRulesBotControlRuleSet
rate_limit	No	Dict	300	Rate limit per 5 minutes per IP

Rule Override Actions¶

Each rule override can specify one of three actions:

Action	Description	Use Case
allow	Permits the request to continue	When rule produces false positives for legitimate traffic
block	Terminates the request with 403 Forbidden	Default for most security rules, blocks malicious requests
count	Logs the match but allows request	Testing and monitoring mode before applying blocks

Usage¶

Here’s an example of how to use the WafBuilder to build a WAF in a CDK stack:

waf_config = app_helper.get_from_env("waf")

waf_builder = WafBuilder()
waf_builder.set_application_helper(app_helper) \
           .set_builder_config(waf_config) \
           .build(scope_from_stack)

Behavior and Features¶

Automatic Security Configuration¶

Multi-Layer Protection:¶

Rate Limiting: 300 requests per 5 minutes per IP address to prevent abuse and DDoS
IP Reputation Filtering: AWS managed list of known malicious IP addresses and botnets
OWASP Top 10 Protection: Core rule set defending against common web application vulnerabilities
Input Validation: Detection and blocking of known malicious request patterns and payloads
SQL Injection Prevention: Advanced SQL injection attack detection using AWS managed rules
Bot Protection: Automated bot detection and mitigation for non-human traffic

CloudFront Optimization:¶

Global Edge Protection: WAF rules applied at CloudFront edge locations worldwide
Low Latency: Minimal impact on legitimate traffic performance
Automatic Scaling: Handles traffic spikes without capacity planning
Regional Compliance: Supports data sovereignty and regional security requirements

Monitoring and Observability:¶

CloudWatch Integration: Comprehensive metrics collection for all rules and overall WAF performance
Sampled Request Logging: Security analysis and threat intelligence gathering
Custom Metrics: Organizational naming patterns for consistent monitoring across environments
Alert Integration: Compatible with CloudWatch alarms and security dashboards

Naming Convention¶

WAF resources follow the pattern: {organization-prefix}-{environment}-waf

The builder automatically:

Applies organizational naming standards
Includes environment identifiers for multi-environment deployments
Truncates names to respect AWS WAF limits
Creates unique metric names for CloudWatch integration

Parameter Store Integration¶

Each WAF automatically creates Parameter Store entries for cross-stack references:

Web ACL ARN: web_acl_id containing the complete WAF Web ACL ARN for CloudFront association

Security Rule Configuration, Priority and Execution Order:¶

Priority 0 - Rate Limiting Rule:¶

*Purpose: Prevent DDoS attacks and traffic abuse
*Configuration: 300 requests per 5-minute window per IP address
*Action: BLOCK requests exceeding the limit
*Customization: Rate limit can be adjusted based on application requirements

Priority 1 - IP Reputation List:¶

Purpose: Block traffic from known malicious IP addresses
Source: AWS managed list of compromised hosts and attack sources
Coverage: Botnets, scanners, and known attack infrastructure
Updates: Automatically updated by AWS threat intelligence

Priority 2 - Core Rule Set:¶

Purpose: Protection against OWASP Top 10 vulnerabilities
Coverage: XSS, CSRF, injection attacks, and common web exploits
Detection: Advanced pattern matching and signature-based detection
Maintenance: Managed and updated by AWS security team

Priority 3 - Known Bad Inputs:¶

Purpose: Detect and block malicious request patterns
Coverage: Malformed requests, exploit attempts, and attack payloads
Detection: Pattern recognition for suspicious input formats
Response: Immediate blocking of identified threats

Priority 4 - SQL Injection Protection:¶

Purpose: Advanced SQL injection attack prevention
Coverage: SQLi variations, blind SQLi, and database-specific attacks
Detection: Deep packet inspection and query analysis
Protection: Database-agnostic SQLi defense

Priority 5 - Bot Control:¶

Purpose: Automated bot detection and management
Coverage: Malicious bots, scrapers, and automated attacks
Detection: Behavioral analysis and traffic pattern recognition
Action: Selective blocking based on bot classification

Notes

The set_builder_config method from the abstract class should not be used in this builder.
The set_usage method from the abstract class should not be used in this builder.
WAF rules are applied in priority order (0-5) with lower numbers evaluated first
Rate limiting uses a 5-minute sliding window for request counting
All AWS Managed Rules are enabled with no exclusions by default
CloudWatch metrics are automatically enabled for comprehensive monitoring
Web ACL ARN is stored in Parameter Store immediately after creation
WAF protection is active at all CloudFront edge locations globally