Adding Rate Based Rules

Does not cover managed rules, match rules, bot, or fraud rule groups; those are separate references. Account-based abuse (credential stuffing, fake accounts) goes to the fraud control reference, not here.

Execute commands using the AWS MCP server when connected (sandboxed execution, audit logging, observability). Fall back to the AWS CLI otherwise.

Table of Contents

• Overview
• Workflow
• Decision: aggregation key
• Request floor and evaluation windows
• The per-web-ACL cap and composite keys
• Scope-down to a subset of requests
• Count mode and the Shield cost-protection link
• Troubleshooting
• Procedure
• Security Considerations
• Additional Resources

Workflow

To add a rate-based rule end to end, follow the procedure exactly. See the Procedure section below.

The procedure covers:

• Choosing the aggregation key and a measured threshold
• Setting a valid evaluation window
• Adding a scope-down statement to target a subset of requests
• Running in Count mode, confirming the threshold, then switching to Block

Decision: aggregation key

Constraints:

• You MUST choose FORWARDED_IP (not IP) when the application sits behind a CDN, or the limit acts on the CDN address (see the recovering-the-real-client-IP reference)
• You MUST add a scope-down statement when using CONSTANT; the API rejects it otherwise

Request floor and evaluation windows

Customers assume an arbitrary threshold and window and get surprised by the constraints.

Constraints:

• You MUST keep the request limit at or above the floor of 10 requests
• You MUST set the evaluation window to one of 60, 120, 300, or 600 seconds; no other value is valid
• You SHOULD compute the limit as acceptable requests per second times the window in seconds

The per-web-ACL cap and composite keys

A web ACL allows only a small number of these high-cost rules (roughly ten). Customers building one rate-based rule per URI path hit the cap.

Constraints:

• You MUST NOT add a separate rate-based rule per path because this quickly exhausts the cap; use composite aggregation keys plus scope-down inside fewer rules
• You SHOULD solve per-path limiting with CUSTOM_KEYS (for example IP plus API key) and a scope-down statement, rather than rule sprawl

Scope-down to a subset of requests

Customers expect a rate-based rule to count only a specific path, then find it counting all traffic, because they did not scope it down.

Constraints:

• You MUST add a scope-down statement when the customer wants to rate limit a subset such as a login endpoint
• You SHOULD apply a LOWERCASE text transformation on the path match so casing does not cause the scope-down to miss

Count mode and the Shield cost-protection link

Turning a new rate-based rule straight to Block catches legitimate bursts. Leaving it in Count has a second consequence on CloudFront and Application Load Balancer resources.

Constraints:

• You MUST run the rule in Count mode against production traffic to confirm the threshold before switching to Block
• You MUST flag that on CloudFront and Application Load Balancer resources, a rate-based rule in Block mode is a prerequisite for AWS Shield Advanced cost protection credits; a Count-only rule silently disqualifies a future claim (the shieldadvanced skill owns that workflow)

Troubleshooting

The rule never fires under load

The scope-down is not matching (often a casing issue), or the threshold is too high. Add LOWERCASE, or remove the scope-down to test (Scope-down to a subset of requests).

Rule creation fails validation

CONSTANT was used without a scope-down statement, or the window is not one of the allowed values (Request floor and evaluation windows).

The rule fires for some sources but not others

Traffic arrives via a proxy and the rule reads the proxy IP. Switch to FORWARDED_IP (Decision: aggregation key).

Procedure

Overview

This procedure adds a rate-based rule with a measured threshold, a valid window, and a scope-down, runs it in Count, then switches to Block, and surfaces the console link.

Parameters

• web_acl_name, web_acl_id, scope (required): Identify the web ACL.
• aggregation_key (required): IP, FORWARDED_IP, CUSTOM_KEYS, or CONSTANT.
• custom_key_components (required when aggregation_key is CUSTOM_KEYS): Up to 5 key components (for example IP, a header name such as x-api-key) used for composite aggregation.
• limit (required): The request limit, at or above 10.
• window (required): One of 60, 120, 300, or 600 seconds.
• scope_down (required for CONSTANT, recommended otherwise): The statement narrowing which requests are counted.

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt
• You MUST confirm logging is enabled so the Count-mode threshold can be validated

Steps

1. Verify dependencies

Constraints:

• You MUST confirm credentials with aws sts get-caller-identity
• You MUST confirm logging and sampling are on

2. Add the rate-based rule in Count mode

Constraints:

• You MUST add the rule with a valid window and a limit at or above 10, in Count mode

• You MUST fetch the current LockToken with get-web-acl immediately before update-web-acl and pass the full rule set

• You MUST preserve the web ACL’s existing DefaultAction from the get-web-acl response and pass it back as {default_action}; do not assume Allow={}, since that would silently open all unmatched traffic on a web ACL whose default action is Block:

  Copy

  aws wafv2 get-web-acl --name {web_acl_name} --scope {scope} --id {web_acl_id} --region {region}
  aws wafv2 update-web-acl --name {web_acl_name} --scope {scope} --id {web_acl_id} \
    --lock-token {lock_token} --default-action {default_action} \
    --rules '[{"Name":"RateLimit","Priority":1,"Action":{"Count":{}},"Statement":{"RateBasedStatement":{"Limit":{limit},"EvaluationWindowSec":{window},"AggregateKeyType":"CUSTOM_KEYS","CustomKeys":[{"Header":{"Name":"x-api-key","TextTransformations":[{"Priority":0,"Type":"NONE"}]}},{"IP":{}}]}},"VisibilityConfig":{"SampledRequestsEnabled":true,"CloudWatchMetricsEnabled":true,"MetricName":"RateLimit"}}]' \
    --visibility-config SampledRequestsEnabled=true,CloudWatchMetricsEnabled=true,MetricName={web_acl_name} \
    --region {region}

• You MUST include a scope-down statement for CONSTANT, and use composite CUSTOM_KEYS rather than many per-path rules

3. Confirm the threshold and switch to Block

Constraints:

• You MUST review Count-mode data to confirm the threshold does not catch legitimate bursts
• You MUST switch the rule action to Block once validated by re-running update-web-acl with the rule’s "Action" changed from {"Count":{}} to {"Block":{}} (fetch a fresh LockToken first and pass the full rule set)
• For CloudFront and Application Load Balancer resources, you MUST confirm the rule is in Block mode if the customer relies on Shield Advanced cost protection

4. Surface the console link

Constraints:

• You MUST present the web ACL console link and tell the customer to open it and confirm the rate-based rule and its action:

  Copy

  https://us-east-1.console.aws.amazon.com/wafv2/homev2/web-acls?region={region}

Example

Example input

Example output

Troubleshooting

The rule never fires

Scope-down casing or threshold too high. Add LOWERCASE or lower the limit (Step 2).

Validation error on creation

CONSTANT without scope-down, or an invalid window. Fix both (Step 2).

Security Considerations

This procedure modifies a security control, so misconfiguration directly weakens the application’s defenses.

• Least-privilege IAM. You MUST grant only the specific wafv2: actions a task needs (for example wafv2:GetWebACL and wafv2:UpdateWebACL) rather than wafv2:* or the AWSWAFFullAccess managed policy.
• Ephemeral credentials. You MUST use IAM roles with temporary credentials (such as an EC2 instance profile, SSO session, or aws sts assume-role) rather than long-lived IAM user access keys when running these WAF CLI commands.
• Monitor configuration changes. You SHOULD enable AWS CloudTrail on wafv2 management events and set CloudWatch alarms on critical web ACL configuration changes (such as DeleteWebACL and UpdateWebACL rule removals) and on the web ACL’s BlockedRequests and CountedRequests metrics, so rule changes and sudden spikes in blocked or counted traffic are detected.

Additional Resources

• Using rate-based rule statements in AWS WAF (AWS WAF Developer Guide) (opens in a new tab)
• Testing and tuning your AWS WAF protections (AWS WAF Developer Guide) (opens in a new tab)
• The three most important AWS WAF rate-based rules (AWS Security Blog) (opens in a new tab)