Resource: awsWafv2WebAcl
Creates a WAFv2 Web ACL resource.
\~> Note: In fieldToMatch
blocks, e.g., in byteMatchStatement
, the body
block includes an optional argument oversizeHandling
. AWS indicates this argument will be required starting February 2023. To avoid configurations breaking when that change happens, treat the oversizeHandling
argument as required as soon as possible.
Example Usage
This resource is based on awsWafv2RuleGroup
, check the documentation of the awsWafv2RuleGroup
resource to see examples of the various available statements.
Managed Rule
/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.wafv2WebAcl.Wafv2WebAcl(this, "example", {
defaultAction: {
allow: {},
},
description: "Example of a managed rule.",
name: "managed-rule-example",
rule: [
{
name: "rule-1",
overrideAction: {
count: {},
},
priority: 1,
statement: {
managedRuleGroupStatement: {
name: "AWSManagedRulesCommonRuleSet",
ruleActionOverride: [
{
actionToUse: {
count: {},
},
name: "SizeRestrictions_QUERYSTRING",
},
{
actionToUse: {
count: {},
},
name: "NoUserAgent_HEADER",
},
],
scopeDownStatement: {
geoMatchStatement: {
countryCodes: ["US", "NL"],
},
},
vendorName: "AWS",
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
],
scope: "REGIONAL",
tags: {
Tag1: "Value1",
Tag2: "Value2",
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-metric-name",
sampledRequestsEnabled: false,
},
});
Rate Based
Rate-limit US and NL-based clients to 10,000 requests for every 5 minutes.
/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.wafv2WebAcl.Wafv2WebAcl(this, "example", {
defaultAction: {
allow: {},
},
description: "Example of a Cloudfront rate based statement.",
name: "rate-based-example",
rule: [
{
action: {
block: {},
},
name: "rule-1",
priority: 1,
statement: {
rateBasedStatement: {
aggregateKeyType: "IP",
limit: 10000,
scopeDownStatement: {
geoMatchStatement: {
countryCodes: ["US", "NL"],
},
},
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
],
scope: "CLOUDFRONT",
tags: {
Tag1: "Value1",
Tag2: "Value2",
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-metric-name",
sampledRequestsEnabled: false,
},
});
Rule Group Reference
/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsWafv2RuleGroupExample = new aws.wafv2RuleGroup.Wafv2RuleGroup(
this,
"example",
{
capacity: 10,
name: "example-rule-group",
rule: [
{
action: {
count: {},
},
name: "rule-1",
priority: 1,
statement: {
geoMatchStatement: {
countryCodes: ["NL"],
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
{
action: {
allow: {},
},
name: "rule-to-exclude-a",
priority: 10,
statement: {
geoMatchStatement: {
countryCodes: ["US"],
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
{
action: {
allow: {},
},
name: "rule-to-exclude-b",
priority: 15,
statement: {
geoMatchStatement: {
countryCodes: ["GB"],
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
],
scope: "REGIONAL",
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-metric-name",
sampledRequestsEnabled: false,
},
}
);
new aws.wafv2WebAcl.Wafv2WebAcl(this, "test", {
defaultAction: {
block: {},
},
name: "rule-group-example",
rule: [
{
name: "rule-1",
overrideAction: {
count: {},
},
priority: 1,
statement: {
ruleGroupReferenceStatement: {
arn: awsWafv2RuleGroupExample.arn,
excludedRule: [
{
name: "rule-to-exclude-b",
},
{
name: "rule-to-exclude-a",
},
],
},
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-rule-metric-name",
sampledRequestsEnabled: false,
},
},
],
scope: "REGIONAL",
tags: {
Tag1: "Value1",
Tag2: "Value2",
},
visibilityConfig: {
cloudwatchMetricsEnabled: false,
metricName: "friendly-metric-name",
sampledRequestsEnabled: false,
},
});
Argument Reference
The following arguments are supported:
customResponseBody
- (Optional) Defines custom response bodies that can be referenced bycustomResponse
actions. SeecustomResponseBody
below for details.defaultAction
- (Required) Action to perform if none of therules
contained in the WebACL match. SeedefaultAction
below for details.description
- (Optional) Friendly description of the WebACL.name
- (Required) Friendly name of the WebACL.rule
- (Optional) Rule blocks used to identify the web requests that you want toallow
,block
, orcount
. Seerule
below for details.scope
- (Required) Specifies whether this is for an AWS CloudFront distribution or for a regional application. Valid values arecloudfront
orregional
. To work with CloudFront, you must also specify the regionusEast1
(N. Virginia) on the AWS provider.tags
- (Optional) Map of key-value pairs to associate with the resource. If configured with a providerdefaultTags
configuration block present, tags with matching keys will overwrite those defined at the provider-level.visibilityConfig
- (Required) Defines and enables Amazon CloudWatch metrics and web request sample collection. SeevisibilityConfig
below for details.
customResponseBody
Each customResponseBody
block supports the following arguments:
key
- (Required) Unique key identifying the custom response body. This is referenced by thecustomResponseBodyKey
argument in thecustomResponse
block.content
- (Required) Payload of the custom response.contentType
- (Required) Type of content in the payload that you are defining in thecontent
argument. Valid values areTEXT_PLAIN
,TEXT_HTML
, orAPPLICATION_JSON
.
defaultAction
The defaultAction
block supports the following arguments:
\~> NOTE: One of allow
or block
, expressed as an empty configuration block {}
, is required when specifying a defaultAction
allow
- (Optional) Specifies that AWS WAF should allow requests by default. Seeallow
below for details.block
- (Optional) Specifies that AWS WAF should block requests by default. Seeblock
below for details.
rule
\~> NOTE: One of action
or overrideAction
is required when specifying a rule
Each rule
supports the following arguments:
action
- (Optional) 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. Seeaction
below for details.name
- (Required) Friendly name of the rule. NOTE: The provider assumes that rules with names matching this pattern,^shieldMitigationRuleGroup_<accountId>_<webAclGuid>_.*
, are AWS-added for automatic application layer DDoS mitigation activities. Such rules will be ignored by the provider unless you explicitly include them in your configuration (for example, by using the AWS CLI to discover their properties and creating matching configuration). However, since these rules are owned and managed by AWS, you may get permission errors.overrideAction
- (Optional) Override action to apply to the rules in a rule group. Used only for rule statements that reference a rule group, likeruleGroupReferenceStatement
andmanagedRuleGroupStatement
. SeeoverrideAction
below for details.priority
- (Required) If you define more than one Rule in a WebACL, AWS WAF evaluates each request against therules
in order based on the value ofpriority
. AWS WAF processes rules with lower priority first.ruleLabel
- (Optional) Labels to apply to web requests that match the rule match statement. SeeruleLabel
below for details.statement
- (Required) The AWS WAF processing statement for the rule, for examplebyteMatchStatement
orgeoMatchStatement
. Seestatement
below for details.visibilityConfig
- (Required) Defines and enables Amazon CloudWatch metrics and web request sample collection. SeevisibilityConfig
below for details.
action
The action
block supports the following arguments:
\~> NOTE: One of allow
, block
, or count
, is required when specifying an action
.
allow
- (Optional) Instructs AWS WAF to allow the web request. Seeallow
below for details.block
- (Optional) Instructs AWS WAF to block the web request. Seeblock
below for details.captcha
- (Optional) Instructs AWS WAF to run a Captcha check against the web request. Seecaptcha
below for details.challenge
- (Optional) Instructs AWS WAF to run a check against the request to verify that the request is coming from a legitimate client session. Seechallenge
below for details.count
- (Optional) Instructs AWS WAF to count the web request and allow it. Seecount
below for details.
overrideAction
The overrideAction
block supports the following arguments:
\~> NOTE: One of count
or none
, expressed as an empty configuration block {}
, is required when specifying an overrideAction
count
- (Optional) Override the rule action setting to count (i.e., only count matches). Configured as an empty block{}
.none
- (Optional) Don't override the rule action setting. Configured as an empty block{}
.
allow
The allow
block supports the following arguments:
customRequestHandling
- (Optional) Defines custom handling for the web request. SeecustomRequestHandling
below for details.
block
The block
block supports the following arguments:
customResponse
- (Optional) Defines a custom response for the web request. SeecustomResponse
below for details.
captcha
The captcha
block supports the following arguments:
customRequestHandling
- (Optional) Defines custom handling for the web request. SeecustomRequestHandling
below for details.
challenge
The challenge
block supports the following arguments:
customRequestHandling
- (Optional) Defines custom handling for the web request. SeecustomRequestHandling
below for details.
count
The count
block supports the following arguments:
customRequestHandling
- (Optional) Defines custom handling for the web request. SeecustomRequestHandling
below for details.
customRequestHandling
The customRequestHandling
block supports the following arguments:
insertHeader
- (Required) TheinsertHeader
blocks used to define HTTP headers added to the request. SeeinsertHeader
below for details.
insertHeader
Each insertHeader
block supports the following arguments. Duplicate header names are not allowed:
name
- Name of the custom header. For custom request header insertion, when AWS WAF inserts the header into the request, it prefixes this namexAmznWaf
, to avoid confusion with the headers that are already in the request. For example, for the header namesample
, AWS WAF inserts the headerxAmznWafSample
.value
- Value of the custom header.
customResponse
The customResponse
block supports the following arguments:
customResponseBodyKey
- (Optional) References the response body that you want AWS WAF to return to the web request client. This must reference akey
defined in acustomResponseBody
block of this resource.responseCode
- (Required) The HTTP status code to return to the client.responseHeader
- (Optional) TheresponseHeader
blocks used to define the HTTP response headers added to the response. SeeresponseHeader
below for details.
responseHeader
Each responseHeader
block supports the following arguments. Duplicate header names are not allowed:
name
- Name of the custom header. For custom request header insertion, when AWS WAF inserts the header into the request, it prefixes this namexAmznWaf
, to avoid confusion with the headers that are already in the request. For example, for the header namesample
, AWS WAF inserts the headerxAmznWafSample
.value
- Value of the custom header.
ruleLabel
Each block supports the following arguments:
name
- Label string.
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.
-> NOTE: Although the statement
block is recursive, currently only 3 levels are supported.
The statement
block supports the following arguments:
andStatement
- (Optional) Logical rule statement used to combine other rule statements with AND logic. SeeandStatement
below for details.byteMatchStatement
- (Optional) Rule statement that defines a string match search for AWS WAF to apply to web requests. SeebyteMatchStatement
below for details.geoMatchStatement
- (Optional) Rule statement used to identify web requests based on country of origin. SeegeoMatchStatement
below for details.ipSetReferenceStatement
- (Optional) Rule statement used to detect web requests coming from particular IP addresses or address ranges. See IP Set Reference Statement below for details.labelMatchStatement
- (Optional) Rule statement that defines a string match search against labels that have been added to the web request by rules that have already run in the web ACL. SeelabelMatchStatement
below for details.managedRuleGroupStatement
- (Optional) Rule statement used to run the rules that are defined in a managed rule group. This statement can not be nested. See Managed Rule Group Statement below for details.notStatement
- (Optional) Logical rule statement used to negate the results of another rule statement. SeenotStatement
below for details.orStatement
- (Optional) Logical rule statement used to combine other rule statements with OR logic. SeeorStatement
below for details.rateBasedStatement
- (Optional) Rate-based rule tracks the rate of requests for each originatingipAddress
, and triggers the rule action when the rate exceeds a limit that you specify on the number of requests in any5Minute
time span. This statement can not be nested. SeerateBasedStatement
below for details.regexMatchStatement
- (Optional) Rule statement used to search web request components for a match against a single regular expression. SeeregexMatchStatement
below for details.regexPatternSetReferenceStatement
- (Optional) Rule statement used to search web request components for matches with regular expressions. See Regex Pattern Set Reference Statement below for details.ruleGroupReferenceStatement
- (Optional) Rule statement used to run the rules that are defined in an WAFv2 Rule Group. See Rule Group Reference Statement below for details.sizeConstraintStatement
- (Optional) Rule statement that compares a number of bytes against the size of a request component, using a comparison operator, such as greater than (>) or less than (<). SeesizeConstraintStatement
below for more details.sqliMatchStatement
- (Optional) 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. SeesqliMatchStatement
below for details.xssMatchStatement
- (Optional) Rule statement that defines a cross-site scripting (XSS) match search for AWS WAF to apply to web requests. SeexssMatchStatement
below for details.
andStatement
A logical rule statement used to combine other rule statements with and
logic. You provide more than one statement
within the andStatement
.
The andStatement
block supports the following arguments:
statement
- (Required) Statements to combine withand
logic. You can use any statements that can be nested. Seestatement
above for details.
byteMatchStatement
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 byteMatchStatement
block supports the following arguments:
fieldToMatch
- (Optional) Part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.positionalConstraint
- (Required) Area within the portion of a web request that you want AWS WAF to search forsearchString
. Valid values include the following:exactly
,STARTS_WITH
,ENDS_WITH
,contains
,CONTAINS_WORD
. See the AWS documentation for more information.searchString
- (Required) 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 infieldToMatch
. The maximum length of the value is 50 bytes.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
geoMatchStatement
The geoMatchStatement
block supports the following arguments:
countryCodes
- (Required) Array of two-character country codes, for example, [ "US", "CN" ], from the alpha-2 country ISO codes of theiso3166
international standard. See the documentation for valid values.forwardedIpConfig
- (Optional) 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. SeeforwardedIpConfig
below for details.
ipSetReferenceStatement
A rule statement used to detect web requests coming from particular IP addresses or address ranges. To use this, create an awsWafv2IpSet
that specifies the addresses you want to detect, then use the arn
of that set in this statement.
The ipSetReferenceStatement
block supports the following arguments:
arn
- (Required) The Amazon Resource Name (ARN) of the IP Set that this statement references.ipSetForwardedIpConfig
- (Optional) 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. SeeipSetForwardedIpConfig
below for more details.
labelMatchStatement
The labelMatchStatement
block supports the following arguments:
scope
- (Required) Specify whether you want to match using the label name or just the namespace. Valid values arelabel
ornamespace
.key
- (Required) String to match against.
managedRuleGroupStatement
A rule statement used to run the rules that are defined in a managed rule group.
You can't nest a managedRuleGroupStatement
, for example for use inside a notStatement
or orStatement
. It can only be referenced as a topLevel
statement within a rule
.
The managedRuleGroupStatement
block supports the following arguments:
excludedRule
- (Optional, Deprecated) Therules
whose actions are set tocount
by the web ACL, regardless of the action that is set on the rule. SeeexcludedRule
below for details. UseruleActionOverride
instead. (See the documentation)name
- (Required) Name of the managed rule group.ruleActionOverride
- (Optional) Action settings to use in the place of the rule actions that are configured inside the rule group. You specify one override for each rule whose action you want to change. SeeruleActionOverride
below for details.managedRuleGroupConfigs
- (Optional) Additional information that's used by a managed rule group. Only one rule attribute is allowed in each config. See Managed Rule Group Configs for more detailsscopeDownStatement
- Narrows the scope of the statement to matching web requests. This can be any nestable statement, and you can nest statements at any level below this scope-down statement. Seestatement
above for details.vendorName
- (Required) Name of the managed rule group vendor.version
- (Optional) Version of the managed rule group. You can setversion10
orversion11
etc. If you want to use the default version, do not set anything.
notStatement
A logical rule statement used to negate the results of another rule statement. You provide one statement
within the notStatement
.
The notStatement
block supports the following arguments:
statement
- (Required) Statement to negate. You can use any statement that can be nested. Seestatement
above for details.
orStatement
A logical rule statement used to combine other rule statements with or
logic. You provide more than one statement
within the orStatement
.
The orStatement
block supports the following arguments:
statement
- (Required) Statements to combine withor
logic. You can use any statements that can be nested. Seestatement
above for details.
rateBasedStatement
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 rateBasedStatement
, for example for use inside a notStatement
or orStatement
. It can only be referenced as a topLevel
statement within a rule
.
The rateBasedStatement
block supports the following arguments:
aggregateKeyType
- (Optional) Setting that indicates how to aggregate the request counts. Valid values include:FORWARDED_IP
orip
. Default:ip
.forwardedIpConfig
- (Optional) 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. IfaggregateKeyType
is set toFORWARDED_IP
, this block is required. SeeforwardedIpConfig
below for details.limit
- (Required) Limit on requests per 5-minute period for a single originating IP address.scopeDownStatement
- (Optional) 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. Seestatement
above for details.
regexMatchStatement
A rule statement used to search web request components for a match against a single regular expression.
The regexMatchStatement
block supports the following arguments:
regexString
- (Required) String representing the regular expression. Minimum of1
and maximum of512
characters.fieldToMatch
- (Required) The part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
regexPatternSetReferenceStatement
A rule statement used to search web request components for matches with regular expressions. To use this, create a awsWafv2RegexPatternSet
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 regexPatternSetReferenceStatement
block supports the following arguments:
arn
- (Required) The Amazon Resource Name (ARN) of the Regex Pattern Set that this statement references.fieldToMatch
- (Optional) Part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
ruleGroupReferenceStatement
A rule statement used to run the rules that are defined in an WAFv2 Rule Group or awsWafv2RuleGroup
resource.
You can't nest a ruleGroupReferenceStatement
, for example for use inside a notStatement
or orStatement
. It can only be referenced as a topLevel
statement within a rule
.
The ruleGroupReferenceStatement
block supports the following arguments:
arn
- (Required) The Amazon Resource Name (ARN) of theawsWafv2RuleGroup
resource.excludedRule
- (Optional) Therules
whose actions are set tocount
by the web ACL, regardless of the action that is set on the rule. SeeexcludedRule
below for details.
sizeConstraintStatement
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 sizeConstraintStatement
block supports the following arguments:
comparisonOperator
- (Required) Operator to use to compare the request part to the size setting. Valid values include:eq
,ne
,le
,lt
,ge
, orgt
.fieldToMatch
- (Optional) Part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.size
- (Required) Size, in bytes, to compare to the request part, after any transformations. Valid values are integers between 0 and 21474836480, inclusive.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
sqliMatchStatement
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 sqliMatchStatement
block supports the following arguments:
fieldToMatch
- (Optional) Part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
xssMatchStatement
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 xssMatchStatement
block supports the following arguments:
fieldToMatch
- (Optional) Part of a web request that you want AWS WAF to inspect. SeefieldToMatch
below for details.textTransformation
- (Required) Text transformations eliminate some of the unusual formatting that attackers use in web requests in an effort to bypass detection. At least one required. SeetextTransformation
below for details.
excludedRule
The excludedRule
block supports the following arguments:
name
- (Required) Name of the rule to exclude. If the rule group is managed by AWS, see the documentation for a list of names in the appropriate rule group in use.
ruleActionOverride
The ruleActionOverride
block supports the following arguments:
actionToUse
- (Required) Override action to use, in place of the configured action of the rule in the rule group. Seeaction
below for details.name
- (Required) Name of the rule to override. See the documentation for a list of names in the appropriate rule group in use.
managedRuleGroupConfigs
The managedRuleGroupConfigs
block support the following arguments:
awsManagedRulesBotControlRuleSet
- (Optional) Additional configuration for using the Bot Control managed rule group. Use this to specify the inspection level that you want to use. SeeawsManagedRulesBotControlRuleSet
for more detailsloginPath
- (Optional) The path of the login endpoint for your application.passwordField
- (Optional) Details about your login page password field. SeepasswordField
for more details.payloadType
- (Optional) The payload type for your login endpoint, either JSON or form encoded.usernameField
- (Optional) Details about your login page username field. SeeusernameField
for more details.
awsManagedRulesBotControlRuleSet
inspectionLevel
- (Optional) The inspection level to use for the Bot Control rule group.
passwordField
identifier
- (Optional) The name of the password field.
usernameField
identifier
- (Optional) The name of the username field.
fieldToMatch
The part of a web request that you want AWS WAF to inspect. Include the single fieldToMatch
type that you want to inspect, with additional specifications as needed, according to the type. You specify a single request component in fieldToMatch
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 fieldToMatch
block supports the following arguments:
\~> NOTE: Only one of allQueryArguments
, body
, cookies
, headers
, jsonBody
, method
, queryString
, singleHeader
, singleQueryArgument
, or uriPath
can be specified. An empty configuration block {}
should be used when specifying allQueryArguments
, method
, or queryString
attributes.
allQueryArguments
- (Optional) Inspect all query arguments.body
- (Optional) Inspect the request body, which immediately follows the request headers. Seebody
below for details.cookies
- (Optional) Inspect the cookies in the web request. Seecookies
below for details.headers
- (Optional) Inspect the request headers. Seeheaders
below for details.jsonBody
- (Optional) Inspect the request body as JSON. SeejsonBody
for details.method
- (Optional) Inspect the HTTP method. The method indicates the type of operation that the request is asking the origin to perform.queryString
- (Optional) Inspect the query string. This is the part of a URL that appears after a?
character, if any.singleHeader
- (Optional) Inspect a single header. SeesingleHeader
below for details.singleQueryArgument
- (Optional) Inspect a single query argument. SeesingleQueryArgument
below for details.uriPath
- (Optional) Inspect the request URI path. This is the part of a web request that identifies a resource, for example,/images/dailyAdJpg
.
forwardedIpConfig
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 forwardedIpConfig
block supports the following arguments:
fallbackBehavior
- (Required) - Match status to assign to the web request if the request doesn't have a valid IP address in the specified position. Valid values include:match
orNO_MATCH
.headerName
- (Required) - Name of the HTTP header to use for the IP address.
ipSetForwardedIpConfig
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 ipSetForwardedIpConfig
block supports the following arguments:
fallbackBehavior
- (Required) - Match status to assign to the web request if the request doesn't have a valid IP address in the specified position. Valid values include:match
orNO_MATCH
.headerName
- (Required) - Name of the HTTP header to use for the IP address.position
- (Required) - Position in the header to search for the IP address. Valid values include:first
,last
, orany
. Ifany
is specified and the header contains more than 10 IP addresses, AWS WAFv2 inspects the last 10.
headers
Inspect the request headers.
The headers
block supports the following arguments:
matchPattern
- (Required) The filter to use to identify the subset of headers to inspect in a web request. ThematchPattern
block supports only one of the following arguments:all
- An empty configuration block that is used for inspecting all headers.includedHeaders
- An array of strings that will be used for inspecting headers that have a key that matches one of the provided values.excludedHeaders
- An array of strings that will be used for inspecting headers that do not have a key that matches one of the provided values.matchScope
- (Required) The parts of the headers to inspect with the rule inspection criteria. If you specifyall
, AWS WAF inspects both keys and values. Valid values include the following:all
,key
,value
.oversizeHandling
- (Required) Oversize handling tells AWS WAF what to do with a web request when the request component that the rule inspects is over the limits. Valid values include the following:continue
,match
,NO_MATCH
. See the AWS documentation for more information.
jsonBody
The jsonBody
block supports the following arguments:
invalidFallbackBehavior
- (Optional) What to do when JSON parsing fails. Defaults to evaluating up to the first parsing failure. Valid values areEVALUATE_AS_STRING
,match
andNO_MATCH
.matchPattern
- (Required) The patterns to look for in the JSON body. You must specify exactly one setting: eitherall
orincludedPaths
. See JsonMatchPattern for details.matchScope
- (Required) The parts of the JSON to match against using thematchPattern
. Valid values areall
,key
andvalue
.oversizeHandling
- (Optional) What to do if the body is larger than can be inspected. Valid values arecontinue
(default),match
andNO_MATCH
.
singleHeader
Inspect a single header. Provide the name of the header to inspect, for example, userAgent
or referer
(provided as lowercase strings).
The singleHeader
block supports the following arguments:
name
- (Optional) Name of the query header to inspect. This setting must be provided as lower case characters.
singleQueryArgument
Inspect a single query argument. Provide the name of the query argument to inspect, such as userName
or salesRegion
(provided as lowercase strings).
The singleQueryArgument
block supports the following arguments:
name
- (Optional) Name of the query header to inspect. This setting must be provided as lower case characters.
body
The body
block supports the following arguments:
oversizeHandling
- (Optional) What WAF should do if the body is larger than WAF can inspect. WAF does not support inspecting the entire contents of the body of a web request when the body exceeds 8 KB (8192 bytes). Only the first 8 KB of the request body are forwarded to WAF by the underlying host service. Valid values:continue
,match
,NO_MATCH
.
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:
matchPattern
- (Required) The filter to use to identify the subset of cookies to inspect in a web request. You must specify exactly one setting: eitherall
,includedCookies
orexcludedCookies
. More details: CookieMatchPatternmatchScope
- (Required) The parts of the cookies to inspect with the rule inspection criteria. If you specify All, AWS WAF inspects both keys and values. Valid values:all
,key
,value
oversizeHandling
- (Required) What AWS WAF should do if the cookies of the request are larger than AWS WAF can inspect. AWS WAF does not support inspecting the entire contents of request cookies when they exceed 8 KB (8192 bytes) or 200 total cookies. The underlying host service forwards a maximum of 200 cookies and at most 8 KB of cookie contents to AWS WAF. Valid values:continue
,match
,NO_MATCH
.
textTransformation
The textTransformation
block supports the following arguments:
priority
- (Required) 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) Transformation to apply, please refer to the Text Transformation documentation for more details.
visibilityConfig
The visibilityConfig
block supports the following arguments:
cloudwatchMetricsEnabled
- (Required) Whether the associated resource sends metrics to CloudWatch. For the list of available metrics, see AWS WAF Metrics.metricName
- (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 exampleall
anddefaultAction
.sampledRequestsEnabled
- (Required) 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
- Web ACL capacity units (WCUs) currently being used by this web ACL.id
- The ID of the WAF WebACL.tagsAll
- Map of tags assigned to the resource, including those inherited from the providerdefaultTags
configuration block.
Import
WAFv2 Web ACLs can be imported using id/name/scope
e.g.,