**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).
# Using rate-based rule statements in AWS WAF
This section explains what a rate-based rule statement is and how it works.
A rate-based rule counts incoming requests and rate limits requests when they are coming at too fast a rate. The rule aggregates requests according to your criteria, and counts and rate limits the aggregate groupings, based on the rule's evaluation window, request limit, and action settings.
**Note**
You can also rate limit web requests using the targeted protection level of the Bot Control AWS Managed Rules rule group. Using this managed rule group incurs additional fees. For more information, see [Options for rate limiting in rate-based rules and targeted Bot Control rules](waf-rate-limiting-options.md).
AWS WAF tracks and manages web requests separately for each instance of a rate-based rule that you use. For example, if you provide the same rate-based rule settings in two web ACLs, each of the two rule statements represents a separate instance of the rate-based rule and each gets its own tracking and management by AWS WAF. If you define a rate-based rule inside a rule group, and then use that rule group in multiple places, each use creates a separate instance of the rate-based rule that gets its own tracking and management by AWS WAF.
**Not nestable** – You can't nest this statement type inside other statements. You can include it directly in a protection pack (web ACL) or rule group.
**Scope-down statement** – This rule type can take a scope-down statement, to narrow the scope of the requests that the rule tracks and rate limits. The scope-down statement can be optional or required, depending on your other rule configuration settings. The details are covered in this section. For general information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).
**WCUs** – 2, as a base cost. For each custom aggregation key that you specify, add 30 WCUs. If you use a scope-down statement in the rule, calculate and add the WCUs for that.
**Where to find this rule statement**
+ **Rule builder** in your protection pack (web ACL), on the console – Under **Rule**, for **Type**, choose **Rate-based rule**.
+ **API** – [RateBasedStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_RateBasedStatement.html)
**Topics**
+ [Rate-based rule high-level settings in AWS WAF](waf-rule-statement-type-rate-based-high-level-settings.md)
+ [Rate-based rule caveats in AWS WAF](waf-rule-statement-type-rate-based-caveats.md)
+ [Aggregating rate-based rules in AWS WAF](waf-rule-statement-type-rate-based-aggregation-options.md)
+ [Rate-based rule aggregation instances and counts](waf-rule-statement-type-rate-based-aggregation-instances.md)
+ [Applying rate limiting to requests in AWS WAF](waf-rule-statement-type-rate-based-request-limiting.md)
+ [Rate-based rule examples in AWS WAF](waf-rule-statement-type-rate-based-examples.md)
+ [Listing IP addresses that are being rate limited by rate-based rules](listing-managed-ips.md)
# Rate-based rule high-level settings in AWS WAF
A rate-based rule statement uses the following high level settings:
+ **Evaluation window** – The amount of time, in seconds, that AWS WAF should include in its request counts, looking back from the current time. For example, for a setting of 120, when AWS WAF checks the rate, it counts the requests for the 2 minutes immediately preceding the current time. Valid settings are 60 (1 minute), 120 (2 minutes), 300 (5 minutes), and 600 (10 minutes), and 300 (5 minutes) is the default.
This setting doesn't determine how often AWS WAF checks the rate, but how far back it looks each time it checks. AWS WAF checks the rate frequently, with timing that's independent of the evaluation window setting.
+ **Rate limit** – The maximum number of requests matching your criteria that AWS WAF should just track for the specified evaluation window. The lowest limit setting allowed is 10. When this limit is breached, AWS WAF applies the rule action setting to additional requests matching your criteria.
AWS WAF applies rate limiting near the limit that you set, but does not guarantee an exact limit match. For more information, see [Rate-based rule caveats](waf-rule-statement-type-rate-based-caveats.md).
+ **Request aggregation** – The aggregation criteria to use on the web requests that the rate-based rule counts and rate limits. The rate limit that you set applies to each aggregation instance. For details, see [Aggregating rate-based rules](waf-rule-statement-type-rate-based-aggregation-options.md) and [Aggregation instances and counts](waf-rule-statement-type-rate-based-aggregation-instances.md).
+ **Action** – The action to take on requests that the rule rate limits. You can use any rule action except Allow. This is set at the rule level as usual, but has some restrictions and behaviors that are specific to rate-based rules. For general information about rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md). For information specific to rate limiting, see [Applying rate limiting to requests in AWS WAF](waf-rule-statement-type-rate-based-request-limiting.md) in this section.
+ **Scope of inspection and rate limiting** – You can narrow the scope of the requests that the rate-based statement tracks and rate limits by adding a scope-down statement. If you specify a scope-down statement, the rule only aggregates, counts, and rate limits requests that match the scope-down statement. If you choose the request aggregation option **Count all**, then the scope-down statement is required. For more information about scope-down statements, see [Using scope-down statements](waf-rule-scope-down-statements.md).
+ **(Optional) Forwarded IP configuration** – This is only used if you specify **IP address in header** in your request aggregation, either alone or as part of the custom keys settings. AWS WAF retrieves the first IP address in the specified header and uses that as the aggregation value. A common header for this purpose is `X-Forwarded-For`, but you can specify any header. For more information, see [Using forwarded IP addresses](waf-rule-statement-forwarded-ip-address.md).
# Rate-based rule caveats in AWS WAF
This section lists the caveats for using rate-based rules.
AWS WAF rate limiting is designed to control high request rates and protect your application's availability in the most efficient and effective way possible. It's not intended for precise request-rate limiting.
+ AWS WAF estimates the current request rate using an algorithm that gives more importance to more recent requests. Because of this, AWS WAF will apply rate limiting near the limit that you set, but does not guarantee an exact limit match.
+ Each time that AWS WAF estimates the rate of requests, AWS WAF looks back at the number of requests that came in during the configured evaluation window. Due to this and other factors such as propagation delays, it's possible for requests to be coming in at too high a rate for up to several minutes before AWS WAF detects and rate limits them. Similarly. the request rate can be below the limit for a period of time before AWS WAF detects the decrease and discontinues the rate limiting action. Usually, this delay is below 30 seconds.
+ If you change any of the rate limit settings in a rule that's in use, the change resets the rule's rate limiting counts. This can pause the rule's rate limiting activities for up to a minute. The rate limit settings are the evaluation window, rate limit, request aggregation settings, forwarded IP configuration, and scope of inspection.
# Aggregating rate-based rules in AWS WAF
This section explains your options for aggregating requests.
By default, a rate-based rule aggregates and rate limits requests based on the request IP address. You can configure the rule to use various other aggregation keys and key combinations. For example, you can aggregate based on a forwarded IP address, on the HTTP method, or on a query argument. You can also specify aggregation key combinations, such as IP address and HTTP method, or the values of two different cookies.
**Note**
All of the request components that you specify in the aggregation key must be present in a web request for the request to be evaluated or rate limited by the rule.
You can configure your rate-based rule with the following aggregation options.
+ **Source IP address** – Aggregate using only the IP address from the web request origin.
The source IP address might not contain the address of the originating client. If a web request goes through one or more proxies or load balancers, this will contain the address of the last proxy.
+ **IP address in header** – Aggregate using only a client address in an HTTP header. This is also referred to as a forwarded IP address.
With this configuration, you also specify a fallback behavior to apply to a web request with a malformed IP address in the header. The fallback behavior sets the matching result for the request, to match or no match. For no match, the rate-based rule doesn't count or rate limit the request. For match, the rate-based rule groups the request together with other requests that have a malformed IP address in the specified header.
Use caution with this option, because headers can be handled inconsistently by proxies and they can also be modified to bypass inspection. For additional information and best practices, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md).
+ **ASN** – Aggregate using an Autonomous System Number (ASN) associated with the source IP address as an aggregate key. This might not be the address of the originating client. If a web request goes through one or more proxies or load balancers, this contains the address of the last proxy.
If AWS WAF can’t derive an ASN from the IP address, it counts the ASN as ASN 0. If you don't want to apply rate limiting to unmapped ASNs, you can create a scope-down rule that excludes requests with ASN 0.
+ **ASN in header** – Aggregate using an ASN associated with a client IP address in an HTTP header. This is also referred to as a forwarded IP address. With this configuration, you also specify a fallback behavior to apply to a web request with an invalid or malformed IP address. The fallback behavior sets the matching result for the request, to match or no match. If you set the fallback behavior to match in the forwarded IP configuration, AWS WAF treats the invalid IP address as a matching value. This allows AWS WAF to continue evaluating any remaining parts of your rate-based rule's composite key. For no match, the rate-based rule doesn't count or rate limit the request.
Use caution with this option, as headers can be handled inconsistently by proxies and they can be modified to bypass inspection. For additional information and best practices, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md).
+ **Count all** – Count and rate limit all requests that match the rule's scope-down statement. This option requires a scope-down statement. This is typically used to rate limit a specific set of requests, such as all requests with a specific label or all requests from a specific geographic area.
+ **Custom keys** – Aggregate using one or more custom aggregation keys. To combine either of the IP address options with other aggregation keys, define them here under custom keys.
Custom aggregation keys are a subset of the web request component options described at [Request components in AWS WAF](waf-rule-statement-fields-list.md).
The key options are the following. Except where noted, you can use an option multiple times, for example, two headers or three label namespaces.
+ **Label namespace** – Use a label namespace as an aggregation key. Each distinct fully qualified label name that has the specified label namespace contributes to the aggregation instance. If you use just one label namespace as your custom key, then each label name fully defines an aggregation instance.
The rate-based rule uses only labels that have been added to the request by rules that are evaluated beforehand in the protection pack (web ACL).
For information about label namespaces and names, see [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md).
+ **Header** – Use a named header as an aggregation key. Each distinct value in the header contributes to the aggregation instance.
Header takes an optional text transformation. See [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **Cookie** – Use a named cookie as an aggregation key. Each distinct value in the cookie contributes to the aggregation instance.
Cookie takes an optional text transformation. See [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **Query argument** – Use a single query argument in the request as an aggregate key. Each distinct value for the named query argument contributes to the aggregation instance.
Query argument takes an optional text transformation. See [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **Query string** – Use the entire query string in the request as an aggregate key. Each distinct query string contributes to the aggregation instance. You can use this key type once.
Query string takes an optional text transformation. See [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **URI path** – Use the URI path in the request as an aggregate key. Each distinct URI path contributes to the aggregation instance. You can use this key type once.
URI path takes an optional text transformation. See [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **JA3 fingerprint** – Use the JA3 fingerprint in the request as an aggregate key. Each distinct JA3 fingerprint contributes to the aggregation instance. You can use this key type once.
+ **JA4 fingerprint** – Use the JA4 fingerprint in the request as an aggregate key. Each distinct JA4 fingerprint contributes to the aggregation instance. You can use this key type once.
+ **HTTP method** – Use the request's HTTP method as an aggregate key. Each distinct HTTP method contributes to the aggregation instance. You can use this key type once.
+ **IP address** – Aggregate using the IP address from the web request origin in combination with other keys.
This might not contain the address of the originating client. If a web request goes through one or more proxies or load balancers, this will contain the address of the last proxy.
+ **IP address in header** – Aggregate using the client address in an HTTP header in combination with other keys. This is also referred to as a forwarded IP address.
Use caution with this option, as headers can be handled inconsistently by proxies and they can be modified to bypass inspection. For additional information and best practices, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md).
# Rate-based rule aggregation instances and counts
This section explains how a rate-based rule evaluates web requests.
When a rate-based rule evaluates web requests using your aggregation criteria, each unique set of values that the rule finds for the specified aggregation keys defines a unique *aggregation instance*.
+ **Multiple keys** – If you've defined multiple custom keys, the value for each key contributes to the aggregation instance definition. Each unique combination of values defines an aggregation instance.
+ **Single key** – If you've chosen a single key, either in the custom keys or by selecting one of the singleton IP address choices, then each unique value for the key defines an aggregation instance.
+ **Count all - no keys** – If you've selected the aggregation option **Count all**, then all requests that the rule evaluates belong to a single aggregation instance for the rule. This choice requires a scope-down statement.
A rate-based rule counts web requests separately for each aggregation instance that it identifies.
For example, assume a rate-based rule evaluates web requests with the following IP address and HTTP method values:
+ IP address 10.1.1.1, HTTP method POST
+ IP address 10.1.1.1, HTTP method GET
+ IP address 127.0.0.0, HTTP method POST
+ IP address 10.1.1.1, HTTP method GET
The rule creates different aggregation instances according to your aggregation criteria.
+ If the aggregation criteria is just the IP address, then each individual IP address is an aggregation instance, and AWS WAF counts requests separately for each. The aggregation instances and request counts for our example would be the following:
+ IP address 10.1.1.1: count 3
+ IP address 127.0.0.0: count 1
+ If the aggregation criteria is HTTP method, then each individual HTTP method is an aggregation instance. The aggregation instances and request counts for our example would be the following:
+ HTTP method POST: count 2
+ HTTP method GET: count 2
+ If the aggregation criteria is IP address and HTTP method, then each IP address and each HTTP method would contribute to the combined aggregation instance. The aggregation instances and request counts for our example would be the following:
+ IP address 10.1.1.1, HTTP method POST: count 1
+ IP address 10.1.1.1, HTTP method GET: count 2
+ IP address 127.0.0.0, HTTP method POST: count 1
# Applying rate limiting to requests in AWS WAF
This section explains how rate limiting behavior works for rate-based rules.
The criteria that AWS WAF uses to rate limit requests for a rate-based rule is the same criteria that AWS WAF uses to aggregate requests for the rule. If you define a scope-down statement for the rule, AWS WAF only aggregates, counts, and rate limits requests that match the scope-down statement.
The match criteria that causes a rate-based rule to apply its rule action settings to a specific web request are as follows:
+ The web request matches the rule's scope-down statement, if one is defined.
+ The web request belongs to an aggregation instance whose request count is currently over the rule's limit.
**How AWS WAF applies the rule action**
When a rate-based rule applies rate limiting to a request, it applies the rule action and, if you've defined any custom handling or labeling in your action specification, the rule applies those. This request handling is the same as the way a match rule applies its action settings to matching web requests. A rate-based rule only applies labels or performs other actions on requests that it is actively rate limiting.
You can use any rule action except Allow. For general information about rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md).
The following list describes how rate limiting works for each of the actions.
+ **Block** – AWS WAF blocks the request and applies any custom blocking behavior that you've defined.
+ **Count** – AWS WAF counts the request, applies any custom headers or labels that you've defined, and continues the protection pack (web ACL) evaluation of the request.
This action doesn't limit the rate of requests. It just counts the requests that are over the limit.
+ **CAPTCHA or Challenge** – AWS WAF handles the request either like a Block or like a Count, depending on the state of the request's token.
This action doesn't limit the rate of requests that have valid tokens. It limits the rate of requests that are over the limit and are also missing valid tokens.
+ If the request doesn't have a valid, unexpired token, the action blocks the request and sends the CAPTCHA puzzle or the browser challenge back to the client.
If the end user or client browser responds successfully, the client receives a valid token and it automatically resends the original request. If rate limiting for the aggregation instance is still in effect, this new request with the valid, unexpired token will have the action applied to it as described in the next bullet point.
+ If the request has a valid, unexpired token, the CAPTCHA or Challenge action verifies the token and takes no action on the request, similar to the Count action. The rate-based rule returns the request evaluation back to the protection pack (web ACL) without taking any terminating action, and the protection pack (web ACL) continues its evaluation of the request.
For additional information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).
**If you rate limit only the IP address or forwarded IP address**
When you configure the rule to rate limit only IP address for forwarded IP address, you can retrieve the list of IP addresses that the rule is currently rate limiting. If you're using a scope-down statement, the requests that are rate limited are only those in the IP list that match the scope-down statement. For information about retrieving the IP address list, see [Listing IP addresses that are being rate limited by rate-based rules](listing-managed-ips.md).
# Rate-based rule examples in AWS WAF
This section describes example configurations for a variety of common rate-based rules use cases.
Each example provides a description of the use case and then shows the solution in JSON listings for the custom configured rules.
**Note**
The JSON listings shown in these examples were created in the console by configuring the rule and then editing it using the **Rule JSON editor**.
**Topics**
+ [Rate limit the requests to a login page](waf-rate-based-example-limit-login-page.md)
+ [Rate limit the requests to a login page from any IP address, user agent pair](waf-rate-based-example-limit-login-page-keys.md)
+ [Rate limit the requests that are missing a specific header](waf-rate-based-example-limit-missing-header.md)
+ [Rate limit the requests with specific labels](waf-rate-based-example-limit-labels.md)
+ [Rate limit the requests for labels that have a specified label namespace](waf-rate-based-example-limit-label-aggregation.md)
+ [Rate limit the requests with specific ASNs](waf-rate-based-example-limit-asn.md)
# Rate limit the requests to a login page
To limit the number of requests to the login page on your website without affecting traffic to the rest of your site, you could create a rate-based rule with a scope-down statement that matches requests to your login page and with the request aggregation set to **Count all**.
The rate-based rule will count all requests for the login page in a single aggregation instance and apply the rule action to all requests matching the scope-down statement when the requests exceed the limit.
The following JSON listing shows an example of this rule configuration. The count all aggregation option is listed in the JSON as the setting `CONSTANT`. This example matches login pages that start with `/login`.
```
{
"Name": "test-rbr",
"Priority": 0,
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr"
},
"Statement": {
"RateBasedStatement": {
"Limit": 1000,
"EvaluationWindowSec": 300,
"AggregateKeyType": "CONSTANT",
"ScopeDownStatement": {
"ByteMatchStatement": {
"FieldToMatch": {
"UriPath": {}
},
"PositionalConstraint": "STARTS_WITH",
"SearchString": "/login",
"TextTransformations": [
{
"Type": "NONE",
"Priority": 0
}
]
}
}
}
}
}
```
# Rate limit the requests to a login page from any IP address, user agent pair
To limit the number of requests to the login page on your website for IP address, user agent pairs that exceed your limit, set the request aggregation to **Custom keys** and provide the aggregation criteria.
The following JSON listing shows an example of this rule configuration. In this example, we've set the limit to 100 requests in any five minute period per IP address, user agent pair.
```
{
"Name": "test-rbr",
"Priority": 0,
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr"
},
"Statement": {
"RateBasedStatement": {
"Limit": 100,
"EvaluationWindowSec": 300,
"AggregateKeyType": "CUSTOM_KEYS",
"CustomKeys": [
{
"Header": {
"Name": "User-Agent",
"TextTransformations": [
{
"Priority": 0,
"Type": "NONE"
}
]
}
},
{
"IP": {}
}
],
"ScopeDownStatement": {
"ByteMatchStatement": {
"FieldToMatch": {
"UriPath": {}
},
"PositionalConstraint": "STARTS_WITH",
"SearchString": "/login",
"TextTransformations": [
{
"Type": "NONE",
"Priority": 0
}
]
}
}
}
}
}
```
# Rate limit the requests that are missing a specific header
To limit the number of requests that are missing a specific header, you can use the **Count all** aggregation option with a scope-down statement. Configure the scope-down statement with a logical `NOT` statement containing a statement that returns true only if the header exists and has a value.
The following JSON listing shows an example of this rule configuration.
```
{
"Name": "test-rbr",
"Priority": 0,
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr"
},
"Statement": {
"RateBasedStatement": {
"Limit": 1000,
"AggregateKeyType": "CONSTANT",
"EvaluationWindowSec": 300,
"ScopeDownStatement": {
"NotStatement": {
"Statement": {
"SizeConstraintStatement": {
"FieldToMatch": {
"SingleHeader": {
"Name": "user-agent"
}
},
"ComparisonOperator": "GT",
"Size": 0,
"TextTransformations": [
{
"Type": "NONE",
"Priority": 0
}
]
}
}
}
}
}
}
}
```
# Rate limit the requests with specific labels
To limit the number of requests of various categories, you can combine rate limiting with any rule or rule group that add labels to requests. To do this, you configure your protection pack (web ACL) as follows:
+ Add the rules or rule groups that add labels, and configure them so that they don't block or allow the requests that you want to rate limit. If you use managed rule groups, you might need to override some rule group rule actions to Count to achieve this behavior.
+ Add a rate-based rule to your protection pack (web ACL) with a priority number setting that is higher than the labeling rules and rule groups. AWS WAF evaluates rules in numeric order, starting from the lowest, so your rate-based rule will run after the labeling rules. Configure your rate limiting on the labels using a combination of label matching in the rule's scope-down statement and label aggregation.
The following example uses the Amazon IP reputation list AWS Managed Rules rule group. The rule group rule `AWSManagedIPDDoSList` detects and labels requests whose IPs are known to be actively engaging in DDoS activities. The rule's action is configured to Count in the rule group definition. For more information about the rule group, see [Amazon IP reputation list managed rule group](aws-managed-rule-groups-ip-rep.md#aws-managed-rule-groups-ip-rep-amazon).
The following protection pack (web ACL) JSON listing uses the IP reputation rule group followed by a label-matching rate-based rule. The rate-based rule uses a scope-down statement to filter for requests that have been marked by the rule group rule. The rate-based rule statement aggregates and rate limits the filtered requests by their IP addresses.
```
{
"Name": "test-web-acl",
"Id": ...
"ARN": ...
"DefaultAction": {
"Allow": {}
},
"Description": "",
"Rules": [
{
"Name": "AWS-AWSManagedRulesAmazonIpReputationList",
"Priority": 0,
"Statement": {
"ManagedRuleGroupStatement": {
"VendorName": "AWS",
"Name": "AWSManagedRulesAmazonIpReputationList"
}
},
"OverrideAction": {
"None": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "AWS-AWSManagedRulesAmazonIpReputationList"
}
},
{
"Name": "test-rbr",
"Priority": 1,
"Statement": {
"RateBasedStatement": {
"Limit": 100,
"EvaluationWindowSec": 300,
"AggregateKeyType": "IP",
"ScopeDownStatement": {
"LabelMatchStatement": {
"Scope": "LABEL",
"Key": "awswaf:managed:aws:amazon-ip-list:AWSManagedIPDDoSList"
}
}
}
},
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr"
}
}
],
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-web-acl"
},
"Capacity": 28,
"ManagedByFirewallManager": false,
"RetrofittedByFirewallManager": false,
"LabelNamespace": "awswaf:0000000000:webacl:test-web-acl:"
}
```
# Rate limit the requests for labels that have a specified label namespace
**Note**
The common level rules in the Bot Control managed rule group add labels for bots of various categories, but they only block requests from unverified bots. For information about these rules, see [Bot Control rules listing](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-rules).
If you use the Bot Control managed rule group, you can add rate limiting for requests from individual verified bots. To do this, you add a rate-based rule that runs after the Bot Control rule group and aggregates requests by their bot name labels. You specify the **Label namespace** aggregation key and set the namespace key to `awswaf:managed:aws:bot-control:bot:name:`. Each unique label with the specified namespace will define an aggregation instance. For example, the labels `awswaf:managed:aws:bot-control:bot:name:axios` and `awswaf:managed:aws:bot-control:bot:name:curl` each define an aggregation instance.
The following protection pack (web ACL) JSON listing shows this configuration. The rule in this example limits requests for any single bot aggregation instance to 1,000 in a two minute period.
```
{
"Name": "test-web-acl",
"Id": ...
"ARN": ...
"DefaultAction": {
"Allow": {}
},
"Description": "",
"Rules": [
{
"Name": "AWS-AWSManagedRulesBotControlRuleSet",
"Priority": 0,
"Statement": {
"ManagedRuleGroupStatement": {
"VendorName": "AWS",
"Name": "AWSManagedRulesBotControlRuleSet",
"ManagedRuleGroupConfigs": [
{
"AWSManagedRulesBotControlRuleSet": {
"InspectionLevel": "COMMON"
}
}
]
}
},
"OverrideAction": {
"None": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "AWS-AWSManagedRulesBotControlRuleSet"
}
},
{
"Name": "test-rbr",
"Priority": 1,
"Statement": {
"RateBasedStatement": {
"Limit": 1000,
"EvaluationWindowSec": 120,
"AggregateKeyType": "CUSTOM_KEYS",
"CustomKeys": [
{
"LabelNamespace": {
"Namespace": "awswaf:managed:aws:bot-control:bot:name:"
}
}
]
}
},
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr"
}
}
],
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "test-web-acl"
},
"Capacity": 82,
"ManagedByFirewallManager": false,
"RetrofittedByFirewallManager": false,
"LabelNamespace": "awswaf:0000000000:webacl:test-web-acl:"
}
```
# Rate limit the requests with specific ASNs
To limit the number of requests from specific Autonomous System Numbers (ASNs) based on the IP address of the requests, set the request aggregation to *Custom keys* and provide the aggregation criteria.
The following JSON shows an example of a rule aggregating ASNs derived from forwarded IP addresses found in the `X-Forwarded-For` header. If AWS WAF can't derive an ASN because the IP address is malformed, the fallback behavior is set to `MATCH`.
```
{
"Name": "test-rbr",
"Priority": 0,
"Statement": {
"RateBasedStatement": {
"AggregateKeyType": "CUSTOM_KEYS",
"CustomKeys": [
{
"ASN": {}
},
{
"ForwardedIP": {}
}
],
"EvaluationWindowSec": 300,
"ForwardedIPConfig": {
"FallbackBehavior": "MATCH",
"HeaderName": "X-Forwarded-For"
},
"Limit": 2000
}
},
"VisibilityConfig": {
"CloudWatchMetricsEnabled": true,
"MetricName": "test-rbr",
"SampledRequestsEnabled": true
}
}
```
# Listing IP addresses that are being rate limited by rate-based rules
This section explains how to access the list of IP addresses that are currently rate-limited by a rate-based rule by using the CLI, the API, or any of the SDKs.
If your rate-based rule only aggregates on IP address or forwarded IP address, you can retrieve the list of IP addresses that the rule is currently rate limiting. AWS WAF stores these IP addresses in the rule's managed keys list.
**Note**
This option is only available if you aggregate on only the IP address or only an IP address in a header. If you use the custom keys request aggregation, you can't retrieve a list of rate limited IP addresses, even if you use one of the IP address specifications in your custom keys.
A rate-based rule applies its rule action to requests from the rule's managed keys list that match the rule's scope-down statement. When a rule has no scope-down statement, it applies the action to all requests from the IP addresses that are in the list. The rule action is Block by default, but it can be any valid rule action except for Allow. The maximum number of IP addresses that AWS WAF can rate limit using a single rate-based rule instance is 10,000. If more than 10,000 addresses exceed the rate limit, AWS WAF limits those with the highest rates.
You can access a rate-based rule's managed keys list using the CLI, the API, or any of the SDKs. This topic covers access using the CLI and APIs. The console doesn't provide access to the list at this time.
For the AWS WAF API, the command is [GetRateBasedStatementManagedKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_GetRateBasedStatementManagedKeys.html).
For the AWS WAF CLI, the command is [get-rate-based-statement-managed-keys](https://docs.aws.amazon.com/cli/latest/reference/wafv2/get-rate-based-statement-managed-keys.html).
The following shows the syntax for retrieving the list of rate limited IP addresses for a rate-based rule that's being used in a protection pack (web ACL) on an Amazon CloudFront distribution.
```
aws wafv2 get-rate-based-statement-managed-keys --scope=CLOUDFRONT --region=us-east-1 --web-acl-name=WebACLName --web-acl-id=WebACLId --rule-name=RuleName
```
The following shows the syntax for a regional application, an Amazon API Gateway REST API, an Application Load Balancer, an AWS AppSync GraphQL API, an Amazon Cognito user pool, an AWS App Runner service, AWS Amplify, or an AWS Verified Access instance.
```
aws wafv2 get-rate-based-statement-managed-keys --scope=REGIONAL --region=region --web-acl-name=WebACLName --web-acl-id=WebACLId --rule-name=RuleName
```
AWS WAF monitors web requests and manages keys independently for each unique combination of protection pack (web ACL), optional rule group, and rate-based rule. For example, if you define a rate-based rule inside a rule group, and then use the rule group in a protection pack (web ACL), AWS WAF monitors web requests and manages keys for that protection pack (web ACL), rule group reference statement, and rate-based rule instance. If you use the same rule group in a second protection pack (web ACL), AWS WAF monitors web requests and manages keys for this second usage completely independent of your first.
For a rate-based rule that you've defined inside a rule group, you need to provide the name of the rule group reference statement in your request, in addition to the protection pack (web ACL) name and the name of the rate-based rule inside the rule group. The following shows the syntax for a regional application where the rate-based rule is defined inside a rule group, and the rule group is used in a protection pack (web ACL).
```
aws wafv2 get-rate-based-statement-managed-keys --scope=REGIONAL --region=region --web-acl-name=WebACLName --web-acl-id=WebACLId --rule-group-rule-name=RuleGroupRuleName --rule-name=RuleName
```