# AWS WAF v2 Terraform Module Terraform module which creates AWS WAF v2 Web ACL resources with comprehensive rule support. [![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) ## Usage ```hcl module "wafv2" { source = "terraform-aws-modules/wafv2/aws" name = "my-web-acl" scope = "REGIONAL" default_action = "allow" rules = { common-rule-set = { priority = 1 override_action = "none" statement = { managed_rule_group_statement = { name = "AWSManagedRulesCommonRuleSet" vendor_name = "AWS" } } } rate-limit = { priority = 2 action = "block" statement = { rate_based_statement = { limit = 1000 } } } } tags = { Environment = "dev" Terraform = "true" } } ``` ## Features - Full coverage of AWS provider WAFv2 surface: every WAFv2 resource is supported by the root module or a submodule - AWS WAF v2 Web ACL with comprehensive rule statement support - All 12+ statement types: byte match, geo match, IP set reference, label match, managed rule group, rate based, regex match, regex pattern set reference, rule group reference, size constraint, SQLi match, XSS match - Compound statements (AND, OR, NOT) with 2 levels of nesting, including AND/OR inside `scope_down_statement` - Dual-mode actions: simple string (`"allow"`, `"block"`, `"count"`, `"captcha"`, `"challenge"`) or objects with custom response/request handling - Custom response bodies - CAPTCHA and challenge configuration - Association configuration for request body size limits - Optional inline Web ACL associations - Optional inline logging configuration - Submodules for IP sets, regex pattern sets, Web ACL associations, logging configuration, custom rule groups, standalone Web ACL rules, Web ACL ↔ rule group associations, and CAPTCHA API keys ## Conditional Creation The module supports conditional resource creation: ```hcl module "wafv2" { source = "terraform-aws-modules/wafv2/aws" create = false } ``` ## Submodules - [ip-set](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/ip-set) - Manages WAF v2 IP sets - [regex-pattern-set](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/regex-pattern-set) - Manages WAF v2 regex pattern sets - [web-acl-association](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/web-acl-association) - Manages WAF v2 Web ACL associations - [logging-configuration](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/logging-configuration) - Manages WAF v2 logging configuration - [rule-group](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/rule-group) - Manages WAF v2 custom rule groups (reusable rule sets with fixed WCU capacity) - [web-acl-rule](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/web-acl-rule) - Manages a single rule attached to an existing Web ACL (provider v6.37.0+, solves IP set deletion-ordering errors) - [web-acl-rule-group-association](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/web-acl-rule-group-association) - Associates a custom or managed rule group with an existing Web ACL - [api-key](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/modules/api-key) - Manages WAFv2 API keys for CAPTCHA / JavaScript challenge token domains ## Examples - [Basic](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/basic) - Minimal example with a single managed rule group - [Complete](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/complete) - Comprehensive example with all major features - [IP Set](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/ip-set) - IP set submodule with IPv4 and IPv6 sets - [Regex Pattern Set](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/regex-pattern-set) - Regex pattern set submodule - [Web ACL Association](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/web-acl-association) - Web ACL association with a Cognito User Pool - [Logging Configuration](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/logging-configuration) - Logging configuration with CloudWatch Logs - [Rule Group](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/rule-group) - Custom rule group with sample rules - [Web ACL Rule](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/web-acl-rule) - Standalone rule attached to a Web ACL (deletion-ordering safe) - [Web ACL Rule Group Association](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/web-acl-rule-group-association) - Associate a managed and a custom rule group with a Web ACL - [API Key](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/examples/api-key) - WAFv2 API key for CAPTCHA token domains ## Module Wrappers For managing multiple similar resources, see [wrappers](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/wrappers). ## Requirements | Name | Version | |------|---------| | [terraform](#requirement\_terraform) | >= 1.5.7 | | [aws](#requirement\_aws) | >= 6.37 | ## Providers | Name | Version | |------|---------| | [aws](#provider\_aws) | >= 6.37 | ## Modules No modules. ## Resources | Name | Type | |------|------| | [aws_wafv2_web_acl.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/wafv2_web_acl) | resource | | [aws_wafv2_web_acl_association.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/wafv2_web_acl_association) | resource | | [aws_wafv2_web_acl_logging_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/wafv2_web_acl_logging_configuration) | resource | ## Inputs | Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | [association\_config](#input\_association\_config) | Configuration for body inspection size limits per resource type. Keys are resource types (e.g., `CLOUDFRONT`, `API_GATEWAY`, `COGNITO_USER_POOL`, `APP_RUNNER_SERVICE`, `VERIFIED_ACCESS_INSTANCE`) |

map(object({
    default_size_inspection_limit = string
  }))

| `{}` | no | | [association\_resource\_arns](#input\_association\_resource\_arns) | Map of resource ARNs to associate with the Web ACL. Key is a friendly name, value is the resource ARN | `map(string)` | `{}` | no | | [captcha\_config](#input\_captcha\_config) | CAPTCHA configuration for the Web ACL. Specifies how long a CAPTCHA timestamp is considered valid |

object({
    immunity_time_property = object({
      immunity_time = number
    })
  })

object({
    immunity_time_property = object({
      immunity_time = number
    })
  })

map(object({
    content      = string
    content_type = string
  }))

| `{}` | no | | [data\_protection\_config](#input\_data\_protection\_config) | Data protection configuration. `data_protections` is a list of objects with `field` (object with `field_keys` list and `field_type` one of `SINGLE_HEADER`/`SINGLE_COOKIE`/`SINGLE_QUERY_ARGUMENT`/`QUERY_STRING`/`BODY`), `action` (`HASH` or `SUBSTITUTION`), `exclude_rate_based_details` (bool, optional), and `exclude_rule_match_details` (bool, optional) | `any` | `null` | no | | [default\_action](#input\_default\_action) | Action to perform if none of the rules contained in the Web ACL match. Use `allow` or `block` for simple actions, or provide an object for custom request handling/response. See examples for object structure | `any` | `"allow"` | no | | [description](#input\_description) | A friendly description of the Web ACL | `string` | `null` | no | | [logging\_filter](#input\_logging\_filter) | A configuration block that specifies which web requests are kept in the logs and which are dropped |

object({
    default_behavior = string
    filters = list(object({
      behavior    = string
      requirement = string
      conditions = list(object({
        action_condition = optional(object({
          action = string
        }))
        label_name_condition = optional(object({
          label_name = string
        }))
      }))
    }))
  })

| `null` | no | | [logging\_log\_destination\_configs](#input\_logging\_log\_destination\_configs) | The Amazon Kinesis Data Firehose, CloudWatch Log Group, or S3 Bucket ARNs for the logging destination. Names must be prefixed with `aws-waf-logs-` | `list(string)` | `[]` | no | | [logging\_redacted\_fields](#input\_logging\_redacted\_fields) | The parts of the request that you want to keep out of the logs. Each entry must specify exactly one of `method`, `query_string`, `uri_path`, or `single_header` |

list(object({
    method        = optional(object({}))
    query_string  = optional(object({}))
    uri_path      = optional(object({}))
    single_header = optional(object({ name = string }))
  }))

| `[]` | no | | [logging\_region](#input\_logging\_region) | Region where the WAF logging configuration will be managed. Defaults to the provider region | `string` | `null` | no | | [name](#input\_name) | A friendly name of the Web ACL. Mutually exclusive with `name_prefix` | `string` | `null` | no | | [name\_prefix](#input\_name\_prefix) | Creates a unique name beginning with the specified prefix. Mutually exclusive with `name` (provider rejects both being set at apply time) | `string` | `null` | no | | [putin\_khuylo](#input\_putin\_khuylo) | Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Russian_invasion_of_Ukraine | `bool` | `true` | no | | [rule\_json](#input\_rule\_json) | Escape hatch: JSON string of WAF rules for cases where dynamic blocks cannot represent all provider features. Mutually exclusive with `rules` | `string` | `null` | no | | [rules](#input\_rules) | Map of WAF rule configurations. The key is used as the rule name.

Each rule supports:
- `priority` - (Required) Rule priority (lower = evaluated first)
- `action` - Action for standalone rules. Use string (`allow`, `block`, `count`, `captcha`, `challenge`) or object for custom response
- `override_action` - Override action for managed/rule group rules. Use string (`none`, `count`) or object
- `statement` - (Required) Rule statement configuration. See AWS provider docs for statement structure
- `visibility_config` - CloudWatch metrics config. Auto-generated from rule key if omitted
- `captcha_config` - Optional CAPTCHA configuration
- `challenge_config` - Optional challenge configuration
- `rule_labels` - Optional list of labels to add to matching requests

See examples/complete for usage patterns. | `any` | `{}` | no | | [scope](#input\_scope) | Specifies whether this is for an AWS CloudFront distribution or for a regional application. Valid values are `CLOUDFRONT` or `REGIONAL` | `string` | `"REGIONAL"` | no | | [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no | | [token\_domains](#input\_token\_domains) | Specifies the domains that AWS WAF should accept in a web request token. Enables token use across multiple protected resources | `list(string)` | `[]` | no | | [visibility\_config](#input\_visibility\_config) | Visibility configuration for the Web ACL. Defines CloudWatch metrics configuration |

object({
    cloudwatch_metrics_enabled = optional(bool, true)
    metric_name                = optional(string)
    sampled_requests_enabled   = optional(bool, true)
  })

| `{}` | no | ## Outputs | Name | Description | |------|-------------| | [logging\_configuration\_id](#output\_logging\_configuration\_id) | The ID of the WAF logging configuration | | [web\_acl\_application\_integration\_url](#output\_web\_acl\_application\_integration\_url) | The URL to use in SDK integrations with managed rule groups | | [web\_acl\_arn](#output\_web\_acl\_arn) | The ARN of the Web ACL | | [web\_acl\_association\_ids](#output\_web\_acl\_association\_ids) | Map of Web ACL association IDs | | [web\_acl\_capacity](#output\_web\_acl\_capacity) | Web ACL capacity units (WCUs) currently being used by this Web ACL | | [web\_acl\_description](#output\_web\_acl\_description) | The description of the Web ACL | | [web\_acl\_id](#output\_web\_acl\_id) | The ID of the Web ACL | | [web\_acl\_lock\_token](#output\_web\_acl\_lock\_token) | A token used for optimistic locking | | [web\_acl\_name](#output\_web\_acl\_name) | The name of the Web ACL | | [web\_acl\_rule\_names](#output\_web\_acl\_rule\_names) | List of rule names in the Web ACL | | [web\_acl\_tags\_all](#output\_web\_acl\_tags\_all) | A map of tags assigned to the resource, including those inherited from the provider default\_tags configuration block | | [web\_acl\_visibility\_config](#output\_web\_acl\_visibility\_config) | The visibility configuration of the Web ACL | ## Authors Module is maintained by [Anton Babenko](https://github.com/antonbabenko) with help from [these awesome contributors](https://github.com/terraform-aws-modules/terraform-aws-wafv2/graphs/contributors). ## License Apache 2 Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-wafv2/tree/master/LICENSE) for full details. ## Additional information for users from Russia and Belarus * Russia has [illegally annexed Crimea in 2014](https://en.wikipedia.org/wiki/Annexation_of_Crimea_by_the_Russian_Federation) and [brought the war in Donbas](https://en.wikipedia.org/wiki/War_in_Donbas) followed by [full-scale invasion of Ukraine in 2022](https://en.wikipedia.org/wiki/2022_Russian_invasion_of_Ukraine). * Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee. * [Putin khuylo!](https://en.wikipedia.org/wiki/Putin_khuylo!)

Controls