AWS WAF

Creates an AWS WAFv2 Web ACL with managed rules, custom rule groups, and custom rules.

Use this module when a Rabbit service needs WAF protection for CloudFront or regional AWS resources.

Supported Features

• WAFv2 Web ACL creation.
• CLOUDFRONT and REGIONAL scopes.
• Default allow or block action.
• AWS managed rule groups.
• Custom rule groups created by the module.
• Rule group references.
• Rate-based rules.
• Byte-match rules.
• IP set references.
• Managed rule action overrides.
• ATP managed rule group configuration.
• Visibility and CloudWatch metric settings.

Prerequisites

• AWS credentials with permission to manage WAFv2 Web ACLs and rule groups.
• For CLOUDFRONT scope, deploy in us-east-1.
• Any referenced IP sets or external rule groups must already exist.
• CloudFront association is configured from the CloudFront module by using web_acl_name or web_acl_id.

Important Notes

• enabled: false skips Web ACL creation.
• scope must be CLOUDFRONT or REGIONAL.
• Managed rule groups use override_action; custom rules use action.
• For a custom rule group created by this module, set rule_group_source: "create" and reference it by rule_group_name.
• For an existing rule group, set rule_group_source: "reference" and provide rule_group_arn.
• The default module config includes Rabbit-managed baseline rules. Override or disable rules by matching their exact name.

Minimal Example

services:
  - name: "AWS WAF"
    module: "aws-waf"
    id: "example-waf"
    deployment_order: 125
    configurations:
      app_name: "example-waf-#{Environment}"
      scope: "CLOUDFRONT"
      default_action: "allow"
      enabled: true
      visibility:
        cloudwatch_metrics_enabled: true
        sampled_requests_enabled: true
      rules:
        - name: "AWS-AWSManagedRulesCommonRuleSet"
          priority: 10
          type: "managed_rule_group"
          vendor_name: "AWS"
          rule_group_name: "AWSManagedRulesCommonRuleSet"
          override_action: "none"

CloudFront Usage

When WAF and CloudFront are deployed together, pass the Web ACL name to the CloudFront module:

services:
  - name: "AWS WAF"
    module: "aws-waf"
    id: "example-waf"
    deployment_order: 125
    configurations:
      app_name: "example-waf-#{Environment}"
      scope: "CLOUDFRONT"

  - name: "AWS CloudFront Distribution"
    module: "aws-cloudfront-distribution"
    id: "example-cloudfront"
    deployment_order: 130
    configurations:
      web_acl_name: "example-waf-#{Environment}"

For an existing Web ACL, pass its ARN as web_acl_id in the CloudFront module.

Outputs

Output	Description
aws_waf_id	Web ACL ID.
aws_waf_arn	Web ACL ARN.
custom_rule_groups	Map of custom rule group names to IDs and ARNs.

Full Configuration Schema

The fields below are public module inputs under configurations.

configurations:
  app_name: "example-waf"
  scope: "CLOUDFRONT"
  default_action: "allow"
  enabled: true
  description: "Example WAF"
  visibility: {}
  default_action_custom_request_handling: {}
  custom_rule_groups: []
  rules: []

Top-Level Fields

Field	Type	Required	Description
app_name	string	Yes	Web ACL name and default metric name.
scope	string	Yes	WAF scope: CLOUDFRONT or REGIONAL.
default_action	string	No	Web ACL default action: allow or block. Defaults to allow.
enabled	boolean	No	Enables Web ACL creation. Defaults to true.
description	string	No	Web ACL description.
visibility	object	No	Web ACL visibility settings.
default_action_custom_request_handling	object	No	Headers inserted when default action is allow.
custom_rule_groups	array[custom_rule_group]	No	Custom rule groups to create.
rules	array[rule]	No	Web ACL rules.

visibility

Field	Type	Required	Description
metric_name	string	No	CloudWatch metric name. Defaults to app_name for the Web ACL or rule name for rules.
cloudwatch_metrics_enabled	boolean	No	Enables CloudWatch metrics. Defaults to true.
sampled_requests_enabled	boolean	No	Enables sampled request collection. Defaults to true.

default_action_custom_request_handling

default_action_custom_request_handling:
  insert_headers:
    - name: "x-example-header"
      value: "example"

Field	Type	Required	Description
insert_headers	array[header]	No	Headers inserted into allowed requests handled by the default action.
insert_headers[].name	string	Yes	Header name.
insert_headers[].value	string	Yes	Header value.

custom_rule_groups

Field	Type	Required	Description
name	string	Yes	Custom rule group name.
capacity	number	Yes	WAF capacity units for the rule group.
enabled	boolean	No	Creates the rule group when true. Defaults to true.
rules	array[custom_rule_group_rule]	No	Rules inside the custom rule group.

rules

Field	Type	Required	Description
name	string	Yes	Rule name. Also used as the override key for default rules.
priority	number	Yes	Rule priority. Lower numbers run first.
enabled	boolean	No	Includes the rule when true. Defaults to true.
type	string	Yes	Rule type: managed_rule_group, rule_group_reference, rate_based, byte_match, or ip_set_reference.
action	string	Conditional	Action for non-managed rules: block, allow, or count. Defaults to block.
override_action	string	Conditional	Override action for managed rule groups and rule group references: none or count. Defaults to none.
visibility	object	No	Rule visibility settings.

Managed Rule Group Rules

rules:
  - name: "AWS-AWSManagedRulesCommonRuleSet"
    priority: 10
    type: "managed_rule_group"
    vendor_name: "AWS"
    rule_group_name: "AWSManagedRulesCommonRuleSet"
    override_action: "none"
    rule_action_overrides:
      - name: "SizeRestrictions_BODY"
        action: "count"

Field	Type	Required	Description
vendor_name	string	Yes	Managed rule group vendor, such as AWS.
rule_group_name	string	Yes	Managed rule group name.
rule_action_overrides	array[rule_action_override]	No	Per-rule action overrides.
excluded_rules	array[string or object]	No	Legacy-style exclusions converted to count overrides.
scope_down_statement	object	No	Scope-down statement for the managed rule group.
managed_rule_group_configs	object	No	Managed rule group specific configuration, such as ATP settings.

Rule Group Reference Rules

rules:
  - name: "example-custom-rules"
    priority: 20
    type: "rule_group_reference"
    rule_group_source: "create"
    rule_group_name: "example-custom-rules"
    override_action: "none"

Field	Type	Required	Description
rule_group_source	string	No	create uses a custom rule group created by this module; reference uses rule_group_arn. Defaults to reference.
rule_group_name	string	Conditional	Custom rule group name when rule_group_source is create.
rule_group_arn	string	Conditional	Existing rule group ARN when rule_group_source is reference.

Rate-Based Rules

rules:
  - name: "rate-limit-login"
    priority: 30
    type: "rate_based"
    action: "block"
    rate_based_statement:
      limit: 100
      aggregate_key_type: "IP"
      evaluation_window_sec: 300

Field	Type	Required	Description
rate_based_statement.limit	number	Yes	Request limit for the evaluation window.
rate_based_statement.aggregate_key_type	string	No	Aggregation key type. Defaults to IP.
rate_based_statement.evaluation_window_sec	number	No	Evaluation window in seconds. Defaults to 300.
rate_based_statement.scope_down_statement	object	No	Optional scope-down statement.

Byte-Match Rules

rules:
  - name: "block-dot-git"
    priority: 40
    type: "byte_match"
    action: "block"
    byte_match_statement:
      search_string: "/.git/"
      field_to_match: "uri_path"
      positional_constraint: "CONTAINS"
      text_transformations:
        - priority: 0
          type: "LOWERCASE"

Field	Type	Required	Description
byte_match_statement.search_string	string	Yes	String to match.
byte_match_statement.field_to_match	string	Yes	Field to inspect. Supported values include uri_path and query_string.
byte_match_statement.positional_constraint	string	Yes	Match position, such as CONTAINS, STARTS_WITH, or EXACTLY.
byte_match_statement.text_transformations	array[object]	No	Text transformations applied before matching.

IP Set Reference Rules

Field	Type	Required	Description
ip_set_arn	string	Yes	ARN of an existing WAFv2 IP set.