How Amazon WAF labeling works - 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).

How Amazon WAF labeling works

When a rule matches a web request, if the rule has labels defined, Amazon WAF adds the labels to the request at the end of the rule evaluation. Rules that are evaluated after the matching rule in the web ACL can match against the labels that the rule has added.

Who adds labels to requests

The web ACL components that evaluate requests can add labels to the requests.

  • Any rule that isn't a rule group reference statement can add labels to matching web requests. The labeling criteria is part of the rule definition, and when a web request matches the rule, Amazon WAF adds the rule's labels to the request. For information, see Amazon WAF rules that add labels.

  • The geo match rule statement adds country and region labels to any request that it inspects, regardless of whether the statement results in a match. For information, see Geographic match rule statement.

  • The Amazon Managed Rules for Amazon WAF all add labels to requests that they inspect. They add some labels based on rule matches in the rule group and they add some based on Amazon processes that the managed rule groups use, such as the token labeling added when you use an intelligent threat mitigation rule group. For information about the labels that each managed rule group adds, see Amazon Managed Rules rule groups list.

How Amazon WAF manages labels

Amazon WAF adds the rule's labels to the request at the end of the rule's inspection of the request. Labeling is part of a rule's match activities, similar to the action.

Labels don't persist with the web request after the web ACL evaluation ends. In order for other rules to match against a label that your rule adds, your rule action must not terminate the evaluation of the web request by the web ACL. The rule action must be set to Count, CAPTCHA, or Challenge. When the web ACL evaluation doesn't terminate, subsequent rules in the web ACL can run their label matching criteria against the request. For more information about rule actions, see Rule action.

Access to labels during web ACL evaluation

Once added, labels remain available on the request as long as Amazon WAF is evaluating the request against the web ACL. Any rule in a web ACL can access labels that have been added by the rules that have already run in the same web ACL. This includes rules that are defined directly inside the web ACL and rules defined inside rule groups that are used in the web ACL.

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

  • The geographic match statement adds labels with or without a match, but they're only available after the statement's containing web ACL rule has completed the request evaluation.

    • You can't use a single rule, for example a logical AND statement, to run a geo match statement followed by a label match statement against the geographic labels. You must put the label match statement in a separate rule that runs after the rule that contains the geo match statement.

    • If you use a geo match statement as a scope-down statement inside a rate-based rule statement or managed rule group reference statement, the labels that the geo match statement adds are not available for inspection by the containing rule's statement. If you need to inspect geographic labeling in a rate-based rule statement or a rule group, you must run the geo match statement in a separate rule that runs beforehand.

Access to label information outside of web ACL evaluation

Labels don't persist with the web request after the web ACL evaluation ends, but Amazon WAF records label information in the logs and in metrics.

  • Amazon WAF stores Amazon CloudWatch metrics for the first 100 labels on any single request. For information about accessing label metrics, see Monitoring with Amazon CloudWatch and Label metrics and dimensions.

  • Amazon WAF summarizes CloudWatch label metrics in the web ACL traffic overview dashboards in the Amazon WAF console. You can access the dashboards on any web ACL page. For more information, see Web ACL traffic overview dashboards.

  • Amazon WAF records labels in the logs for the first 100 labels on a request. You can use labels, along with the rule action, to filter the logs that Amazon WAF records. For information, see Logging Amazon WAF web ACL traffic.

Your web ACL evaluation can apply more than 100 labels to a web request and match against more than 100 labels, but Amazon WAF only records the first 100 in the logs and metrics.