**Introducing a new console experience for AWS WAF** You can now use the updated experience to access AWS WAF functionality anywhere in the console. For more details, see [Working with the console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). # Using rule statements in AWS WAF Using rule statements This section explains how rule statements work. Rule statements are the part of a rule that tells AWS WAF how to inspect a web request. When AWS WAF finds the inspection criteria in a web request, we say that the web request matches the statement. Every rule statement specifies what to look for and how, according to the statement type. Every rule in AWS WAF has a single top-level rule statement, which can contain other statements. Rule statements can be very simple. For example, you could have a statement that provides a set of originating countries to inspect your web requests for or you could have a rule statement in a protection pack (web ACL) that just references a rule group. Rule statements can also be very complex. For example, you could have a statement that combines many other statements with logical AND, OR, and NOT statements. For most rules, you can add custom AWS WAF labeling to matching requests. The rules in the AWS Managed Rules rule groups add labels to matching requests. The labels that a rule adds provide information about the request to rules that are evaluated later in the protection pack (web ACL) and also in AWS WAF logs and metrics. For information about labeling, see [Web request labeling in AWS WAF](waf-labels.md) and [Label match rule statement](waf-rule-statement-type-label-match.md). **Nesting rule statements** AWS WAF supports nesting for many rule statements, but not for all. For example, you can't nest a rule group statement inside of another statement. You need to use nesting for some scenarios, such as scope-down statements and logical statements. The rule statement lists and rule details that follow describe the nesting capabilities and requirements for each category and rule. The visual editor for rules in the console supports only one level of nesting for rule statements. For example, you can nest many types of statements inside a logical AND or OR rule, but you can't nest another AND or OR rule, because that requires a second level of nesting. To implement multiple levels of nesting, provide the rule definition in JSON, either through the JSON rule editor in the console or through the APIs. **Topics** + [ # Adjusting rule statement settings in AWS WAF ](waf-rule-statement-fields.md) + [ # Using scope-down statements in AWS WAF ](waf-rule-scope-down-statements.md) + [ # Referencing reusable entities in AWS WAF ](waf-rule-statement-reusable-entities.md) # Adjusting rule statement settings in AWS WAF Adjusting rule statement settings This section describes the settings that you can specify in rule statements that inspect a component of the web request. For information on usage, see the individual rule statements at [Using match rule statements in AWS WAF](waf-rule-statements-match.md). A subset of these web request components can also be used in rate-based rules, as custom request aggregation keys. For information, see [Aggregating rate-based rules in AWS WAF](waf-rule-statement-type-rate-based-aggregation-options.md). For the request component settings, you specify the component type itself, and any additional options, depending on the component type. For example, when you inspect a component type that contains text, you can apply text transformations to it before inspecting it. **Note** Unless otherwise noted, if a web request doesn't have the request component that's specified in the rule statement, AWS WAF evaluates the request as not matching the rule criteria. **Contents** + [ # Request components in AWS WAF ](waf-rule-statement-fields-list.md) + [ ## HTTP method ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-http-method) + [ ## Single header ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-header) + [ ## All headers ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-headers) + [ ## Header order ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-header-order) + [ ## Cookies ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-cookies) + [ ## URI fragment ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-fragment) + [ ## URI path ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-path) + [ ## JA3 fingerprint ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja3-fingerprint) + [ ## JA4 fingerprint ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja4-fingerprint) + [ ## Query string ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-query-string) + [ ## Single query parameter ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-query-param) + [ ## All query parameters ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-all-query-params) + [ ## Body ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-body) + [ ## JSON body ](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-json-body) + [ # Using forwarded IP addresses in AWS WAF ](waf-rule-statement-forwarded-ip-address.md) + [ # Inspecting HTTP/2 pseudo headers in AWS WAF ](waf-rule-statement-request-components-for-http2-pseudo-headers.md) + [ # Using text transformations in AWS WAF ](waf-rule-statement-transformation.md) # Request components in AWS WAF Request components optionsNew AWS WAF request component You can now inspect the URI fragment. New AWS WAF request components: Headers and Cookies You can now inspect cookies and you can inspect all headers, in addition to just a single header.New AWS WAF request components: Headers and Cookies You can now inspect the cookies in a web request and you can inspect all headers in a web request, in addition to just a single header. This section describes the components of the web request that you can specify for inspection. You specify the request component for match rule statements that look for patterns inside the web request. These types of statements include string match, regex match, size constraint, and SQL injection attack statements. For information on how to use these request component settings, see the individual rule statements at [Using match rule statements in AWS WAF](waf-rule-statements-match.md) Unless otherwise noted, if a web request doesn't have the request component that's specified in the rule statement, AWS WAF evaluates the request as not matching the rule criteria. **Note** You specify a single request component for each rule statement that requires it. To inspect more than one component of a request, create a rule statement for each component. The AWS WAF console and API documentation provide guidance for the request component settings in the following locations: + **Rule builder** on the console – In the **Statement** settings for a regular rule type, choose the component that you want to inspect in the **Inspect** dialogue under **Request components**. + **API statement contents** – `FieldToMatch` The rest of this section describes the options for the part of the web request to inspect. **Topics** + [ ## HTTP method ](#waf-rule-statement-request-component-http-method) + [ ## Single header ](#waf-rule-statement-request-component-single-header) + [ ## All headers ](#waf-rule-statement-request-component-headers) + [ ## Header order ](#waf-rule-statement-request-component-header-order) + [ ## Cookies ](#waf-rule-statement-request-component-cookies) + [ ## URI fragment ](#waf-rule-statement-request-component-uri-fragment) + [ ## URI path ](#waf-rule-statement-request-component-uri-path) + [ ## JA3 fingerprint ](#waf-rule-statement-request-component-ja3-fingerprint) + [ ## JA4 fingerprint ](#waf-rule-statement-request-component-ja4-fingerprint) + [ ## Query string ](#waf-rule-statement-request-component-query-string) + [ ## Single query parameter ](#waf-rule-statement-request-component-single-query-param) + [ ## All query parameters ](#waf-rule-statement-request-component-all-query-params) + [ ## Body ](#waf-rule-statement-request-component-body) + [ ## JSON body ](#waf-rule-statement-request-component-json-body) ## HTTP method HTTP method Inspects the HTTP method for the request. The HTTP method indicates the type of operation that the web request is asking your protected resource to perform, such as `POST` or `GET`. ## Single header Single header Inspects a single named header in the request. For this option, you specify the header name, for example, `User-Agent` or `Referer`. The string match for the name is not case sensitive and is performed after trimming leading and trailing spaces from both the request header and the rule. ## All headers All headersAll headers specification is not case sensitive Changed the all headers specification to be case insensitive. This matches the single header behavior. Inspects all of the request headers, including cookies. You can apply a filter to inspect a subset of all headers. For this option, you provide the following specifications: + **Match patterns** – The filter to use to obtain a subset of headers for inspection. AWS WAF looks for these patterns in the headers keys. The match patterns setting can be one of the following: + **All** – Match all keys. Evaluate the rule inspection criteria for all headers. + **Excluded headers** – Inspect only the headers whose keys don't match any of the strings that you specify here. The string match for a key is not case sensitive. The matching is performed after trimming the leading and trailing spaces from request header and the match rule. + **Included headers** – Inspect only the headers that have a key that matches one of the strings that you specify here. The string match for a key is not case sensitive. The matching is performed after trimming the leading and trailing spaces from request header and the match rule. + **Match scope** – The parts of the headers that AWS WAF should inspect with the rule inspection criteria. You can specify **Keys**, **Values**, or **All** to inspect both keys and values for a match. **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. + **Oversize handling** – How AWS WAF should handle requests that have header data that is larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request headers and at most the first 200 headers. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). ## Header order Header orderNew AWS WAF request component: Header order You can now match against an ordered list of the names of the headers in the request. 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 with colons and with no added spaces, for example `host:user-agent:accept:authorization:referer`. For this option, you provide the following specifications: + **Oversize handling** – How AWS WAF should handle requests that have header data that is more numerous or larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request headers and at most the first 200 headers. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue inspecting the headers that are available, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). ## Cookies Cookies Inspects all of the request cookies. You can apply a filter to inspect a subset of all cookies. For this option, you provide the following specifications: + **Match patterns** – The filter to use to obtain a subset of cookies for inspection. AWS WAF looks for these patterns in the cookie keys. The match patterns setting can be one of the following: + **All** – Match all keys. Evaluate the rule inspection criteria for all cookies. + **Excluded cookies** – Inspect only the cookies whose keys don't match any of the strings that you specify here. The string match for a key is case sensitive and must be exact. + **Included cookies** – Inspect only the cookies that have a key that matches one of the strings that you specify here. The string match for a key is case sensitive and must be exact. + **Match scope** – The parts of the cookies that AWS WAF should inspect with the rule inspection criteria. You can specify **Keys**, **Values**, or **All** for both keys and values. **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. + **Oversize handling** – How AWS WAF should handle requests that have cookie data that is larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request cookies and at most the first 200 cookies. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). ## URI fragment URI fragment **Note** Uri Fragment inspection is available only for CloudFront distributions and Application Load Balancers. Inspects the part of a URL that follows the "\$1" symbol, providing additional information about the resource, for example, \$1section2. For information, see [Uniform Resource Identifier (URI): Generic Syntax](https://tools.ietf.org/html/rfc3986#section-3). If you don't use a text transformation with this option, AWS WAF doesn't normalize the URI fragment and inspects it exactly as it receives it from the client in the request. For information about text transformations, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md). **Rule statement requirements** You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if URI is missing the fragment or associated service is not Application Load Balancer or CloudFront. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement. ## URI path URI path Inspects the part of a URL that identifies a resource, for example, `/images/daily-ad.jpg`. For information, see [Uniform Resource Identifier (URI): Generic Syntax](https://tools.ietf.org/html/rfc3986#section-3). If you don't use a text transformation with this option, AWS WAF doesn't normalize the URI and inspects it exactly as it receives it from the client in the request. For information about text transformations, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md). ## JA3 fingerprint JA3 fingerprintAWS WAF adds inspection of JA3 fingerprint You can now perform an exact match against the web request's JA3 fingerprint, for Amazon CloudFront distributions and Application Load Balancers. Inspects the request's JA3 fingerprint. **Note** JA3 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers. The JA3 fingerprint is a 32-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation. Almost all web requests include this information. **How to get the JA3 fingerprint for a client** You can obtain the JA3 fingerprint for a client's requests from the protection pack (web ACL) logs. If AWS WAF is able to calculate the fingerprint, it includes it in the logs. For information about the logging fields, see [Log fields for protection pack (web ACL) traffic](logging-fields.md). **Rule statement requirements** You can inspect the JA3 fingerprint only inside a string match statement that's set to exactly match the string that you provide. Provide the JA3 fingerprint string from the logs in your string match statement specification, to match with any future requests that have the same TLS configuration. For information about the string match statement, see [String match rule statement](waf-rule-statement-type-string-match.md). You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if AWS WAF is unable to calculate the JA3 fingerprint. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement. To use this match option, you must log your protection pack (web ACL) traffic. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). ## JA4 fingerprint JA4 fingerprintAWS WAF adds inspection of JA4 fingerprint You can now perform an exact match against the web request's JA4 fingerprint, for Amazon CloudFront distributions and Application Load Balancers. AWS WAF supports new JA4 field matching You can detect and block traffic based on advanced JavaScript Fingerprinting (JA4) characteristics and use the JA4 fingerprint as one of the supported request keys within WAF rate-based rules. Inspects the request's JA4 fingerprint. **Note** JA4 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers. The JA4 fingerprint is a 36-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. JA4 fingerprinting is an extension of the JA3 fingerprinting that can result in fewer unique fingerprints for some browsers. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation. Almost all web requests include this information. **How to get the JA4 fingerprint for a client** You can obtain the JA4 fingerprint for a client's requests from the protection pack (web ACL) logs. If AWS WAF is able to calculate the fingerprint, it includes it in the logs. For information about the logging fields, see [Log fields for protection pack (web ACL) traffic](logging-fields.md). **Rule statement requirements** You can inspect the JA4 fingerprint only inside a string match statement that's set to exactly match the string that you provide. Provide the JA4 fingerprint string from the logs in your string match statement specification, to match with any future requests that have the same TLS configuration. For information about the string match statement, see [String match rule statement](waf-rule-statement-type-string-match.md). You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if AWS WAF is unable to calculate the JA4 fingerprint. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement. To use this match option, you must log your protection pack (web ACL) traffic. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). ## Query string Query string Inspects the part of the URL that appears after a `?` character, if any. **Note** For cross-site scripting match statements, we recommend that you choose **All query parameters** instead of **Query string**. Choosing **All query parameters** adds 10 WCUs to the base cost. ## Single query parameter Single query parameter Inspects a single query parameter that you have defined as part of the query string. AWS WAF inspects the value of the parameter that you specify. For this option, you also specify a **Query argument**. For example, if the URL is `www.xyz.com?UserName=abc&SalesRegion=seattle`, you can specify `UserName` or `SalesRegion` for the query argument. The maximum length for the name of the argument is 30 characters. The name is not case sensitive, so if you specify `UserName`, AWS WAF matches all variations of `UserName`, including `username` and `UsERName`. If the query string contains more than one instance of the query argument that you've specified, AWS WAF inspects all the values for a match, using OR logic. For example, in the URL `www.xyz.com?SalesRegion=boston&SalesRegion=seattle`, AWS WAF evaluates the name that you've specified against `boston` and `seattle`. If either is a match, the inspection is a match. ## All query parameters All query parameters Inspects all query parameters in the request. This is similar to the single query parameter component choice, but AWS WAF inspects the values of all arguments within the query string. For example, if the URL is `www.xyz.com?UserName=abc&SalesRegion=seattle`, AWS WAF triggers a match if either the value of `UserName` or `SalesRegion` match the inspection criteria. Choosing this option adds 10 WCUs to the base cost. ## Body Body Inspects the request body, evaluated as plain text. You can also evaluate the body as JSON using the JSON content type. The request body is the part of the request that immediately follows the request headers. It contains any additional data that is needed for the web request, for example, data from a form. + In the console, you select this under the **Request option** choice **Body**, by selecting the **Content type** choice **Plain text**. + In the API, in the rule's `FieldToMatch` specification, you specify `Body` to inspect the request body as plain text. For Application Load Balancer and AWS AppSync, AWS WAF can inspect the first 8 KB of the body of a request. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, by default, AWS WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md). You must specify oversize handling for this component type. Oversize handling defines how AWS WAF handles requests that have body data that is larger than AWS WAF can inspect. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). You can also evaluate the body as parsed JSON. For information about this, see the section that follows. ## JSON body JSON bodyClarify how JSON body parsing works Updated coverage for JSON body inspection to clarify how AWS WAF handles parsing and the body parsing fallback behavior. Inspect a web request body as parsed JSON Added the option to inspect the web request body as parsed and filtered JSON. This is in addition to the existing option to inspect the web request body as plain text. Inspects the request body, evaluated as JSON. You can also evaluate the body as plain text. The request body is the part of the request that immediately follows the request headers. It contains any additional data that is needed for the web request, for example, data from a form. + In the console, you select this under the **Request option** choice **Body**, by selecting the **Content type** choice **JSON**. + In the API, in the rule's `FieldToMatch` specification, you specify `JsonBody`. For Application Load Balancer and AWS AppSync, AWS WAF can inspect the first 8 KB of the body of a request. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, by default, AWS WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md). You must specify oversize handling for this component type. Oversize handling defines how AWS WAF handles requests that have body data that is larger than AWS WAF can inspect. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). Choosing this option doubles the match statement's base cost WCUs. For example, if the match statement base cost is 5 WCUs without JSON parsing, using JSON parsing doubles the cost to 10 WCUs. For this option, you provide additional specifications, as described in the following section. **How AWS WAF handles JSON body inspection** When AWS WAF inspects the web request body as JSON, it performs steps to parse the body and extract the JSON elements for inspection. AWS WAF performs these steps in accordance with your configuration choices. The following lists the steps that AWS WAF performs. 1. **Parse the body contents** – AWS WAF parses the contents of the web request body in order to extract the JSON elements for inspection. AWS WAF does its best to parse the entire contents of the body, but parsing can fail for a variety of error states in the contents. Examples include invalid characters, duplicate keys, truncation, and content whose root node isn't an object or an array. The option **Body parsing fallback behavior** determines what AWS WAF does if it fails to completely parse the JSON body: + **None (default behavior)** - AWS WAF evaluates the content only up to the point where it encountered a parsing error. + **Evaluate as string** - Inspect the body as plain text. AWS WAF applies the text transformations and inspection criteria that you defined for the JSON inspection to the body text string. + **Match** - Treat the web request as matching the rule statement. AWS WAF applies the rule action to the request. + **No match** - Treat the web request as not matching the rule statement. **Note** This fallback behavior only triggers when AWS WAF encounters an error while parsing the JSON string. **Parsing doesn't fully validate the JSON** AWS WAF parsing doesn't fully validate the input JSON string, so parsing can succeed even for invalid JSON. For example, AWS WAF parses the following invalid JSON without error: + Missing comma: `{"key1":"value1""key2":"value2"}` + Missing colon: `{"key1":"value1","key2""value2"}` + Extra colons: `{"key1"::"value1","key2""value2"}` For cases such as these where the parsing succeeds but the result isn't completely valid JSON, the outcome of the subsequent steps in the evaluation can vary. The extraction might miss some elements, or the rule evaluation might have unexpected results. We recommend that you validate the JSON that you receive in your application and handle invalid JSON as needed. 1. **Extract the JSON elements** – AWS WAF identifies the subset of JSON elements to inspect according to your settings: + The option **JSON match scope** specifies the types of elements in the JSON that AWS WAF should inspect. You can specify **Keys**, **Values**, or **All** for both keys and values. **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. + The option **Content to inspect** specifies how to filter the element set to the subset that you want AWS WAF to inspect. You must specify one of the following: + **Full JSON content** - Evaluate all elements. + **Only included elements** - Evaluate only elements whose paths match the JSON Pointer criteria that you provide. Don't use this option to indicate *all* paths in the JSON. Instead, use **Full JSON content**. For information about JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation [JavaScript Object Notation (JSON) Pointer](https://tools.ietf.org/html/rfc6901). For example, in the console, you can provide the following: ``` /dogs/0/name /dogs/1/name ``` In the API or CLI, you can provide the following: ``` "IncludedPaths": ["/dogs/0/name", "/dogs/1/name"] ``` For example, say that the **Content to inspect** setting is **Only included elements**, and the included elements setting is `/a/b`. For the following example JSON body: ``` { "a":{ "c":"d", "b":{ "e":{ "f":"g" } } } } ``` The element sets that AWS WAF would inspect for each **JSON match scope** setting are listed below. Note that the key `b`, which is part of the included elements path, isn't evaluated. + **All**: `e`, `f,` and `g`. + **Keys**: `e` and `f`. + **Values**: `g`. 1. **Inspect the JSON element set** – AWS WAF applies any text transformations that you've specified to the extracted JSON elements and then matches the resulting element set against the rule statement's match criteria. This is the same transformation and evaluation behavior as for other web request components. If any of the extracted JSON elements match, the web request is a match for the rule. # Using forwarded IP addresses in AWS WAF Using forwarded IP addressesSpecify IP address location in web request Added the option to use IP addresses from an HTTP header that you specify, instead of using the web request origin. The alternate header is commonly `X-Forwarded-For` (XFF), but you can specify any header name. You can use this option for IP set matching, geo matching, and rate-based rule count aggregation. This section applies to rule statements that use the IP address of a web request. By default, AWS WAF uses the IP address from the web request origin. However, if a web request goes through one or more proxies or load balancers, the web request origin will contain the address of the last proxy, and not the originating address of the client. In this case, the originating client address is usually forwarded in another HTTP header. This header is typically `X-Forwarded-For` (XFF), but it can be a different one. **Rule statements that use IP addresses** The rule statements that use IP addresses are the following: + [IP set match](waf-rule-statement-type-ipset-match.md) - Inspects the IP address for a match with the addresses that are defined in an IP set. + [Geographic match](waf-rule-statement-type-geo-match.md) - Uses the IP address to determine country and region of origin and matches the country of origin against a list of countries. + [ASN match](waf-rule-statement-type-asn-match.md) - Uses the IP address to determine the Autonomous System Number (ASN) and matches the ASN against a list of ASNs. + [Using rate-based rule statements](waf-rule-statement-type-rate-based.md) - Can aggregate requests by their IP addresses to ensure that no individual IP address sends requests at too high a rate. You can use IP address aggregation by itself or in combination with other aggregation keys. You can instruct AWS WAF to use a forwarded IP address for any of these rule statements, either from the `X-Forwarded-For` header or from another HTTP header, instead of using the web request's origin. For details on how to provide the specifications, see the guidance for the individual rule statement types. **Note** If a header is missing, AWS WAF evaluates any statement that uses that header as "No match." If you use a NOT statement with a "No match" result, AWS WAF converts the evaluation to "Match." Missing headers don't trigger fallback behavior - only invalid header values do. **Fallback behavior** When you use the forwarded IP address, you indicate the match status for AWS WAF to assign to the web request if the request doesn't have a valid IP address in the specified position: + **MATCH** - Treat the web request as matching the rule statement. AWS WAF applies the rule action to the request. + **NO MATCH** - Treat the web request as not matching the rule statement. **IP addresses used in AWS WAF Bot Control** The Bot Control managed rule group verifies bots using the IP addresses from AWS WAF. If you use Bot Control and you have verified bots that route through a proxy or load balancer, you need to explicitly allow them using a custom rule. For example, you can configure a custom IP set match rule that uses forwarded IP addresses to detect and allow your verified bots. You can use the rule to customize your bot management in a number of ways. For information and examples, see [AWS WAF Bot Control](waf-bot-control.md). **General considerations for using forwarded IP addresses** Before you use a forwarded IP address, note the following general caveats: + A header can be modified by proxies along the way, and the proxies might handle the header in different ways. + Attackers might alter the contents of the header in an attempt to bypass AWS WAF inspections. + The IP address inside the header can be malformed or invalid. + The header that you specify might not be present at all in a request. **Considerations for using forwarded IP addresses with AWS WAF** The following list describes requirements and caveats for using forwarded IP addresses in AWS WAF: + For any single rule, you can specify one header for the forwarded IP address. The header specification is case insensitive. + For rate-based rule statements, any nested scoping statements do not inherit the forwarded IP configuration. Specify the configuration for each statement that uses a forwarded IP address. + For geo match, ASN match, and rate-based rules, AWS WAF uses the first address in the header. For example, if a header contains `10.1.1.1, 127.0.0.0, 10.10.10.10` AWS WAF uses `10.1.1.1` + For IP set match, you indicate whether to match against the first, last, or any address in the header. If you specify any, AWS WAF inspects all addresses in the header for a match, up to 10 addresses. If the header contains more than 10 addresses, AWS WAF inspects the last 10. + Headers that contain multiple addresses must use a comma separator between the addresses. If a request uses a separator other than a comma, AWS WAF considers the IP addresses in the header malformed. + If the IP addresses inside the header are malformed or invalid, AWS WAF designates the web request as matching the rule or not matching, according to the fallback behavior that you specify in the forwarded IP configuration. + If the header that you specify isn’t present in a request, AWS WAF doesn’t apply the rule to the request at all. This means that AWS WAF doesn't apply the rule action and doesn't apply the fallback behavior. + A rule statement that uses a forwarded IP header for the IP address won’t use the IP address that’s reported by the web request origin. **Best practices for using forwarded IP addresses with AWS WAF** When you use forwarded IP addresses, use the following best practices: + Carefully consider all possible states of your request headers before enabling forwarded IP configuration. You might need to use more than one rule to get the behavior you want. + To inspect multiple forwarded IP headers or to inspect the web request origin and a forwarded IP header, use one rule for each IP address source. + To block web requests that have an invalid header, set the rule action to block and set the fallback behavior for the forwarded IP configuration to match. **Example JSON for forwarded IP addresses** The following geo match statement matches only if the `X-Forwarded-For` header contains an IP whose country of origin is `US`: ``` { "Name": "XFFTestGeo", "Priority": 0, "Action": { "Block": {} }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "XFFTestGeo" }, "Statement": { "GeoMatchStatement": { "CountryCodes": [ "US" ], "ForwardedIPConfig": { "HeaderName": "x-forwarded-for", "FallbackBehavior": "MATCH" } } } } ``` The following rate-based rule aggregates requests based on the first IP in the `X-Forwarded-For` header. The rule counts only requests that match the nested geo match statement, and it only blocks requests that match the geo match statement. The nested geo match statement also uses the `X-Forwarded-For` header to determine whether the IP address indicates a country of origin of `US`. If it does, or if the header is present but malformed, the geo match statement returns a match. ``` { "Name": "XFFTestRateGeo", "Priority": 0, "Action": { "Block": {} }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "XFFTestRateGeo" }, "Statement": { "RateBasedStatement": { "Limit": "100", "AggregateKeyType": "FORWARDED_IP", "ScopeDownStatement": { "GeoMatchStatement": { "CountryCodes": [ "US" ], "ForwardedIPConfig": { "HeaderName": "x-forwarded-for", "FallbackBehavior": "MATCH" } } }, "ForwardedIPConfig": { "HeaderName": "x-forwarded-for", "FallbackBehavior": "MATCH" } } } } ``` # Inspecting HTTP/2 pseudo headers in AWS WAF Inspecting HTTP/2 pseudo headersHow to inspect HTTP/2 pseudo headers Added a section that maps HTTP/2 pseudo headers to their corresponding web request components. This section explains how you can use AWS WAF to inspect HTTP/2 pseudo headers. Protected AWS resources that support HTTP/2 traffic do not forward HTTP/2 pseudo headers to AWS WAF for inspection, but they provide contents of pseudo headers in web request components that AWS WAF inspects. You can use AWS WAF to inspect only the pseudo headers that are listed in the following table. **HTTP/2 pseudo header contents mapped to web request components** | HTTP/2 pseudo header | Web request component to inspect | Documentation | | --- | --- | --- | | `:method` | HTTP method | [HTTP method](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-http-method) | | `:authority` | `Host` header | [Single header](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-header) [All headers](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-headers) | | `:path` URI path | URI path | [URI path](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-path) | | `:path` query | Query string | [Query string](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-query-string) [Single query parameter](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-query-param) [All query parameters](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-all-query-params) | # Using text transformations in AWS WAF Using text transformationsAWS WAF HTML entity decode text transformation Expanded the functionality of the HTML entity decode text transformation. AWS WAF additional text transformation options Expanded options for text transformations, which you can apply to web request components before inspecting them. This section explains how to provide transformations for AWS WAF to apply before inspecting the request. In statements that look for patterns or set constraints, you can provide transformations for AWS WAF to apply before inspecting the request. A transformation reformats a web request to eliminate some of the unusual formatting that attackers use in an effort to bypass AWS WAF. When you use this with the JSON body request component selection, AWS WAF applies your transformations after parsing and extracting the elements to inspect from the JSON. For more information, see [JSON body](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-json-body). If you provide more than one transformation, you also set the order for AWS WAF to apply them. **WCUs** – Each text transformation is 10 WCUs. The AWS WAF console and API documentation also provide guidance for these settings in the following locations: + **Rule builder** on the console – **Text transformation**. This option is available when you use request components. + **API statement contents** – `TextTransformations`Options for text transformations Each transformation listing shows the console and API specifications followed by the description. Base64 decode – `BASE64_DECODE` AWS WAF decodes a Base64-encoded string. Base64 decode extension – `BASE64_DECODE_EXT` AWS WAF decodes a Base64-encoded string, but uses a forgiving implementation that ignores characters that aren't valid. Command line – `CMD_LINE` This option mitigates situations where attackers might be injecting an operating system command-line command and are using unusual formatting to disguise some or all of the command. Use this option to perform the following transformations: + Delete the following characters: `\ " ' ^` + Delete spaces before the following characters: `/ (` + Replace the following characters with a space: `, ;` + Replace multiple spaces with one space + Convert uppercase letters, `A-Z`, to lowercase, `a-z` Compress whitespace – `COMPRESS_WHITE_SPACE` AWS WAF compresses white space by replacing multiple spaces with one space and replacing the following characters with a space character (ASCII 32): + Formfeed (ASCII 12) + Tab (ASCII 9) + Newline (ASCII 10) + Carriage return (ASCII 13) + Vertical tab (ASCII 11) + Non-breaking space (ASCII 160) CSS decode – `CSS_DECODE` AWS WAF decodes characters that were encoded using CSS 2.x escape rules `syndata.html#characters`. This function uses up to two bytes in the decoding process, so it can help to uncover ASCII characters that were encoded using CSS encoding that wouldn’t typically be encoded. It's also useful in countering evasion, which is a combination of a backslash and non-hexadecimal characters. For example, `ja\vascript` for `javascript`. Escape sequences decode – `ESCAPE_SEQ_DECODE` AWS WAF decodes the following ANSI C escape sequences: `\a`, `\b`, `\f`, `\n`, `\r`, `\t`, `\v`, `\\`, `\?`, `\'`, `\"`, `\xHH` (hexadecimal), `\0OOO` (octal). Encodings that aren't valid remain in the output. Hex decode – `HEX_DECODE` AWS WAF decodes a string of hexadecimal characters into a binary. HTML entity decode – `HTML_ENTITY_DECODE` AWS WAF replaces characters that are represented in hexadecimal format `&#xhhhh;` or decimal format `&#nnnn;` with the corresponding characters. AWS WAF replaces the following HTML-encoded characters with unencoded characters. This list uses lowercase HTML encoding, but the handling is case insensitive, for example `&QuOt;` and `"` are treated the same. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-transformation.html) JS decode – `JS_DECODE` AWS WAF decodes JavaScript escape sequences. If a `\uHHHH` code is in the full-width ASCII code range of `FF01-FF5E`, then the higher byte is used to detect and adjust the lower byte. If not, only the lower byte is used and the higher byte is zeroed, causing a possible loss of information. Lowercase – `LOWERCASE` AWS WAF converts uppercase letters (A-Z) to lowercase (a-z). MD5 – `MD5` AWS WAF calculates an MD5 hash from the data in the input. The computed hash is in a raw binary form. None – `NONE` AWS WAF inspects the web request as received, without any text transformations. Normalize path – `NORMALIZE_PATH` AWS WAF normalizes the input string by removing multiple slashes, directory self-references, and directory back-references that are not at the beginning of the input. Normalize path Windows – `NORMALIZE_PATH_WIN` AWS WAF converts backslash characters to forward slashes and then processes the resulting string using the `NORMALIZE_PATH` transformation. Remove nulls – `REMOVE_NULLS` AWS WAF removes all `NULL` bytes from the input. Replace comments – `REPLACE_COMMENTS` AWS WAF replaces each occurrence of a C-style comment (/\$1 ... \$1/) with a single space. It doesn't compress multiple consecutive occurrences. It replaces unterminated comments with a space (ASCII 0x20). It doesn't change a standalone termination of a comment (\$1/). Replace nulls – `REPLACE_NULLS` AWS WAF replaces each `NULL` byte in the input with the space character (ASCII 0x20). SQL hex decode – `SQL_HEX_DECODE` AWS WAF decodes SQL hex data. For example, AWS WAF decodes (`0x414243`) to (`ABC`). URL decode – `URL_DECODE` AWS WAF decodes a URL-encoded value. URL decode Unicode – `URL_DECODE_UNI` Like `URL_DECODE`, but with support for Microsoft-specific `%u` encoding. If the code is in the full-width ASCII code range of `FF01-FF5E`, the higher byte is used to detect and adjust the lower byte. Otherwise, only the lower byte is used and the higher byte is zeroed. UTF8 to Unicode – `UTF8_TO_UNICODE` AWS WAF converts all UTF-8 character sequences to Unicode. This helps normalize input and it minimizes false-positives and false-negatives for non-English languages. # Using scope-down statements in AWS WAF Using scope-down statementsScope-down statement for managed rule groups You can now use a scope-down statement with managed rule groups in the same way as you can with a rate-based statement. This section explains what a scope-down statement and how it works. A scope-down statement is a nestable rule statement that you add inside a managed rule group statement or a rate-based statement to narrow the set of requests that the containing rule evaluates. The containing rule only evaluates the requests that first match the scope-down statement. + **Managed rule group statement** – If you add a scope-down statement to a managed rule group statement, AWS WAF evaluates any request that doesn't match the scope-down statement as not matching the rule group. Only those requests that match the scope-down statement are evaluated against the rule group. For managed rule groups with pricing that's based on the number of requests evaluated, scope-down statements can help contain costs. For more information about managed rule group statements, see [Using managed rule group statements in AWS WAF](waf-rule-statement-type-managed-rule-group.md). + **Rate-based rule statement** – A rate-based rule statement without a scope-down statement rate limits all requests that the rule evaluates. If you want to only control the rate for a specific category of requests, add a scope-down statement to the rate-based rule. For example, to only track and control the rate of requests from a specific geographical area, you can specify that geographical area in a geographic match statement and add it to your rate-based rule as the scope-down statement. For more information about rate-based rule statements, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md). You can use any nestable rule in a scope-down statement. For the available statements, see [Using match rule statements in AWS WAF](waf-rule-statements-match.md) and [Using logical rule statements in AWS WAF](waf-rule-statements-logical.md). The WCUs for a scope-down statement are the WCUs required for the rule statement that you define in it. There's no additional cost for the use of a scope-down statement. You can configure a scope-down statement in the same way as you do when you use the statement in a regular rule. For example, you can apply text transformations to a web request component that you're inspecting and you can specify a forwarded IP address to use as the IP address. These configurations apply only to the scope-down statement and are not inherited by the containing managed rule group or rate-based rule statement. For example, if you apply text transformations to a query string in your scope-down statement, the scope-down statement inspects the query string after applying the transformations. If the request matches the scope-down statement criteria, AWS WAF then passes the web request to the containing rule in its original state, without the scope-down statement's transformations. The rule that contains the scope-down statement might apply text transformations of its own, but it doesn't inherit any from the scope-down statement. You can't use a scope-down statement to specify any request inspection configuration for the containing rule statement. You can't use a scope-down statement as a web request preprocessor for the containing rule statement. The only role of a scope-down statement is to determine which requests are passed to the containing rule statement for inspection. # Referencing reusable entities in AWS WAF Referencing reusable entities This section explains how reusable entities work in AWS WAF. Some rules use entities that are reusable and that are managed outside of your web ACLs, either by you, AWS, or an AWS Marketplace seller. When the reusable entity is updated, AWS WAF propagates the update to your rule. For example, if you use an AWS Managed Rules rule group in a protection pack (web ACL), when AWS updates the rule group, AWS propagates the change to your web ACL, to update its behavior. If you use an IP set statement in a rule, when you update the set, AWS WAF propagates the change to all rules that reference it, so any protection packs (web ACLs) that use those rules are kept up-to-date with your changes. The following are the reusable entities that you can use in a rule statement. + **IP sets** – You create and manage your own IP sets. On the console, you can access these from the navigation pane. For information about managing IP sets, see [IP sets and regex pattern sets in AWS WAF](waf-referenced-set-managing.md). + **Regex match sets** – You create and manage your own regex match sets. On the console, you can access these from the navigation pane. For information about managing regex pattern sets, see [IP sets and regex pattern sets in AWS WAF](waf-referenced-set-managing.md). + **AWS Managed Rules rule groups** – AWS manages these rule groups. On the console, these are available for your use when you add a managed rule group to your protection pack (web ACL). For more information about these, see [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md). + **AWS Marketplace managed rule groups** – AWS Marketplace sellers manage these rule groups and you can subscribe to them to use them. To manage your subscriptions, on the navigation pane of the console, choose **AWS Marketplace**. The AWS Marketplace managed rule groups are listed when you add a managed rule group to your protection pack (web ACL). For rule groups that you haven't yet subscribed to, you can find a link to AWS Marketplace on that page as well. For more information about AWS Marketplace seller managed rule groups, see [AWS Marketplace rule groups](marketplace-rule-groups.md). + **Your own rule groups** – You manage your own rule groups, usually when you need some behavior that isn't available through the managed rule groups. On the console, you can access these from the navigation pane. For more information, see [Managing your own rule groups](waf-user-created-rule-groups.md). **Deleting a referenced set or rule group** When you delete a referenced entity, AWS WAF checks to see if it's currently being used in a protection pack (web ACL). If AWS WAF finds that it's in use, it warns you. AWS WAF is almost always able to determine if an entity is being referenced by a protection pack (web ACL). However, in rare cases, it might not be able to do so. If you need to be sure that the entity that you want to delete isn't in use, check for it in your web ACLs before deleting it.