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 that allows a rule that matches the request to communicate its match results to the rules that are evaluated later in the same web ACL.

  • Rules add labels – 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. The labels remain available on the request as long as AWS WAF is evaluating it against the web ACL.

  • The label match statement matches against labels – 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 against the web ACL only if the matching rule action is count. Labels allow you to evaluate and collect information for multiple rules before taking an action of allow or block on the web request. To do this, you change the actions for your existing rules to count and add labels to them. Use the labels to indicate the match and the action that you want to take on the request. The rules that you modify in this way can all run and provide information about the matches that they find, to destinations like logs and metrics. Then, in a final additional rule, you can evaluate the labels that were applied and determine how to handle the request.

  • 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. For some managed rule groups, the 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 in this way, you can place the rules in count mode, and then run a rule after the rule group that handles the web request based on the added 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 token service that's used by the account takeover prevention managed rule group AWSManagedRulesATPRuleSet adds labels to rules. For information about managed rule groups and the labels they add, see AWS Managed Rules rule groups list.