Request component options - Amazon WAF, Amazon Firewall Manager, and Amazon Shield Advanced
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Request component options

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 Match rule statements

Unless otherwise noted, if a web request doesn't have the request component that's specified in the rule statement, Amazon 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 Amazon 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 contentsFieldToMatch

The rest of this section describes the options for the part of the web request to inspect.

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

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.

All headers

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. Amazon 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.

    • 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.

  • Match scope – The parts of the headers that Amazon 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 Amazon WAF should handle requests that have header data that is larger than Amazon WAF can inspect. Amazon 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 Amazon 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 Handling of oversize request components in Amazon WAF.

Header order

Inspect a string containing the list of the request's header names, ordered as they appear in the web request that Amazon WAF receives for inspection. Amazon WAF generates the string and then uses that as the field to match component in its inspection. Amazon 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 Amazon WAF should handle requests that have header data that is more numerous or larger than Amazon WAF can inspect. Amazon 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 Amazon 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 Handling of oversize request components in Amazon WAF.

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. Amazon 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 Amazon 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 Amazon WAF should handle requests that have cookie data that is larger than Amazon WAF can inspect. Amazon 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 Amazon 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 Handling of oversize request components in Amazon WAF.

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.

If you don't use a text transformation with this option, Amazon 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 Text transformation options.

JA3 fingerprint

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. Amazon 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 web ACL logs. If Amazon WAF is able to calculate the fingerprint, it includes it in the logs. For information about the logging fields, see Log fields.

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.

You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want Amazon WAF to assign to the web request if Amazon WAF is unable to calculate the JA3 fingerprint. If you choose to match, Amazon WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, Amazon WAF treats the request as not matching the rule statement.

To use this match option, you must log your web ACL traffic. For information, see Logging Amazon WAF web ACL traffic.

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

Inspects a single query parameter that you have defined as part of the query string. Amazon 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, Amazon 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, Amazon WAF inspects all the values for a match, using OR logic. For example, in the URL www.xyz.com?SalesRegion=boston&SalesRegion=seattle, Amazon 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

Inspects all query parameters in the request. This is similar to the single query parameter component choice, but Amazon WAF inspects the values of all arguments within the query string. For example, if the URL is www.xyz.com?UserName=abc&SalesRegion=seattle, Amazon 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

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 Amazon AppSync, Amazon 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, Amazon WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your web ACL configuration. For more information, see Managing body inspection size limits.

You must specify oversize handling for this component type. Oversize handling defines how Amazon WAF handles requests that have body data that is larger than Amazon 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 Handling of oversize request components in Amazon WAF.

You can also evaluate the body as parsed JSON. For information about this, see the section that follows.

JSON body

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 Amazon AppSync, Amazon 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, Amazon WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your web ACL configuration. For more information, see Managing body inspection size limits.

You must specify oversize handling for this component type. Oversize handling defines how Amazon WAF handles requests that have body data that is larger than Amazon 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 Handling of oversize request components in Amazon WAF.

When Amazon WAF inspects the web request body as parsed JSON, it parses and extracts the elements from the JSON and inspects the parts that you indicate using the rule's match statement criteria.

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.

With this option, Amazon WAF runs two match patterns against the web request body. The output of the first match pattern is used as input to the second match pattern:

  1. Amazon WAF parses and extracts the JSON content and identifies the elements to inspect. To do this, Amazon WAF uses the criteria that you provide in the rule's JSON body specification.

  2. Amazon WAF applies any text transformations to the extracted elements and then matches the resulting JSON element set against the rule statement's match criteria. If any of the elements match, the web request is a match for the rule.

You specify the following criteria for Amazon WAF to use for the first pattern matching step, to identify the JSON elements to inspect:

  • Body parsing fallback behavior – What Amazon WAF should do if it fails to completely parse the JSON body. The options are the following:

    • None (default behavior) - Amazon WAF evaluates the content only up to the point where it encountered a parsing error.

    • Evaluate as string - Inspect the body as plain text. Amazon 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. Amazon WAF applies the rule action to the request.

    • No match - Treat the web request as not matching the rule statement.

    Amazon WAF does its best to parse the entire JSON body, but might be forced to stop for reasons such as invalid characters, duplicate keys, truncation, and any content whose root node isn't an object or an array.

    Amazon WAF parses the JSON in the following examples as two valid key:value pairs:

    • Missing comma: {"key1":"value1""key2":"value2"}

    • Missing colon: {"key1":"value1","key2""value2"}

    • Extra colons: {"key1"::"value1","key2""value2"}

  • JSON match scope – The types of elements in the JSON that Amazon 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.

  • Content to inspect – The elements in the parsed and extracted JSON that you want Amazon WAF to inspect.

    You must specify one of the following:

    • Full JSON content - Evaluate all elements in the parsed JSON.

    • Only included elements - Evaluate only elements in the JSON that match the JSON Pointer criteria that you provide. For information about the JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation JavaScript Object Notation (JSON) Pointer.

      Don't use this option to include all paths in the JSON. Use Full JSON content instead.

      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"]
Example JSON body inspection scenario

If the included elements setting is /a/b, then for the following JSON body:

{ "a":{ "c":"d", "b":{ "e":{ "f":"g" } } } }

The following list describes what Amazon WAF would evaluate for each match scope setting. The key b, which is part of the included elements path, isn't evaluated.

  • For a match scope set to all: e, f, and g.

  • For a match scope set to keys: e and f.

  • For a match scope set to values: g.