» Resource: aws_wafv2_web_acl

Creates a WAFv2 Web ACL resource.

» Example Usage

This resource is based on aws_wafv2_rule_group, check the documentation of the aws_wafv2_rule_group resource to see examples of the various available statements.

» Managed Rule

resource "aws_wafv2_web_acl" "example" {
  name        = "managed-rule-example"
  description = "Example of a managed rule."
  scope       = "REGIONAL"

  default_action {
    allow {}
  }

  rule {
    name     = "rule-1"
    priority = 1

    override_action {
      count {}
    }

    statement {
      managed_rule_group_statement {
        name        = "AWSManagedRulesCommonRuleSet"
        vendor_name = "AWS"

        excluded_rule {
          name = "SizeRestrictions_QUERYSTRING"
        }

        excluded_rule {
          name = "NoUserAgent_HEADER"
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  tags = {
    Tag1 = "Value1"
    Tag2 = "Value2"
  }

  visibility_config {
    cloudwatch_metrics_enabled = false
    metric_name                = "friendly-metric-name"
    sampled_requests_enabled   = false
  }
}

» Rate Based

resource "aws_wafv2_web_acl" "example" {
  name        = "rate-based-example"
  description = "Example of a rate based statement."
  scope       = "REGIONAL"

  default_action {
    block {}
  }

  rule {
    name     = "rule-1"
    priority = 1

    action {
      count {}
    }

    statement {
      rate_based_statement {
        limit              = 10000
        aggregate_key_type = "IP"

        scope_down_statement {
          geo_match_statement {
            country_codes = ["US", "NL"]
          }
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  tags = {
    Tag1 = "Value1"
    Tag2 = "Value2"
  }

  visibility_config {
    cloudwatch_metrics_enabled = false
    metric_name                = "friendly-metric-name"
    sampled_requests_enabled   = false
  }
}

» Rule Group Reference

resource "aws_wafv2_rule_group" "example" {
  capacity = 10
  name     = "example-rule-group"
  scope    = "REGIONAL"

  rule {
    name     = "rule-1"
    priority = 1

    action {
      count {}
    }

    statement {
      geo_match_statement {
        country_codes = ["NL"]
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  rule {
    name     = "rule-to-exclude-a"
    priority = 10

    action {
      allow {}
    }

    statement {
      geo_match_statement {
        country_codes = ["US"]
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  rule {
    name     = "rule-to-exclude-b"
    priority = 15

    action {
      allow {}
    }

    statement {
      geo_match_statement {
        country_codes = ["GB"]
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  visibility_config {
    cloudwatch_metrics_enabled = false
    metric_name                = "friendly-metric-name"
    sampled_requests_enabled   = false
  }
}

resource "aws_wafv2_web_acl" "test" {
  name  = "rule-group-example"
  scope = "REGIONAL"

  default_action {
    block {}
  }

  rule {
    name     = "rule-1"
    priority = 1

    override_action {
      count {}
    }

    statement {
      rule_group_reference_statement {
        arn = aws_wafv2_rule_group.example.arn

        excluded_rule {
          name = "rule-to-exclude-b"
        }

        excluded_rule {
          name = "rule-to-exclude-a"
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "friendly-rule-metric-name"
      sampled_requests_enabled   = false
    }
  }

  tags = {
    Tag1 = "Value1"
    Tag2 = "Value2"
  }

  visibility_config {
    cloudwatch_metrics_enabled = false
    metric_name                = "friendly-metric-name"
    sampled_requests_enabled   = false
  }
}

» Argument Reference

The following arguments are supported:

  • default_action - (Required) The action to perform if none of the rules contained in the WebACL match. See Default Action below for details.
  • description - (Optional) A friendly description of the WebACL.
  • name - (Required) A friendly name of the WebACL.
  • rule - (Optional) The rule blocks used to identify the web requests that you want to allow, block, or count. See Rules below for details.
  • scope - (Required) Specifies whether this is for an AWS CloudFront distribution or for a regional application. Valid values are CLOUDFRONT or REGIONAL. To work with CloudFront, you must also specify the region us-east-1 (N. Virginia) on the AWS provider.
  • tags - (Optional) An array of key:value pairs to associate with the resource.
  • visibility_config - (Required) Defines and enables Amazon CloudWatch metrics and web request sample collection. See Visibility Configuration below for details.

» Default Action

The default_action block supports the following arguments:

  • allow - (Optional) Specifies that AWS WAF should allow requests by default.
  • block - (Optional) Specifies that AWS WAF should block requests by default.

» Rules

Each rule supports the following arguments:

  • action - (Optional) The action that AWS WAF should take on a web request when it matches the rule's statement. This is used only for rules whose statements do not reference a rule group. Rule statements that reference a rule group include rule_group_reference_statement and managed_rule_group_statement. See Action below for details.
  • name - (Required) A friendly name of the rule.
  • override_action - (Optional) The override action to apply to the rules in a WebACL. Required and used only for rule statements that reference a rule group, like rule_group_reference_statement and managed_rule_group_statement. See Override Action below for details.
  • priority - (Required) If you define more than one Rule in a WebACL, AWS WAF evaluates each request against the rules in order based on the value of priority. AWS WAF processes rules with lower priority first.
  • statement - (Required) The AWS WAF processing statement for the rule, for example byte_match_statement or geo_match_statement. See Statement below for details.
  • visibility_config - (Required) Defines and enables Amazon CloudWatch metrics and web request sample collection. See Visibility Configuration below for details.

» Action

The action block supports the following arguments:

  • allow - (Optional) Instructs AWS WAF to allow the web request.
  • block - (Optional) Instructs AWS WAF to block the web request.
  • count - (Optional) Instructs AWS WAF to count the web request and allow it.

» Override Action

The override_action block supports the following arguments:

  • count - (Optional) Override the rule action setting to count.
  • none - (Optional) Don't override the rule action setting.

» Statement

The processing guidance for a Rule, used by AWS WAF to determine whether a web request matches the rule. See the documentation for more information.

The statement block supports the following arguments:

» AND Statement

A logical rule statement used to combine other rule statements with AND logic. You provide more than one statement within the and_statement.

The and_statement block supports the following arguments:

  • statement - (Required) The statements to combine with AND logic. You can use any statements that can be nested. See Statement above for details.

» Byte Match Statement

The byte match statement provides the bytes to search for, the location in requests that you want AWS WAF to search, and other settings. The bytes to search for are typically a string that corresponds with ASCII characters.

The byte_match_statement block supports the following arguments:

  • field_to_match - (Required) The part of a web request that you want AWS WAF to inspect. See Field to Match below for details.
  • positional_constraint - (Required) The area within the portion of a web request that you want AWS WAF to search for search_string. Valid values include the following: EXACTLY, STARTS_WITH, ENDS_WITH, CONTAINS, CONTAINS_WORD. See the AWS documentation for more information.
  • search_string - (Required) A string value that you want AWS WAF to search for. AWS WAF searches only in the part of web requests that you designate for inspection in field_to_match. The maximum length of the value is 50 bytes.
  • text_transformation - (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. See Text Transformation below for details.

» GEO Match Statement

The geo_match_statement block supports the following arguments:

  • country_codes - (Required) An array of two-character country codes, for example, [ "US", "CN" ], from the alpha-2 country ISO codes of the ISO 3166 international standard. See the documentation for valid values.

» IP Set Reference Statement

A rule statement used to detect web requests coming from particular IP addresses or address ranges. To use this, create an aws_wafv2_ip_set that specifies the addresses you want to detect, then use the ARN of that set in this statement.

The ip_set_reference_statement block supports the following arguments:

  • arn - (Required) The Amazon Resource Name (ARN) of the IP Set that this statement references.

» Managed Rule Group Statement

A rule statement used to run the rules that are defined in a managed rule group.

You can't nest a managed_rule_group_statement, for example for use inside a not_statement or or_statement. It can only be referenced as a top-level statement within a rule.

The managed_rule_group_statement block supports the following arguments:

  • excluded_rule - (Required) The rules whose actions are set to COUNT by the web ACL, regardless of the action that is set on the rule. See Excluded Rule below for details.
  • name - (Required) The name of the managed rule group.
  • vendor_name - (Required) The name of the managed rule group vendor.

» NOT Statement

A logical rule statement used to negate the results of another rule statement. You provide one statement within the not_statement.

The not_statement block supports the following arguments:

  • statement - (Required) The statement to negate. You can use any statement that can be nested. See Statement above for details.

» OR Statement

A logical rule statement used to combine other rule statements with OR logic. You provide more than one statement within the or_statement.

The or_statement block supports the following arguments:

  • statement - (Required) The statements to combine with OR logic. You can use any statements that can be nested. See Statement above for details.

» Rate Based Statement

A rate-based rule tracks the rate of requests for each originating IP address, and triggers the rule action when the rate exceeds a limit that you specify on the number of requests in any 5-minute time span. You can use this to put a temporary block on requests from an IP address that is sending excessive requests. See the documentation for more information.

You can't nest a rate_based_statement, for example for use inside a not_statement or or_statement. It can only be referenced as a top-level statement within a rule.

The rate_based_statement block supports the following arguments:

  • aggregate_key_type - (Optional) Setting that indicates how to aggregate the request counts. Currently the only supported value is IP which is set as the default.
  • limit - (Required) The limit on requests per 5-minute period for a single originating IP address.
  • scope_down_statement - (Optional) An optional nested statement that narrows the scope of the rate-based statement to matching web requests. This can be any nestable statement, and you can nest statements at any level below this scope-down statement. See Statement above for details.

» Regex Pattern Set Reference Statement

A rule statement used to search web request components for matches with regular expressions. To use this, create a aws_wafv2_regex_pattern_set that specifies the expressions that you want to detect, then use the ARN of that set in this statement. A web request matches the pattern set rule statement if the request component matches any of the patterns in the set.

The regex_pattern_set_reference_statement block supports the following arguments:

  • arn - (Required) The Amazon Resource Name (ARN) of the Regex Pattern Set that this statement references.

» Rule Group Reference Statement

A rule statement used to run the rules that are defined in an aws_wafv2_rule_group.

You can't nest a rule_group_reference_statement, for example for use inside a not_statement or or_statement. It can only be referenced as a top-level statement within a rule.

The rule_group_reference_statement block supports the following arguments:

  • arn - (Required) The Amazon Resource Name (ARN) of the aws_wafv2_rule_group resource.
  • excluded_rule - (Required) The rules whose actions are set to COUNT by the web ACL, regardless of the action that is set on the rule. See Excluded Rule below for details.

» Excluded Rule

The excluded_rule block supports the following arguments:

  • name - (Required) The name of the rule to exclude.

» SQL Injection Match Statement

An SQL injection match condition identifies the part of web requests, such as the URI or the query string, that you want AWS WAF to inspect. Later in the process, when you create a web ACL, you specify whether to allow or block requests that appear to contain malicious SQL code.

The sqli_match_statement block supports the following arguments:

  • field_to_match - (Required) The part of a web request that you want AWS WAF to inspect. See Field to Match below for details.
  • text_transformation - (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. See Text Transformation below for details.

» XSS Match Statement

The XSS match statement provides the location in requests that you want AWS WAF to search and text transformations to use on the search area before AWS WAF searches for character sequences that are likely to be malicious strings.

The xss_match_statement block supports the following arguments:

  • field_to_match - (Required) The part of a web request that you want AWS WAF to inspect. See Field to Match below for details.
  • text_transformation - (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. See Text Transformation below for details.

» Field to Match

The part of a web request that you want AWS WAF to inspect. Include the single field_to_match type that you want to inspect, with additional specifications as needed, according to the type. You specify a single request component in field_to_match for each rule statement that requires it. To inspect more than one component of a web request, create a separate rule statement for each component. See the documentation for more details.

The field_to_match block supports the following arguments:

  • all_query_arguments - (Optional) Inspect all query arguments.
  • body - (Optional) Inspect the request body, which immediately follows the request headers.
  • method - (Optional) Inspect the HTTP method. The method indicates the type of operation that the request is asking the origin to perform.
  • query_string - (Optional) Inspect the query string. This is the part of a URL that appears after a ? character, if any.
  • single_header - (Optional) Inspect a single header. See Single Header below for details.
  • single_query_argument - (Optional) Inspect a single query argument. See Single Query Argument below for details.
  • uri_path - (Optional) Inspect the request URI path. This is the part of a web request that identifies a resource, for example, /images/daily-ad.jpg.

» Single Header

Inspect a single header. Provide the name of the header to inspect, for example, User-Agent or Referer (provided as lowercase strings).

The single_header block supports the following arguments:

  • name - (Optional) The name of the query header to inspect. This setting must be provided as lower case characters.

» Single Query Argument

Inspect a single query argument. Provide the name of the query argument to inspect, such as UserName or SalesRegion (provided as lowercase strings).

The single_query_argument block supports the following arguments:

  • name - (Optional) The name of the query header to inspect. This setting must be provided as lower case characters.

» Text Transformation

The text_transformation block supports the following arguments:

  • priority - (Required) The relative processing order for multiple transformations that are defined for a rule statement. AWS WAF processes all transformations, from lowest priority to highest, before inspecting the transformed content.
  • type - (Required) The transformation to apply, you can specify the following types: NONE, COMPRESS_WHITE_SPACE, HTML_ENTITY_DECODE, LOWERCASE, CMD_LINE, URL_DECODE. See the documentation for more details.

» Visibility Configuration

The visibility_config block supports the following arguments:

  • cloudwatch_metrics_enabled - (Required) A boolean indicating whether the associated resource sends metrics to CloudWatch. For the list of available metrics, see AWS WAF Metrics.
  • metric_name - (Required) A friendly name of the CloudWatch metric. The name can contain only alphanumeric characters (A-Z, a-z, 0-9) hyphen(-) and underscore (_), with length from one to 128 characters. It can't contain whitespace or metric names reserved for AWS WAF, for example All and Default_Action.
  • sampled_requests_enabled - (Required) A boolean indicating whether AWS WAF should store a sampling of the web requests that match the rules. You can view the sampled requests through the AWS WAF console.

» Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • arn - The ARN of the WAF WebACL.
  • capacity - The web ACL capacity units (WCUs) currently being used by this web ACL.
  • id - The ID of the WAF WebACL.

» Import

WAFv2 Web ACLs can be imported using ID/Name/Scope e.g.

$ terraform import aws_wafv2_web_acl.example a1b2c3d4-d5f6-7777-8888-9999aaaabbbbcccc/example/REGIONAL