Labels on web requests - AWS WAF, AWS Firewall Manager, and AWS Shield Advanced

Labels on web requests

A label is metadata added to a web request by a matching rule. You can use labels to communicate rule match results to rules that are evaluated later in the same web ACL.

  • Any rule that isn't a rule group reference statement can add labels to matching web requests. When a web request matches a rule, AWS WAF adds the rule's labels to the request. For the geographical match rule, AWS WAF adds the rule's labels to any request that the rule inspects, match or no match.

  • AWS WAF adds labels to a request at the end of the rule's inspection of the request. So when a single rule contains multiple statements, for example within a logical AND or OR statement, any labels that the contained statements assign are available on the web request only after all contained statements have been evaluated.

  • Once added, labels remain available on the request as long as AWS WAF is evaluating the request against the web ACL.

  • You can match against a label in your rule's request inspection criteria using the label match statement. For statement details, see Label match rule statement.

Common use cases for AWS WAF labels include the following:

  • Evaluating a web request against multiple rule statements before taking action on the request – After a match is found with a rule in a web ACL, AWS WAF continues evaluating the request against the web ACL if the rule action is Count. You can use labels to evaluate and collect information from multiple rules before you decide to allow or block the request. To do this, change the actions for your existing rules to Count and configure them to add labels to matching requests. Then, add one or more new rules to run after your other rules, and configure them to evaluate the labels and manage the requests according to the label match combinations.

  • Managing web requests by geographical region – You can use the geographic match rule alone to manage web requests by the country of origin. To fine-tune the location down to the region level, you use the geo match rule with a Count action followed by a label match rule. For information about the geo match rule, see Geographic match rule statement.

  • Reusing logic across multiple rules – If you need to reuse the same logic across multiple rules, you can use labels to single-source the logic and just test for the results. When you have multiple complex rules that use a common subset of nested rule statements, duplicating the common rule set across your complex rules can be time consuming and error prone. With labels, you can create a new rule with the common rule subset that counts matching requests and adds a label to them. You add the new rule to your web ACL so that it runs before your original complex rules. Then, in your original rules, you replace the shared rule subset with a single rule that checks for the label.

    For example, say you have multiple rules that you want to only apply to your login paths. Rather than have each rule specify the same logic to match potential login paths, you can implement a single new rule that contains that logic. Have the new rule add a label to matching requests to indicate that the request is on a login path. In your web ACL, give this new rule a lower numeric priority setting than your original rules so that it runs first. Then, in your original rules, replace the shared logic with a check for the presence of the label. For information about priority settings, see Processing order of rules and rule groups in a web ACL.

  • Creating exceptions to rules in rule groups – This option is particularly useful for managed rule groups, which you can't view or alter. Many managed rule group rules add labels to matching web requests, to indicate the rules that matched and possibly to provide additional information about the match. When you use a rule group that adds labels to requests, you can override the rule group rules to count matches, and then run a rule after the rule group that handles the web request based on the rule group labels. All AWS Managed Rules add labels to matching web requests. For details, see the rule descriptions at AWS Managed Rules rule groups list.

AWS Managed Rules rule groups add labels to the web requests that they evaluate. Most of these labels are added by the rules in the rule groups. Some labels are added by AWS processes that are used by managed rules. For example, the account takeover prevention and Bot Control managed rule groups use AWS WAF token management to add labels to requests that indicate the status of their tokens. For information about managed rule groups and the labels that they add, see AWS Managed Rules rule groups list.