**Introducing a new console experience for AWS WAF**

You can now use the updated experience to access AWS WAF functionality anywhere in the console. For more details, see [Working with the console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

# Web request labeling in AWS WAF
<a name="waf-labels"></a>

This section explains what AWS WAF labels are.

A label is metadata added to a web request by a rule when the rule matches the request. Once added, a label remains available on the request until the protection pack (web ACL) evaluation ends. You can access labels in rules that run later in the protection pack (web ACL) evaluation by using a label match statement. For details, see [Label match rule statement](waf-rule-statement-type-label-match.md). 

Labels on web requests generate Amazon CloudWatch label metrics. For a list of metrics and dimensions, see [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). For information about accessing metrics and metric summaries through CloudWatch and through the AWS WAF console, see [Monitoring and tuning your AWS WAF protections](web-acl-testing-activities.md).

**Labeling use cases**  
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 protection pack (web ACL), AWS WAF continues evaluating the request against the protection pack (web ACL) if the rule action doesn't terminate the protection pack (web ACL) evaluation. 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](waf-rule-statement-type-geo-match.md). 
+ **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 protection pack (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 protection pack (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 [Setting rule priority](web-acl-processing-order.md). 
+ **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-rule-groups-list.md). 
+ **Using label metrics to monitor traffic patterns** – You can access metrics for labels that you add through your rules and for metrics added by any managed rule groups that you use in your protection pack (web ACL). All of the AWS Managed Rules rule groups add labels to the web requests that they evaluate. For a list of label metrics and dimensions, see [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). You can access metrics and metric summaries through CloudWatch and through the protection pack (web ACL) page in the AWS WAF console. For information, see [Monitoring and tuning your AWS WAF protections](web-acl-testing-activities.md). 

# How labeling works in AWS WAF
<a name="waf-rule-label-overview"></a>

This section explains how AWS WAF labels work.

When a rule matches a web request, if the rule has labels defined, AWS 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 (web ACL) can match against the labels that the rule has added. 

**Who adds labels to requests**  
The protection pack (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, AWS WAF adds the rule's labels to the request. For information, see [AWS WAF rules that add labels](waf-rule-label-add.md).
+ 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](waf-rule-statement-type-geo-match.md).
+ The AWS Managed Rules for AWS 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 AWS 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 [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md).

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

**Access to labels during protection pack (web ACL) evaluation**  
Once added, labels remain available on the request as long as AWS WAF is evaluating the request against the protection pack (web ACL). Any rule in a protection pack (web ACL) can access labels that have been added by the rules that have already run in the same protection pack (web ACL). This includes rules that are defined directly inside the protection pack (web ACL) and rules defined inside rule groups that are used in the protection pack (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](waf-rule-statement-type-label-match.md). 
+ The geographic match statement adds labels with or without a match, but they're only available after the statement's containing protection pack (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 (web ACL) evaluation**  
Labels don't persist with the web request after the protection pack (web ACL) evaluation ends, but AWS WAF records label information in the logs and in metrics. 
+ AWS 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](monitoring-cloudwatch.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label).
+ AWS WAF summarizes CloudWatch label metrics in the protection pack (web ACL) traffic overview dashboards in the AWS WAF console. You can access the dashboards on any protection pack (web ACL) page. For more information, see [Traffic overview dashboards for protection packs (web ACLs)](web-acl-dashboards.md).
+ AWS 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 AWS WAF records. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

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

# Label syntax and naming requirements in AWS WAF
<a name="waf-rule-label-requirements"></a>

This section explains how to construct and match against an AWS WAF label.

A label is a string made up of a prefix, optional namespaces, and a name. The components of a label are delimited with a colon. Labels have the following requirements and characteristics:
+ Labels are case-sensitive. 
+ Each label namespace or label name can have up to 128 characters. 
+ You can specify up to five namespaces in a label. 
+ Components of a label are separated by colon (`:`).
+ You can't use the following reserved strings in the namespaces or name that you specify for a label: `awswaf`, `aws`, `waf`, `rulegroup`, `webacl`, `regexpatternset`, `ipset`, and `managed`.

## Label syntax
<a name="waf-rule-label-syntax"></a>

A fully qualified label has a prefix, optional namespaces, and label name. The prefix identifies the rule group or protection pack (web ACL) context of the rule that added the label. Namespaces might be used to add more context for the label. The label name provides the lowest level of detail for a label. It often indicates the specific rule that added the label to the request. 

The label prefix varies depending on its origin. 
+ **Your labels** – The following shows the full label syntax for labels that you create in your protection pack (web ACL) and rule group rules. The entity types are `rulegroup` and `webacl`.

  ```
  awswaf:<entity owner account id>:<entity type>:<entity name>:<custom namespace>:...:<label name>
  ```
  + Label namespace prefix: `awswaf:<entity owner account id>:<entity type>:<entity name>:`
  + Custom namespace additions: `<custom namespace>:…:`

  When you define a label for a rule in a rule group or protection pack (web ACL), you control the custom namespace strings and the label name. The rest is generated for you by AWS WAF. AWS WAF automatically prefixes all labels with `awswaf` and the account and protection pack (web ACL) or rule group entity settings.
+ **Managed rule group labels** – The following shows the full label syntax for labels that are created by rules in managed rule groups. 

  ```
  awswaf:managed:<vendor>:<rule group name>:<custom namespace>:...:<label name>
  ```
  + Label namespace prefix: `awswaf:managed:<vendor>:<rule group name>:`
  + Custom namespace additions: `<custom namespace>:…:`

  All AWS Managed Rules rule groups add labels. For information about managed rule groups, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md). 
+ **Labels from other AWS processes** – These processes are used by AWS Managed Rules rule groups, so you see them added to web requests that you evaluate using managed rule groups. The following shows the full label syntax for labels that are created by processes that are called by managed rule groups. 

  ```
  awswaf:managed:<process>:<custom namespace>:...:<label name>
  ```
  + Label namespace prefix: `awswaf:managed:<process>:`
  + Custom namespace additions: `<custom namespace>:…:`

  Labels of this type are listed for the managed rule groups that call the AWS process. For information about managed rule groups, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md). 

## Label examples for your rules
<a name="waf-rule-label-examples-rules"></a>

The following example labels are defined by rules in a rule group named `testRules` that belongs to the account, 111122223333. 

```
awswaf:111122223333:rulegroup:testRules:testNS1:testNS2:LabelNameA
```

```
awswaf:111122223333:rulegroup:testRules:testNS1:LabelNameQ
```

```
awswaf:111122223333:rulegroup:testRules:LabelNameZ
```

The following listing shows an example label specification in JSON. These label names include custom namespace strings before the ending label name. 

```
Rule: {
    Name: "label_rule",
    Statement: {...}
    RuleLabels: [
        Name: "header:encoding:utf8",
        Name: "header:user_agent:firefox"
    ],
    Action: { Count: {} }
}
```

**Note**  
You can access this type of listing in the console through the rule JSON editor. 

If you run the preceding rule in the same rule group and account as the preceding label examples, the resulting, fully qualified labels would be the following: 

```
awswaf:111122223333:rulegroup:testRules:header:encoding:utf8
```

```
awswaf:111122223333:rulegroup:testRules:header:user_agent:firefox
```

## Label examples for managed rule groups
<a name="waf-rule-label-examples-rule-groups"></a>

The following show example labels from AWS Managed Rules rule groups and processes that they invoke.

```
awswaf:managed:aws:core-rule-set:NoUserAgent_Header
```

```
awswaf:managed:aws:sql-database:SQLiExtendedPatterns_QueryArguments
```

```
awswaf:managed:aws:atp:aggregate:attribute:compromised_credentials
```

```
awswaf:managed:token:accepted
```

# AWS WAF rules that add labels
<a name="waf-rule-label-add"></a>

In almost all rules, you can define labels and AWS WAF will apply them to any matching request. 

The following rule types are the only exceptions: 
+ **Rate-based rules label only while rate limiting** – Rate-based rules only add labels to web requests for a specific aggregation instance while that instance is being rate limited by AWS WAF. For information about rate-based rules, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md). 
+ **Labeling isn't allowed in rule group reference statements** – The console doesn't accept labels for rule group statements or managed rule group statements. Through the API, specifying a label for either statement type results in a validation exception. For information about these statement types, see [Using managed rule group statements in AWS WAF](waf-rule-statement-type-managed-rule-group.md) and [Using rule group statements in AWS WAF](waf-rule-statement-type-rule-group.md).

**WCUs ** – 1 WCU for every 5 labels that you define in your protection pack (web ACL) or rule group rules. 

**Where to find this**
+ **Rule builder** on the console – Under the rule's **Action** settings, under **Label**. 
+ **API data type** – `Rule` `RuleLabels`

You define a label in a rule by specifying the custom namespace strings and name to append to the label namespace prefix. AWS WAF derives the prefix from the context in which you define the rule. For information about this, see the label syntax information under [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md). 

# AWS WAF rules that match labels
<a name="waf-rule-label-match"></a>

This section explains how to use a label match statement to evaluate web request labels. You can match against *Label*, which requires the label name, or against *Namespace*, which requires a namespace specification. For either label or namespace, you can optionally include preceding namespaces and the prefix in your specification. For general information about this statement type, see [Label match rule statement](waf-rule-statement-type-label-match.md). 

A label's prefix defines the context of the rule group or protection pack (web ACL) where the label's rule is defined. In a rule's label match statement, if your label or namespace match string doesn't specify the prefix, AWS WAF uses the prefix for the label match rule. 
+ Labels for rules that are defined directly inside a protection pack (web ACL) have a prefix that specifies the protection pack (web ACL) context. 
+ Labels for rules that are inside a rule group have a prefix that specifies the rule group context. This could be your own rule group or a rule group that's managed for you. 

For information about this, see label syntax under [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md). 

**Note**  
Some managed rule groups add labels. You can retrieve these through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the `AvailableLabels` property in the response.

If you want to match against a rule that's in a different context than the context of your rule, you must provide the prefix in your match string. For example, if you want to match against labels that are added by rules in a managed rule group, you could add a rule in your protection pack (web ACL) with a label match statement whose match string specifies the rule group's prefix followed by your additional match criteria. 

In the match string for the label match statement, you specify either a label or a namespace: 
+ **Label** – The label specification for a match consists of the ending part of the label. You can include any number of the contiguous namespaces that immediately precede the label name followed by the name. You can also provide the fully qualified label by starting the specification with the prefix. 

  Example specifications:
  + `testNS1:testNS2:LabelNameA`
  + `awswaf:managed:aws:managed-rule-set:testNS1:testNS2:LabelNameA`
+ **Namespace** – The namespace specification for a match consists of any contiguous subset of the label specification excluding the name. You can include the prefix and you can include one or more namespace strings. 

  Example specifications: 
  + `testNS1:testNS2:`
  + `awswaf:managed:aws:managed-rule-set:testNS1:`

# AWS WAF label match examples
<a name="waf-rule-label-match-examples"></a>

This section provides examples of match specifications, for the label match rule statement. 

**Note**  
These JSON listings were created in the console by adding a rule to a protection pack (web ACL) with the label match specifications and then editing the rule and switching to the **Rule JSON editor**. You can also get the JSON for a rule group or protection pack (web ACL) through the APIs or the command line interface. 

**Topics**
+ [Match against a local label](#waf-rule-label-match-examples-local-label)
+ [Match against a label from another context](#waf-rule-label-match-examples-label)
+ [Match against a managed rule group label](#waf-rule-label-match-examples-mgd-rg-label)
+ [Match against a local namespace](#waf-rule-label-match-examples-local-namespace)
+ [Match against a managed rule group namespace](#waf-rule-label-match-examples-mgd-rg-namespace)

## Match against a local label
<a name="waf-rule-label-match-examples-local-label"></a>

The following JSON listing shows a label match statement for a label that's been added to the web request locally, in the same context as this rule.

```
Rule: {
    Name: "match_rule",
    Statement: {
        LabelMatchStatement: {
            Scope: "LABEL",
            Key: "header:encoding:utf8"
        }
    },
    RuleLabels: [
        ...generate_more_labels...
    ],
    Action: { Block: {} }
}
```

If you use this match statement in account 111122223333, in a rule that you define for protection pack (web ACL) `testWebACL`, it would match the following labels. 

```
awswaf:111122223333:webacl:testWebACL:header:encoding:utf8
```

```
awswaf:111122223333:webacl:testWebACL:testNS1:testNS2:header:encoding:utf8
```

It wouldn't match the following label, because the label string isn't an exact match.

```
awswaf:111122223333:webacl:testWebACL:header:encoding2:utf8
```

It wouldn't match the following label, because the context isn't the same, so the prefix doesn't match. This is true even if you added the rule group `productionRules` to the protection pack (web ACL) `testWebACL`, where the rule is defined. 

```
awswaf:111122223333:rulegroup:productionRules:header:encoding:utf8
```

## Match against a label from another context
<a name="waf-rule-label-match-examples-label"></a>

The following JSON listing shows a label match rule that matches against a label from a rule inside a user-created rule group. The prefix is required in the specification for all rules running in the protection pack (web ACL) that aren't part of the named rule group. This example label specification matches only the exact label. 

```
Rule: {
    Name: "match_rule",
    Statement: {
        LabelMatchStatement: {
            Scope: "LABEL",
            Key: "awswaf:111122223333:rulegroup:testRules:header:encoding:utf8"
        }
    },
    RuleLabels: [
        ...generate_more_labels...
    ],
    Action: { Block: {} }
}
```

## Match against a managed rule group label
<a name="waf-rule-label-match-examples-mgd-rg-label"></a>

This is a special case of matching against a label that's from another context than that of the match rule. The following JSON listing shows a label match statement for a managed rule group label. This matches only the exact label that's specified in the label match statement's key setting.

```
Rule: {
    Name: "match_rule",
    Statement: {
        LabelMatchStatement: {
            Scope: "LABEL",
            Key: "awswaf:managed:aws:managed-rule-set:header:encoding:utf8"
        }
    },
    RuleLabels: [
        ...generate_more_labels...
    ],
    Action: { Block: {} }
}
```

## Match against a local namespace
<a name="waf-rule-label-match-examples-local-namespace"></a>

The following JSON listing shows a label match statement for a local namespace.

```
Rule: {
    Name: "match_rule",
    Statement: {
        LabelMatchStatement: {
            Scope: "NAMESPACE",
            Key: "header:encoding:"
        }
    },
    Labels: [
        ...generate_more_labels...
    ],
    Action: { Block: {} }
}
```

Similar to the local `Label` match, if you use this statement in account 111122223333, in a rule that you define for protection pack (web ACL) `testWebACL`, it would match the following label. 

```
awswaf:111122223333:webacl:testWebACL:header:encoding:utf8
```

It wouldn't match the following label, because the account isn't the same, so the prefix doesn't match. 

```
awswaf:444455556666:webacl:testWebACL:header:encoding:utf8
```

The prefix also doesn't match any labels applied by managed rule groups, like the following. 

```
awswaf:managed:aws:managed-rule-set:header:encoding:utf8
```

## Match against a managed rule group namespace
<a name="waf-rule-label-match-examples-mgd-rg-namespace"></a>

The following JSON listing shows a label match statement for a managed rule group namespace. For a rule group that you own, you'd also need to provide the prefix in order to match for a namespace that's outside of the rule's context. 

```
Rule: {
    Name: "match_rule",
    Statement: {
        LabelMatchStatement: {
            Scope: "NAMESPACE",
            Key: "awswaf:managed:aws:managed-rule-set:header:"
        }
    },
    RuleLabels: [
        ...generate_more_labels...
    ],
    Action: { Block: {} }
}
```

This specification matches against the following example labels. 

```
awswaf:managed:aws:managed-rule-set:header:encoding:utf8
```

```
awswaf:managed:aws:managed-rule-set:header:encoding:unicode
```

It doesn't match the following label.

```
awswaf:managed:aws:managed-rule-set:query:badstring
```