How labeling works in Amazon WAF - Amazon WAF, Amazon Firewall Manager, Amazon Shield Advanced, and Amazon Shield network security director
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).

Introducing a new console experience for Amazon WAF

You can now use the updated experience to access Amazon WAF functionality anywhere in the console. For more details, see Working with the updated console experience.

How labeling works in Amazon WAF

This section explains how Amazon WAF labels work.

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 protection pack or web ACL can match against the labels that the rule has added.

Who adds labels to requests

The protection pack or 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 protection pack or 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 protection pack or web ACL. The rule action must be set to Count, CAPTCHA, or Challenge. When the protection pack or web ACL evaluation doesn't terminate, subsequent rules in the protection pack or web ACL can run their label matching criteria against the request. For more information about rule actions, see Using rule actions in Amazon WAF.

Access to labels during protection pack or web ACL evaluation

Once added, labels remain available on the request as long as Amazon WAF is evaluating the request against the protection pack or web ACL. Any rule in a protection pack or web ACL can access labels that have been added by the rules that have already run in the same protection pack or web ACL. This includes rules that are defined directly inside the protection pack or web ACL and rules defined inside rule groups that are used in the protection pack or 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 protection pack or 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 protection pack or web ACL evaluation

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

Your protection pack or 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.