Resource: aws_wafv2_rule_group

Creates a WAFv2 Rule Group resource.

Example Usage

Simple

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

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

    action {
      allow {}
    }

    statement {

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

    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
  }
}

Complex

resource "aws_wafv2_ip_set" "test" {
  name               = "test"
  scope              = "REGIONAL"
  ip_address_version = "IPV4"
  addresses          = ["1.1.1.1/32", "2.2.2.2/32"]
}

resource "aws_wafv2_regex_pattern_set" "test" {
  name  = "test"
  scope = "REGIONAL"

  regular_expression {
    regex_string = "one"
  }
}

resource "aws_wafv2_rule_group" "example" {
  name        = "complex-example"
  description = "An rule group containing all statements"
  scope       = "REGIONAL"
  capacity    = 500

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

    action {
      block {}
    }

    statement {

      not_statement {
        statement {

          and_statement {
            statement {

              geo_match_statement {
                country_codes = ["US"]
              }
            }

            statement {

              byte_match_statement {
                positional_constraint = "CONTAINS"
                search_string         = "word"

                field_to_match {
                  all_query_arguments {}
                }

                text_transformation {
                  priority = 5
                  type     = "CMD_LINE"
                }

                text_transformation {
                  priority = 2
                  type     = "LOWERCASE"
                }
              }
            }
          }
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "rule-1"
      sampled_requests_enabled   = false
    }
  }

  rule {
    name     = "rule-2"
    priority = 2

    action {
      count {}
    }

    statement {

      or_statement {
        statement {

          regex_match_statement {

            regex_string = "[a-z]([a-z0-9_-]*[a-z0-9])?"

            field_to_match {
              single_header {
                name = "user-agent"
              }
            }

            text_transformation {
              priority = 6
              type     = "NONE"
            }
          }
        }

        statement {

          sqli_match_statement {

            field_to_match {
              body {}
            }

            text_transformation {
              priority = 5
              type     = "URL_DECODE"
            }

            text_transformation {
              priority = 4
              type     = "HTML_ENTITY_DECODE"
            }

            text_transformation {
              priority = 3
              type     = "COMPRESS_WHITE_SPACE"
            }
          }
        }

        statement {

          xss_match_statement {

            field_to_match {
              method {}
            }

            text_transformation {
              priority = 2
              type     = "NONE"
            }
          }
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "rule-2"
      sampled_requests_enabled   = false
    }

    captcha_config {
      immunity_time_property {
        immunity_time = 240
      }
    }
  }

  rule {
    name     = "rule-3"
    priority = 3

    action {
      block {}
    }

    statement {

      size_constraint_statement {
        comparison_operator = "GT"
        size                = 100

        field_to_match {
          single_query_argument {
            name = "username"
          }
        }

        text_transformation {
          priority = 5
          type     = "NONE"
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "rule-3"
      sampled_requests_enabled   = false
    }
  }

  rule {
    name     = "rule-4"
    priority = 4

    action {
      block {}
    }

    statement {

      or_statement {
        statement {

          ip_set_reference_statement {
            arn = aws_wafv2_ip_set.test.arn
          }
        }

        statement {

          regex_pattern_set_reference_statement {
            arn = aws_wafv2_regex_pattern_set.test.arn

            field_to_match {
              single_header {
                name = "referer"
              }
            }

            text_transformation {
              priority = 2
              type     = "NONE"
            }
          }
        }
      }
    }

    visibility_config {
      cloudwatch_metrics_enabled = false
      metric_name                = "rule-4"
      sampled_requests_enabled   = false
    }
  }

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

  captcha_config {
    immunity_time_property {
      immunity_time = 120
    }
  }

  tags = {
    Name = "example-and-statement"
    Code = "123456"
  }
}

Argument Reference

This resource supports the following arguments:

Custom Response Body

Each custom_response_body block supports the following arguments:

Rules

Each rule supports the following arguments:

Action

The action block supports the following arguments:

Allow

The allow block supports the following arguments:

Block

The block block supports the following arguments:

Captcha

The captcha block supports the following arguments:

Challenge

The challenge block supports the following arguments:

Count

The count block supports the following arguments:

Custom Request Handling

The custom_request_handling block supports the following arguments:

Custom Response

The custom_response block supports the following arguments:

Custom HTTP Header

Each block supports the following arguments. Duplicate header names are not allowed:

Rule Label

Each block supports the following arguments:

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:

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:

GEO Match Statement

The geo_match_statement block supports the following arguments:

Label Match Statement

The label_match_statement block supports the following arguments:

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:

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:

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:

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:

Regex Match Statement

A rule statement used to search web request components for a match against a single regular expression.

The regex_match_statement block supports the following arguments:

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:

Size Constraint Statement

A rule statement that uses a comparison operator to compare a number of bytes against the size of a request component. AWS WAFv2 inspects up to the first 8192 bytes (8 KB) of a request body, and when inspecting the request URI Path, the slash / in the URI counts as one character.

The size_constraint_statement block supports the following arguments:

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:

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

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:

Forwarded IP Config

The configuration for inspecting IP addresses in an HTTP header that you specify, instead of using the IP address that's reported by the web request origin. Commonly, this is the X-Forwarded-For (XFF) header, but you can specify any header name. If the specified header isn't present in the request, AWS WAFv2 doesn't apply the rule to the web request at all. AWS WAFv2 only evaluates the first IP address found in the specified HTTP header.

The forwarded_ip_config block supports the following arguments:

IPSet Forwarded IP Config

The configuration for inspecting IP addresses in an HTTP header that you specify, instead of using the IP address that's reported by the web request origin. Commonly, this is the X-Forwarded-For (XFF) header, but you can specify any header name.

The ip_set_forwarded_ip_config block supports the following arguments:

Header Order

Inspect a string containing the list of the request's header names, ordered as they appear in the web request that AWS WAF receives for inspection. AWS WAF generates the string and then uses that as the field to match component in its inspection. AWS WAF separates the header names in the string using colons and no added spaces, for example host:user-agent:accept:authorization:referer.

The header_order block supports the following arguments:

Headers

Inspect the request headers.

The headers block supports the following arguments:

JSON Body

The json_body block supports the following arguments:

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:

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:

Cookies

Inspect the cookies in the web request. You can specify the parts of the cookies to inspect and you can narrow the set of cookies to inspect by including or excluding specific keys. This is used to indicate the web request component to inspect, in the FieldToMatch specification.

The cookies block supports the following arguments:

Text Transformation

The text_transformation block supports the following arguments:

Visibility Configuration

The visibility_config block supports the following arguments:

Captcha Configuration

The captcha_config block supports the following arguments:

Immunity Time Property

The immunity_time_property block supports the following arguments:

Attribute Reference

This resource exports the following attributes in addition to the arguments above:

custom_key Block

Aggregate the request counts using one or more web request components as the aggregate keys. With this option, you must specify the aggregate keys in the custom_keys block. To aggregate on only the IP address or only the forwarded IP address, don't use custom keys. Instead, set the aggregate_key_type to IP or FORWARDED_IP.

The custom_key block supports the following arguments:

Use the value of a cookie in the request as an aggregate key. Each distinct value in the cookie contributes to the aggregation instance. If you use a single cookie as your custom key, then each value fully defines an aggregation instance.

The cookie block supports the following arguments:

RateLimit forwarded_ip Block

Use the first IP address in an HTTP header as an aggregate key. Each distinct forwarded IP address contributes to the aggregation instance. When you specify an IP or forwarded IP in the custom key settings, you must also specify at least one other key to use. You can aggregate on only the forwarded IP address by specifying FORWARDED_IP in your rate-based statement's aggregate_key_type. With this option, you must specify the header to use in the rate-based rule's Forwarded IP Config block.

The forwarded_ip block is configured as an empty block {}.

RateLimit http_method Block

Use the request's HTTP method as an aggregate key. Each distinct HTTP method contributes to the aggregation instance. If you use just the HTTP method as your custom key, then each method fully defines an aggregation instance.

The http_method block is configured as an empty block {}.

RateLimit header Block

Use the value of a header in the request as an aggregate key. Each distinct value in the header contributes to the aggregation instance. If you use a single header as your custom key, then each value fully defines an aggregation instance.

The header block supports the following arguments:

RateLimit ip Block

Use the request's originating IP address as an aggregate key. Each distinct IP address contributes to the aggregation instance. When you specify an IP or forwarded IP in the custom key settings, you must also specify at least one other key to use. You can aggregate on only the IP address by specifying IP in your rate-based statement's aggregate_key_type.

The ip block is configured as an empty block {}.

RateLimit label_namespace Block

Use the specified label namespace as an aggregate key. Each distinct fully qualified label name that has the specified label namespace contributes to the aggregation instance. If you use just one label namespace as your custom key, then each label name fully defines an aggregation instance. This uses only labels that have been added to the request by rules that are evaluated before this rate-based rule in the web ACL. For information about label namespaces and names, see Label syntax and naming requirements (https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-label-requirements.html) in the WAF Developer Guide.

The label_namespace block supports the following arguments:

RateLimit query_argument Block

Use the specified query argument as an aggregate key. Each distinct value for the named query argument contributes to the aggregation instance. If you use a single query argument as your custom key, then each value fully defines an aggregation instance.

The query_argument block supports the following arguments:

RateLimit query_string Block

Use the request's query string as an aggregate key. Each distinct string contributes to the aggregation instance. If you use just the query string as your custom key, then each string fully defines an aggregation instance.

The query_string block supports the following arguments:

RateLimit uri_path Block

Use the request's URI path as an aggregate key. Each distinct URI path contributes to the aggregation instance. If you use just the URI path as your custom key, then each URI path fully defines an aggregation instance.

The uri_path block supports the following arguments:

Import

In Terraform v1.5.0 and later, use an import block to import WAFv2 Rule Group using ID/name/scope. For example:

import {
  to = aws_wafv2_rule_group.example
  id = "a1b2c3d4-d5f6-7777-8888-9999aaaabbbbcccc/example/REGIONAL"
}

Using terraform import, import WAFv2 Rule Group using ID/name/scope. For example:

% terraform import aws_wafv2_rule_group.example a1b2c3d4-d5f6-7777-8888-9999aaaabbbbcccc/example/REGIONAL