**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). 

# AWS WAF
<a name="waf-chapter"></a>

AWS WAF is a web application firewall that lets you monitor the HTTP(S) requests that are forwarded to your protected web application resources. You can protect the following resource types: 
+ Amazon CloudFront distribution
+ Amazon API Gateway REST API
+ Application Load Balancer
+ AWS AppSync GraphQL API
+ Amazon Cognito user pool
+ AWS App Runner service
+ AWS Verified Access instance
+ AWS Amplify

AWS WAF lets you control access to your content. Based on criteria that you specify, such as the IP addresses that requests originate from or the values of query strings, the service associated with your protected resource responds to requests either with the requested content, with an HTTP 403 status code (Forbidden), or with a custom response. 

**Note**  
You can also use AWS WAF to protect your applications that are hosted in Amazon Elastic Container Service (Amazon ECS) containers. Amazon ECS is a highly scalable, fast container management service that makes it easy to run, stop, and manage Docker containers on a cluster. To use this option, you configure Amazon ECS to use an Application Load Balancer that is enabled for AWS WAF to route and protect HTTP(S) layer 7 traffic across the tasks in your service. For more information, see [Service Load Balancing](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-load-balancing.html) in the *Amazon Elastic Container Service Developer Guide*.

**Topics**
+ [

# Get started with AWS WAF
](getting-started.md)
+ [

# How AWS WAF works
](how-aws-waf-works.md)
+ [

# Configuring protection in AWS WAF
](web-acl.md)
+ [

# AWS WAF rules
](waf-rules.md)
+ [

# AWS WAF rule groups
](waf-rule-groups.md)
+ [

# Web ACL capacity units (WCUs) in AWS WAF
](aws-waf-capacity-units.md)
+ [

# Oversize web request components in AWS WAF
](waf-oversize-request-components.md)
+ [

# Supported regular expression syntax in AWS WAF
](waf-regex-pattern-support.md)
+ [

# IP sets and regex pattern sets in AWS WAF
](waf-referenced-set-managing.md)
+ [

# Customized web requests and responses in AWS WAF
](waf-custom-request-response.md)
+ [

# Web request labeling in AWS WAF
](waf-labels.md)
+ [

# Intelligent threat mitigation in AWS WAF
](waf-managed-protections.md)
+ [

# Data protection and logging for AWS WAF protection pack (web ACL) traffic
](waf-data-protection-and-logging.md)
+ [

# Testing and tuning your AWS WAF protections
](web-acl-testing.md)
+ [

# Using AWS WAF with Amazon CloudFront
](cloudfront-features.md)
+ [

# Security in your use of the AWS WAF service
](security.md)
+ [

# AWS WAF quotas
](limits.md)
+ [

# Migrating your AWS WAF Classic resources to AWS WAF
](waf-migrating-from-classic.md)

# Get started with AWS WAF
<a name="getting-started"></a>

 Getting started with AWS WAF depends on which console experience you use. Both experiences provide access to the same core AWS WAF functionality, but they differ in how you configure and manage your web application protections. 

 AWS WAF offers two options for using the console:

 The **new console** aims to simplify web ACL configuration process required by standard console workflows. You can use guided workflows to simplify the web ACL creation and management process through a protection pack. A protection pack makes it easier to use and manage web ACLs in the console, but is not functionally different from a web ACL. In addition to the improved protection configuration process, the new console offers enhanced visibility into your protections through security dashboards, making it easier to monitor your security posture within the AWS WAF console. 

 The **standard AWS WAF console** provides a traditional approach to configuring web application firewall protections using web ACLs. It offers granular control over individual rules and rule groups and is familiar to existing AWS WAF users. With this console, you have detailed control over your protection configurations, allowing for precise customization of your security settings. 

**Tip**  
 Choose the console experience that best fits your needs. If you're new to AWS WAF or want to begin configuring protections based on AWS recommendations, we recommend starting with the new console experience. However, the standard experience is always available to open from the navigation pane in the console. 

 The following sections provide getting started guidance for both console experiences. Review each approach and select the one that best aligns with your security requirements and operational preferences: 

**Topics**
+ [

# Getting started with AWS WAF using the new console experience
](setup-iap-console.md)
+ [

# Getting started with AWS WAF using the standard console experience
](setup-existing-console.md)

# Getting started with AWS WAF using the new console experience
<a name="setup-iap-console"></a>

This section guides you through setting up AWS WAF using the new new console experience, which provides simplified configuration workflows and enhanced security management capabilities.

## Access the new console experience
<a name="accessing-iap-console"></a>

To access the new AWS WAF console experience:

Sign in to the new AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2-pro](https://console.aws.amazon.com/wafv2-pro). 
+ In the navigation pane, locate and select **Try the new experience**.

**Note**  
You can switch between console experiences at any time using the link in the navigation pane.

## Get started with a protection pack (web ACL)
<a name="getting-started-protection-packs"></a>

This tutorial shows you how to create and configure a protection pack (web ACL) to protect your applications. Protection packs (Web ACLs) provide pre-configured security rules tailored to specific workload types.

In this tutorial, you'll learn how to:
+ Create a protection pack (web ACL)
+ Configure application-specific protection settings
+ Add AWS resources to protect
+ Choose and customize rules
+ Configure logging and monitoring

**Note**  
AWS typically bills you less than US \$10.25 per day for the resources that you create during this tutorial. When you're finished, we recommend that you delete the resources to prevent incurring unnecessary charges.

### Step 1: Set up AWS WAF
<a name="getting-started-prerequisites"></a>

If you haven't already followed the general setup steps in [Setting up your account to use the services](setting-up-waf.md), do that now.

### Step 2: Create a protection pack (web ACL)
<a name="getting-started-create-protection-pack"></a>

In this step, you'll create a protection pack (web ACL) and configure its basic settings to match your application type.

1. Sign in to the new AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2-pro](https://console.aws.amazon.com/wafv2-pro). 

1. In the navigation pane, choose **Resources & protection packs (web ACLs)**.

1. On the **Resources & protection packs (web ACLs)** page, choose **Add protection pack (web ACL)**.

1. Under **Tell us about your app**, for **App category**, select one or more app categories that best describe your application.

1. For **Traffic source**, choose the type of traffic your application handles:
   + **API** - For API-only applications
   + **Web** - For web-only applications
   + **Both API and Web** - For applications that handle both types of traffic

### Step 3: Add resources to protect
<a name="getting-started-add-resources"></a>

Now you'll specify which AWS resources to protect with your protection pack (web ACL).

1. Under **Resources to protect**, choose **Add resources**.

1. Choose the category of AWS resource to associate with this protection pack (web ACL):
   + Amazon CloudFront distributions
   + Regional resources

   For more information about resource types, see [Associating protection with an AWS resource](web-acl-associating.md).

### Step 4: Choose initial protections
<a name="getting-started-configure-protection"></a>

In this step, you'll select the rules for your protection pack (web ACL). For first-time users, we recommend choosing the **Recommended** option.

AWS WAF generates **Recommended** for you based on your selections in the **Tell us about your app** section. These packs implement security best practices for your application type.
+  Choose **Next** to continue with the protection pack (web ACL) setup.

**Note**  
If you're interested in creating custom rules or using the **You build it** option, we recommend first gaining experience with the pre-configured options. For more information about creating custom protection packs (web ACLs) and rules, see [Creating a protection pack (web ACL) in AWS WAF](web-acl-creating.md).

### Step 5: Customize protection pack (web ACL) settings
<a name="getting-started-customize-settings"></a>

Now you'll configure additional settings like default actions, rate limits, and logging.

1. Under **Name and description**, enter a name for your protection pack (web ACL). Optionally, enter a description.
**Note**  
You can't change the name after you create the protection pack (web ACL).

1. Under **Customize protection pack (web ACL)**, configure the following settings:

   1. Under **Default rule actions**, choose the default action for requests that don't match any rules. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

   1. Under **Rule configuration**, customize these settings:
      + **Default rate limits** - Set limits to protect against DDoS attacks
      + **IP Addresses** - Configure IP allow/block lists
      + **Country specific origins** - Manage access by country

   1. For **Logging destination**, configure where you want to store logs. For more information, see [AWS WAF logging destinations](logging-destinations.md).

1. Review your settings and choose **Add protection pack (web ACL)**.

### Step 6: Clean up your resources
<a name="getting-started-clean-up"></a>

You've now successfully completed the tutorial. To prevent your account from accruing additional AWS WAF charges, you should either delete the protection pack (web ACL) you created or modify it to match your production needs.

**To delete your protection pack (web ACL)**

1. In the navigation pane, choose **Resources & protection packs (web ACLs)**.

1. Select the protection pack (web ACL) you created.

1. Choose the trash icon, then confirm the deletion by typing "delete".

**Note**  
If you plan to use this protection pack (web ACL) in production, instead of deleting it, you should review and adjust the protection settings to match your application's security requirements.

# Getting started with AWS WAF using the standard console experience
<a name="setup-existing-console"></a>

The AWS WAF console guides you through the process of configuring AWS WAF to block or allow web requests based on criteria that you specify, such as the IP addresses that the requests originate from or values in the requests. In this step, you create a protection pack (web ACL). For more information about AWS WAF protection packs (web ACLs), see [Configuring protection in AWS WAF](web-acl.md).

This tutorial shows how to use AWS WAF to perform the following tasks:
+ Set up AWS WAF.
+ Create a web access control list (web ACL) using the wizard in the AWS WAF console.

**To create a web ACL**

  1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

  1. From the AWS WAF home page, choose **Create web ACL**. 

  1. For **Name**, enter the name that you want to use to identify this web ACL. 
**Note**  
You can't change the name after you create the web ACL.

  1. (Optional) For **Description - optional**, enter a longer description for the web ACL if you want to. 

  1. For **CloudWatch metric name**, change the default name if applicable. Follow the guidance on the console for valid characters. The name can't contain special characters, white space, or metric names reserved for AWS WAF, including "All" and "Default\$1Action."
**Note**  
You can't change the CloudWatch metric name after you create the web ACL.

  1. For **Resource type**, choose **CloudFront distributions**. The **Region** automatically populates to **Global (CloudFront)** for CloudFront distributions.

  1. (Optional) For **Associated AWS resources - optional**, choose **Add AWS resources**. In the dialog box, choose the resources that you want to associate, and then choose **Add**. AWS WAF returns you to the **Describe web ACL and associated AWS resources** page. 

  1. Choose **Next**.

**Note**  
AWS typically bills you less than US \$10.25 per day for the resources that you create during this tutorial. When you're finished with the tutorial, we recommend that you delete the resources to prevent incurring unnecessary charges. 

## Step 1: Set up AWS WAF
<a name="getting-started-aws-account"></a>

If you haven't already followed the general setup steps in [Setting up your account to use the services](setting-up-waf.md), do that now.

## Step 2: Create a web ACL
<a name="getting-started-wizard-create-web-acl"></a>

The AWS WAF console guides you through the process of configuring AWS WAF to block or allow web requests based on criteria that you specify, such as the IP addresses that the requests originate from or values in the requests. In this step, you create a web ACL. For more information about AWS WAF web ACLs, see [Configuring protection in AWS WAF](web-acl.md).

**To create a web ACL**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. From the AWS WAF home page, choose **Create web ACL**.

1. For **Name**, enter the name that you want to use to identify this web ACL.
**Note**  
You can't change the name after you create the web ACL.

1. (Optional) For **Description - optional**, enter a longer description for the web ACL if you want to.

1. For **CloudWatch metric name**, change the default name if applicable. Follow the guidance on the console for valid characters. The name can't contain special characters, white space, or metric names reserved for AWS WAF, including "All" and "Default\$1Action."
**Note**  
You can't change the CloudWatch metric name after you create the web ACL.

1. For **Resource type**, choose **CloudFront distributions**. The **Region** automatically populates to **Global (CloudFront)** for CloudFront distributions.

1. (Optional) For **Associated AWS resources - optional**, choose **Add AWS resources**. In the dialog box, choose the resources that you want to associate, and then choose **Add**. AWS WAF returns you to the **Describe web ACL and associated AWS resources** page.

1. Choose **Next**.

## Step 3: Add a string match rule
<a name="getting-started-wizard-create-string-condition"></a>

In this step, you create a rule with a string match statement and indicate what to do with matching requests. A string match rule statement identifies strings that you want AWS WAF to search for in a request. Usually, a string consists of printable ASCII characters, but you can specify any character from hexadecimal 0x00 to 0xFF (decimal 0 to 255). In addition to specifying the string to search for, you specify the web request component that you want to search, such as a header, a query string, or the request body. 

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

For additional information about AWS WAF rules, see [AWS WAF rules](waf-rules.md). 

**To create a string match rule statement**

1. On the **Add rules and rule groups** page, choose **Add rules**, **Add my own rules and rule groups**, **Rule builder**, then **Rule visual editor**. 
**Note**  
The console provides the **Rule visual editor** and also a **Rule JSON editor**. The JSON editor makes it easy for you to copy configurations between web ACLs and is required for more complex rule sets, like those with multiple levels of nesting.   
This procedure uses the **Rule visual editor**. 

1. For **Name**, enter the name that you want to use to identify this rule. 

1. For **Type** choose **Regular rule**.

1. For **If a request** choose **matches the statement**. 

   The other options are for the logical rule statement types. You can use them to combine or negate the results of other rule statements. 

1. On **Statement**, for **Inspect**, open the dropdown and choose the web request component that you want AWS WAF to inspect. For this example, choose **Single header**.

   When you choose **Single header**, you also specify which header you want AWS WAF to inspect. Enter **User-Agent**. This value isn't case sensitive.

1. For **Match type**, choose where the specified string must appear in the `User-Agent` header. 

   For this example, choose **Exactly matches string**. This indicates that AWS WAF inspects the user-agent header in each web request for a string that is identical to the string that you specify.

1. For **String to match**, specify a string that you want AWS WAF to search for. The maximum length of **String to match** is 200 characters. If you want to specify a base64-encoded value, you can specify up to 200 characters before encoding.

   For this example, enter **MyAgent**. AWS WAF will inspect the `User-Agent` header in web requests for the value `MyAgent`.

1. Leave **Text transformation** set to **None**. 

1. For **Action**, select the action that you want the rule to take when it matches a web request. For this example, choose **Count** and leave the other choices as they are. The count action creates metrics for web requests that match the rule, but doesn't affect whether the request is allowed or blocked. For more information about action choices, see [Using rule actions in AWS WAF](waf-rule-action.md) and [Setting rule priority](web-acl-processing-order.md).

1. Choose **Add rule**.

## Step 4: Add a AWS Managed Rules rule group
<a name="getting-started-wizard-add-rule-group"></a>

AWS Managed Rules offers a set of managed rule groups for your use, most of which are free of charge to AWS WAF customers. For more information about rule groups, see [AWS WAF rule groups](waf-rule-groups.md). We'll add an AWS Managed Rules rule group to this web ACL. 

**To add an AWS Managed Rules rule group**

1. On the **Add rules and rule groups** page, choose **Add rules**, and then choose **Add managed rule groups**. 

1. On the **Add managed rule groups** page, expand the listing for the **AWS managed rule groups**. (You'll also see listings offered for AWS Marketplace sellers. You can subscribe to their offerings and then use them in the same way as for AWS Managed Rules rule groups.)

1. For the rule group that you want to add, do the following: 

   1. In the **Action** column, turn on the **Add to web ACL** toggle. 

   1. Select **Edit** and, in the rule group's **Rules** listing, open the **Override all rule actions** dropdown and select **Count**. This sets the action for all rules in the rule group to count only. This allows you to see how all of the rules in the rule group behave with your web requests before you put any of them to use.

   1. Choose **Save rule**.

1. In the **Add managed rule groups** page, choose **Add rules**. This returns you to the **Add rules and rule groups** page.

## Step 5: Finish your web ACL configuration
<a name="getting-started-wizard-finish-webacl-options"></a>

When you're done adding rules and rule groups to your web ACL configuration, finish up by managing the priority of the rules in the web ACL and configuring settings like metrics, tagging, and logging. 

**To finish your web ACL configuration**

1. On the **Add rules and rule groups** page, choose **Next**. 

1. On the **Set rule priority** page, you can see the processing order for the rules and rule groups in the web ACL. AWS WAF processes them starting from the top of the list. You can change the processing order by moving the rules up or down. To do this, select one in the list and choose **Move up** or **Move down**. For more information about rule priority, see [Setting rule priority](web-acl-processing-order.md). 

1. Choose **Next**.

1. On the **Configure metrics** page, for **Amazon CloudWatch metrics**, you can see the planned metrics for your rules and rule groups and you can see the web request sampling options. For information about viewing sampled requests, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 

   You can access summaries of the web traffic metrics on the web ACL's page in the AWS WAF console, under the **Traffic overview** tab. The console dashboards provide near real-time summaries of the web ACL's Amazon CloudWatch metrics. For more information, see [Traffic overview dashboards for protection packs (web ACLs)](web-acl-dashboards.md). 

1. Choose **Next**.

1. On the **Review and create web ACL** page, review your settings, then choose **Create web ACL**. 

The wizard returns you to the **web ACL** page, where your new web ACL is listed.

## Step 6: Clean up your resources
<a name="getting-started-wizard-clean-up"></a>

You've now successfully completed the tutorial. To prevent your account from accruing additional AWS WAF charges, clean up the AWS WAF objects that you created. Alternatively, you can change the configuration to match the web requests that you really want to manage using AWS WAF.

**Note**  
AWS typically bills you less than US \$10.25 per day for the resources that you create during this tutorial. When you're finished, we recommend that you delete the resources to prevent incurring unnecessary charges. 

**To delete the objects that AWS WAF charges for**

1. In the **web ACL** page, select your web ACL from the list and choose **Edit**. 

1. On the **Associated AWS resources** tab, for each associated resource, select the radio button next to the resource name and then choose **Disassociate**. This disassociates the web ACL from your AWS resources. 

1. In each of the following screens, choose **Next** until you return to the **web ACL** page.

   In the **web ACL** page, select your web ACL from the list and choose **Delete**. 

Rules and rule statements don't exist outside of rule group and web ACL definitions. If you delete a web ACL, this deletes all individual rules that you've defined in the web ACL. When you remove a rule group from a web ACL, you just remove the reference to it. 

# How AWS WAF works
<a name="how-aws-waf-works"></a>

You use AWS WAF to control how your protected resources respond to HTTP(S) web requests. You do this by defining a web access control list (web ACL) and then associating it with one or more web application resources that you want to protect. The associated resources forward incoming requests to AWS WAF for inspection by the web ACL. 

The **new console** simplifies the web ACL configuration process. It introduces protection packs to streamline setup while maintaining full control over your security rules. 

Protection packs are the new location for web ACLs and simplify web ACL management in the console, but they don't change the underlying web ACL functionality. When using the standard console or the API, you'll still work directly with web ACLs.

In your protection pack (web ACL), you create rules to define traffic patterns to look for in requests and to specify the actions to take on matching requests. The action choices include the following: 
+ Allow the requests to go to the protected resource for processing and response. 
+ Block the requests. 
+ Count the requests. 
+ Run CAPTCHA or challenge checks against requests to verify human users and standard browser use. 

**AWS WAF components**  
The following are the central components of AWS WAF:
+ **web ACLs** – You use a web access control list (web ACL) to protect a set of AWS resources. You create a web ACL and define its protection strategy by adding rules. Rules define criteria for inspecting web requests and they specify the action to take on requests that match their criteria. You also set a default action for the web ACL that indicates whether to block or allow through any requests that the rules haven't already blocked or allowed. For more information about web ACLs, see [Configuring protection in AWS WAF](web-acl.md).

  A web ACL is an AWS WAF resource.
+ **Protection pack (Web ACL)s** – In the new console, protection packs are the new location for your web ACLs. During setup, you provide information about your apps and resources. AWS WAF reccomends a protection pack tailored to your scenario, and then creates a web ACL that contains rules, rule groups, and actions defined by the protection pack (web ACL) you choose. For more information about protection packs (web ACLs), see [Configuring protection in AWS WAF](web-acl.md).

  A protection pack (web ACL) is an AWS WAF resource.
+ **Rules** – Each rule contains a statement that defines the inspection criteria, and an action to take if a web request meets the criteria. When a web request meets the criteria, that's a match. You can configure rules to block matching requests, allow them through, count them, or run bot controls against them that use CAPTCHA puzzles or silent client browser challenges. For more information about rules, see [AWS WAF rules](waf-rules.md). 

  A rule is not an AWS WAF resource. It only exists in the context of a protection pack (web ACL) or rule group.
+ **Rule groups** – You can define rules directly inside a protection pack (web ACL) or in reusable rule groups. AWS Managed Rules and AWS Marketplace sellers provide managed rule groups for your use. You can also define your own rule groups. For more information about rule groups, see [AWS WAF rule groups](waf-rule-groups.md). 

  A rule group is an AWS WAF resource.
+ **web ACL capacity units (WCUs)** – AWS WAF uses WCUs to calculate and control the operating resources that are required to run your rules, rule groups, protection packs (web ACLs), or web ACLs. 

  A WCU is not an AWS WAF resource. It only exists in the context of a protection pack (web ACL), rule, or rule group.

# Resources that you can protect with AWS WAF
<a name="how-aws-waf-works-resources"></a>

You can use an AWS WAF protection pack (web ACL) to protect global or regional resource types. You do this by associating the protection pack (web ACL) with the resources that you want to protect. The protection pack (web ACL) and any AWS WAF resources that it uses must be located in the Region where the associated resource is located. For Amazon CloudFront distributions, this is set to US East (N. Virginia).

**Amazon CloudFront distributions**  
You can associate an AWS WAF protection pack (web ACL) with a CloudFront distribution using the AWS WAF console or APIs. You can also associate a protection pack (web ACL) with a CloudFront distribution when you create or update the distribution itself. To configure an association in AWS CloudFormation, you must use the CloudFront distribution configuration. For information about Amazon CloudFront, see [Using AWS WAF to Control Access to Your Content](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-awswaf.html) in the *Amazon CloudFront Developer Guide*.

AWS WAF is available globally for CloudFront distributions, but you must use the Region US East (N. Virginia) to create your protection pack (web ACL) and any resources used in the protection pack (web ACL), such as rule groups, IP sets, and regex pattern sets. Some interfaces offer a region choice of "Global (CloudFront)". Choosing this is identical to choosing Region US East (N. Virginia) or "us-east-1".

**Regional resources**  
You can protect regional resources in all Regions where AWS WAF is available. You can see the list at [AWS WAF endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/waf.html) in the *Amazon Web Services General Reference*. 

You can use AWS WAF to protect the following regional resource types: 
+ Amazon API Gateway REST API
+ Application Load Balancer
+ AWS AppSync GraphQL API
+ Amazon Cognito user pool
+ AWS App Runner service
+ AWS Verified Access instance
+ AWS Amplify

You can only associate a protection pack (web ACL) to an Application Load Balancer that's within AWS Regions. For example, you cannot associate a protection pack (web ACL) to an Application Load Balancer that's on AWS Outposts.

You must create any protection pack (web ACL) that you want to associate with an Amplify app in the Global CloudFront Region. You might already have a Regional protection pack (web ACL) in your AWS account, but they are not compatible with Amplify.

The protection pack (web ACL) and any other AWS WAF resources that it uses must be located in the same Region as the protected resources. When monitoring and managing web requests for a protected regional resource, AWS WAF keeps all data in the same Region as the protected resource. 

**Restrictions on multiple resource associations**  
You can associate a single protection pack (web ACL) with one or more AWS resources, with the following restrictions:
+ You can associate each AWS resource with only one protection pack (web ACL). The relationship between protection pack (web ACL) and AWS resources is one-to-many. 
+ You can associate a protection pack (web ACL) with one or more CloudFront distributions. You cannot associate a protection pack (web ACL) that you have associated with a CloudFront distribution with any other AWS resource type.

# Working with the updated console experience
<a name="working-with-console"></a>

 AWS WAF offers two options for using the console:

 The **new console** aims to simplify web ACL configuration process required by standard console workflows. You can use guided workflows to simplify the web ACL creation and management process through a protection pack (web ACL). A protection pack (web ACL) makes it easier to use and manage web ACLs in the console, but is not functionally different from a web ACL. In addition to the improved protection configuration process, the new console offers enhanced visibility into your protections through security dashboards, making it easier to monitor your security posture within the AWS WAF console. 

 The **standard AWS WAF console** provides a traditional approach to configuring web application firewall protections using web ACLs. It offers granular control over individual rules and rule groups and is familiar to existing AWS WAF users. With this console, you have detailed control over your protection configurations, allowing for precise customization of your security settings. 

**Tip**  
 Choose the console experience that best fits your needs. If you're new to AWS WAF or want to begin configuring protections based on AWS recommendations, we recommend starting with the new console experience. However, the standard experience is always available to open from the navigation pane in the console. 

## Feature parity between the new and standard console experience
<a name="feature-parity"></a>

The new console experience maintains complete feature parity with the existing console while introducing new capabilities:
+ All existing AWS WAF functionality remains available
+ Enhanced visibility through unified dashboards
+ Simplified configuration workflows
+ New protection pack (web ACL) templates

**Important**  
The new console experience uses the same WAFv2 APIs as the existing console. This means that protection packs created in the new console are implemented as standard WAFv2 web ACLs at the API level.

## Key differences
<a name="key-differences"></a>


**Comparison of Console Experiences**  

| Feature | Previous AWS WAF console experience | Updated console experience | 
| --- | --- | --- | 
| Configuration process | Multi-page workflow | Single-page interface | 
| Rule configuration | Individual rule creation | Option for pre-configured protection packs | 
| Monitoring | Separate dashboards | Unified visibility including AI Traffic Analysis | 

## Understanding the new dashboards
<a name="understanding-new-dashboard"></a>

Dashboards available through new provide unified visibility into your security posture through these visualizations:

**Traffic insight recommendations** – AWS Threat Intelligence monitors your previous 2 weeks of allowed traffic, analyzes vulnerabilities, and provides the following:  
+ Traffic-based rule suggestions
+ Application-specific security recommendations
+ Protection optimization guidance

**Summary** – Shows request counts for all traffic during a specified time range. You can use the following criteria to filter traffic data:  
+ **Rule** – Filter by the individual rules in the protection pack.
+ **Actions** – Show counts for specific actions taken on traffic like Allow, Block, Captcha, and Challenge.
+ **Traffic type** – Only show counts for specific traffic types like anti-DDoS or bots.
+ **Time range ** – Choose from a selection of predefined time ranges, or set a custom range. 
+ **Local or UTC time** – You can set your preferred time format.

**AI Traffic Analysis** – Provides comprehensive visibility into AI bot and agent activity:  
+ **Bot identification** – Bot names, organizations, and verification status.
+ **Intent analysis** – Purpose and behavior patterns of AI agents.
+ **Access patterns** – Most frequently accessed URLs and endpoints.
+ **Temporal trends** – Activity patterns by time of day and historical trends (0-14 days).
+ **Traffic characteristics** – Volume, distribution, and anomaly detection for AI traffic.

**Protection activity** – Visualizes your protection rules and how their order contributes to terminating actions.  
+ **Traffic flow through your rules** – Show the traffic flow through your rules. Switch from **Sequential rules view** to **Non-sequential rules view** to see how rule order affects outcomes.
+ **Rule actions and their outcomes** – Shows the terminating actions that a rule took on traffic in the specified time period. 

**Action totals ** – A chart that visualizes the total number of actions taken on requests during a specified time range. Use the **Overlay last 3 hours** option to compare the current time range with the previous 3 hour time window. You can filter data by:   
+ **Allow action**
+ **Total actions**
+ **Captcha actions**
+ **Challenge actions**
+ **Block actions**

**All rules** – A chart that visualizes metrics for all rules in the protection pack.  
+  Use the **Overlay last 3 hours** option to compare the current time range with the previous 3 hour time window.

**Overview Dashboard** – Provides a comprehensive, graphical view of your security status, including the following:  
+ **Traffic characteristics** – See an overview of traffic by origin, attack types, or by the device type of the clients that sent requests.
+ **Rule characteristics** – A breakdown of attacks by the 10 most common rules and termnating actions.
+ **Bots** – Visualize bot activity, detection, categories, and bot-related signal labels.
+ **Anti-DDoS** – An overview of detected and mitigated layer 7 DDoS activity.

# Configuring protection in AWS WAF
<a name="web-acl"></a>

This page explains what protection packs (web ACLs) are and how they work.

 A protection pack (web ACL) gives you fine-grained control over all of the HTTP(S) web requests that your protected resource responds to. You can protect Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, Amazon Cognito, AWS App Runner, AWS Amplify, Amazon CloudWatch, and AWS Verified Access resources.

You can use criteria like the following to allow or block requests: 
+ IP address origin of the request
+ Country of origin of the request
+ String match or regular expression (regex) match in a part of the request
+ Size of a particular part of the request
+ Detection of malicious SQL code or scripting 

You can also test for any combination of these conditions. You can block or count web requests that not only meet the specified conditions, but also exceed a specified number of requests in a single minute. You can combine conditions using logical operators. You can also run CAPTCHA puzzles and silent client session challenges against requests. 

You provide your matching criteria and the action to take on matches in AWS WAF rule statements. You can define rule statements directly inside your protection pack (web ACL) and in reusable rule groups that you use in your protection pack (web ACL). For a full list of the options, see [Using rule statements in AWS WAF](waf-rule-statements.md) and [Using rule actions in AWS WAF](waf-rule-action.md).

When you create a protection pack (web ACL), you specify the types of resources that you want to use it with. For information, see [Creating a protection pack (web ACL) in AWS WAF](web-acl-creating.md). After you define a protection pack (web ACL), you can associate it with your resources to begin providing protection for them. For more information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md). 

**Note**  
On some occasions, AWS WAF might encounter an internal error that delays the response to associated AWS resources about whether to allow or block a request. On those occasions, CloudFront typically allows the request or serves the content, while the Regional services typically deny the request and don't serve the content.

**Production traffic risk**  
Before you deploy changes in your protection pack (web ACL) for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

**Topics**
+ [

# Creating a protection pack (web ACL) in AWS WAF
](web-acl-creating.md)
+ [

# Editing a protection pack (web ACL) in AWS WAF
](web-acl-editing.md)
+ [

# Managing rule group behavior
](web-acl-rule-group-settings.md)
+ [

# Associating or disassociating protection with an AWS resource
](web-acl-associating-aws-resource.md)
+ [

# Using protection packs (web ACLs) with rules and rule groups in AWS WAF
](web-acl-processing.md)
+ [

# Setting the protection pack (web ACL) default action in AWS WAF
](web-acl-default-action.md)
+ [

# Considerations for managing body inspection in AWS WAF
](web-acl-setting-body-inspection-limit.md)
+ [

# Configuring CAPTCHA, challenge, and tokens in AWS WAF
](web-acl-captcha-challenge-token-domains.md)
+ [

# Viewing web traffic metrics in AWS WAF
](web-acl-working-with.md)
+ [

# Deleting a protection pack (web ACL)
](web-acl-deleting.md)

# Creating a protection pack (web ACL) in AWS WAF
<a name="web-acl-creating"></a>

------
#### [ Using the new console ]

This section provides procedures for creating protection packs (web ACLs) through the new AWS console. 

To create a new protection pack (web ACL), use the protection pack (web ACL) creation wizard following the procedure on this page. 

**Production traffic risk**  
Before you deploy changes in your protection pack (web ACL) for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

1. Sign in to the new AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2-pro](https://console.aws.amazon.com/wafv2-pro). 

1. In the navigation pane, choose **Resources & protection packs (web ACLs)**.

1. On the **Resources & protection packs (web ACLs)** page, choose **Add protection pack (web ACL)**.

1. Under **Tell us about your app**, for **App category**, select one or more app categories.

1. For **Traffic source**, choose the type of traffic the application engages with; **API**, **Web**, or **Both API and Web**.

1. Under **Resources to protect,** choose **Add resources**.

1. Choose the category of AWS resource that you want to associate with this protection pack (web ACL), either Amazon CloudFront distributions or Regional resources. For more information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md). 

1. Under **Choose initial protections,** select your preferred protection level: **Recommended**, **Essentials**, or **You build it**. 

1. (Optional) If you choose **You build it**, build your rules.

   1. (Optional) If you want to add your own rule, on the **Add rules ** page, choose **Custom rule** and then choose **Next**.

      1. Choose the rule type.

      1. For **Action**, select the action you want the rule to take when it matches a web request. For information on your choices, see [Using rule actions in AWS WAF](waf-rule-action.md) and [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md).

         If you are using the **CAPTCHA** or **Challenge** action, adjust the **Immunity time** configuration as needed for the rule. If you don't specify the setting, the rule inherits it from the protection pack (web ACL). To modify the protection pack (web ACL) immunity time settings, edit the protection pack (web ACL) after you create it. For more information about immunity times, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).
**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

         If you want to customize the request or response, choose the options for that and fill in the details of your customization. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

         If you want to have your rule add labels to matching web requests, choose the options for that and fill in your label details. For more information, see [Web request labeling in AWS WAF](waf-labels.md).

      1. For **Name**, enter the name that you want to use to identify this rule. Don't use names that start with `AWS`, `Shield`, `PreFM`, or `PostFM`. These strings are either reserved or could cause confusion with rule groups that are managed for you by other services.

      1. Enter your rule definition, according to your needs. You can combine rules inside logical `AND` and `OR` rule statements. The wizard guides you through the options for each rule, according to context. For information about your rules options, see [AWS WAF rules](waf-rules.md). 

      1. Choose **Create rule**.
**Note**  
If you add more than one rule to a protection pack (web ACL), AWS WAF evaluates the rules in the order that they're listed for the protection pack (web ACL). For more information, see [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md).

   1. (Optional) If you want to add managed rule groups, on the **Add rules** page, choose **AWS-managed rule group** or **AWS Marketplace rule group** and then choose **Next**. Do the following for each managed rule group that you want to add:

      1. On the **Add rules** page, expand the listing for AWS managed rule groups or for the AWS Marketplace seller.

      1. Choose the version of the rule group.

      1. To customize how your protection pack (web ACL) uses the rule group, choose **Edit**. The following are common customization settings: 
         + Reduce the scope of the web requests that the rule group inspects by adding a scope-down statement in the **Inspection** section. For information about this option, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).
         + Override the rule actions for some or all rules in **Rule overrides**. If you don't define an override action for a rule, the evaluation uses the rule action that's defined inside the rule group. For information about this option, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 
         + Some managed rule groups require you to provide additional configuration. See the documentation from your managed rule group provider. For information specific to the AWS Managed Rules rule groups, see [AWS Managed Rules for AWS WAF](aws-managed-rule-groups.md). 

      1. Choose **Next**.

   1. (Optional) If you want to add your own rule group, on the **Add rules** page, choose **Custom rule group** and then choose **Next**. Do the following for each rule group that you want to add:

      1. For **Name**, enter the name that you want to use for the rule group rule in this protection pack (web ACL). Don't use names that start with `AWS`, `Shield`, `PreFM`, or `PostFM`. These strings are either reserved or could cause confusion with rule groups that are managed for you by other services. See [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md). 

      1. Choose your rule group from the list. 

      1. (Optional) Under **Rule configuration**, choose a **Rule override**. You can override the rule actions to any valid action setting, the same as you can do for managed rule groups.

      1. (Optional) Under **Add labels**, choose **Add label** and then enter any labels you want to add to requests that match the rule. Rules that are evaluated later in the same protection pack (web ACL) can reference the labels this rule adds.

      1. Choose **Create rule**.

1. Under **Name and description**, enter a name for your protection pack (web ACL). Optionally, enter a description.
**Note**  
You can't change the name after you create the protection pack (web ACL).

1. (Optional) Under **Customize protection pack (web ACL)**, configure default rule actions, configurations, and logging destination:

   1. (Optional) Under **Default rule actions**, choose the default action for the protection pack (web ACL). This is the action that AWS WAF takes on a request when the rules in the protection pack (web ACL) don't explicitly take an action. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

   1. (Optional) Under Rule configuration, customize settings for rules in the protection pack (web ACL):
      + **Default rate limits** - Set rate limits to block Denial of Service (DoS) attacts that can affect availability, compromise security, or consume excessive resources. This rule rate blocks requests per IP address that exceed the allowed rate for your application. For more information, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md)
      + **IP Addresses** - Enter IP addresses to block or allow. This setting overrides other rules.
      + **Country specific origins** - Block requests from specified countries or Count all traffic.

   1. For **Logging destination**, configure the logging destination type and the place to store logs. For more information, see [AWS WAF logging destinations](logging-destinations.md).

1. Review your settings and choose **Add protection pack (web ACL)**.

------
#### [ Using the standard console ]

This section provides procedures for creating web ACLs through the AWS console. 

To create a new web ACL, use the web ACL creation wizard following the procedure on this page. 

**Production traffic risk**  
Before you deploy changes in your web ACL for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**To create a web ACL**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choose **web ACLs** in the navigation pane, and then choose **Create web ACL**.

1. For **Name**, enter the name that you want to use to identify this web ACL. 
**Note**  
You can't change the name after you create the web ACL.

1. (Optional) For **Description - optional**, enter a longer description for the web ACL if you want to. 

1. For **CloudWatch metric name**, change the default name if applicable. Follow the guidance on the console for valid characters. The name can't contain special characters, white space, or metric names reserved for AWS WAF, including "All" and "Default\$1Action."
**Note**  
You can't change the CloudWatch metric name after you create the web ACL.

1. Under **Resource type**, choose the category of AWS resource that you want to associate with this web ACL, either Amazon CloudFront distributions or Regional resources. For more information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

1. For **Region**, if you've chosen a Regional resource type, choose the Region where you want AWS WAF to store the web ACL. 

   You only need to choose this option for Regional resource types. For CloudFront distributions, the Region is hard-coded to the US East (N. Virginia) Region, `us-east-1`, for Global (CloudFront) applications.

1. (CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access) For **Web request inspection size limit - optional**, if you want to specify a different body inspection size limit, select the limit. Inspecting body sizes over the default of 16 KB can incur additional costs. For information about this option, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md). 

1. (Optional) For **Associated AWS resources - optional**, if you want to specify your resources now, choose **Add AWS resources**. In the dialog box, choose the resources that you want to associate, and then choose **Add**. AWS WAF returns you to the **Describe web ACL and associated AWS resources** page.
**Note**  
When you choose to associate an Application Load Balancer with your web ACL, **Resource-level DDoS protection** is enabled. For more information, see [AWS WAF Distributed Denial of Service (DDoS) prevention](waf-anti-ddos.md).

1. Choose **Next**.

1. (Optional) If you want to add managed rule groups, on the **Add rules and rule groups** page, choose **Add rules**, and then choose **Add managed rule groups**. Do the following for each managed rule group that you want to add:

   1. On the **Add managed rule groups** page, expand the listing for AWS managed rule groups or for the AWS Marketplace seller of your choice.

   1. For the rule group that you want to add, in the **Action** column, turn on the **Add to web ACL** toggle. 

      To customize how your web ACL uses the rule group, choose **Edit**. The following are common customization settings: 
      + Override the rule actions for some or all rules. If you don't define an override action for a rule, the evaluation uses the rule action that's defined inside the rule group. For information about this option, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 
      + Reduce the scope of the web requests that the rule group inspects by adding a scope-down statement. For information about this option, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).
      + Some managed rule groups require you to provide additional configuration. See the documentation from your managed rule group provider. For information specific to the AWS Managed Rules rule groups, see [AWS Managed Rules for AWS WAF](aws-managed-rule-groups.md). 

      When you're finished with your settings, choose **Save rule**.

   Choose **Add rules** to finish adding managed rules and return to the **Add rules and rule groups** page.
**Note**  
If you add more than one rule to a web ACL, AWS WAF evaluates the rules in the order that they're listed for the web ACL. For more information, see [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md).

1. (Optional) If you want to add your own rule group, on the **Add rules and rule groups** page, choose **Add rules**, and then choose **Add my own rules and rule groups**. Do the following for each rule group that you want to add:

   1. On the **Add my own rules and rule groups** page, choose **Rule group**.

   1. For **Name**, enter the name that you want to use for the rule group rule in this web ACL. Don't use names that start with `AWS`, `Shield`, `PreFM`, or `PostFM`. These strings are either reserved or could cause confusion with rule groups that are managed for you by other services. See [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md). 

   1. Choose your rule group from the list. 
**Note**  
If you want to override the rule actions for a rule group of your own, first save it to the web ACL, and then edit the web ACL and the rule group reference statement in the web ACL's rule listing. You can override the rule actions to any valid action setting, the same as you can do for managed rule groups.

   1. Choose **Add rule**.

1. (Optional) If you want to add your own rule, on the **Add rules and rule groups** page, choose **Add rules**, **Add my own rules and rule groups**, **Rule builder**, then **Rule visual editor**. 
**Note**  
The console **Rule visual editor** supports one level of nesting. For example, you can use a single logical `AND` or `OR` statement and nest one level of other statements inside it, but you can't nest logical statements within logical statements. To manage more complex rule statements, use the **Rule JSON editor**. For information about all options for rules, see [AWS WAF rules](waf-rules.md).   
This procedure covers the **Rule visual editor**. 

   1. For **Name**, enter the name that you want to use to identify this rule. Don't use names that start with `AWS`, `Shield`, `PreFM`, or `PostFM`. These strings are either reserved or could cause confusion with rule groups that are managed for you by other services.

   1. Enter your rule definition, according to your needs. You can combine rules inside logical `AND` and `OR` rule statements. The wizard guides you through the options for each rule, according to context. For information about your rules options, see [AWS WAF rules](waf-rules.md). 

   1. For **Action**, select the action you want the rule to take when it matches a web request. For information on your choices, see [Using rule actions in AWS WAF](waf-rule-action.md) and [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md).

      If you are using the **CAPTCHA** or **Challenge** action, adjust the **Immunity time** configuration as needed for the rule. If you don't specify the setting, the rule inherits it from the web ACL. To modify the web ACL immunity time settings, edit the web ACL after you create it. For more information about immunity times, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).
**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

      If you want to customize the request or response, choose the options for that and fill in the details of your customization. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

      If you want to have your rule add labels to matching web requests, choose the options for that and fill in your label details. For more information, see [Web request labeling in AWS WAF](waf-labels.md).

   1. Choose **Add rule**.

1. Choose the default action for the web ACL, either Block or Allow. This is the action that AWS WAF takes on a request when the rules in the web ACL don't explicitly allow or block it. For more information, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md).

   If you want to customize the default action, choose the options for that and fill in the details of your customization. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

1. You can define a **Token domain list** to enable token sharing between protected applications. Tokens are used by the CAPTCHA and Challenge actions and by the application integration SDKs that you implement when you use the AWS Managed Rules rule groups for AWS WAF Fraud Control account creation fraud prevention (ACFP), AWS WAF Fraud Control account takeover prevention (ATP), and AWS WAF Bot Control. 

   Public suffixes aren't allowed. For example, you can't use `gov.au` or `co.uk` as a token domain.

   By default, AWS WAF accepts tokens only for the domain of the protected resource. If you add token domains in this list, AWS WAF accepts tokens for all domains in the list and for the domain of the associated resource. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).

1. Choose **Next**.

1. In the **Set rule priority** page, select and move your rules and rule groups to the order that you want AWS WAF to process them. AWS WAF processes rules starting from the top of the list. When you save the web ACL AWS WAF assigns numeric priority settings to the rules, in the order that you have them listed. For more information, see [Setting rule priority](web-acl-processing-order.md). 

1. Choose **Next**.

1. In the **Configure metrics** page, review the options and apply any updates that you need. You can combine metrics from multiple sources by providing the same **CloudWatch metric name** for them. 

1. Choose **Next**.

1. In the **Review and create web ACL** page, check over your definitions. If you want to change any area, choose **Edit** for the area. This returns you to the page in the web ACL wizard. Make any changes, then choose **Next** through the pages until you come back to the **Review and create web ACL** page.

1. Choose **Create web ACL**. Your new web ACL is listed in the **web ACLs** page.

------

# Editing a protection pack (web ACL) in AWS WAF
<a name="web-acl-editing"></a>

------
#### [ Using the new console ]

This section provides procedures for editing protection packs (web ACLs) through the AWS console. 

To add or remove rules from a protection pack (web ACL) or change configuration settings, access the protection pack (web ACL) using the procedure on this page. While updating a protection pack (web ACL), AWS WAF provides continuous coverage to the resources that you have associated with the protection pack (web ACL). 

**Production traffic risk**  
Before you deploy changes in your protection pack (web ACL) for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**To edit a protection pack (web ACL)**

1. Sign in to the new AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2-pro](https://console.aws.amazon.com/wafv2-pro). 

1. In the navigation pane, choose **Resources & protection packs (web ACLs)**.

1. Choose the protection pack (web ACL) that you want to edit. The console makes the main protection pack (web ACL) card editable, and also opens a side pane with details you can edit.

1. Edit the protection pack (web ACL) as needed. 

   The following lists the editable protection pack (web ACL) configuration components. 

   This section provides procedures for editing web ACLs through the AWS console. 

   To add or remove rules from a web ACL or change configuration settings, access the web ACL using the procedure on this page. While updating a web ACL, AWS WAF provides continuous coverage to the resources that you have associated with the web ACL. 

**Production traffic risk**  
Before you deploy changes in your web ACL for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

------
#### [ Using the standard console ]

This section provides procedures for editing web ACLs through the AWS console. 

To add or remove rules from a web ACL or change configuration settings, access the web ACL using the procedure on this page. While updating a web ACL, AWS WAF provides continuous coverage to the resources that you have associated with the web ACL. 

**Production traffic risk**  
Before you deploy changes in your web ACL for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**To edit a web ACL**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **web ACLs**.

1. Choose the name of the web ACL that you want to edit. The console takes you to the web ACL's description. 

1. Edit the web ACL as needed. Select the tabs for the configuration areas that you're interested in and edit the mutable settings. For each setting that you edit, when you choose **Save** and return to the web ACL's description page, the console saves your changes to the web ACL. 

   The following lists the tabs that contain web ACL configuration components. 
   + **Rules** tab
     + **Rules defined in the web ACL** – You can edit and manage the rules that you have defined in the web ACL, similar to how you did during web ACL creation. 
**Note**  
Don't change the names of any rules that you didn't add by hand to your web ACL. If you are using other services to manage rules for you, changing their names could remove or lessen their ability to provide the intended protections. AWS Shield Advanced and AWS Firewall Manager both can create rules in your web ACL. For information, see [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md).
**Note**  
If you change the name of a rule and you want the rule's metric name to reflect the change, you must update the metric name as well. AWS WAF doesn't automatically update the metric name for a rule when you change the rule name. You can change the metric name when you edit the rule in the console, by using the rule JSON editor. You can also change both names through the APIs and in any JSON listing that you use to define your protection pack (web ACL) or rule group.

       For information about rules and rule group settings, see [AWS WAF rules](waf-rules.md) and [AWS WAF rule groups](waf-rule-groups.md).
     + **web ACL rule capacity units used** – The current capacity usage for your web ACL. This is view only. 
     + **Default web ACL action for requests that don't match any rules**– For information about this setting, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md). 
     + **web ACL CAPTCHA and challenge configurations** – These immunity times determine how long a CAPTCHA or challenge token remains valid after it's acquired. You can only modify this setting here, after you create the web ACL. For information about these settings, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).
     + **Token domain list** – AWS WAF accepts tokens for all domains in the list and for the domain of the associated resource. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).
   + **Associated AWS resources** tab
     + **Web request inspection size limit** – Included only for web ACLs that protect CloudFront distributions. The body inspection size limit determines how much of the body component is forwarded to AWS WAF for inspection. For more information about this setting, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md).
     + **Associated AWS resources** – The list of resources that the web ACL is currently associated with and protecting. You can locate resources that are within the same Region as the web ACL and associate them to the web ACL. For more information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).
   + **Custom response bodies** tab
     + Custom response bodies that are available for use by your web ACL rules that have the action set to Block. For more information, see [Sending custom responses for Block actions](customizing-the-response-for-blocked-requests.md).
   + **Logging and metrics** tab
     + **Logging** – Logging for the traffic that the web ACL evaluates. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).
     + **Security Lake integration** – The status of any data collection that you've configured for the web ACL in Amazon Security Lake. For information, see [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
     + **Sampled requests** – Information about the rules that match web requests. For information about viewing sampled requests, see [Viewing a sample of web requests](web-acl-testing-view-sample.md).
     + **Data protection settings** – You can configure web traffic data redaction and filtering for all data that's available for the web ACL and for just the data that the AWS WAF sends to the configured web ACL logging destination. For information about data protection, see [Data protection and logging for AWS WAF protection pack (web ACL) traffic](waf-data-protection-and-logging.md). 
     + **CloudWatch metrics** – Metrics for the rules in your web ACL. For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

------

# Managing rule group behavior
<a name="web-acl-rule-group-settings"></a>

This section describes your options for modifying how you use a rule group in your protection pack (web ACL). This information applies to all rule group types. After you add a rule group to a protection pack (web ACL), you can override the actions of the individual rules in the rule group to Count or to any other valid rule action setting. You can also override the rule group's resulting action to Count, which has no effect on how the rules are evaluated inside the rule group. 

For information about these options, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md).

## Overriding rule actions in a rule group
<a name="web-acl-rule-group-rule-action-override"></a>

For each rule group in a protection pack (web ACL), you can override the contained rule's actions for some or all of the rules. 

The most common use case for this is overriding the rule actions to Count to test new or updated rules. If you have metrics enabled, you receive metrics for each rule that you override. For more information about testing, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

You can make these changes when you're adding a managed rule group to the protection pack (web ACL), and you can make them to any type of rule group when you edit the protection pack (web ACL). These instructions are for a rule group that has already been added to the protection pack (web ACL). See additional information about this option at [Rule group rule action overrides](web-acl-rule-group-override-options.md#web-acl-rule-group-override-options-rules).

------
#### [ Using the new console ]

**To override rule actions in a rule group**

1. Choose the protection pack (web ACL) that you want to edit. The console makes the main protection pack (web ACL) card editable, and also opens a side panel with details you can edit.

1. In the protection pack (web ACL) card, choose the **Edit** link next to **Rules** to open the **Manage rules **panel.

1. In the **Manage rules** section for the rule group, choose the managed rule to open its action settings.
   + **Override rule group** – Changes the rule group action to Count mode but keeps all individual rule actions unchanged.
   + **Override all rule actions** – Applies a rule action to all rules, overriding their current state.
   + **Single rule override** – Applies a rule action to an individual rule.

1. When you are finished making your changes, choose **Save rule**. 

------
#### [ Using the standard console ]

**To override rule actions in a rule group**

1. Edit the web ACL. 

1. In the web ACL page **Rules** tab, select the rule group, then choose **Edit**. 

1. In the **Rules** section for the rule group, manage the action settings as needed. 
   + **All rules** – To set an override action for all rules in the rule group, open the **Override all rule actions** dropdown and select the override action. To remove the overrides for all rules, select **Remove all overrides**. 
   + **Single rule** – To set an override action for a single rule, open the rule's dropdown and select the override action. To remove an override for a rule, open the rule's dropdown and select **Remove override**.

1. When you are finished making your changes, choose **Save rule**. The rule action and override action settings are listed in the rule group page. 

------

The following example JSON listing shows a rule group declaration inside a protection pack (web ACL) that overrides the rule actions to Count for the rules `CategoryVerifiedSearchEngine` and `CategoryVerifiedSocialMedia`. In the JSON, you override all rule actions by providing a `RuleActionOverrides` entry for each individual rule.

```
{
    "Name": "AWS-AWSBotControl-Example",
   "Priority": 5, 
   "Statement": {
    "ManagedRuleGroupStatement": {
        "VendorName": "AWS",
        "Name": "AWSManagedRulesBotControlRuleSet",
        "RuleActionOverrides": [
          {
            "ActionToUse": {
              "Count": {}
            },
            "Name": "CategoryVerifiedSearchEngine"
          },
          {
            "ActionToUse": {
              "Count": {}
            },
            "Name": "CategoryVerifiedSocialMedia"
          }
        ],
        "ExcludedRules": []
    },
   "VisibilityConfig": {
       "SampledRequestsEnabled": true,
       "CloudWatchMetricsEnabled": true,
       "MetricName": "AWS-AWSBotControl-Example"
   }
}
```

## Overriding a rule group's evaluation result to Count
<a name="web-acl-rule-group-action-override"></a>

You can override the action that results from a rule group evaluation, without altering how the rules in the rule group are configured or evaluated. This option is not commonly used. If any rule in the rule group results in a match, this override sets the resulting action from the rule group to Count.

**Note**  
This is an uncommon use case. Most action overrides are done at the rule level, inside the rule group, as described in [Overriding rule actions in a rule group](#web-acl-rule-group-rule-action-override).

You can override the rule group's resulting action in the protection pack (web ACL) when you add or edit the rule group. In the console, open the rule group's **Override rule group action - optional** pane and enable the override. In the JSON set `OverrideAction` in the rule group statement, as shown in the following example listing: 

```
{
   "Name": "AWS-AWSBotControl-Example",
   "Priority": 5,  
   "Statement": {
    "ManagedRuleGroupStatement": {
     "VendorName": "AWS",
     "Name": "AWSManagedRulesBotControlRuleSet"
     }
   },
    "OverrideAction": {
       "Count": {}
    },
   "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWS-AWSBotControl-Example"
   }
}
```

# Associating or disassociating protection with an AWS resource
<a name="web-acl-associating-aws-resource"></a>

You can use AWS WAF to create the following associations between protection packs (web ACLs) and your resources: 
+ Associate a regional protection pack (web ACL) with any of the regional resources listed below. For this option, the protection pack (web ACL) must be in the same region as your resource. 
  + Amazon API Gateway REST API
  + Application Load Balancer
  + AWS AppSync GraphQL API
  + Amazon Cognito user pool
  + AWS App Runner service
  + AWS Verified Access instance
  + AWS Amplify
+ Associate a global protection pack (web ACL) with a Amazon CloudFront distribution. The global protection pack (web ACL) will have a hard-coded Region of US East (N. Virginia) Region.

You can also associate a protection pack (web ACL) with a CloudFront distribution when you create or update the distribution itself. For information, see [Using AWS WAF to Control Access to Your Content](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-awswaf.html) in the *Amazon CloudFront Developer Guide*.

**Restrictions on multiple associations**  
You can associate a single protection pack (web ACL) with one or more AWS resources, according to the following restrictions:
+ You can associate each AWS resource with only one protection pack (web ACL). The relationship between protection pack (web ACL) and AWS resources is one-to-many. 
+ You can associate a protection pack (web ACL) with one or more CloudFront distributions. You cannot associate a protection pack (web ACL) that you have associated with a CloudFront distribution with any other AWS resource type.

**Additional restrictions**  
The following additional restrictions apply to protection pack (web ACL) associations: 
+ You can only associate a protection pack (web ACL) to an Application Load Balancer within AWS Regions. For example, you cannot associate a protection pack (web ACL) to an Application Load Balancer that is on AWS Outposts.
+ You can't associate an Amazon Cognito user pool with a protection pack (web ACL) that uses the AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group `AWSManagedRulesACFPRuleSet` or the AWS WAF Fraud Control account takeover prevention (ATP) managed rule group `AWSManagedRulesATPRuleSet`. For information about account creation fraud prevention, see [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md). For information about account takeover prevention, see [AWS WAF Fraud Control account takeover prevention (ATP)](waf-atp.md). 

**Production traffic risk**  
Before you deploy your protection pack (web ACL) for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

# Associating protection with an AWS resource
<a name="web-acl-associating"></a>

------
#### [ Using the new console ]

1. Choose the protection pack (web ACL) that you want to edit. The console makes the main protection pack (web ACL) card editable, and also opens a side panel with details you can edit.

1. In the protection pack (web ACL) card, choose the **Edit** link next to **Resources** to open the **Manage resources **panel.

1. In the **Manage resources** section for the rule group, choose **Add regional resources** or **Add global resources**.

1. Choose resources and then choose **Add**.

------
#### [ Using the standard console ]

To associate a web ACL with an AWS resource, perform the following procedure.

**To associate a web ACL with an AWS resource**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **web ACLs**.

1. Choose the name of the web ACL that you want to associate with a resource. The console takes you to the web ACL's description, where you can edit it.

1. On the **Associated AWS resources** tab, choose **Add AWS resources**.

1. When prompted, choose the resource type, select the radio button next to the resource that you want to associate, and then choose **Add**. 

------

# Disassociating a protection from an AWS resource
<a name="web-acl-dissociating-aws-resource"></a>

------
#### [ Using the new console ]

1. Choose the protection pack (web ACL) that you want to edit. The console makes the main protection pack (web ACL) card editable, and also opens a side panel with details you can edit.

1. In the protection pack (web ACL) card, choose the **Edit** link next to **Resources** to open the **Manage resources ** panel.

1. In the **Manage resources** section for the rule group, choose the resource you want to disassociate, and then choose **Disassociate**.
**Note**  
You must disassociate one resource at a time. Do not choose multiple resources. 

1. In the confirmation page, type "disassociate", and then choose **Disassociate**.

------
#### [ Using the standard console ]

To dissociate a web ACL from an AWS resource, perform the following procedure.

**To disassociate a web ACL from an AWS resource**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **web ACLs**.

1. Choose the name of the web ACL that you want to disassociate from your resource. The console takes you to the web ACL's description, where you can edit it.

1. On the **Associated AWS resources** tab, select the resource that you want to disassociate this web ACL from. 
**Note**  
You must disassociate one resource at a time. Do not choose multiple resources. 
**Note**  
When you choose to associate an Application Load Balancer with your webACL, **Resource-level DDoS protection** is enabled. For more information, see [AWS WAF Distributed Denial of Service (DDoS) prevention](waf-anti-ddos.md).

1. Choose **Disassociate**. The console opens a confirmation dialogue. Confirm your choice to disassociate the web ACL from the AWS resource. 

------

# Using protection packs (web ACLs) with rules and rule groups in AWS WAF
<a name="web-acl-processing"></a>

This section introduces how protection packs (web ACLs) and web ACLs work with rules and rule groups.

The way a protection pack (web ACL) handles a web request depends on the following: 
+ The numeric priority settings of the rules in the protection pack (web ACL) and inside rule groups
+ The action settings on the rules and protection pack (web ACL)
+ Any overrides that you place on the rules in the rule groups that you add

For a list of the rule action settings, see [Using rule actions in AWS WAF](waf-rule-action.md). 

You can customize request and response handling in your rule action settings and default protection pack (web ACL) action settings. For information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

**Topics**
+ [

# Setting rule priority
](web-acl-processing-order.md)
+ [

# How AWS WAF handles rule and rule group actions
](web-acl-rule-actions.md)
+ [

# Overriding rule group actions in AWS WAF
](web-acl-rule-group-override-options.md)

# Setting rule priority
<a name="web-acl-processing-order"></a>

This section explains how AWS WAF uses numeric priority settings to set the evaluation order for rules.

In a protection pack (web ACL) and inside any rule group, you determine the evaluation order of the rules using numeric priority settings. You must give each rule in a protection pack (web ACL) a unique priority setting within that protection pack (web ACL), and you must give each rule in a rule group a unique priority setting within that rule group. 

**Note**  
When you manage rule groups, protection packs (web ACLs) through the console, AWS WAF assigns unique numeric priority settings for you based on the order of the rules in the list. AWS WAF assigns the lowest numeric priority to the rule at the top of the list, and the highest numeric priority to the rule at the bottom. 

When AWS WAF evaluates any rule group, protection pack (web ACL) against a web request, it evaluates the rules from the lowest numeric priority setting on up until it either finds a match that terminates the evaluation or exhausts all of the rules.

For example, say you have the following rules and rule groups in your protection pack (web ACL), prioritized as shown:
+ Rule1 – priority 0
+ RuleGroupA – priority 100
  + RuleA1 – priority 10,000
  + RuleA2 – priority 20,000
+ Rule2 – priority 200
+ RuleGroupB – priority 300
  + RuleB1 – priority 0
  + RuleB2 – priority 1

AWS WAF would evaluate the rules for this protection pack (web ACL) in the following order:
+ Rule1
+ RuleGroupA RuleA1
+ RuleGroupA RuleA2
+ Rule2
+ RuleGroupB RuleB1
+ RuleGroupB RuleB2

# How AWS WAF handles rule and rule group actions
<a name="web-acl-rule-actions"></a>

This section explains how AWS WAF uses rules and rule groups to handle actions.

When you configure your rules and rule groups, you choose how you want AWS WAF to handle matching web requests: 
+ **Allow and Block are terminating actions** – Allow and Block actions stop all other processing of the protection pack (web ACL) on the matching web request. If a rule in a protection pack (web ACL) finds a match for a request and the rule action is Allow or Block, that match determines the final disposition of the web request for the protection pack (web ACL). AWS WAF doesn't process any other rules in the protection pack (web ACL) that come after the matching one. This is true for rules that you add directly to the protection pack (web ACL) and rules that are inside an added rule group. With the Block action, the protected resource doesn't receive or process the web request.
+ **Count is a non-terminating action** – When a rule with a Count action matches a request, AWS WAF counts the request, then continues processing the rules that follow in the protection pack (web ACL) rule set. 
+ **CAPTCHA and Challenge can be non-terminating or terminating actions** – When a rule with one of these actions matches a request, AWS WAF checks its token status. If the request has a valid token, AWS WAF treats the match similar to a Count match, and then continues processing the rules that follow in the protection pack (web ACL) rule set. If the request doesn't have a valid token, AWS WAF terminates the evaluation and sends the client a CAPTCHA puzzle or silent background client session challenge to solve. 

If the rule evaluation doesn't result in any terminating action, then AWS WAF applies the protection pack (web ACL) default action to the request. For information, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md).

In your protection pack (web ACL), you can override the action settings for rules inside a rule group and you can override the action that's returned by a rule group. For information, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 

**Interaction between actions and priority settings**  
The actions that AWS WAF applies to a web request are affected by the numeric priority settings of the rules in the protection pack (web ACL). For example, say that your protection pack (web ACL) has a rule with Allow action and a numeric priority of 50 and another rule with Count action and a numeric priority of 100. AWS WAF evaluates the rules in a protection pack (web ACL) in the order of their priority, starting from the lowest setting, so it will evaluate the allow rule before the count rule. A web request that matches both rules will match the allow rule first. Since Allow is a terminating action, AWS WAF will stop the evaluation at this match and won't evaluate the request against the count rule. 
+ If you only want to include requests that don't match the allow rule in your count rule metrics, then the priority settings of the rules would work. 
+ On the other hand, if you want count metrics from the count rule even for requests that match the allow rule, you'd need to give the count rule a lower numeric priority setting than the allow rule, so that it runs first. 

For more information about priority settings, see [Setting rule priority](web-acl-processing-order.md). 

# Overriding rule group actions in AWS WAF
<a name="web-acl-rule-group-override-options"></a>

This section explains how to override rule group actions.

When you add a rule group to your protection pack (web ACL), you can override the actions it takes on matching web requests. Overriding the actions for a rule group inside your protection pack (web ACL) configuration doesn't alter the rule group itself. It only alters how AWS WAF uses the rule group in the context of the protection pack (web ACL). 

## Rule group rule action overrides
<a name="web-acl-rule-group-override-options-rules"></a>

You can override the actions of the rules inside a rule group to any valid rule action. When you do this, matching requests are handled exactly as if the configured rule's action were the override setting. 

**Note**  
Rule actions can be terminating or non-terminating. A terminating action stops the protection pack (web ACL) evaluation of the request and either lets it continue to your protected application or blocks it. 

Here are the rule action options: 
+ **Allow** – AWS WAF allows the request to be forwarded to the protected AWS resource for processing and response. This is a terminating action. In rules that you define, you can insert custom headers into the request before forwarding it to the protected resource.
+ **Block** – AWS WAF blocks the request. This is a terminating action. By default, your protected AWS resource responds with an HTTP `403 (Forbidden)` status code. In rules that you define, you can customize the response. When AWS WAF blocks a request, the Block action settings determine the response that the protected resource sends back to the client. 
+ **Count** – AWS WAF counts the request but does not determine whether to allow it or block it. This is a non-terminating action. AWS WAF continues processing the remaining rules in the protection pack (web ACL). In rules that you define, you can insert custom headers into the request and you can add labels that other rules can match against.
+ **CAPTCHA and Challenge** – AWS WAF uses CAPTCHA puzzles and silent challenges to verify that the request is not coming from a bot, and AWS WAF uses tokens to track recent successful client responses. 

  CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. 
**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

  These rule actions can be terminating or non-terminating, depending on the state of the token in the request: 
  + **Non-terminating for valid, unexpired token** – If the token is valid and unexpired according to the configured CAPTCHA or challenge immunity time, AWS WAF handles the request similar to the Count action. AWS WAF continues to inspect the web request based on the remaining rules in the protection pack (web ACL). Similar to the Count configuration, in rules that you define, you can optionally configure these actions with custom headers to insert into the request, and you can add labels that other rules can match against. 
  + **Terminating with blocked request for invalid or expired token** – If the token is invalid or the indicated timestamp is expired, AWS WAF terminates the inspection of the web request and blocks the request, similar to the Block action. AWS WAF then responds to the client with a custom response code. For CAPTCHA, if the request contents indicate that the client browser can handle it, AWS WAF sends a CAPTCHA puzzle in a JavaScript interstitial, which is designed to distinguish human clients from bots. For the Challenge action, AWS WAF sends a JavaScript interstitial with a silent challenge that is designed to distinguish normal browsers from sessions that are being run by bots. 

  For additional information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

For information about how to use this option, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

### Overriding the rule action to Count
<a name="web-acl-rule-group-override-to-count"></a>

The most common use case for rule action overrides is overriding some or all of the rule actions to Count, to test and monitor a rule group's behavior before putting it into production. 

You can also use this to troubleshoot a rule group that's generating false positives. False positives occur when a rule group blocks traffic that you aren't expecting it to block. If you identify a rule within a rule group that would block requests that you want to allow through, you can keep the count action override on that rule, to exclude it from acting on your requests.

For more information about using the rule action override in testing, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

### JSON listing: `RuleActionOverrides` replaces `ExcludedRules`
<a name="web-acl-rule-group-override-replaces-exclude"></a>

If you set rule group rule actions to Count in your protection pack (web ACL) configuration before October 27, 2022, AWS WAF saved your overrides in the protection pack (web ACL) JSON as `ExcludedRules`. Now, the JSON setting for overriding a rule to Count is in the `RuleActionOverrides` settings. 

We recommend that you update all of your `ExcludedRules` settings in your JSON listings to `RuleActionOverrides` settings with the action set to Count. The API accepts either setting, but you'll get consistency in your JSON listings, between your console work and your API work, if you only use the new `RuleActionOverrides` setting. 

**Note**  
In the AWS WAF console, the protection pack (web ACL) **Sampled requests** tab doesn't show samples for rules with the old setting. For more information, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

When you use the AWS WAF console to edit the existing rule group settings, the console automatically converts any `ExcludedRules` settings in the JSON to `RuleActionOverrides` settings, with the override action set to Count. 
+ Current setting example: 

  ```
         "ManagedRuleGroupStatement": {
            "VendorName": "AWS",
            "Name": "AWSManagedRulesAdminProtectionRuleSet",
            "RuleActionOverrides": [
              {
                "Name": "AdminProtection_URIPATH",
                "ActionToUse": {
                  "Count": {}
                }
              }
            ]
  ```
+ Old setting example: 

  ```
  OLD SETTING
         "ManagedRuleGroupStatement": {
            "VendorName": "AWS",
            "Name": "AWSManagedRulesAdminProtectionRuleSet",
            "ExcludedRules": [
              {
                "Name": "AdminProtection_URIPATH"
              }
            ]
  OLD SETTING
  ```

## Rule group return action override to Count
<a name="web-acl-rule-group-override-options-rule-group"></a>

You can override the action that the rule group returns, setting it to Count. 

**Note**  
This is not a good option for testing the rules in a rule group, because it doesn't alter how AWS WAF evaluates the rule group itself. It only affects how AWS WAF handles results that are returned to the protection pack (web ACL) from the rule group evaluation. If you want to test the rules in a rule group, use the option described in the preceding section, [Rule group rule action overrides](#web-acl-rule-group-override-options-rules).

When you override the rule group action to Count, AWS WAF processes the rule group evaluation normally. 

If no rules in the rule group match or if all matching rules have a Count action, then this override has no effect on the processing of the rule group or the protection pack (web ACL).

The first rule in the rule group that matches a web request and that has a terminating rule action causes AWS WAF to stop evaluating the rule group and return the terminating action result to the protection pack (web ACL) evaluation level. At this point, in the protection pack (web ACL) evaluation, this override takes effect. AWS WAF overrides the terminating action so that the result of the rule group evaluation is only a Count action. AWS WAF then continues processing the rest of the rules in the protection pack (web ACL).

For information about how to use this option, see [Overriding a rule group's evaluation result to Count](web-acl-rule-group-settings.md#web-acl-rule-group-action-override).

# Setting the protection pack (web ACL) default action in AWS WAF
<a name="web-acl-default-action"></a>

This section explains how protection pack (web ACL) default actions work.

When you create and configure a protection pack (web ACL), you must set the protection pack (web ACL) default action. AWS WAF applies this action to any web request that makes it through all of the protection pack (web ACL)'s rule evaluations without having a terminating action applied to it. A terminating action stops the protection pack (web ACL) evaluation of the request and either lets it continue to your protected application or blocks it. For information about rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md).

The protection pack (web ACL) default action must determine the final disposition of the web request, so it's a terminating action: 
+ **Allow** – If you want to allow most users to access your website, but you want to block access to attackers whose requests originate from specified IP addresses, or whose requests appear to contain malicious SQL code or specified values, choose Allow for the default action. Then, when you add rules to your protection pack (web ACL), add rules that identify and block the specific requests that you want to block. With this action, you can insert custom headers into the request before forwarding it to the protected resource.
+ **Block** – If you want to prevent most users from accessing your website, but you want to allow access to users whose requests originate from specified IP addresses, or whose requests contain specified values, choose Block for the default action. Then when you add rules to your protection pack (web ACL), add rules that identify and allow the specific requests that you want to allow in. By default, for the Block action, the AWS resource responds with an HTTP `403 (Forbidden)` status code, but you can customize the response. 

For information about customizing requests and responses, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

Your configuration of your own rules and rule groups depends in part on whether you want to allow or block most web requests. For example, if you want to *allow* most requests, you would set the protection pack (web ACL) default action to Allow, and then add rules that identify web requests that you want to *block*, such as the following:
+ Requests that originate from IP addresses that are making an unreasonable number of requests
+ Requests that originate from countries that either you don't do business in or are the frequent source of attacks
+ Requests that include fake values in the `User-agent` header
+ Requests that appear to include malicious SQL code

Managed rule group rules usually use the Block action, but not all do. For examples, some rules used for Bot Control use the CAPTCHA and Challenge action settings. For information about managed rule groups, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md).

# Considerations for managing body inspection in AWS WAF
<a name="web-acl-setting-body-inspection-limit"></a>

The body inspection size limit is the maximum request body size that AWS WAF can inspect. When a web request body is larger than the limit, the underlying host service only forwards the contents that are within the limit to AWS WAF for inspection. 
+ For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB (8,192 bytes).
+ For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB (16,384 bytes), and you can increase the limit for any of the resource types by increments of 16 KB, up to 64 KB. The setting options are 16 KB, 32 KB, 48 KB, and 64 KB. 

**Important**  
AWS WAF does not support request body inspection rules for gRPC traffic. If you enabled these rules on the protection pack (web ACL) for a CloudFront distribution or Application Load Balancer, any request that uses gRPC will ignore the request body inspection rules. All other AWS WAF rules will still apply. For more information, see [Enable AWS WAF for distributions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/WAF-one-click.html) in the *Amazon CloudFront Developer Guide*. 

**Oversize body handling**  
If your web traffic includes bodies that are larger than the limit, your configured oversize handling will apply. For information about the options for oversize handling, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

**Pricing considerations for increasing the limit setting**  
AWS WAF charges a base rate for inspecting traffic that's within the default limit for the resource type. 

For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access resources, if you increase the limit setting, the traffic that AWS WAF can inspect includes body sizes up to your new limit. You're charged extra only for the inspection of requests that have body sizes larger than the default 16 KB. For more information about pricing, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Options for modifying the body inspection size limit**  
You can configure the body inspection size limit for CloudFront, API Gateway, Amazon Cognito, App Runner, or Verified Access resources. 

When you create or edit a protection pack (web ACL), you can modify the body inspection size limits in the resource association configuration. For the API, see the protection pack (web ACL)'s association configuration at [AssociationConfig](https://docs.aws.amazon.com/waf/latest/APIReference/API_AssociationConfig.html). For the console, see the configuration on the page where you specify the protection pack (web ACL)'s associated resources. For guidance on the console configuration, see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md). 

# Configuring CAPTCHA, challenge, and tokens in AWS WAF
<a name="web-acl-captcha-challenge-token-domains"></a>

You can configure options in your protection pack (web ACL) for the rules that use the CAPTCHA or Challenge rule actions and for the application integration SDKs that manage silent client challenges for AWS WAF managed protections. 

These features mitigate bot activity by challenging end users with CAPTCHA puzzles and by presenting client sessions with silent challenges. When the client responds successfully, AWS WAF provides a token for them to use in their web request, timestamped with the last successful puzzle and challenge responses. For more information, see [Intelligent threat mitigation in AWS WAF](waf-managed-protections.md).

In your protection pack (web ACL) configuration, you can configure how AWS WAF manages these tokens: 
+ **CAPTCHA and challenge immunity times** – These specify how long a CAPTCHA or challenge timestamp remains valid. The protection pack (web ACL) settings are inherited by all rules that don't have their own immunity time settings configured and also by the application integration SDKs. For more information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).
+ **Token domains** – By default, AWS WAF accepts tokens only for the domain of the resource that the protection pack (web ACL) is associated with. If you configure a token domain list, AWS WAF accepts tokens for all domains in the list and for the domain of the associated resource. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).

# Viewing web traffic metrics in AWS WAF
<a name="web-acl-working-with"></a>

This section explains how to access summaries of web traffic metrics.

For any protection pack (web ACL) that you're using, you can access summaries of the web traffic metrics on the protection pack (web ACL)'s page in the AWS WAF console, under the **Traffic overview** tab. The console dashboards provide near real-time summaries of the Amazon CloudWatch metrics that AWS WAF collects when it evaluates your application web traffic. For more information about the dashboards, see [Traffic overview dashboards for protection packs (web ACLs)](web-acl-dashboards.md). For additional information about monitoring your protection pack (web ACL)'s traffic, see [Monitoring and tuning your AWS WAF protections](web-acl-testing-activities.md).

# Deleting a protection pack (web ACL)
<a name="web-acl-deleting"></a>

This section provides procedures for deleting protection packs (web ACLs) through the AWS console. 

**Important**  
Deleting a protection pack (web ACL) is permanent and can't be undone.

To delete a protection pack (web ACL), you first disassociate all AWS resources from the protection pack (web ACL). Perform the following procedure.

------
#### [ Using the new console ]

1. Sign in to the new AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2-pro](https://console.aws.amazon.com/wafv2-pro). 

1. In the navigation pane, choose **Resources & protection packs (web ACLs)**.

1. In the protection pack (web ACL) card, choose the **Edit** link next to **Resources** to open the **Manage resources ** panel.

1. In the **Manage resources** section for the rule group, choose the resource you want to disassociate, and then choose **Disassociate**.
**Note**  
You must disassociate one resource at a time. Do not choose multiple resources. 

1. In the confirmation page, type "disassociate", and then choose **Disassociate**. Repeat to disassociate each resource in the protection pack (web ACL).

1. Choose the protection pack (web ACL) that you want to delete. The console makes the main protection pack (web ACL) card editable, and also opens a side panel with details you can edit.

1. In the details panel, choose the trash can icon.

1. In the confirmation page, type "delete" and then choose **Delete**.

------
#### [ Using the standard console ]

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **web ACLs**.

1. Select the name of the web ACL that you want to delete. The console takes you to the web ACL's description, where you can edit it.
**Note**  
If you don't see the web ACL that you want to delete, make sure the Region selection inside the web ACLs section is correct. Any web ACLs that protect Amazon CloudFront distributions are in **Global (CloudFront)**.

1. On the **Associated AWS resources** tab, for each associated resource, select the radio button next to the resource name and then choose **Disassociate**. This disassociates the protection pack (web ACL) from your AWS resources. 

1. In the navigation pane, choose **web ACLs**.

1. Select the radio button next to the web ACL that you are deleting, and then choose **Delete**.

------

# AWS WAF rules
<a name="waf-rules"></a>

This section explains what an AWS WAF rule is and how it works.

An AWS WAF rule defines how to inspect HTTP(S) web requests and the action to take on a request when it matches the inspection criteria. You define rules only in the context of a rule group or protection pack (web ACL). 

Rules don't exist in AWS WAF on their own. They aren't AWS resources, and they don't have Amazon Resource Names (ARNs). You can access a rule by name in the rule group or protection pack (web ACL) where it's defined. You can manage rules and copy them to other protection packs (web ACLs) by using the JSON view of the rule group or protection pack (web ACL) that contains the rule. You can also manage them through the AWS WAF console rule builder, which is available for protection packs (web ACLs) and rule groups.

**Rule name**  
Each rule requires a name. Avoid names that start with `AWS` and names that are used for rule groups or rules that are managed for you by other services. See [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md). 

**Note**  
If you change the name of a rule and you want the rule's metric name to reflect the change, you must update the metric name as well. AWS WAF doesn't automatically update the metric name for a rule when you change the rule name. You can change the metric name when you edit the rule in the console, by using the rule JSON editor. You can also change both names through the APIs and in any JSON listing that you use to define your protection pack (web ACL) or rule group.

**Rule statement**  
Each rule also requires a rule statement that defines how the rule inspects web requests. The rule statement might contain other, nested statements at any depth, depending on the rule and statement type. Some rule statements take sets of criteria. For example, you can specify up to 10,000 IP addresses or IP address ranges for an IP set match rule.

You can define rules that inspect for criteria like the following: 
+ Scripts that are likely to be malicious. Attackers embed scripts that can exploit vulnerabilities in web applications. This is known as cross-site scripting (XSS).
+ IP addresses or address ranges that requests originate from.
+ Country or geographical location that requests originate from.
+ Length of a specified part of the request, such as the query string.
+ SQL code that is likely to be malicious. Attackers try to extract data from your database by embedding malicious SQL code in a web request. This is known as SQL injection.
+ Strings that appear in the request, for example, values that appear in the `User-Agent` header or text strings that appear in the query string. You can also use regular expressions (regex) to specify these strings.
+ Labels that prior rules in the protection pack (web ACL) have added to the request.

In addition to statements with web request inspection criteria, like the ones in the preceding list, AWS WAF supports logical statements for `AND`, `OR`, and `NOT` that you use to combine statements in a rule. 

For example, based on recent requests that you've seen from an attacker, you might create a rule with a logical `AND` statement that combines the following nested statements: 
+ The requests come from 192.0.2.44.
+ They contain the value `BadBot` in the `User-Agent` header.
+ They appear to include SQL-like code in the query string.

In this case, the web request needs to match all of the statements to result in a match for the top-level `AND`. 

**Topics**
+ [

# Using rule actions in AWS WAF
](waf-rule-action.md)
+ [

# Using rule statements in AWS WAF
](waf-rule-statements.md)
+ [

# Using match rule statements in AWS WAF
](waf-rule-statements-match.md)
+ [

# Using logical rule statements in AWS WAF
](waf-rule-statements-logical.md)
+ [

# Using rate-based rule statements in AWS WAF
](waf-rule-statement-type-rate-based.md)
+ [

# Using rule group rule statements in AWS WAF
](waf-rule-statements-rule-group.md)

# Using rule actions in AWS WAF
<a name="waf-rule-action"></a>

This section explains how rule actions work.

The rule action tells AWS WAF what to do with a web request when it matches the criteria defined in the rule. You can optionally add custom behavior to each rule action. 

**Note**  
Rule actions can be terminating or non-terminating. A terminating action stops the protection pack (web ACL) evaluation of the request and either lets it continue to your protected application or blocks it. 

Here are the rule action options: 
+ **Allow** – AWS WAF allows the request to be forwarded to the protected AWS resource for processing and response. This is a terminating action. In rules that you define, you can insert custom headers into the request before forwarding it to the protected resource.
+ **Block** – AWS WAF blocks the request. This is a terminating action. By default, your protected AWS resource responds with an HTTP `403 (Forbidden)` status code. In rules that you define, you can customize the response. When AWS WAF blocks a request, the Block action settings determine the response that the protected resource sends back to the client. 
+ **Count** – AWS WAF counts the request but does not determine whether to allow it or block it. This is a non-terminating action. AWS WAF continues processing the remaining rules in the protection pack (web ACL). In rules that you define, you can insert custom headers into the request and you can add labels that other rules can match against.
+ **CAPTCHA and Challenge** – AWS WAF uses CAPTCHA puzzles and silent challenges to verify that the request is not coming from a bot, and AWS WAF uses tokens to track recent successful client responses. 

  CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. 
**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

  These rule actions can be terminating or non-terminating, depending on the state of the token in the request: 
  + **Non-terminating for valid, unexpired token** – If the token is valid and unexpired according to the configured CAPTCHA or challenge immunity time, AWS WAF handles the request similar to the Count action. AWS WAF continues to inspect the web request based on the remaining rules in the protection pack (web ACL). Similar to the Count configuration, in rules that you define, you can optionally configure these actions with custom headers to insert into the request, and you can add labels that other rules can match against. 
  + **Terminating with blocked request for invalid or expired token** – If the token is invalid or the indicated timestamp is expired, AWS WAF terminates the inspection of the web request and blocks the request, similar to the Block action. AWS WAF then responds to the client with a custom response code. For CAPTCHA, if the request contents indicate that the client browser can handle it, AWS WAF sends a CAPTCHA puzzle in a JavaScript interstitial, which is designed to distinguish human clients from bots. For the Challenge action, AWS WAF sends a JavaScript interstitial with a silent challenge that is designed to distinguish normal browsers from sessions that are being run by bots. 

  For additional information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

For information about customizing requests and responses, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

For information about adding labels to matching requests, see [Web request labeling in AWS WAF](waf-labels.md).

For information about how protection pack (web ACL) and rule settings interact, see [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md). 

# Using rule statements in AWS WAF
<a name="waf-rule-statements"></a>

This section explains how rule statements work.

Rule statements are the part of a rule that tells AWS WAF how to inspect a web request. When AWS WAF finds the inspection criteria in a web request, we say that the web request matches the statement. Every rule statement specifies what to look for and how, according to the statement type. 

Every rule in AWS WAF has a single top-level rule statement, which can contain other statements. Rule statements can be very simple. For example, you could have a statement that provides a set of originating countries to inspect your web requests for or you could have a rule statement in a protection pack (web ACL) that just references a rule group. Rule statements can also be very complex. For example, you could have a statement that combines many other statements with logical AND, OR, and NOT statements. 

For most rules, you can add custom AWS WAF labeling to matching requests. The rules in the AWS Managed Rules rule groups add labels to matching requests. The labels that a rule adds provide information about the request to rules that are evaluated later in the protection pack (web ACL) and also in AWS WAF logs and metrics. For information about labeling, see [Web request labeling in AWS WAF](waf-labels.md) and [Label match rule statement](waf-rule-statement-type-label-match.md).

**Nesting rule statements**  
AWS WAF supports nesting for many rule statements, but not for all. For example, you can't nest a rule group statement inside of another statement. You need to use nesting for some scenarios, such as scope-down statements and logical statements. The rule statement lists and rule details that follow describe the nesting capabilities and requirements for each category and rule.

The visual editor for rules in the console supports only one level of nesting for rule statements. For example, you can nest many types of statements inside a logical AND or OR rule, but you can't nest another AND or OR rule, because that requires a second level of nesting. To implement multiple levels of nesting, provide the rule definition in JSON, either through the JSON rule editor in the console or through the APIs. 

**Topics**
+ [

# Adjusting rule statement settings in AWS WAF
](waf-rule-statement-fields.md)
+ [

# Using scope-down statements in AWS WAF
](waf-rule-scope-down-statements.md)
+ [

# Referencing reusable entities in AWS WAF
](waf-rule-statement-reusable-entities.md)

# Adjusting rule statement settings in AWS WAF
<a name="waf-rule-statement-fields"></a>

This section describes the settings that you can specify in rule statements that inspect a component of the web request. For information on usage, see the individual rule statements at [Using match rule statements in AWS WAF](waf-rule-statements-match.md). 

A subset of these web request components can also be used in rate-based rules, as custom request aggregation keys. For information, see [Aggregating rate-based rules in AWS WAF](waf-rule-statement-type-rate-based-aggregation-options.md).

For the request component settings, you specify the component type itself, and any additional options, depending on the component type. For example, when you inspect a component type that contains text, you can apply text transformations to it before inspecting it. 

**Note**  
Unless otherwise noted, if a web request doesn't have the request component that's specified in the rule statement, AWS WAF evaluates the request as not matching the rule criteria.

**Contents**
+ [

# Request components in AWS WAF
](waf-rule-statement-fields-list.md)
  + [

## HTTP method
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-http-method)
  + [

## Single header
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-header)
  + [

## All headers
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-headers)
  + [

## Header order
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-header-order)
  + [

## Cookies
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-cookies)
  + [

## URI fragment
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-fragment)
  + [

## URI path
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-path)
  + [

## JA3 fingerprint
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja3-fingerprint)
  + [

## JA4 fingerprint
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja4-fingerprint)
  + [

## Query string
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-query-string)
  + [

## Single query parameter
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-query-param)
  + [

## All query parameters
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-all-query-params)
  + [

## Body
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-body)
  + [

## JSON body
](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-json-body)
+ [

# Using forwarded IP addresses in AWS WAF
](waf-rule-statement-forwarded-ip-address.md)
+ [

# Inspecting HTTP/2 pseudo headers in AWS WAF
](waf-rule-statement-request-components-for-http2-pseudo-headers.md)
+ [

# Using text transformations in AWS WAF
](waf-rule-statement-transformation.md)

# Request components in AWS WAF
<a name="waf-rule-statement-fields-list"></a>

This section describes the components of the web request that you can specify for inspection. You specify the request component for match rule statements that look for patterns inside the web request. These types of statements include string match, regex match, size constraint, and SQL injection attack statements. For information on how to use these request component settings, see the individual rule statements at [Using match rule statements in AWS WAF](waf-rule-statements-match.md)

Unless otherwise noted, if a web request doesn't have the request component that's specified in the rule statement, AWS WAF evaluates the request as not matching the rule criteria.

**Note**  
You specify a single request component for each rule statement that requires it. To inspect more than one component of a request, create a rule statement for each component. 

The AWS WAF console and API documentation provide guidance for the request component settings in the following locations: 
+ **Rule builder** on the console – In the **Statement** settings for a regular rule type, choose the component that you want to inspect in the **Inspect** dialogue under **Request components**.
+ **API statement contents** – `FieldToMatch`

The rest of this section describes the options for the part of the web request to inspect. 

**Topics**
+ [

## HTTP method
](#waf-rule-statement-request-component-http-method)
+ [

## Single header
](#waf-rule-statement-request-component-single-header)
+ [

## All headers
](#waf-rule-statement-request-component-headers)
+ [

## Header order
](#waf-rule-statement-request-component-header-order)
+ [

## Cookies
](#waf-rule-statement-request-component-cookies)
+ [

## URI fragment
](#waf-rule-statement-request-component-uri-fragment)
+ [

## URI path
](#waf-rule-statement-request-component-uri-path)
+ [

## JA3 fingerprint
](#waf-rule-statement-request-component-ja3-fingerprint)
+ [

## JA4 fingerprint
](#waf-rule-statement-request-component-ja4-fingerprint)
+ [

## Query string
](#waf-rule-statement-request-component-query-string)
+ [

## Single query parameter
](#waf-rule-statement-request-component-single-query-param)
+ [

## All query parameters
](#waf-rule-statement-request-component-all-query-params)
+ [

## Body
](#waf-rule-statement-request-component-body)
+ [

## JSON body
](#waf-rule-statement-request-component-json-body)

## HTTP method
<a name="waf-rule-statement-request-component-http-method"></a>

Inspects the HTTP method for the request. The HTTP method indicates the type of operation that the web request is asking your protected resource to perform, such as `POST` or `GET`. 

## Single header
<a name="waf-rule-statement-request-component-single-header"></a>

Inspects a single named header in the request. 

For this option, you specify the header name, for example, `User-Agent` or `Referer`. The string match for the name is not case sensitive and is performed after trimming leading and trailing spaces from both the request header and the rule.

## All headers
<a name="waf-rule-statement-request-component-headers"></a>

Inspects all of the request headers, including cookies. You can apply a filter to inspect a subset of all headers. 

For this option, you provide the following specifications: 
+ **Match patterns** – The filter to use to obtain a subset of headers for inspection. AWS WAF looks for these patterns in the headers keys. 

  The match patterns setting can be one of the following: 
  + **All** – Match all keys. Evaluate the rule inspection criteria for all headers. 
  + **Excluded headers** – Inspect only the headers whose keys don't match any of the strings that you specify here. The string match for a key is not case sensitive. The matching is performed after trimming the leading and trailing spaces from request header and the match rule.
  + **Included headers** – Inspect only the headers that have a key that matches one of the strings that you specify here. The string match for a key is not case sensitive. The matching is performed after trimming the leading and trailing spaces from request header and the match rule.
+ **Match scope** – The parts of the headers that AWS WAF should inspect with the rule inspection criteria. You can specify **Keys**, **Values**, or **All** to inspect both keys and values for a match. 

  **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. 
+ **Oversize handling** – How AWS WAF should handle requests that have header data that is larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request headers and at most the first 200 headers. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).

## Header order
<a name="waf-rule-statement-request-component-header-order"></a>

Inspect a string containing the list of the request's header names, ordered as they appear in the web request that AWS WAF receives for inspection. AWS WAF generates the string and then uses that as the field to match component in its inspection. AWS WAF separates the header names in the string with colons and with no added spaces, for example `host:user-agent:accept:authorization:referer`.

For this option, you provide the following specifications: 
+ **Oversize handling** – How AWS WAF should handle requests that have header data that is more numerous or larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request headers and at most the first 200 headers. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue inspecting the headers that are available, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).

## Cookies
<a name="waf-rule-statement-request-component-cookies"></a>

Inspects all of the request cookies. You can apply a filter to inspect a subset of all cookies. 

For this option, you provide the following specifications: 
+ **Match patterns** – The filter to use to obtain a subset of cookies for inspection. AWS WAF looks for these patterns in the cookie keys. 

  The match patterns setting can be one of the following: 
  + **All** – Match all keys. Evaluate the rule inspection criteria for all cookies. 
  + **Excluded cookies** – Inspect only the cookies whose keys don't match any of the strings that you specify here. The string match for a key is case sensitive and must be exact. 
  + **Included cookies** – Inspect only the cookies that have a key that matches one of the strings that you specify here. The string match for a key is case sensitive and must be exact. 
+ **Match scope** – The parts of the cookies that AWS WAF should inspect with the rule inspection criteria. You can specify **Keys**, **Values**, or **All** for both keys and values. 

  **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. 
+ **Oversize handling** – How AWS WAF should handle requests that have cookie data that is larger than AWS WAF can inspect. AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request cookies and at most the first 200 cookies. The content is available for inspection by AWS WAF up to the first limit reached. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).

## URI fragment
<a name="waf-rule-statement-request-component-uri-fragment"></a>

**Note**  
Uri Fragment inspection is available only for CloudFront distributions and Application Load Balancers.

Inspects the part of a URL that follows the "\$1" symbol, providing additional information about the resource, for example, \$1section2. For information, see [Uniform Resource Identifier (URI): Generic Syntax](https://tools.ietf.org/html/rfc3986#section-3). 

If you don't use a text transformation with this option, AWS WAF doesn't normalize the URI fragment and inspects it exactly as it receives it from the client in the request. For information about text transformations, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

**Rule statement requirements**  
You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if URI is missing the fragment or associated service is not Application Load Balancer or CloudFront. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement.

## URI path
<a name="waf-rule-statement-request-component-uri-path"></a>

Inspects the part of a URL that identifies a resource, for example, `/images/daily-ad.jpg`. For information, see [Uniform Resource Identifier (URI): Generic Syntax](https://tools.ietf.org/html/rfc3986#section-3). 

If you don't use a text transformation with this option, AWS WAF doesn't normalize the URI and inspects it exactly as it receives it from the client in the request. For information about text transformations, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

## JA3 fingerprint
<a name="waf-rule-statement-request-component-ja3-fingerprint"></a>

Inspects the request's JA3 fingerprint. 

**Note**  
JA3 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers.

The JA3 fingerprint is a 32-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation. Almost all web requests include this information.

**How to get the JA3 fingerprint for a client**  
You can obtain the JA3 fingerprint for a client's requests from the protection pack (web ACL) logs. If AWS WAF is able to calculate the fingerprint, it includes it in the logs. For information about the logging fields, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).

**Rule statement requirements**  
You can inspect the JA3 fingerprint only inside a string match statement that's set to exactly match the string that you provide. Provide the JA3 fingerprint string from the logs in your string match statement specification, to match with any future requests that have the same TLS configuration. For information about the string match statement, see [String match rule statement](waf-rule-statement-type-string-match.md).

You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if AWS WAF is unable to calculate the JA3 fingerprint. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement.

To use this match option, you must log your protection pack (web ACL) traffic. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

## JA4 fingerprint
<a name="waf-rule-statement-request-component-ja4-fingerprint"></a>

Inspects the request's JA4 fingerprint. 

**Note**  
JA4 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers.

The JA4 fingerprint is a 36-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. JA4 fingerprinting is an extension of the JA3 fingerprinting that can result in fewer unique fingerprints for some browsers. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation. Almost all web requests include this information.

**How to get the JA4 fingerprint for a client**  
You can obtain the JA4 fingerprint for a client's requests from the protection pack (web ACL) logs. If AWS WAF is able to calculate the fingerprint, it includes it in the logs. For information about the logging fields, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).

**Rule statement requirements**  
You can inspect the JA4 fingerprint only inside a string match statement that's set to exactly match the string that you provide. Provide the JA4 fingerprint string from the logs in your string match statement specification, to match with any future requests that have the same TLS configuration. For information about the string match statement, see [String match rule statement](waf-rule-statement-type-string-match.md).

You must provide a fallback behavior for this rule statement. The fallback behavior is the match status that you want AWS WAF to assign to the web request if AWS WAF is unable to calculate the JA4 fingerprint. If you choose to match, AWS WAF treats the request as matching the rule statement and applies the rule action to the request. If you choose to not match, AWS WAF treats the request as not matching the rule statement.

To use this match option, you must log your protection pack (web ACL) traffic. For information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

## Query string
<a name="waf-rule-statement-request-component-query-string"></a>

Inspects the part of the URL that appears after a `?` character, if any.

**Note**  
For cross-site scripting match statements, we recommend that you choose **All query parameters** instead of **Query string**. Choosing **All query parameters** adds 10 WCUs to the base cost.

## Single query parameter
<a name="waf-rule-statement-request-component-single-query-param"></a>

Inspects a single query parameter that you have defined as part of the query string. AWS WAF inspects the value of the parameter that you specify. 

For this option, you also specify a **Query argument**. For example, if the URL is `www.xyz.com?UserName=abc&SalesRegion=seattle`, you can specify `UserName` or `SalesRegion` for the query argument. The maximum length for the name of the argument is 30 characters. The name is not case sensitive, so if you specify `UserName`, AWS WAF matches all variations of `UserName`, including `username` and `UsERName`.

If the query string contains more than one instance of the query argument that you've specified, AWS WAF inspects all the values for a match, using OR logic. For example, in the URL `www.xyz.com?SalesRegion=boston&SalesRegion=seattle`, AWS WAF evaluates the name that you've specified against `boston` and `seattle`. If either is a match, the inspection is a match.

## All query parameters
<a name="waf-rule-statement-request-component-all-query-params"></a>

Inspects all query parameters in the request. This is similar to the single query parameter component choice, but AWS WAF inspects the values of all arguments within the query string. For example, if the URL is `www.xyz.com?UserName=abc&SalesRegion=seattle`, AWS WAF triggers a match if either the value of `UserName` or `SalesRegion` match the inspection criteria. 

Choosing this option adds 10 WCUs to the base cost.

## Body
<a name="waf-rule-statement-request-component-body"></a>

Inspects the request body, evaluated as plain text. You can also evaluate the body as JSON using the JSON content type. 

The request body is the part of the request that immediately follows the request headers. It contains any additional data that is needed for the web request, for example, data from a form. 
+ In the console, you select this under the **Request option** choice **Body**, by selecting the **Content type** choice **Plain text**. 
+ In the API, in the rule's `FieldToMatch` specification, you specify `Body` to inspect the request body as plain text.

For Application Load Balancer and AWS AppSync, AWS WAF can inspect the first 8 KB of the body of a request. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, by default, AWS WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md).

You must specify oversize handling for this component type. Oversize handling defines how AWS WAF handles requests that have body data that is larger than AWS WAF can inspect. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

You can also evaluate the body as parsed JSON. For information about this, see the section that follows. 

## JSON body
<a name="waf-rule-statement-request-component-json-body"></a>

Inspects the request body, evaluated as JSON. You can also evaluate the body as plain text. 

The request body is the part of the request that immediately follows the request headers. It contains any additional data that is needed for the web request, for example, data from a form. 
+ In the console, you select this under the **Request option** choice **Body**, by selecting the **Content type** choice **JSON**. 
+ In the API, in the rule's `FieldToMatch` specification, you specify `JsonBody`.

For Application Load Balancer and AWS AppSync, AWS WAF can inspect the first 8 KB of the body of a request. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, by default, AWS WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md).

You must specify oversize handling for this component type. Oversize handling defines how AWS WAF handles requests that have body data that is larger than AWS WAF can inspect. You can choose to continue the inspection, or to skip inspection and mark the request as matching or not matching the rule. For more information about handling oversize content, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

Choosing this option doubles the match statement's base cost WCUs. For example, if the match statement base cost is 5 WCUs without JSON parsing, using JSON parsing doubles the cost to 10 WCUs. 

For this option, you provide additional specifications, as described in the following section.

**How AWS WAF handles JSON body inspection**  
When AWS WAF inspects the web request body as JSON, it performs steps to parse the body and extract the JSON elements for inspection. AWS WAF performs these steps in accordance with your configuration choices. 

The following lists the steps that AWS WAF performs. 

1. **Parse the body contents** – AWS WAF parses the contents of the web request body in order to extract the JSON elements for inspection. AWS WAF does its best to parse the entire contents of the body, but parsing can fail for a variety of error states in the contents. Examples include invalid characters, duplicate keys, truncation, and content whose root node isn't an object or an array. 

   The option **Body parsing fallback behavior** determines what AWS WAF does if it fails to completely parse the JSON body: 
   + **None (default behavior)** - AWS WAF evaluates the content only up to the point where it encountered a parsing error. 
   + **Evaluate as string** - Inspect the body as plain text. AWS WAF applies the text transformations and inspection criteria that you defined for the JSON inspection to the body text string.
   + **Match** - Treat the web request as matching the rule statement. AWS WAF applies the rule action to the request.
   + **No match** - Treat the web request as not matching the rule statement.
**Note**  
This fallback behavior only triggers when AWS WAF encounters an error while parsing the JSON string. 

**Parsing doesn't fully validate the JSON**  
AWS WAF parsing doesn't fully validate the input JSON string, so parsing can succeed even for invalid JSON.

   For example, AWS WAF parses the following invalid JSON without error: 
   + Missing comma: `{"key1":"value1""key2":"value2"}`
   + Missing colon: `{"key1":"value1","key2""value2"}`
   + Extra colons: `{"key1"::"value1","key2""value2"}`

   For cases such as these where the parsing succeeds but the result isn't completely valid JSON, the outcome of the subsequent steps in the evaluation can vary. The extraction might miss some elements, or the rule evaluation might have unexpected results. We recommend that you validate the JSON that you receive in your application and handle invalid JSON as needed. 

1. **Extract the JSON elements** – AWS WAF identifies the subset of JSON elements to inspect according to your settings: 
   + The option **JSON match scope** specifies the types of elements in the JSON that AWS WAF should inspect. 

     You can specify **Keys**, **Values**, or **All** for both keys and values. 

     **All** does not require a match to be found in the keys and a match to be found in the values. It requires a match to be found in the keys or the values or both. To require a match in the keys and in the values, use a logical `AND` statement to combine two match rules, one that inspects the keys and another that inspects the values. 
   + The option **Content to inspect** specifies how to filter the element set to the subset that you want AWS WAF to inspect. 

     You must specify one of the following:
     + **Full JSON content** - Evaluate all elements. 
     + **Only included elements** - Evaluate only elements whose paths match the JSON Pointer criteria that you provide. Don't use this option to indicate *all* paths in the JSON. Instead, use **Full JSON content**. 

       For information about JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation [JavaScript Object Notation (JSON) Pointer](https://tools.ietf.org/html/rfc6901). 

       For example, in the console, you can provide the following: 

       ```
       /dogs/0/name
       /dogs/1/name
       ```

       In the API or CLI, you can provide the following: 

       ```
       "IncludedPaths": ["/dogs/0/name", "/dogs/1/name"]
       ```

   For example, say that the **Content to inspect** setting is **Only included elements**, and the included elements setting is `/a/b`. 

   For the following example JSON body: 

   ```
   { 
     "a":{
       "c":"d",
       "b":{
         "e":{
           "f":"g"
         }
       }
     }
   }
   ```

   The element sets that AWS WAF would inspect for each **JSON match scope** setting are listed below. Note that the key `b`, which is part of the included elements path, isn't evaluated.
   + **All**: `e`, `f,` and `g`.
   + **Keys**: `e` and `f`.
   + **Values**: `g`.

1. **Inspect the JSON element set** – AWS WAF applies any text transformations that you've specified to the extracted JSON elements and then matches the resulting element set against the rule statement's match criteria. This is the same transformation and evaluation behavior as for other web request components. If any of the extracted JSON elements match, the web request is a match for the rule. 

# Using forwarded IP addresses in AWS WAF
<a name="waf-rule-statement-forwarded-ip-address"></a>

This section applies to rule statements that use the IP address of a web request. By default, AWS WAF uses the IP address from the web request origin. However, if a web request goes through one or more proxies or load balancers, the web request origin will contain the address of the last proxy, and not the originating address of the client. In this case, the originating client address is usually forwarded in another HTTP header. This header is typically `X-Forwarded-For` (XFF), but it can be a different one. 

**Rule statements that use IP addresses**  
The rule statements that use IP addresses are the following:
+ [IP set match](waf-rule-statement-type-ipset-match.md) - Inspects the IP address for a match with the addresses that are defined in an IP set.
+ [Geographic match](waf-rule-statement-type-geo-match.md) - Uses the IP address to determine country and region of origin and matches the country of origin against a list of countries.
+ [ASN match](waf-rule-statement-type-asn-match.md) - Uses the IP address to determine the Autonomous System Number (ASN) and matches the ASN against a list of ASNs.
+ [Using rate-based rule statements](waf-rule-statement-type-rate-based.md) - Can aggregate requests by their IP addresses to ensure that no individual IP address sends requests at too high a rate. You can use IP address aggregation by itself or in combination with other aggregation keys. 

You can instruct AWS WAF to use a forwarded IP address for any of these rule statements, either from the `X-Forwarded-For` header or from another HTTP header, instead of using the web request's origin. For details on how to provide the specifications, see the guidance for the individual rule statement types.

**Note**  
If a header is missing, AWS WAF evaluates any statement that uses that header as "No match." If you use a NOT statement with a "No match" result, AWS WAF converts the evaluation to "Match." Missing headers don't trigger fallback behavior - only invalid header values do.

**Fallback behavior**  
When you use the forwarded IP address, you indicate the match status for AWS WAF to assign to the web request if the request doesn't have a valid IP address in the specified position: 
+ **MATCH** - Treat the web request as matching the rule statement. AWS WAF applies the rule action to the request.
+ **NO MATCH** - Treat the web request as not matching the rule statement. 

**IP addresses used in AWS WAF Bot Control**  
The Bot Control managed rule group verifies bots using the IP addresses from AWS WAF. If you use Bot Control and you have verified bots that route through a proxy or load balancer, you need to explicitly allow them using a custom rule. For example, you can configure a custom IP set match rule that uses forwarded IP addresses to detect and allow your verified bots. You can use the rule to customize your bot management in a number of ways. For information and examples, see [AWS WAF Bot Control](waf-bot-control.md). 

**General considerations for using forwarded IP addresses**  
Before you use a forwarded IP address, note the following general caveats: 
+ A header can be modified by proxies along the way, and the proxies might handle the header in different ways. 
+ Attackers might alter the contents of the header in an attempt to bypass AWS WAF inspections. 
+ The IP address inside the header can be malformed or invalid.
+ The header that you specify might not be present at all in a request.

**Considerations for using forwarded IP addresses with AWS WAF**  
The following list describes requirements and caveats for using forwarded IP addresses in AWS WAF:
+ For any single rule, you can specify one header for the forwarded IP address. The header specification is case insensitive.
+ For rate-based rule statements, any nested scoping statements do not inherit the forwarded IP configuration. Specify the configuration for each statement that uses a forwarded IP address. 
+ For geo match, ASN match, and rate-based rules, AWS WAF uses the first address in the header. For example, if a header contains `10.1.1.1, 127.0.0.0, 10.10.10.10` AWS WAF uses `10.1.1.1`
+ For IP set match, you indicate whether to match against the first, last, or any address in the header. If you specify any, AWS WAF inspects all addresses in the header for a match, up to 10 addresses. If the header contains more than 10 addresses, AWS WAF inspects the last 10. 
+ Headers that contain multiple addresses must use a comma separator between the addresses. If a request uses a separator other than a comma, AWS WAF considers the IP addresses in the header malformed.
+ If the IP addresses inside the header are malformed or invalid, AWS WAF designates the web request as matching the rule or not matching, according to the fallback behavior that you specify in the forwarded IP configuration.
+ If the header that you specify isn’t present in a request, AWS WAF doesn’t apply the rule to the request at all. This means that AWS WAF doesn't apply the rule action and doesn't apply the fallback behavior.
+ A rule statement that uses a forwarded IP header for the IP address won’t use the IP address that’s reported by the web request origin.

**Best practices for using forwarded IP addresses with AWS WAF**  
When you use forwarded IP addresses, use the following best practices: 
+ Carefully consider all possible states of your request headers before enabling forwarded IP configuration. You might need to use more than one rule to get the behavior you want.
+ To inspect multiple forwarded IP headers or to inspect the web request origin and a forwarded IP header, use one rule for each IP address source. 
+ To block web requests that have an invalid header, set the rule action to block and set the fallback behavior for the forwarded IP configuration to match. 

**Example JSON for forwarded IP addresses**  
The following geo match statement matches only if the `X-Forwarded-For` header contains an IP whose country of origin is `US`: 

```
{
  "Name": "XFFTestGeo",
  "Priority": 0,
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "XFFTestGeo"
  },
  "Statement": {
    "GeoMatchStatement": {
      "CountryCodes": [
        "US"
      ],
      "ForwardedIPConfig": {
        "HeaderName": "x-forwarded-for",
        "FallbackBehavior": "MATCH"
      }
    }
  }
}
```

The following rate-based rule aggregates requests based on the first IP in the `X-Forwarded-For` header. The rule counts only requests that match the nested geo match statement, and it only blocks requests that match the geo match statement. The nested geo match statement also uses the `X-Forwarded-For` header to determine whether the IP address indicates a country of origin of `US`. If it does, or if the header is present but malformed, the geo match statement returns a match. 

```
{
  "Name": "XFFTestRateGeo",
  "Priority": 0,
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "XFFTestRateGeo"
  },
  "Statement": {
    "RateBasedStatement": {
      "Limit": "100",
      "AggregateKeyType": "FORWARDED_IP",
      "ScopeDownStatement": {
        "GeoMatchStatement": {
          "CountryCodes": [
            "US"
          ],
          "ForwardedIPConfig": {
            "HeaderName": "x-forwarded-for",
            "FallbackBehavior": "MATCH"
          }
        }
      },
      "ForwardedIPConfig": {
        "HeaderName": "x-forwarded-for",
        "FallbackBehavior": "MATCH"
      }
    }
  }
}
```

# Inspecting HTTP/2 pseudo headers in AWS WAF
<a name="waf-rule-statement-request-components-for-http2-pseudo-headers"></a>

This section explains how you can use AWS WAF to inspect HTTP/2 pseudo headers.

Protected AWS resources that support HTTP/2 traffic do not forward HTTP/2 pseudo headers to AWS WAF for inspection, but they provide contents of pseudo headers in web request components that AWS WAF inspects. 

You can use AWS WAF to inspect only the pseudo headers that are listed in the following table. 


**HTTP/2 pseudo header contents mapped to web request components**  

| HTTP/2 pseudo header | Web request component to inspect | Documentation | 
| --- | --- | --- | 
|  `:method`  |  HTTP method   |  [HTTP method](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-http-method)  | 
|  `:authority`  |  `Host` header   |  [Single header](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-header)  [All headers](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-headers)  | 
|  `:path` URI path  | URI path  | [URI path](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-uri-path) | 
|  `:path` query  |  Query string  |  [Query string](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-query-string) [Single query parameter](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-single-query-param) [All query parameters](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-all-query-params)  | 

# Using text transformations in AWS WAF
<a name="waf-rule-statement-transformation"></a>

This section explains how to provide transformations for AWS WAF to apply before inspecting the request.

In statements that look for patterns or set constraints, you can provide transformations for AWS WAF to apply before inspecting the request. A transformation reformats a web request to eliminate some of the unusual formatting that attackers use in an effort to bypass AWS WAF. 

When you use this with the JSON body request component selection, AWS WAF applies your transformations after parsing and extracting the elements to inspect from the JSON. For more information, see [JSON body](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-json-body).

If you provide more than one transformation, you also set the order for AWS WAF to apply them. 

**WCUs** – Each text transformation is 10 WCUs.

The AWS WAF console and API documentation also provide guidance for these settings in the following locations: 
+ **Rule builder** on the console – **Text transformation**. This option is available when you use request components. 
+ **API statement contents** – `TextTransformations`Options for text transformations

Each transformation listing shows the console and API specifications followed by the description.

Base64 decode – `BASE64_DECODE`  
AWS WAF decodes a Base64-encoded string.

Base64 decode extension – `BASE64_DECODE_EXT`  
AWS WAF decodes a Base64-encoded string, but uses a forgiving implementation that ignores characters that aren't valid. 

Command line – `CMD_LINE`  
This option mitigates situations where attackers might be injecting an operating system command-line command and are using unusual formatting to disguise some or all of the command.   
Use this option to perform the following transformations:  
+ Delete the following characters: `\ " ' ^`
+ Delete spaces before the following characters: `/ (`
+ Replace the following characters with a space: `, ;`
+ Replace multiple spaces with one space
+ Convert uppercase letters, `A-Z`, to lowercase, `a-z`

Compress whitespace – `COMPRESS_WHITE_SPACE`  
AWS WAF compresses white space by replacing multiple spaces with one space and replacing the following characters with a space character (ASCII 32):  
+ Formfeed (ASCII 12)
+ Tab (ASCII 9)
+ Newline (ASCII 10)
+ Carriage return (ASCII 13)
+ Vertical tab (ASCII 11)
+ Non-breaking space (ASCII 160)

CSS decode – `CSS_DECODE`  
AWS WAF decodes characters that were encoded using CSS 2.x escape rules `syndata.html#characters`. This function uses up to two bytes in the decoding process, so it can help to uncover ASCII characters that were encoded using CSS encoding that wouldn’t typically be encoded. It's also useful in countering evasion, which is a combination of a backslash and non-hexadecimal characters. For example, `ja\vascript` for `javascript`.

Escape sequences decode – `ESCAPE_SEQ_DECODE`  
AWS WAF decodes the following ANSI C escape sequences: `\a`, `\b`, `\f`, `\n`, `\r`, `\t`, `\v`, `\\`, `\?`, `\'`, `\"`, `\xHH` (hexadecimal), `\0OOO` (octal). Encodings that aren't valid remain in the output.

Hex decode – `HEX_DECODE`  
AWS WAF decodes a string of hexadecimal characters into a binary.

HTML entity decode – `HTML_ENTITY_DECODE`  
AWS WAF replaces characters that are represented in hexadecimal format `&#xhhhh;` or decimal format `&#nnnn;` with the corresponding characters.  
AWS WAF replaces the following HTML-encoded characters with unencoded characters. This list uses lowercase HTML encoding, but the handling is case insensitive, for example `&QuOt;` and `&quot;` are treated the same.       
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-transformation.html)

JS decode – `JS_DECODE`  
AWS WAF decodes JavaScript escape sequences. If a `\uHHHH` code is in the full-width ASCII code range of `FF01-FF5E`, then the higher byte is used to detect and adjust the lower byte. If not, only the lower byte is used and the higher byte is zeroed, causing a possible loss of information.

Lowercase – `LOWERCASE`  
AWS WAF converts uppercase letters (A-Z) to lowercase (a-z).

MD5 – `MD5`  
AWS WAF calculates an MD5 hash from the data in the input. The computed hash is in a raw binary form.

None – `NONE`  
AWS WAF inspects the web request as received, without any text transformations. 

Normalize path – `NORMALIZE_PATH`  
AWS WAF normalizes the input string by removing multiple slashes, directory self-references, and directory back-references that are not at the beginning of the input.

Normalize path Windows – `NORMALIZE_PATH_WIN`  
AWS WAF converts backslash characters to forward slashes and then processes the resulting string using the `NORMALIZE_PATH` transformation.

Remove nulls – `REMOVE_NULLS`  
AWS WAF removes all `NULL` bytes from the input. 

Replace comments – `REPLACE_COMMENTS`  
AWS WAF replaces each occurrence of a C-style comment (/\$1 ... \$1/) with a single space. It doesn't compress multiple consecutive occurrences. It replaces unterminated comments with a space (ASCII 0x20). It doesn't change a standalone termination of a comment (\$1/).

Replace nulls – `REPLACE_NULLS`  
AWS WAF replaces each `NULL` byte in the input with the space character (ASCII 0x20).

SQL hex decode – `SQL_HEX_DECODE`  
AWS WAF decodes SQL hex data. For example, AWS WAF decodes (`0x414243`) to (`ABC`).

URL decode – `URL_DECODE`  
AWS WAF decodes a URL-encoded value.

URL decode Unicode – `URL_DECODE_UNI`  
Like `URL_DECODE`, but with support for Microsoft-specific `%u` encoding. If the code is in the full-width ASCII code range of `FF01-FF5E`, the higher byte is used to detect and adjust the lower byte. Otherwise, only the lower byte is used and the higher byte is zeroed.

UTF8 to Unicode – `UTF8_TO_UNICODE`  
AWS WAF converts all UTF-8 character sequences to Unicode. This helps normalize input and it minimizes false-positives and false-negatives for non-English languages.

# Using scope-down statements in AWS WAF
<a name="waf-rule-scope-down-statements"></a>

This section explains what a scope-down statement and how it works.

A scope-down statement is a nestable rule statement that you add inside a managed rule group statement or a rate-based statement to narrow the set of requests that the containing rule evaluates. The containing rule only evaluates the requests that first match the scope-down statement. 
+ **Managed rule group statement** – If you add a scope-down statement to a managed rule group statement, AWS WAF evaluates any request that doesn't match the scope-down statement as not matching the rule group. Only those requests that match the scope-down statement are evaluated against the rule group. For managed rule groups with pricing that's based on the number of requests evaluated, scope-down statements can help contain costs. 

  For more information about managed rule group statements, see [Using managed rule group statements in AWS WAF](waf-rule-statement-type-managed-rule-group.md).
+ **Rate-based rule statement** – A rate-based rule statement without a scope-down statement rate limits all requests that the rule evaluates. If you want to only control the rate for a specific category of requests, add a scope-down statement to the rate-based rule. For example, to only track and control the rate of requests from a specific geographical area, you can specify that geographical area in a geographic match statement and add it to your rate-based rule as the scope-down statement. 

  For more information about rate-based rule statements, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md).

You can use any nestable rule in a scope-down statement. For the available statements, see [Using match rule statements in AWS WAF](waf-rule-statements-match.md) and [Using logical rule statements in AWS WAF](waf-rule-statements-logical.md). The WCUs for a scope-down statement are the WCUs required for the rule statement that you define in it. There's no additional cost for the use of a scope-down statement.

You can configure a scope-down statement in the same way as you do when you use the statement in a regular rule. For example, you can apply text transformations to a web request component that you're inspecting and you can specify a forwarded IP address to use as the IP address. These configurations apply only to the scope-down statement and are not inherited by the containing managed rule group or rate-based rule statement. 

For example, if you apply text transformations to a query string in your scope-down statement, the scope-down statement inspects the query string after applying the transformations. If the request matches the scope-down statement criteria, AWS WAF then passes the web request to the containing rule in its original state, without the scope-down statement's transformations. The rule that contains the scope-down statement might apply text transformations of its own, but it doesn't inherit any from the scope-down statement. 

You can't use a scope-down statement to specify any request inspection configuration for the containing rule statement. You can't use a scope-down statement as a web request preprocessor for the containing rule statement. The only role of a scope-down statement is to determine which requests are passed to the containing rule statement for inspection. 

# Referencing reusable entities in AWS WAF
<a name="waf-rule-statement-reusable-entities"></a>

This section explains how reusable entities work in AWS WAF.

Some rules use entities that are reusable and that are managed outside of your web ACLs, either by you, AWS, or an AWS Marketplace seller. When the reusable entity is updated, AWS WAF propagates the update to your rule. For example, if you use an AWS Managed Rules rule group in a protection pack (web ACL), when AWS updates the rule group, AWS propagates the change to your web ACL, to update its behavior. If you use an IP set statement in a rule, when you update the set, AWS WAF propagates the change to all rules that reference it, so any protection packs (web ACLs) that use those rules are kept up-to-date with your changes. 

The following are the reusable entities that you can use in a rule statement. 
+ **IP sets** – You create and manage your own IP sets. On the console, you can access these from the navigation pane. For information about managing IP sets, see [IP sets and regex pattern sets in AWS WAF](waf-referenced-set-managing.md). 
+ **Regex match sets** – You create and manage your own regex match sets. On the console, you can access these from the navigation pane. For information about managing regex pattern sets, see [IP sets and regex pattern sets in AWS WAF](waf-referenced-set-managing.md). 
+ **AWS Managed Rules rule groups** – AWS manages these rule groups. On the console, these are available for your use when you add a managed rule group to your protection pack (web ACL). For more information about these, see [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md).
+ **AWS Marketplace managed rule groups** – AWS Marketplace sellers manage these rule groups and you can subscribe to them to use them. To manage your subscriptions, on the navigation pane of the console, choose **AWS Marketplace**. The AWS Marketplace managed rule groups are listed when you add a managed rule group to your protection pack (web ACL). For rule groups that you haven't yet subscribed to, you can find a link to AWS Marketplace on that page as well. For more information about AWS Marketplace seller managed rule groups, see [AWS Marketplace rule groups](marketplace-rule-groups.md).
+ **Your own rule groups** – You manage your own rule groups, usually when you need some behavior that isn't available through the managed rule groups. On the console, you can access these from the navigation pane. For more information, see [Managing your own rule groups](waf-user-created-rule-groups.md).

**Deleting a referenced set or rule group**  
When you delete a referenced entity, AWS WAF checks to see if it's currently being used in a protection pack (web ACL). If AWS WAF finds that it's in use, it warns you. AWS WAF is almost always able to determine if an entity is being referenced by a protection pack (web ACL). However, in rare cases, it might not be able to do so. If you need to be sure that the entity that you want to delete isn't in use, check for it in your web ACLs before deleting it.

# Using match rule statements in AWS WAF
<a name="waf-rule-statements-match"></a>

This section explains what a match statement is and how it works.

Match statements compare the web request or its origin against criteria that you provide. For many statements of this type, AWS WAF compares a specific component of the request for matching content. 

Match statements are nestable. You can nest any of these statements inside logical rule statements and you can use them in scope-down statements. For information about logical rule statements, see [Using logical rule statements in AWS WAF](waf-rule-statements-logical.md). For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

This table describes the regular match statements that you can add to a rule and provides some guidelines for calculating protection pack (web ACL) capacity units (WCU) usage for each. For information about WCUs, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md). 


| Match Statement | Description | WCUs | 
| --- | --- | --- | 
| [Geographic match](waf-rule-statement-type-geo-match.md) | Inspects the request's country of origin and applies labels for the country and region of origin.  | 1 | 
|  [ASN match](waf-rule-statement-type-asn-match.md)  |  Inspects the request against an ASN associated with IP addresses and address ranges.  |  1  | 
|  [IP set match](waf-rule-statement-type-ipset-match.md)  |  Inspects the request against a set of IP addresses and address ranges.   |  1 for most cases. If you configure the statement to use a header with forwarded IP addresses and specify a position in the header of Any, then increase the WCUs by 4.  | 
|  [Label match rule statement](waf-rule-statement-type-label-match.md)  |  Inspects the request for labels that have been added by other rules in the same protection pack (web ACL).  |  1   | 
| [Regex match rule statement](waf-rule-statement-type-regex-match.md) | Compares a regex pattern against a specified request component.  | 3, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.  | 
|  [Regex pattern set](waf-rule-statement-type-regex-pattern-set-match.md)  |  Compares regex patterns against a specified request component.   |  25 per pattern set, as a base cost.  If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.  | 
| [Size constraint](waf-rule-statement-type-size-constraint-match.md) | Checks size constraints against a specified request component.  | 1, as a base cost.  If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.  | 
| [SQLi attack](waf-rule-statement-type-sqli-match.md) | Inspects for malicious SQL code in a specified request component.  | 20, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs. | 
| [String match](waf-rule-statement-type-string-match.md) | Compares a string to a specified request component.  |  The base cost depends on the type of string match and is between 1 and 10. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.  | 
| [XSS scripting attack](waf-rule-statement-type-xss-match.md) | Inspects for cross-site scripting attacks in a specified request component.  | 40, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs. | 

# Geographic match rule statement
<a name="waf-rule-statement-type-geo-match"></a>

This section explains what a geographic match statement is and how it works.

Use geographic or geo match statements to manage web requests based on country and region of origin. A geo match statement add labels to web requests that indicate the country of origin and the region of origin. It adds these labels regardless of whether the statement criteria is a match for the request. A geo match statement also performs matching against the request's country of origin.

## How to use the geo match statement
<a name="waf-rule-statement-geo-how-to-use"></a>

You can use the geo match statement for country or region matching, as follows: 
+ **Country** — You can use a geo match rule by itself to manage requests based solely on their country of origin. The rule statement matches against country codes. You can also follow a geo match rule with a label match rule that matches on the country of origin label. 
**Note**  
To filter traffic from Hong Kong, use the ISO 3166-1 alpha-2 country code `HK` in your geo match statement.
+ **Region** — Use a geo match rule followed by a label match rule to manage requests based on their region of origin. You can't use a geo match rule alone to match against region codes.

For information about using label match rules, see [Label match rule statement](waf-rule-statement-type-label-match.md) and [Web request labeling in AWS WAF](waf-labels.md).

## How the geo match statement works
<a name="waf-rule-statement-geo-how-it-works"></a>

With the geo match statement, AWS WAF manages each web request as follows: 

1. **Determines the request's country and region codes** — AWS WAF determines the country and region of a request based on its IP address. By default, AWS WAF uses the IP address of the web request's origin. You can instruct AWS WAF to use an IP address from an alternate request header, like `X-Forwarded-For`, by enabling forwarded IP configuration in the rule statement settings. 

   AWS WAF determines the location of requests using MaxMind GeoIP databases. MaxMind reports very high accuracy of their data at the country level, although accuracy varies according to factors such as country and type of IP. For more information about MaxMind, see [MaxMind IP Geolocation](https://support.maxmind.com/hc/en-us/sections/4407519834267-IP-Geolocation). If you think any of the GeoIP data is incorrect, you can submit a correction request to Maxmind at [MaxMind Correct GeoIP2 Data](https://support.maxmind.com/hc/en-us/articles/4408252036123-GeoIP-Correction).

   AWS WAF uses the alpha-2 country and region codes from the International Organization for Standardization (ISO) 3166 standard. You can find the codes at the following locations:
   + At the ISO website, you can search the country codes at [ISO Online Browsing Platform (OBP)](https://www.iso.org/obp/ui#home). 
   + On Wikipedia, the country codes are listed at [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2).

     The region codes for a country are listed at the URL `https://en.wikipedia.org/wiki/ISO_3166-2:<ISO country code>`. For example, the regions for the United States are at [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) and for Ukraine they're at [ISO 3166-2:UA](https://en.wikipedia.org/wiki/ISO_3166-2:UA).

1. **Determines the country label and region label to add to the request** — The labels indicate whether the geo match statement uses the origin IP or a forwarded IP configuration.
   + **Origin IP** 

     The country label is `awswaf:clientip:geo:country:<ISO country code>`. Example for the United States: `awswaf:clientip:geo:country:US`.

     The region label is `awswaf:clientip:geo:region:<ISO country code>-<ISO region code>`. Example for Oregon in the United States: `awswaf:clientip:geo:region:US-OR`.
   + **Forwarded IP** 

     The country label is `awswaf:forwardedip:geo:country:<ISO country code>`. Example for the United States: `awswaf:forwardedip:geo:country:US`.

     The region label is `awswaf:forwardedip:geo:region:<ISO country code>-<ISO region code>`. Example for Oregon in the United States: `awswaf:forwardedip:geo:region:US-OR`.

   If the country or region code isn't available for a request's specified IP address, AWS WAF uses `XX` in the labels, in the place of the value. For example, the following label is for a client IP whose country code isn't available: `awswaf:clientip:geo:country:XX` and the following is for a forwarded IP whose country is the United States, but whose region code isn't available: `awswaf:forwardedip:geo:region:US-XX`. 

1. **Evaluates the request's country code against the rule criteria** 

The geo match statement adds country and region labels to all requests that it inspects, regardless of whether it finds a match. 

**Note**  
AWS WAF adds any labels at the end of a rule's web request evaluation. Because of this, any label matching that you use against the labels from a geo match statement must be defined in a separate rule from the rule that contains the geo match statement. 

If you want to inspect only region values, you can write a geo match rule with Count action and with a single country code match, followed by a label match rule for the region labels. You are required to supply a country code for the geo match rule to evaluate, even for this approach. You can reduce logging and count metrics by specifying a country that's very unlikely to be a source of traffic to your site. 

## CloudFront distributions and the CloudFront geo restriction feature
<a name="cloudfront-distributions-geo-restriction"></a>

For CloudFront distributions, if you use the CloudFront geo restriction feature, be aware that the feature doesn't forward blocked requests to AWS WAF. It does forward allowed requests to AWS WAF. If you want to block requests based on the geography plus other criteria that you can specify in AWS WAF, use the AWS WAF geo match statement and don't use the CloudFront geo restriction feature. 

## Rule statement characteristics
<a name="geo-match-statement-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs ** – 1 WCU.

**Settings** – This statement uses the following settings: 
+ **Country codes** – An array of country codes to compare for a geo match. These must be two-character country codes from the alpha-2 country ISO codes of the ISO 3166 international standard, for example, `["US","CN"]`. 
+ **(Optional) Forwarded IP configuration** – By default, AWS WAF uses the IP address in the web request origin to determine country of origin. Alternatively, you can configure the rule to use a forwarded IP in an HTTP header like `X-Forwarded-For` instead. AWS WAF uses the first IP address in the header. 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 more information, see [Using forwarded IP addresses](waf-rule-statement-forwarded-ip-address.md). 

## Where to find this rule statement
<a name="geo-match-statement-where-to-find"></a>
+ **Rule builder** on the console – For **Request option**, choose **Originates from a country in**.
+ **API** – [GeoMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_GeoMatchStatement.html)

## Examples
<a name="waf-rule-statement-geo-examples"></a>

You can use the geo match statement to manage requests from specific countries or regions. For example, if you want to block requests from certain countries, but still allow requests from a specific set of IP addresses in those countries, you could create a rule with the action set to Block and the following nested statements, shown in pseudocode:
+ AND statement
  + Geo match statement listing the countries that you want to block
  + NOT statement 
    + IP set statement that specifies the IP addresses that you want to allow through

Or, if you want to block some regions in certain countries, but still allow requests from other regions in those countries, you could first define a geo match rule with the action set to Count. Then, define a label match rule that matches against the added geo match labels and handles the requests as you need. 

The following pseudo code describes an example of this approach:

1. Geo match statement listing the countries with regions that you want to block, but with the action set to Count. This labels every web request regardless of match status, and it also gives you count metrics for the countries of interest. 

1. `AND` statement with Block action
   + Label match statement that specifies the labels for the countries that you want to block
   + `NOT` statement 
     + Label match statement that specifies the labels of the regions in those countries that you want to allow through

The following JSON listing shows an implementation of the two rules described in the prior pseudocode. These rules block all traffic from the United States except for traffic from Oregon and Washington. The geo match statement adds country and region labels to all requests that it inspects. The label match rule runs after the geo match rule, so it can match against the country and region labels that the geo match rule has just added. The geo match statement uses a forwarded IP address, so the label matching also specifies forwarded IP labels. 

```
{
   "Name": "geoMatchForLabels",
   "Priority": 10,
   "Statement": {
     "GeoMatchStatement": {
       "CountryCodes": [
         "US"
       ],
       "ForwardedIPConfig": {
           "HeaderName": "X-Forwarded-For",
           "FallbackBehavior": "MATCH"
       }
     }
   },
   "Action": {
     "Count": {}
   },
   "VisibilityConfig": {
     "SampledRequestsEnabled": true,
     "CloudWatchMetricsEnabled": true,
     "MetricName": "geoMatchForLabels"
   }
},
{
   "Name": "blockUSButNotOROrWA",
   "Priority": 11,
   "Statement": {
     "AndStatement": {
       "Statements": [
         {
           "LabelMatchStatement": {
             "Scope": "LABEL",
             "Key": "awswaf:forwardedip:geo:country:US"
           }
         },
         {
           "NotStatement": {
             "Statement": {
                "OrStatement": {
                  "Statements": [
                    {
                       "LabelMatchStatement": {
                         "Scope": "LABEL",
                         "Key": "awswaf:forwardedip:geo:region:US-OR"
                       }
                    },
                    {
                       "LabelMatchStatement": {
                         "Scope": "LABEL",
                         "Key": "awswaf:forwardedip:geo:region:US-WA"
                       }
                    }
                 ]
               }
             }
           }
         }
       ]
     }
   },
   "Action": {
     "Block": {}
   },
   "VisibilityConfig": {
     "SampledRequestsEnabled": true,
     "CloudWatchMetricsEnabled": true,
     "MetricName": "blockUSButNotOROrWA"
   }
}
```

As another example, you can combine geo matching with rate-based rules to prioritize resources for users in a particular country or region. You create a different rate-based statement for each geo match or label match statement that you use to differentiate your users. Set a higher rate limit for users in the preferred country or region and set a lower rate limit for other users. 

The following JSON listing shows a geo match rule followed by rate-based rules that limit the rate of traffic from the United States. The rules allow traffic from Oregon to come in at a higher rate than traffic from anywhere else in the country. 

```
{
  "Name": "geoMatchForLabels",
  "Priority": 190,
  "Statement": {
    "GeoMatchStatement": {
      "CountryCodes": [
        "US"
      ]
    }
  },
  "Action": {
    "Count": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "geoMatchForLabels"
  }
},
{
  "Name": "rateLimitOregon",
  "Priority": 195,
  "Statement": {
    "RateBasedStatement": {
      "Limit": 3000,
      "AggregateKeyType": "IP",
      "ScopeDownStatement": {
        "LabelMatchStatement": {
          "Scope": "LABEL",
          "Key": "awswaf:clientip:geo:region:US-OR"
        }
      }
    }
  },
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "rateLimitOregon"
  }
},
{
  "Name": "rateLimitUSNotOR",
  "Priority": 200,
  "Statement": {
    "RateBasedStatement": {
      "Limit": 100,
      "AggregateKeyType": "IP",
      "ScopeDownStatement": {
        "AndStatement": {
          "Statements": [
            {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:clientip:geo:country:US"
              }
            },
            {
              "NotStatement": {
                "Statement": {
                  "LabelMatchStatement": {
                    "Scope": "LABEL",
                    "Key": "awswaf:clientip:geo:region:US-OR"
                  }
                }
              }
            }
          ]
        }
      }
    }
  },
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "rateLimitUSNotOR"
  }
}
```

# IP set match rule statement
<a name="waf-rule-statement-type-ipset-match"></a>

This section explains what an IP set match statement is and how it works.

The IP set match statement inspects the IP address of a web request against a set of IP addresses and address ranges. Use this to allow or block web requests based on the IP addresses that the requests originate from. By default, AWS WAF uses the IP address from the web request origin, but you can configure the rule to use an HTTP header like `X-Forwarded-For` instead. 



AWS WAF supports all IPv4 and IPv6 CIDR ranges except for `/0`. For more information about CIDR notation, see the Wikipedia entry [Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). An IP set can hold up to 10,000 IP addresses or IP address ranges to check.

**Note**  
Each IP set match rule references an IP set, which you create and maintain independent of your rules. You can use a single IP set in multiple rules, and when you update the referenced set, AWS WAF automatically updates all rules that reference it.   
For information about creating and managing an IP set, see [Creating and managing an IP set in AWS WAF](waf-ip-set-managing.md).

When you add or update the rules in your rule group or protection pack (web ACL), choose the option **IP set** and select the name of the IP set that you want to use. 

## Rule statement characteristics
<a name="ipset-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 1 WCU for most. If you configure the statement to use forwarded IP addresses and specify a position of ANY, increase the WCU usage by 4.

This statement uses the following settings: 
+ **IP set specification** – Choose the IP set that you want to use from the list or create a new one. 
+ **(Optional) Forwarded IP configuration** – An alternate forwarded IP header name to use in place of the request origin. You specify whether to match against the first, last, or any address in the header. You also specify a fallback behavior to apply to a web request with a malformed IP address in the specified header. The fallback behavior sets the matching result for the request, to match or no match. For more information, see [Using forwarded IP addresses](waf-rule-statement-forwarded-ip-address.md). 

## Where to find this rule statement
<a name="ipset-match-where-to-find"></a>

**Where to find this rule statement**
+ **Rule builder** on the console – For **Request option**, choose **Originates from an IP address in**.
+ **Add my own rules and rule groups** page on the console – Choose the **IP set** option.
+ **API** – [IPSetReferenceStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_IPSetReferenceStatement.html)

# Autonomous System Number (ASN) match rule statement
<a name="waf-rule-statement-type-asn-match"></a>

An ASN match rule statement in AWS WAF allows you to inspect web traffic based on the Autonomous System Number (ASN) associated with the request's IP address. ASNs are unique identifiers assigned to large internet networks managed by organizations such as internet service providers, enterprises, universities, or government agencies. By using ASN match statements, you can allow or block traffic from specific network organizations without having to manage individual IP addresses. This approach offers a more stable and efficient way to control access compared to IP-based rules, as ASNs change less frequently than IP ranges. 

ASN matching is particularly useful for scenarios such as blocking traffic from known problematic networks or allowing access only from trusted partner networks. The ASN match statement provides flexibility in determining the client IP address through optional forwarded IP configuration, making it compatible with various network setups including those using content delivery networks (CDNs) or reverse proxies.

**Note**  
ASN matching supplements, but doesn't replace, standard authentication and authorization controls. We recommend that you implement authentication and authorization mechanisms, such as IAM, to verify the identity of all requests in your applications.

## How the ASN match statement works
<a name="waf-rule-statement-type-asn-match-how-it-works"></a>

AWS WAF determines the ASN of a request based on its IP address. By default, AWS WAF uses the IP address of the web request's origin. You can configure AWS WAF to use an IP address from an alternate request header, like `X-Forwarded-For`, by enabling forwarded IP configuration in the rule statement settings.

The ASN match statement compares the request's ASN against the list of ASNs specified in the rule. If the ASN matches one in the list, the statement evaluates to true, and the associated rule action is applied.

### Handling unmapped ASNs
<a name="waf-rule-statement-type-asn-match-unmapped"></a>

If AWS WAF cannot determine an ASN for a valid IP address, it assigns ASN 0. You can include ASN 0 in your rule to handle these cases explicitly.

### Fallback Behavior for Invalid IP Addresses
<a name="waf-rule-statement-type-asn-match-fallback"></a>

When you configure the ASN match statement to use forwarded IP addresses, you can specify a fallback behavior of *Match* or *No match* for requests with invalid or missing IP addresses in the designated header.

## Rule statement characteristics
<a name="waf-rule-statement-type-asn-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 1 WCU

This statement uses the following settings:
+ **ASN list** – An array of ASN numbers to compare for an ASN match. Valid values range from 0 to 4294967295. You can specify up to 100 ASNs for each rule.
+ **(Optional) Forwarded IP configuration** – By default, AWS WAF uses the IP address in the web request origin to determine the ASN. Alternatively, you can configure the rule to use a forwarded IP in an HTTP header like `X-Forwarded-For` instead. You specify whether to use the first, last, or any address in the header. 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 more information, see [Using forwarded IP addresses](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-forwarded-ip-address.html).

## Where to find this rule statement
<a name="waf-rule-statement-type-asn-match-where-to-find"></a>
+ **Rule builder** on the console – For **Request option**, choose **Originates from ASN in**.
+ **API** – [AsnMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_AsnMatchStatement.html)

## Examples
<a name="waf-rule-statement-type-asn-match-examples"></a>

This example blocks requests originating from two specific ASNs derived from an `X-Forwarded-For` header. If the IP address in the header is malformed, the configured fallback behavior is `NO_MATCH`.

```
{
  "Action": {
    "Block": {}
  },
  "Name": "AsnMatchStatementRule",
  "Priority": 1,
  "Statement": {
    "AsnMatchStatement": {
      "AsnList": [64496, 64500]
    },
    "ForwardedIPConfig": {
      "FallbackBehavior": "NO_MATCH",
      "HeaderName": "X-Forwarded-For"
    }
  },
  "VisibilityConfig": {
    "CloudWatchMetricsEnabled": true,
    "MetricName": "AsnMatchRuleMetrics",
    "SampledRequestsEnabled": true
  }
},
"VisibilityConfig": {
  "CloudWatchMetricsEnabled": true,
  "MetricName": "WebAclMetrics",
  "SampledRequestsEnabled": true
}
}
```

# Label match rule statement
<a name="waf-rule-statement-type-label-match"></a>

This section explains what a label match statement is and how it works.

The label match statement inspects the labels that are on the web request against a string specification. The labels that are available to a rule for inspection are those that have already been added to the web request by other rules in the same protection pack (web ACL) evaluation. 

Labels don't persist outside of the protection pack (web ACL) evaluation, but you can access label metrics in CloudWatch and you can see summaries of label information for any protection pack (web ACL) in the AWS WAF console. For more information, see [Label metrics and dimensions](waf-metrics.md#waf-metrics-label) and [Monitoring and tuning your AWS WAF protections](web-acl-testing-activities.md). You can also see labels in the logs. For information, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).

**Note**  
A label match statement can only see labels from rules that are evaluated earlier in the protection pack (web ACL). For information about how AWS WAF evaluates the rules and rule groups in a protection pack (web ACL), see [Setting rule priority](web-acl-processing-order.md).

For more information about adding and matching labels, see [Web request labeling in AWS WAF](waf-labels.md).

## Rule statement characteristics
<a name="label-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 1 WCU

This statement uses the following settings: 
+ **Match scope** – Set this to **Label** to match against the label name and, optionally, the preceding namespaces and prefix. Set this to **Namespace** to match against some or all of the namespace specifications and, optionally, the preceding prefix. 
+ **Key** – The string that you want to match against. If you specify a namespace match scope, this should only specify namespaces and optionally the prefix, with an ending colon. If you specify a label match scope, this must include the label name and can optionally include preceding namespaces and prefix. 

For more information about these settings, see [AWS WAF rules that match labels](waf-rule-label-match.md) and [AWS WAF label match examples](waf-rule-label-match-examples.md).

## Where to find this rule statement
<a name="label-match-where-to-find"></a>
+ **Rule builder** on the console – For **Request option**, choose **Has label**.
+ **API** – [LabelMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_LabelMatchStatement.html)

# Regex match rule statement
<a name="waf-rule-statement-type-regex-match"></a>

This section explains what a regex match statement is and how it works.

A regex match statement instructs AWS WAF to match a request component against a single regular expression (regex). A web request matches the statement if the request component matches the regex that you specify. 

This statement type is a good alternative to the [Regex pattern set match rule statement](waf-rule-statement-type-regex-pattern-set-match.md) for situations where you want to combine your matching criteria using mathematical logic. For example, if you want a request component to match against some regex patterns and to not match against others, you can combine the regex match statements using the [AND rule statement](waf-rule-statement-type-and.md) and the [NOT rule statement](waf-rule-statement-type-not.md). 

AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

## Rule statement characteristics
<a name="regex-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 3 WCUs, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

## Where to find this rule statement
<a name="regex-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, choose **Matches regular expression**.
+ **API** – [RegexMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_RegexMatchStatement.html)

# Regex pattern set match rule statement
<a name="waf-rule-statement-type-regex-pattern-set-match"></a>

This section explains what a regex pattern set match statement is and how it works.

The regex pattern set match inspects the part of the web request that you specify for the regular expression patterns that you've specified inside a regex pattern set.

AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

**Note**  
Each regex pattern set match rule references a regex pattern set, which you create and maintain independent of your rules. You can use a single regex pattern set in multiple rules, and when you update the referenced set, AWS WAF automatically updates all rules that reference it.   
For information about creating and managing a regex pattern set, see [Creating and managing a regex pattern set in AWS WAF](waf-regex-pattern-set-managing.md).

A regex pattern set match statement instructs AWS WAF to search for any of the patterns in the set inside the request component that you choose. A web request will match the pattern set rule statement if the request component matches any of the patterns in the set. 

If you want to combine your regex pattern matches using logic, for example to match against some regular expressions and not match against others, consider using [Regex match rule statement](waf-rule-statement-type-regex-match.md). 

## Rule statement characteristics
<a name="regex-pattern-set-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 25 WCUs, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

This statement requires the following settings: 
+ Regex pattern set specification – Choose the regex pattern set that you want to use from the list or create a new one. 

## Where to find this rule statement
<a name="regex-pattern-set-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, choose **String match condition** > **Matches pattern from regular expression set**.
+ **API** – [RegexPatternSetReferenceStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_RegexPatternSetReferenceStatement.html)

# Size constraint rule statement
<a name="waf-rule-statement-type-size-constraint-match"></a>

This section explains what a size constraint statement is and how it works.

A size constraint statement compares the number of bytes that AWS WAF receives for a web request component to a number that you provide, and matches according to your comparison criteria. 

The comparison criteria is an operator such as greater than (>) or less than (<). For example, you can match on requests that have a query string with a size that's greater than 100 bytes. 

If you inspect the URI path, any `/` in the path counts as one character. For example, the URI path `/logo.jpg` is nine characters long.

**Note**  
This statement only inspects the size of the web request component. It doesn't inspect the contents of the component. 

## Rule statement characteristics
<a name="size-constraint-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 1 WCU, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body. For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).

  A size constraint statement inspects only the size of the component after any transformations have been applied. It does not inspect the contents of the component. 
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting its size. For example, you could compress white space or decode HTML entities. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

Additionally, this statement requires the following settings: 
+ **Size match condition** – This indicates the numerical comparison operator to use to compare the size that you provide with the request component that you've chosen. Choose the operator from the list.
+ **Size** – The size setting, in bytes, to use in the comparison. 

## Where to find this rule statement
<a name="size-constraint-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, under **Size match condition**, choose the condition that you want to use.
+ **API** – [SizeConstraintStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_SizeConstraintStatement.html)

# SQL injection attack rule statement
<a name="waf-rule-statement-type-sqli-match"></a>

This section explains what a SQL injection rule statement is and how it works.

An SQL injection rule statement inspects for malicious SQL code. Attackers insert malicious SQL code into web requests in order to do things like modify your database or extract data from it.

## Rule statement characteristics
<a name="sqli-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – The base cost depends on the sensitivity level setting for the rule statement: Low costs 20 and High costs 30. 

If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

Additionally, this statement requires the following setting: 
+ **Sensitivity level** – This setting tunes the sensitivity of the SQL injection match criteria. The options are LOW and HIGH. The default setting is LOW. 

  The HIGH setting detects more SQL injection attacks, and is the recommended setting. Due to the higher sensitivity, this setting generates more false positives, especially if your web requests typically contain unusual strings. During your protection pack (web ACL) testing and tuning, you might need to do more work to mitigate false positives. For information, see [Testing and tuning your AWS WAF protections](web-acl-testing.md). 

  The lower setting provides less stringent SQL injection detection, which also results in fewer false positives. LOW can be a better choice for resources that have other protections against SQL injection attacks or that have a low tolerance for false positives. 

## Where to find this rule statement
<a name="sqli-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, choose **Attack match condition** > **Contains SQL injection attacks**.
+ **API** – [SqliMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_SqliMatchStatement.html)

# String match rule statement
<a name="waf-rule-statement-type-string-match"></a>

This section explains what a string match statement is and how it works.

A string match statement indicates the string that you want AWS WAF to search for in a request, where in the request to search, and how. For example, you can look for a specific string at the start of any query string in the request or as an exact match for the request's `User-agent` header. Usually, the string consists of printable ASCII characters, but you can use any character from hexadecimal 0x00 to 0xFF (decimal 0 to 255). 

## Rule statement characteristics
<a name="string-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – The base cost depends on the type of match that you use.
+ **Exactly matches string** – 2 
+ **Starts with string** – 2 
+ **Ends with string** – 2 
+ **Contains string** – 10 
+ **Contains word** – 10 

If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

Additionally, this statement requires the following settings: 
+ **String to match** – This is the string that you want AWS WAF to compare to the specified request component. Usually, the string consists of printable ASCII characters, but you can use any character from hexadecimal 0x00 to 0xFF (decimal 0 to 255).
+ **String match condition** – This indicates the search type that you want AWS WAF to perform. 
  + **Exactly matches string** – The string and the value of the request component are identical.
  + **Starts with string** – The string appears at the beginning of the request component. 
  + **Ends with string** – The string appears at the end of the request component. 
  + **Contains string** – The string appears anywhere in the request component. 
  + **Contains word** – The string that you specify must appear in the request component. 

    For this option, the string that you specify must contain only alphanumeric characters or underscore (A-Z, a-z, 0-9, or \$1). 

    One of the following must be true for the request to match: 
    + The string exactly matches the value of the request component, such as the value of a header.
    + The string is at the beginning of the request component and is followed by a character other than an alphanumeric character or underscore (\$1), for example, `BadBot;`.
    + The string is at the end of the request component and is preceded by a character other than an alphanumeric character or underscore (\$1), for example, `;BadBot`.
    + The string is in the middle of the request component and is preceded and followed by characters other than alphanumeric characters or underscore (\$1), for example, `-BadBot;`.

## Where to find this rule statement
<a name="string-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, choose **String match condition**, and then fill in the strings that you want to match against.
+ **API** – [ByteMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_ByteMatchStatement.html)

# Cross-site scripting attack rule statement
<a name="waf-rule-statement-type-xss-match"></a>

This section explains what an XSS (cross-site scripting) attack statement is and how it works.

An XSS attack statement inspects for malicious scripts in a web request component. In an XSS attack, the attacker uses vulnerabilities in a benign website as a vehicle to inject malicious client-site scripts into other legitimate web browsers. 

## Rule statement characteristics
<a name="xss-match-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – 40 WCUs, as a base cost. If you use the request component **All query parameters**, add 10 WCUs. If you use the request component **JSON body**, double the base cost WCUs. For each **Text transformation** that you apply, add 10 WCUs.

This statement type operates on a web request component, and requires the following request component settings: 
+ **Request component** – The part of the web request to inspect, for example, a query string or the body.
**Warning**  
If you inspect the request components **Body**, **JSON body**, **Headers**, or **Cookies**, read about the limitations on how much content AWS WAF can inspect at [Oversize web request components in AWS WAF](waf-oversize-request-components.md). 

  For information about web request components, see [Adjusting rule statement settings in AWS WAF](waf-rule-statement-fields.md).
+ **Optional text transformations** – Transformations that you want AWS WAF to perform on the request component before inspecting it. For example, you could transform to lowercase or normalize white space. If you specify more than one transformation, AWS WAF processes them in the order listed. For information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).

## Where to find this rule statement
<a name="xss-match-where-to-find"></a>
+ **Rule builder** on the console – For **Match type**, choose **Attack match condition** > **Contains XSS injection attacks**.
+ **API** – [XssMatchStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_XssMatchStatement.html)

# Using logical rule statements in AWS WAF
<a name="waf-rule-statements-logical"></a>

This section explains what a logical rule statement is and how it works.

Use logical rules statements to combine other statements or negate their results. Every logical rule statement takes at least one nested statement.

To logically combine or negate rule statement results, you nest the statements under logical rule statements. 

Logical rules statements are nestable. You can nest them inside other logical rule statements and use them in scope-down statements. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

**Note**  
The visual editor on the console supports one level of rule statement nesting, which works for many needs. To nest more levels, edit the JSON representation of the rule on the console or use the APIs. 

This table describes the logical rule statements and provides guidelines for calculating protection pack (web ACL) capacity units (WCU) usage for each. For information about WCUs, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md). 


| Logical Statement  | Description | WCUs | 
| --- | --- | --- | 
| [AND logic](waf-rule-statement-type-and.md) | Combines nested statements with AND logic. | Based on nested statements | 
|  [NOT logic](waf-rule-statement-type-not.md)  |  Negates the results of a nested statement.  |  Based on nested statement  | 
| [OR logic](waf-rule-statement-type-or.md) | Combines nested statements with OR logic. | Based on nested statements | 

# AND rule statement
<a name="waf-rule-statement-type-and"></a>

The AND rule statement combines nested statements with a logical AND operation, so all nested statements must match for the AND statement to match. This requires at least two nested statements. 

## Rule statement characteristics
<a name="and-rule-statement-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – Depends on the nested statements.

## Where to find this rule statement
<a name="and-rule-statement-where-to-find"></a>
+ **Rule builder** on the console – For **If a request**, choose **matches all the statements (AND)**, and then fill in the nested statements. 
+ **API** – [AndStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_AndStatement.html)

## Examples
<a name="and-rule-statement-examples"></a>

The following listing shows the use of AND and NOT logical rule statements to eliminate false positives from the matches for an SQL injection attack statement. For this example, suppose we can write a single byte match statement to match the requests that are resulting in false positives. 

The AND statement matches for requests that do not match the byte match statement and that do match the SQL injection attack statement. 

```
{
      "Name": "SQLiExcludeFalsePositives",
      "Priority": 0,
      "Statement": {
        "AndStatement": {
          "Statements": [
            {
              "NotStatement": {
                "Statement": {
                  "ByteMatchStatement": {
                    "SearchString": "string identifying a false positive",
                    "FieldToMatch": {
                      "Body": {
                        "OversizeHandling": "MATCH"
                      }
                    },
                    "TextTransformations": [
                      {
                        "Priority": 0,
                        "Type": "NONE"
                      }
                    ],
                    "PositionalConstraint": "CONTAINS"
                  }
                }
              }
            },
            {
              "SqliMatchStatement": {
                "FieldToMatch": {
                  "Body": {
                    "OversizeHandling": "MATCH"
                  }
                },
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                  }
                ]
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "SQLiExcludeFalsePositives"
      }
    }
```

Using the console rule visual editor, you can nest a non-logical statement or a NOT statement under an OR or AND statement. The nesting of the NOT statement is shown in the prior example. 

Using the console rule visual editor, you can nest most nestable statements under a logical rule statement, such as the one shown in the prior example. You can't use the visual editor to nest OR or AND statements. To configure this type of nesting, you need to provide your rule statement in JSON. For example, the following JSON rule listing includes an OR statement nested inside an AND statement. 

```
{
  "Name": "match_rule",
  "Priority": 0,
  "Statement": {
    "AndStatement": {
      "Statements": [
        {
          "LabelMatchStatement": {
            "Scope": "LABEL",
            "Key": "awswaf:managed:aws:bot-control:bot:category:monitoring"
          }
        },
        {
          "NotStatement": {
            "Statement": {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:managed:aws:bot-control:bot:name:pingdom"
              }
            }
          }
        },
        {
          "OrStatement": {
            "Statements": [
              {
                "GeoMatchStatement": {
                  "CountryCodes": [
                    "JM",
                    "JP"
                  ]
                }
              },
              {
                "ByteMatchStatement": {
                  "SearchString": "JCountryString",
                  "FieldToMatch": {
                    "Body": {}
                  },
                  "TextTransformations": [
                    {
                      "Priority": 0,
                      "Type": "NONE"
                    }
                  ],
                  "PositionalConstraint": "CONTAINS"
                }
              }
            ]
          }
        }
      ]
    }
  },
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "match_rule"
  }
}
```

# NOT rule statement
<a name="waf-rule-statement-type-not"></a>

The NOT rule statement logically negates the results of a single nested statement, so the nested statements must not match for the NOT statement to match, and vice versa. This requires one nested statement. 

For example, if you want to block requests that don't originate in a specific country, create a NOT statement with action set to block, and nest a geographic match statement that specifies the country. 

## Rule statement characteristics
<a name="not-rule-statement-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – Depends on the nested statement.

## Where to find this rule statement
<a name="not-rule-statement-where-to-find"></a>
+ **Rule builder** on the console – For **If a request**, choose **doesn't match the statement (NOT)**, and then fill in the nested statement.
+ **API** – [NotStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_NotStatement.html)

# OR rule statement
<a name="waf-rule-statement-type-or"></a>

The OR rule statement combines nested statements with OR logic, so one of the nested statements must match for the OR statement to match. This requires at least two nested statements. 

For example, if you want to block requests that come from a specific country or that contain a specific query string, you could create an OR statement and nest in it a geo match statement for the country and a string match statement for the query string. 

If instead you want to block requests that *don't* come from a specific country or that contain a specific query string, you would modify the previous OR statement to nest the geo match statement one level lower, inside a NOT statement. This level of nesting requires you to use the JSON formatting, because the console supports only one level of nesting.

## Rule statement characteristics
<a name="or-rule-statement-characteristics"></a>

**Nestable** – You can nest this statement type. 

**WCUs** – Depends on the nested statements.

## Where to find this rule statement
<a name="or-rule-statement-where-to-find"></a>
+ **Rule builder** on the console – For **If a request**, choose **matches at least one of the statements (OR)**, and then fill in the nested statements. 
+ **API** – [OrStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_OrStatement.html)

**Examples**  
The following listing shows the use of OR to combine two other statements. The OR statement is a match if either of the nested statements match. 

```
{
  "Name": "neitherOfTwo",
  "Priority": 1,
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "neitherOfTwo"
  },
  "Statement": {
    "OrStatement": {
      "Statements": [
        {
          "GeoMatchStatement": {
            "CountryCodes": [
              "CA"
            ]
          }
        },
        {
          "IPSetReferenceStatement": {
            "ARN": "arn:aws:wafv2:us-east-1:111111111111:regional/ipset/test-ip-set-22222222/33333333-4444-5555-6666-777777777777"
          }
        }
      ]
    }
  }
}
```

Using the console rule visual editor, you can nest most nestable statements under a logical rule statement, but you can't use the visual editor to nest OR or AND statements. To configure this type of nesting, you need to provide your rule statement in JSON. For example, the following JSON rule listing includes an OR statement nested inside an AND statement. 

```
{
  "Name": "match_rule",
  "Priority": 0,
  "Statement": {
    "AndStatement": {
      "Statements": [
        {
          "LabelMatchStatement": {
            "Scope": "LABEL",
            "Key": "awswaf:managed:aws:bot-control:bot:category:monitoring"
          }
        },
        {
          "NotStatement": {
            "Statement": {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:managed:aws:bot-control:bot:name:pingdom"
              }
            }
          }
        },
        {
          "OrStatement": {
            "Statements": [
              {
                "GeoMatchStatement": {
                  "CountryCodes": [
                    "JM",
                    "JP"
                  ]
                }
              },
              {
                "ByteMatchStatement": {
                  "SearchString": "JCountryString",
                  "FieldToMatch": {
                    "Body": {}
                  },
                  "TextTransformations": [
                    {
                      "Priority": 0,
                      "Type": "NONE"
                    }
                  ],
                  "PositionalConstraint": "CONTAINS"
                }
              }
            ]
          }
        }
      ]
    }
  },
  "Action": {
    "Block": {}
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "match_rule"
  }
}
```

# Using rate-based rule statements in AWS WAF
<a name="waf-rule-statement-type-rate-based"></a>

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 name="waf-rule-statement-type-rate-based-high-level-settings"></a>

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
<a name="waf-rule-statement-type-rate-based-caveats"></a>

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
<a name="waf-rule-statement-type-rate-based-aggregation-options"></a>

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
<a name="waf-rule-statement-type-rate-based-aggregation-instances"></a>

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
<a name="waf-rule-statement-type-rate-based-request-limiting"></a>

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
<a name="waf-rule-statement-type-rate-based-examples"></a>

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
<a name="waf-rate-based-example-limit-login-page"></a>

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
<a name="waf-rate-based-example-limit-login-page-keys"></a>

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
<a name="waf-rate-based-example-limit-missing-header"></a>

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
<a name="waf-rate-based-example-limit-labels"></a>

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
<a name="waf-rate-based-example-limit-label-aggregation"></a>

**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
<a name="waf-rate-based-example-limit-asn"></a>

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
<a name="listing-managed-ips"></a>

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
```

# Using rule group rule statements in AWS WAF
<a name="waf-rule-statements-rule-group"></a>

**Note**  
Rule group rule statements are not nestable. 

This section describes the rule group rule statements that you can use in your protection pack (web ACL). Rule group protection pack (web ACL) capacity units (WCUs) are set by the rule group owner at the time of creation. For information about WCUs, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md). 


| Rule group statement | Description | WCUs | 
| --- | --- | --- | 
|  [Using managed rule group statements](waf-rule-statement-type-managed-rule-group.md)  |  Runs the rules that are defined in the specified managed rule group.  You can narrow the scope of requests that the rule group evaluates by adding a scope-down statement.  You can't nest a managed rule group statement inside any other statement type.  |  Defined by the rule group, plus any additional WCUs for a scope-down statement.  | 
| [Using rule group statements](waf-rule-statement-type-rule-group.md) | Runs the rules that are defined in a rule group that you manage.  You can't add a scope-down statement to a rule group reference statement for your own rule group.  You can't nest a rule group statement inside any other statement type  | You define the WCU limit for the rule group when you create it. | 

# Using managed rule group statements in AWS WAF
<a name="waf-rule-statement-type-managed-rule-group"></a>

This section explains how managed rule group rule statements work.

The managed rule group rule statement adds a reference in your protection pack (web ACL) rules list to a managed rule group. You don't see this option under your rule statements on the console, but when you work with the JSON format of your web ACL, any managed rule groups that you've added show up under the protection pack (web ACL) rules as this type.

A managed rule group is either an AWS Managed Rules rule group, most of which are free for AWS WAF customers, or an AWS Marketplace managed rule group. You automatically subscribe to the paid AWS Managed Rules rule groups when you add them to your protection pack (web ACL). You can subscribe to AWS Marketplace managed rule groups through AWS Marketplace. For more information, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md).

When you add a rule group to a protection pack (web ACL), you can override the actions of rules in the group to Count or to another rule action. For more information, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md).

You can narrow the scope of the requests that AWS WAF evaluates with the rule group. To do this, you add a scope-down statement inside the rule group statement. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md). This can help you manage how the rule group affects your traffic and can help you contain costs associated with traffic volume when you use the rule group. For information and examples for using scope-down statements with the AWS WAF Bot Control managed rule group, see [AWS WAF Bot Control](waf-bot-control.md).

## Rule statement characteristics
<a name="managed-rule-group-rule-statement-characteristics"></a>

**Not nestable** – You can't nest this statement type inside other statements, and you can't include it in a rule group. You can include it directly in a protection pack (web ACL). 

**(Optional) Scope-down statement** – This rule type takes an optional scope-down statement, to narrow the scope of the requests that the rule group evaluates. For more information, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

**WCUs** – Set for the rule group at creation.

## Where to find this rule statement
<a name="managed-rule-group-rule-statement-where-to-find"></a>
+ **Console** – During the process of creating a protection pack (web ACL), on the **Add rules and rule groups** page, choose **Add managed rule groups**, and then find and select the rule group that you want to use.
+ **API** – [ManagedRuleGroupStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_ManagedRuleGroupStatement.html)

# Using rule group statements in AWS WAF
<a name="waf-rule-statement-type-rule-group"></a>

This section explains how rule group rule statements work.

The rule group rule statement adds a reference to your protection pack (web ACL) rules list to a rule group that you manage. You don't see this option under your rule statements on the console, but when you work with the JSON format of your protection pack (web ACL), any of your own rule groups that you've added show up under the protection pack (web ACL) rules as this type. For information about using your own rule groups, see [Managing your own rule groups](waf-user-created-rule-groups.md).

When you add a rule group to a protection pack (web ACL), you can override the actions of rules in the group to Count or to another rule action. For more information, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md).

## Rule statement characteristics
<a name="rule-group-rule-statement-characteristics"></a>

**Not nestable** – You can't nest this statement type inside other statements, and you can't include it in a rule group. You can include it directly in a protection pack (web ACL). 

**WCUs** – Set for the rule group at creation.

## Where to find this rule statement
<a name="rule-group-rule-statement-where-to-find"></a>
+ **Console** – During the process of creating a protection pack (web ACL), on the **Add rules and rule groups** page, choose **Add my own rules and rule groups**, **Rule group**, and then add the rule group that you want to use.
+ **API** – [RuleGroupReferenceStatement](https://docs.aws.amazon.com/waf/latest/APIReference/API_RuleGroupReferenceStatement.html)

# AWS WAF rule groups
<a name="waf-rule-groups"></a>

This section explains what a rule group is and how it works.

A rule group is a reusable set of rules that you can add to a protection pack (web ACL). For more information about protection packs (web ACLs), see [Configuring protection in AWS WAF](web-acl.md).

Rule groups fall into the following main categories: 
+ Your own rule groups, which you create and maintain. 
+ Managed rule groups that AWS Managed Rules teams create and maintain for you. 
+ Managed rule groups that AWS Marketplace sellers create and maintain for you. 
+ Rule groups that are owned and managed by other services like AWS Firewall Manager and Shield Advanced.

**Differences between rule groups and protection packs (web ACLs)**  
Rule groups and protection packs (web ACLs) both contain rules, which are defined in the same manner in both places. Rule groups differ from protection packs (web ACLs) in the following ways: 
+ Rule groups can't contain rule group reference statements. 
+ You can reuse a single rule group in multiple protection packs (web ACLs) by adding a rule group reference statement to each protection pack (web ACL). You can't reuse a protection pack (web ACL).
+ Rule groups don't have default actions. In a protection pack (web ACL), you set a default action for each rule or rule group that you include. Each individual rule inside a rule group or protection pack (web ACL) has an action defined. 
+ You don't directly associate a rule group with an AWS resource. To protect resources using a rule group, you use the rule group in a protection pack (web ACL). 
+ The system defines a maximum capacity of 5,000 protection pack (web ACL) capacity units (WCUs) for each protection pack (web ACL). Each rule group has a WCU setting that must be set at creation. You can use this setting to calculate the additional capacity requirements that using a rule group would add to your protection pack (web ACL). For more information about WCUs, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md).

For information about rules, see [AWS WAF rules](waf-rules.md).

This section provides guidance for creating and managing your own rule groups, describes the managed rule groups that are available to you, and provides guidance for using managed rule groups. 

**Topics**
+ [

# Using managed rule groups in AWS WAF
](waf-managed-rule-groups.md)
+ [

# Managing your own rule groups
](waf-user-created-rule-groups.md)
+ [

# AWS Marketplace rule groups
](marketplace-rule-groups.md)
+ [

# Recognizing rule groups provided by other services
](waf-service-owned-rule-groups.md)

# Using managed rule groups in AWS WAF
<a name="waf-managed-rule-groups"></a>

This section explains what managed rule groups are and how they work.

Managed rule groups are collections of predefined, ready-to-use rules that AWS and AWS Marketplace sellers write and maintain for you. Basic AWS WAF pricing applies to your use of any managed rule group. For AWS WAF pricing information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).
+ *The AWS Managed Rules rule groups for AWS WAF Bot Control, AWS WAF Fraud Control account takeover prevention (ATP), and AWS WAF Fraud Control account creation fraud prevention (ACFP)* are available for additional fees, beyond the basic AWS WAF charges. For pricing details, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). 
+ *All other AWS Managed Rules rule groups* are available to AWS WAF customers at no additional cost. 
+ *AWS Marketplace rule groups* are available by subscription through AWS Marketplace. Each of these rule groups is owned and managed by the AWS Marketplace seller. For pricing information to use an AWS Marketplace rule group, contact the AWS Marketplace seller. 

Some managed rule groups are designed to help protect specific types of web applications like WordPress, Joomla, or PHP. Others offer broad protection against known threats or common web application vulnerabilities, including some of the ones listed in the [OWASP Top 10](https://owasp.org/www-project-top-ten/). If you're subject to regulatory compliance like PCI or HIPAA, you might be able to use managed rule groups to satisfy web application firewall requirements.

**Automatic updates**  
Keeping up to date on the constantly changing threat landscape can be time consuming and expensive. Managed rule groups can save you time when you implement and use AWS WAF. Many AWS and AWS Marketplace sellers automatically update managed rule groups and provide new versions of rule groups when new vulnerabilities and threats emerge. 

In some cases, AWS is notified of new vulnerabilities before public disclosure, due to its participation in a number of private disclosure communities. In those cases, AWS can update the AWS Managed Rules rule groups and deploy them for you even before a new threat is widely known. 

**Restricted access to rules in a managed rule group**  
Each managed rule group provides a comprehensive description of the types of attacks and vulnerabilities that it's designed to protect against. To protect the intellectual property of the rule group providers, you can't view all of the details for the individual rules within a rule group. This restriction also helps to keep malicious users from designing threats that specifically circumvent published rules.

**Topics**
+ [

# Using versioned managed rule groups in AWS WAF
](waf-managed-rule-groups-versioning.md)
+ [

# Working with managed rule groups
](waf-using-managed-rule-groups.md)
+ [

# AWS Managed Rules for AWS WAF
](aws-managed-rule-groups.md)

# Using versioned managed rule groups in AWS WAF
<a name="waf-managed-rule-groups-versioning"></a>

This section explains how versioning is handled for managed rule groups.

Many managed rule group providers use versioning to update a rule group's options and capabilities. Usually, a specific version of a managed rule group is static. Occasionally, a provider might need to update some or all of the static versions of a managed rule group, for example, to respond to an emerging security threat. 

When you use a versioned managed rule group in your protection pack (web ACL), you can select the default version and let the provider manage which static version you use, or you can select a specific static version. 

**Can't find the version you want?**  
If you don't see a version in a rule group's version listing, the version is probably scheduled for expiration or already expired. After a version is scheduled for expiration, AWS WAF no longer lets you to choose it for the rule group. 

**SNS notifications for AWS Managed Rules rule groups**  
The AWS Managed Rules rule groups all provide versioning and SNS update notifications except for the IP reputation rule groups. The AWS Managed Rules rule groups that provide notifications all use the same SNS topic Amazon Resource Name (ARN). To sign up for SNS notifications, see [Getting notified of new versions and updates](waf-using-managed-rule-groups-sns-topic.md).

**Topics**
+ [

# Version life cycle for managed rule groups
](waf-managed-rule-groups-versioning-lifecycle.md)
+ [

# Version expiration for managed rule groups
](waf-managed-rule-groups-versioning-expiration.md)
+ [

# Best practices for handling managed rule group versions
](waf-managed-rule-groups-best-practice.md)

# Version life cycle for managed rule groups
<a name="waf-managed-rule-groups-versioning-lifecycle"></a>

Providers handle the following life cycle stages of a managed rule group static version: 
+ **Release and updates** – A managed rule group provider announces upcoming and new static versions of their managed rule groups through notifications to an Amazon Simple Notification Service (Amazon SNS) topic. Providers might also use the topic to communicate other important information about their rule groups, such as urgent required updates. 

  You can subscribe to the rule group's topic and configure how you want to receive notifications. For more information see [Getting notified of new versions and updates](waf-using-managed-rule-groups-sns-topic.md).
+ **Expiration scheduling** – A managed rule group provider schedules older versions of a rule group for expiration. A version that's scheduled to expire cannot be added to your protection pack (web ACL) rules. After expiration is scheduled for a version, AWS WAF tracks the expiration with a countdown metric in Amazon CloudWatch. 
+ **Version expiration** – If you have a protection pack (web ACL) configured to use an expired version of a managed rule group, then during protection pack (web ACL) evaluation, AWS WAF uses the rule group's default version. Additionally, AWS WAF blocks any updates to the protection pack (web ACL) that don't either remove the rule group or change its version to an unexpired one.

If you use AWS Marketplace managed rule groups, ask the provider for any additional information about version life cycles. 

# Version expiration for managed rule groups
<a name="waf-managed-rule-groups-versioning-expiration"></a>

 This section explains how version expiration works for a versioned managed rule group.

If you use a specific version of a rule group, make sure that you don't keep using a version past its expiration date. You can monitor version expiration through the rule group's SNS notifications and through Amazon CloudWatch metrics. 

If a version that you're using in a protection pack (web ACL) is expired, AWS WAF blocks any updates to the protection pack (web ACL) that don't include moving the rule group to an unexpired version. You can update the rule group to an available version or remove it from your protection pack (web ACL). 

Expiration handling for a managed rule group depends on the rule group provider. For AWS Managed Rules rule groups, an expired version is automatically changed to the rule group's default version. For AWS Marketplace rule groups, ask the provider how they handle expiration.

When the provider creates a new version of the rule group, it sets the version's forecasted lifetime. While the version isn't scheduled to expire, the Amazon CloudWatch metric value is set to the forecasted lifetime setting, and in CloudWatch, you'll see a flat value for the metric. After the provider schedules the metric to expire, the metric value diminishes each day until it reaches zero on the day of expiration. For information about monitoring expiration, see [Tracking version expiration](waf-using-managed-rule-groups-expiration.md).

# Best practices for handling managed rule group versions
<a name="waf-managed-rule-groups-best-practice"></a>

Follow this best practice guidance for handling versioning when you use a versioned managed rule group.

When you use a managed rule group in your protection pack (web ACL), you can choose to use a specific, static version of the rule group, or you can choose to use the default version: 
+ **Default version** – AWS WAF always sets the default version to the static version that's currently recommended by the provider. When the provider updates their recommended static version, AWS WAF automatically updates the default version setting for the rule group in your protection pack (web ACL). 

  When you use the default version of a managed rule group, do the following as best practice: 
  + **Subscribe to notifications** – Subscribe to notifications for changes to the rule group and keep an eye on those. Most providers send advanced notification of new static versions and of default version changes. These let you check the effects of a new static version before AWS switches the default version to it. For more information see [Getting notified of new versions and updates](waf-using-managed-rule-groups-sns-topic.md).
  + **Review the effects of static version settings and make adjustments as needed before your default is set to it** – Before your default is set to a new static version, review the effects of the static version on the monitoring and management of your web requests. The new static version might have new rules to review. Look for false positives or other unexpected behavior, in case you need to modify how you use the rule group. You can set rules to count, for example, to stop them from blocking traffic while you figure out how you want to handle the new behavior. For more information, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).
+ **Static version** – If you choose to use a static version, you must manually update the version setting when you're ready to adopt a new version of the rule group. 

  When you use a static version of a managed rule group, do the following as best practice: 
  + **Keep your version up to date** – Keep your managed rule group as close as you can to the latest version. When a new version is released, test it, adjust settings as needed, and implement it in a timely manner. For information about testing, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).
  + **Subscribe to notifications** – Subscribe to notifications for changes to the rule group, so you know when your provider releases new static versions. Most providers give advanced notification of version changes. Additionally, your provider might need to update the static version that you're using to close a security loophole or for other urgent reasons. You'll know what's happening if you're subscribed to the provider's notifications. For more information, see [Getting notified of new versions and updates](waf-using-managed-rule-groups-sns-topic.md).
  + **Avoid version expiration** – Don't allow a static version to expire while you're using it. Provider handling of expired versions can vary and might include forcing an upgrade to an available version or other changes that can have unexpected consequences. Track the AWS WAF expiry metric and set an alarm that gives you a sufficient number of days to successfully upgrade to a supported version. For more information, see [Tracking version expiration](waf-using-managed-rule-groups-expiration.md).



# Working with managed rule groups
<a name="waf-using-managed-rule-groups"></a>

This section provides guidance for accessing and managing your managed rule groups. 

When you add a managed rule group to your protection pack (web ACL), you can choose the same configuration options as you can your own rule groups, plus additional settings. 

Through the console, you access managed rule group information during the process of adding and editing the rules in your protection packs (web ACLs). Through the APIs and the command line interface (CLI), you can directly request managed rule group information.

When you use a managed rule group in your protection pack (web ACL), you can edit the following settings: 
+ **Version** – This is available only if the rule group is versioned. For more information, see [Using versioned managed rule groups in AWS WAF](waf-managed-rule-groups-versioning.md).
+ **Override rule actions** – You can override the actions for rules in the rule group to any action. Setting them to Count is useful for testing a rule group before using it to manage your web requests. For more information, see [Rule group rule action overrides](web-acl-rule-group-override-options.md#web-acl-rule-group-override-options-rules).
+ **Scope-down statement** – You can add a scope-down statement, to filter out web requests that you don't want to evaluate with the rule group. For more information, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).
+ **Override rule group action** – You can override the action that results from the rule group evaluation, and set it to Count only. This option isn't commonly used. It doesn't alter how AWS WAF evaluates the rules in the rule group. For more information, see [Rule group return action override to Count](web-acl-rule-group-override-options.md#web-acl-rule-group-override-options-rule-group).

**To edit the managed rule group settings in your protection pack (web ACL)**
+ **Console** 
  + (Option) When you add the managed rules group to your protection pack (web ACL), you can choose **Edit** to view and edit the settings. 
  + (Option) After you've added the managed rule group into your protection pack (web ACL), from the **protection packs (web ACLs)** page, choose the protection pack (web ACL) you just created. This takes you to the protection pack (web ACL) edit page. 
    + Choose **Rules**. 
    + Select the rule group, then choose **Edit** to view and edit the settings. 
+ **APIs and CLI** – Outside of the console, you can manage the managed rule group settings when you create and update the protection pack (web ACL). 

# Retrieving the list of managed rule groups
<a name="waf-using-managed-rule-groups-list"></a>

You can retrieve the list of managed rule groups that are available for you to use in your protection packs (web ACLs). The list includes the following: 
+ All AWS Managed Rules rule groups.
+ The AWS Marketplace rule groups that you have subscribed to. 
**Note**  
For information about subscribing to AWS Marketplace rule groups, see [AWS Marketplace rule groups](marketplace-rule-groups.md).

When you retrieve the list of managed rule groups, the list you get back depends on the interface that you're using: 
+ **Console** – Through the console, you can see all managed rule groups, including the AWS Marketplace rule groups that you haven't subscribed to yet. For the ones that you haven't subscribed to yet, the interface provides links that you can follow to subscribe. 
+ **APIs and CLI** – Outside of the console, your request returns only the rule groups that are available for you to use. 

**To retrieve the list of managed rule groups**
+ **Console** – During the process of creating a web ACL, on the **Add rules and rule groups** page, choose **Add managed rule groups**. At the top level, the provider names are listed. Expand each provider listing to see the list of managed rule groups. For versioned rule groups, the information shown at this level is for the default version. When you add a managed rule group to your protection pack (web ACL), the console lists it based on the naming scheme `<Vendor Name>-<Managed Rule Group Name>`. 
+ **API** –
  +  `ListAvailableManagedRuleGroups`
+ **CLI** –
  + `aws wafv2 list-available-managed-rule-groups --scope=<CLOUDFRONT|REGIONAL>`

# Retrieving the rules in a managed rule group
<a name="waf-using-managed-rule-groups-rules"></a>

You can retrieve a list of the rules in a managed rule group. The API and CLI calls return the rules specifications that you can reference in the JSON model or through AWS CloudFormation.

**To retrieve the list of rules in a managed rule group**
+ **Console** 
  + (Option) When you add the managed rules group to your protection pack (web ACL), you can choose **Edit** to view the rules. 
  + (Option) After you've added the managed rule group into your protection pack (web ACL), from the **protection packs (web ACLs)** page, choose the protection pack (web ACL) you just created. This takes you to the protection pack (web ACL) edit page. 
    + Choose **Rules**. 
    + Select the rule group you want to see a rules list for, then choose **Edit**. AWS WAF shows the list of rules in the rule group. 
+ **API** – `DescribeManagedRuleGroup`
+ **CLI** – `aws wafv2 describe-managed-rule-group --scope=<CLOUDFRONT|REGIONAL> --vendor-name <vendor> --name <managedrule_name>`

# Retrieving the available versions for a managed rule group
<a name="waf-using-managed-rule-groups-versions"></a>

The available versions of a managed rule group are versions that haven't yet been scheduled to expire. The list indicates which version is the current default version for the rule group.

**To retrieve a list of the available versions of a managed rule group**
+ **Console** 
  + (Option) When you add the managed rule group to your protection pack (web ACL), choose **Edit** to see the rule group's information. Expand the **Version** dropdown to see the list of available versions. 
  + (Option) After you've added the managed rule group into your protection pack (web ACL), choose **Edit** on the protection pack (web ACL), and then select and edit the rule group rule. Expand the **Version** dropdown to see the list of available versions. 
+ **API** –
  +  `ListAvailableManagedRuleGroupVersions`
+ **CLI** –
  +  `aws wafv2 list-available-managed-rule-group-versions --scope=<CLOUDFRONT|REGIONAL> --vendor-name <vendor> --name <managedrule_name>`

# Adding a managed rule group to a protection pack (web ACL) through the console
<a name="waf-using-managed-rule-group"></a>

This section explains how to add a managed rule group to a protection pack (web ACL) through the console. This guidance applies to all AWS Managed Rules rule groups and to the AWS Marketplace rule groups that you're subscribed to. 

**Production traffic risk**  
Before you deploy changes in your protection pack (web ACL) for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**To add a managed rule group to a protection pack (web ACL) through the console**

**To add a managed rule group to a web ACL through the console**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choose **protection packs (web ACLs)** in the navigation pane. 

1. In the **protection packs (web ACLs)** page, from the list of protection packs (web ACLs), select the one that you want to add the rule group to. This takes you to the page for the single protection pack (web ACL).

1. In your protection pack (web ACL)'s page, choose the **Rules** tab. 

1. In the **Rules** pane, choose **Add rules**, then choose **Add managed rule groups**. 

1. In the **Add managed rule groups** page, expand the selection for your rule group vendor, to see the list of available rule groups. 

1. For each rule group that you want to add, choose **Add to protection pack (web ACL)**. If you want to change the protection pack (web ACL)'s configuration for the rule group, choose **Edit**, make your changes, and then choose **Save rule**. For information about the options, see the versioning guidance at [Using versioned managed rule groups in AWS WAF](waf-managed-rule-groups-versioning.md) and the guidance for using a managed rule group in a protection pack (web ACL) at [Using managed rule group statements in AWS WAF](waf-rule-statement-type-managed-rule-group.md).

1. At the bottom of the **Add managed rule groups** page, choose **Add rules**. 

1. In the **Set rule priority** page, adjust the order that the rules run as needed, then choose **Save**. For more information, see [Setting rule priority](web-acl-processing-order.md). 

In your protection pack (web ACL)'s page, the managed rule groups that you've added are listed under the **Rules** tab. 

Test and tune any changes to your AWS WAF protections before you use them for production traffic. For information, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

# Getting notified of new versions and updates to a managed rule group
<a name="waf-using-managed-rule-groups-sns-topic"></a>

This section explains how to receive Amazon SNS notifications of new versions and updates.

A managed rule group provider uses SNS notifications to announce rule group changes, like upcoming new versions and urgent security updates. 

**How to subscribe to SNS notifications**  
To subscribe to notifications for a rule group, you create an Amazon SNS subscription for the rule group's Amazon SNS topic ARN in the US East (N. Virginia) Region us-east-1. 

For information about how to subscribe, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/). 

**Note**  
Create your subscription for the SNS topic only in the us-east-1 Region.

The versioned AWS Managed Rules rule groups all use the same SNS topic Amazon Resource Name (ARN). For more information about AWS Managed Rules rule group notifications, see [Deployment notifications](waf-managed-rule-groups-deployments-notifications.md).

**Where to find the Amazon SNS topic ARN for a managed rule group**  
AWS Managed Rules rule groups use a single SNS topic ARN, so you can retrieve the topic ARN from one of the rule groups and subscribe to it to get notifications for all of the AWS Managed Rules rule groups that provide SNS notifications. 
+ **Console** 
  + (Option) When you add the managed rule group to your protection pack (web ACL), choose **Edit** to see the rule group's information, which includes the rule group's Amazon SNS topic ARN. 
  + (Option) After you've added the managed rule group into your protection pack (web ACL), choose **Edit** on the protection pack (web ACL), and then select and edit the rule group rule to see the rule group's Amazon SNS topic ARN. 
+ **API** – `DescribeManagedRuleGroup`
+ **CLI** – `aws wafv2 describe-managed-rule-group --scope=<CLOUDFRONT|REGIONAL> --vendor-name <vendor> --name <managedrule_name>`

For general information about Amazon SNS notification formats and how to filter the notifications that you receive, see [Parsing message formats](https://docs.aws.amazon.com/sns/latest/dg/sns-message-and-json-formats.html) and [Amazon SNS subscription filter policies](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html) in the Amazon Simple Notification Service Developer Guide. 

# Tracking a rule group's version expiration
<a name="waf-using-managed-rule-groups-expiration"></a>

This section explains how to monitor expiration scheduling for a managed rule group through Amazon CloudWatch.

If you use a specific version of a rule group, make sure that you don't keep using a version past its expiration date. 

**Tip**  
Sign up for Amazon SNS notifications for managed rule groups, and keep current with managed rule group versions. You'll benefit from the most up-to-date protections from the rule group and stay ahead of expiration. For information, see [Getting notified of new versions and updates](waf-using-managed-rule-groups-sns-topic.md).

**To monitor expiration scheduling for a managed rule group through Amazon CloudWatch**

1. In CloudWatch, locate the expiry metrics from AWS WAF for your managed rule group. The metrics have the following metric names and dimensions: 
   + Metric name: DaysToExpiry
   + Metric dimensions: Region, ManagedRuleGroup, Vendor, and Version

   If you have a managed rule group in your protection pack (web ACL) that's evaluating traffic, you will get a metric for it. The metric isn't available for rule groups that you don't use. 

1. Set an alarm on the metrics that you're interested in, so that you're notified in time to switch to a newer version of the rule group. 

For information about using Amazon CloudWatch metrics and configuring alarms, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). 

# Example managed rule group configurations in JSON and YAML
<a name="waf-using-managed-rule-groups-json-yaml"></a>

This section provides example managed rule group configurations.

The API and CLI calls return a list of all rules in the managed rule group that you can reference in the JSON model or through AWS CloudFormation.

**JSON**  
You can reference and modify managed rule groups within a rule statement using JSON. The following listing shows the AWS Managed Rules rule group, `AWSManagedRulesCommonRuleSet`, in JSON format. The RuleActionOverrides specification lists a rule whose action has been overridden to Count. 

```
{
    "Name": "AWS-AWSManagedRulesCommonRuleSet",
    "Priority": 0,
    "Statement": {
      "ManagedRuleGroupStatement": {
        "VendorName": "AWS",
        "Name": "AWSManagedRulesCommonRuleSet",
        "RuleActionOverrides": [                                                                                                                                            
          {                                                                                                                                                                
            "ActionToUse": {                                                                                                                                              
              "Count": {}                                                                                                                                                
            },                                                                                                                                                            
            "Name": "NoUserAgent_HEADER"                                                                                                                                 
          }                                                                                                                                                                
        ],
        "ExcludedRules": []
      }
    },
    "OverrideAction": {
      "None": {}
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSManagedRulesCommonRuleSet"
    }
}
```

**YAML**  
You can reference and modify managed rule groups within a rule statement using the CloudFormation YAML template. The following listing shows the AWS Managed Rules rule group, `AWSManagedRulesCommonRuleSet`, in CloudFormation template. The RuleActionOverrides specification lists a rule whose action has been overridden to Count. 

```
Name: AWS-AWSManagedRulesCommonRuleSet
Priority: 0
Statement:
  ManagedRuleGroupStatement:
    VendorName: AWS
    Name: AWSManagedRulesCommonRuleSet
    RuleActionOverrides:
    - ActionToUse:
        Count: {}
      Name: NoUserAgent_HEADER
    ExcludedRules: []
OverrideAction:
  None: {}
VisibilityConfig:
  SampledRequestsEnabled: true
  CloudWatchMetricsEnabled: true
  MetricName: AWS-AWSManagedRulesCommonRuleSet
```

# AWS Managed Rules for AWS WAF
<a name="aws-managed-rule-groups"></a>

This section explains what AWS Managed Rules for AWS WAF is.

AWS Managed Rules for AWS WAF is a managed service that provides protection against application vulnerabilities or other unwanted traffic. You have the option of selecting one or more rule groups from AWS Managed Rules for each web ACL, up to the maximum protection pack (web ACL) capacity unit (WCU) limit. 

**Mitigating false positives and testing rule group changes**  
Before using any managed rule group in production, test it in a non-production environment according to the guidance at [Testing and tuning your AWS WAF protections](web-acl-testing.md). Follow the testing and tuning guidance when you add a rule group to your protection pack (web ACL), to test a new version of a rule group, and whenever a rule group isn't handling your web traffic as you need it to. 

**Shared security responsibilities**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

**Important**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

# AWS Managed Rules rule groups list
<a name="aws-managed-rule-groups-list"></a>

This section provides a list of available AWS Managed Rules rule groups.

This section describes the most recent versions of the AWS Managed Rules rule groups. You see these on the console when you add a managed rule group to your protection pack (web ACL). Through the API, you can retrieve this list along with the AWS Marketplace rule groups that you're subscribed to by calling `ListAvailableManagedRuleGroups`. 

**Note**  
For information about retrieving an AWS Managed Rules rule group's versions, see [Retrieving the available versions for a managed rule group](waf-using-managed-rule-groups-versions.md). 

All AWS Managed Rules rule groups support labeling, and the rule listings in this section include label specifications. You can retrieve the labels for a managed rule group through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the AvailableLabels property in the response. For information about labeling, see [Web request labeling in AWS WAF](waf-labels.md).

Test and tune any changes to your AWS WAF protections before you use them for production traffic. For information, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Contents**
+ [

# Baseline rule groups
](aws-managed-rule-groups-baseline.md)
  + [

## Core rule set (CRS) managed rule group
](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs)
  + [

## Admin protection managed rule group
](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-admin)
  + [

## Known bad inputs managed rule group
](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)
+ [

# Use-case specific rule groups
](aws-managed-rule-groups-use-case.md)
  + [

## SQL database managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-sql-db)
  + [

## Linux operating system managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os)
  + [

## POSIX operating system managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os)
  + [

## Windows operating system managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-windows-os)
  + [

## PHP application managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-php-app)
  + [

## WordPress application managed rule group
](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-wordpress-app)
+ [

# IP reputation rule groups
](aws-managed-rule-groups-ip-rep.md)
  + [

## Amazon IP reputation list managed rule group
](aws-managed-rule-groups-ip-rep.md#aws-managed-rule-groups-ip-rep-amazon)
  + [

## Anonymous IP list managed rule group
](aws-managed-rule-groups-ip-rep.md#aws-managed-rule-groups-ip-rep-anonymous)
+ [

# AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group
](aws-managed-rule-groups-acfp.md)
  + [

## Considerations for using this rule group
](aws-managed-rule-groups-acfp.md#aws-managed-rule-groups-acfp-using)
  + [

## Labels added by this rule group
](aws-managed-rule-groups-acfp.md#aws-managed-rule-groups-acfp-labels)
    + [

### Token labels
](aws-managed-rule-groups-acfp.md#aws-managed-rule-groups-acfp-labels-token)
    + [

### ACFP labels
](aws-managed-rule-groups-acfp.md#aws-managed-rule-groups-acfp-labels-rg)
  + [

## Account creation fraud prevention rules listing
](aws-managed-rule-groups-acfp.md#aws-managed-rule-groups-acfp-rules)
+ [

# AWS WAF Fraud Control account takeover prevention (ATP) rule group
](aws-managed-rule-groups-atp.md)
  + [

## Considerations for using this rule group
](aws-managed-rule-groups-atp.md#aws-managed-rule-groups-atp-using)
  + [

## Labels added by this rule group
](aws-managed-rule-groups-atp.md#aws-managed-rule-groups-atp-labels)
    + [

### Token labels
](aws-managed-rule-groups-atp.md#aws-managed-rule-groups-atp-labels-token)
    + [

### ATP labels
](aws-managed-rule-groups-atp.md#aws-managed-rule-groups-atp-labels-rg)
  + [

## Account takeover prevention rules listing
](aws-managed-rule-groups-atp.md#aws-managed-rule-groups-atp-rules)
+ [

# AWS WAF Bot Control rule group
](aws-managed-rule-groups-bot.md)
  + [

## Protection levels
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-prot-levels)
  + [

## Considerations for using this rule group
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-using)
  + [

## Labels added by this rule group
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-labels)
    + [

### Token labels
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-labels-token)
    + [

### Bot Control labels
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-labels-rg)
  + [

## Bot Control rules listing
](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-rules)
+ [

# AWS WAF Distributed Denial of Service (DDoS) prevention rule group
](aws-managed-rule-groups-anti-ddos.md)
  + [

## Considerations for using this rule group
](aws-managed-rule-groups-anti-ddos.md#aws-managed-rule-groups-anti-ddos-using)
  + [

## Labels added by this rule group
](aws-managed-rule-groups-anti-ddos.md#aws-managed-rule-groups-anti-ddos-labels)
    + [

### Token labels
](aws-managed-rule-groups-anti-ddos.md#aws-managed-rule-groups-anti-ddos-labels-token)
    + [

### Anti-DDoS labels
](aws-managed-rule-groups-anti-ddos.md#aws-managed-rule-groups-anti-ddos-labels-rg)
  + [

## Anti-DDoS rules listing
](aws-managed-rule-groups-anti-ddos.md#aws-managed-rule-groups-anti-ddos-rules)

# Baseline rule groups
<a name="aws-managed-rule-groups-baseline"></a>

Baseline managed rule groups provide general protection against a wide variety of common threats. Choose one or more of these rule groups to establish baseline protection for your resources. 

## Core rule set (CRS) managed rule group
<a name="aws-managed-rule-groups-baseline-crs"></a>

VendorName: `AWS`, Name: `AWSManagedRulesCommonRuleSet`, WCU: 700

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The core rule set (CRS) rule group contains rules that are generally applicable to web applications. This provides protection against exploitation of a wide range of vulnerabilities, including some of the high risk and commonly occurring vulnerabilities described in OWASP publications such as [OWASP Top 10](https://owasp.org/www-project-top-ten/). Consider using this rule group for any AWS WAF use case.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| NoUserAgent\$1HEADER |  Inspects for requests that are missing the HTTP `User-Agent` header. Rule action: Block Label: `awswaf:managed:aws:core-rule-set:NoUserAgent_Header`  | 
| UserAgent\$1BadBots\$1HEADER |  Inspects for common `User-Agent` header values that indicate that the request is a bad bot. Example patterns include `nessus`, and `nmap`. For bot management, see also [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:BadBots_Header`  | 
| SizeRestrictions\$1QUERYSTRING |  Inspects for URI query strings that are over 2,048 bytes.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:SizeRestrictions_QueryString`  | 
| SizeRestrictions\$1Cookie\$1HEADER |  Inspects for cookie headers that are over 10,240 bytes.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:SizeRestrictions_Cookie_Header`  | 
| SizeRestrictions\$1BODY |  Inspects for request bodies that are over 8 KB (8,192 bytes).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:SizeRestrictions_Body`  | 
| SizeRestrictions\$1URIPATH |  Inspects for URI paths that are over 1,024 bytes.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:SizeRestrictions_URIPath`  | 
| EC2MetaDataSSRF\$1BODY |  Inspects for attempts to exfiltrate Amazon EC2 metadata from the request body.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:EC2MetaDataSSRF_Body`  | 
| EC2MetaDataSSRF\$1COOKIE |  Inspects for attempts to exfiltrate Amazon EC2 metadata from the request cookie.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:EC2MetaDataSSRF_Cookie`  | 
| EC2MetaDataSSRF\$1URIPATH |  Inspects for attempts to exfiltrate Amazon EC2 metadata from the request URI path.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:EC2MetaDataSSRF_URIPath`  | 
| EC2MetaDataSSRF\$1QUERYARGUMENTS |  Inspects for attempts to exfiltrate Amazon EC2 metadata from the request query arguments.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:EC2MetaDataSSRF_QueryArguments`  | 
| GenericLFI\$1QUERYARGUMENTS |  Inspects for the presence of Local File Inclusion (LFI) exploits in the query arguments. Examples include path traversal attempts using techniques like `../../`.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericLFI_QueryArguments`  | 
| GenericLFI\$1URIPATH |  Inspects for the presence of Local File Inclusion (LFI) exploits in the URI path. Examples include path traversal attempts using techniques like `../../`.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericLFI_URIPath`  | 
| GenericLFI\$1BODY |  Inspects for the presence of Local File Inclusion (LFI) exploits in the request body. Examples include path traversal attempts using techniques like `../../`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericLFI_Body`  | 
| RestrictedExtensions\$1URIPATH |  Inspects for requests whose URI paths contain system file extensions that are unsafe to read or run. Example patterns include extensions like `.log` and `.ini`.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:RestrictedExtensions_URIPath`  | 
| RestrictedExtensions\$1QUERYARGUMENTS |  Inspects for requests whose query arguments contain system file extensions that are unsafe to read or run. Example patterns include extensions like `.log` and `.ini`.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:RestrictedExtensions_QueryArguments`  | 
| GenericRFI\$1QUERYARGUMENTS |  Inspects the values of all query parameters for attempts to exploit RFI (Remote File Inclusion) in web applications by embedding URLs that contain IPv4 addresses. Examples include patterns like `http://`, `https://`, `ftp://`, `ftps://`, and `file://`, with an IPv4 host header in the exploit attempt.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericRFI_QueryArguments`  | 
| GenericRFI\$1BODY |  Inspects the request body for attempts to exploit RFI (Remote File Inclusion) in web applications by embedding URLs that contain IPv4 addresses. Examples include patterns like `http://`, `https://`, `ftp://`, `ftps://`, and `file://`, with an IPv4 host header in the exploit attempt.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericRFI_Body`  | 
| GenericRFI\$1URIPATH |  Inspects the URI path for attempts to exploit RFI (Remote File Inclusion) in web applications by embedding URLs that contain IPv4 addresses. Examples include patterns like `http://`, `https://`, `ftp://`, `ftps://`, and `file://`, with an IPv4 host header in the exploit attempt.  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:GenericRFI_URIPath`  | 
| CrossSiteScripting\$1COOKIE |  Inspects the values of cookie headers for common cross-site scripting (XSS) patterns using the built-in AWS WAF [Cross-site scripting attack rule statement](waf-rule-statement-type-xss-match.md). Example patterns include scripts like `<script>alert("hello")</script>`.   The rule match details in the AWS WAF logs is not populated for version 2.0 of this rule group.   Rule action: Block Label: `awswaf:managed:aws:core-rule-set:CrossSiteScripting_Cookie`  | 
| CrossSiteScripting\$1QUERYARGUMENTS |  Inspects the values of query arguments for common cross-site scripting (XSS) patterns using the built-in AWS WAF [Cross-site scripting attack rule statement](waf-rule-statement-type-xss-match.md). Example patterns include scripts like `<script>alert("hello")</script>`.   The rule match details in the AWS WAF logs is not populated for version 2.0 of this rule group.   Rule action: Block Label: `awswaf:managed:aws:core-rule-set:CrossSiteScripting_QueryArguments`  | 
| CrossSiteScripting\$1BODY |  Inspects the request body for common cross-site scripting (XSS) patterns using the built-in AWS WAF [Cross-site scripting attack rule statement](waf-rule-statement-type-xss-match.md). Example patterns include scripts like `<script>alert("hello")</script>`.   The rule match details in the AWS WAF logs is not populated for version 2.0 of this rule group.   This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:core-rule-set:CrossSiteScripting_Body`  | 
| CrossSiteScripting\$1URIPATH |  Inspects the value of the URI path for common cross-site scripting (XSS) patterns using the built-in AWS WAF [Cross-site scripting attack rule statement](waf-rule-statement-type-xss-match.md). Example patterns include scripts like `<script>alert("hello")</script>`.   The rule match details in the AWS WAF logs is not populated for version 2.0 of this rule group.   Rule action: Block Label: `awswaf:managed:aws:core-rule-set:CrossSiteScripting_URIPath`  | 

## Admin protection managed rule group
<a name="aws-managed-rule-groups-baseline-admin"></a>

VendorName: `AWS`, Name: `AWSManagedRulesAdminProtectionRuleSet`, WCU: 100

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Admin protection rule group contains rules that allow you to block external access to exposed administrative pages. This might be useful if you run third-party software or want to reduce the risk of a malicious actor gaining administrative access to your application.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| AdminProtection\$1URIPATH |  Inspects for URI paths that are generally reserved for administration of a web server or application. Example patterns include `sqlmanager`.  Rule action: Block Label: `awswaf:managed:aws:admin-protection:AdminProtection_URIPath`  | 

## Known bad inputs managed rule group
<a name="aws-managed-rule-groups-baseline-known-bad-inputs"></a>

VendorName: `AWS`, Name: `AWSManagedRulesKnownBadInputsRuleSet`, WCU: 200

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Known bad inputs rule group contains rules to block request patterns that are known to be invalid and are associated with exploitation or discovery of vulnerabilities. This can help reduce the risk of a malicious actor discovering a vulnerable application.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| JavaDeserializationRCE\$1HEADER |  Inspects the keys and values of HTTP request headers for patterns indicating Java deserialization Remote Command Execution (RCE) attempts, such as the Spring Core and Cloud Function RCE vulnerabilities (CVE-2022-22963, CVE-2022-22965). Example patterns include `(java.lang.Runtime).getRuntime().exec("whoami")`.  This rule only inspects the first 8 KB of the request headers or the first 200 headers, whichever limit is reached first, and it uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:JavaDeserializationRCE_Header`   | 
| JavaDeserializationRCE\$1BODY |  Inspects the request body for patterns indicating Java deserialization Remote Command Execution (RCE) attempts, such as the Spring Core and Cloud Function RCE vulnerabilities (CVE-2022-22963, CVE-2022-22965). Example patterns include `(java.lang.Runtime).getRuntime().exec("whoami")`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:JavaDeserializationRCE_Body`  | 
| JavaDeserializationRCE\$1URIPATH |  Inspects the request URI for patterns indicating Java deserialization Remote Command Execution (RCE) attempts, such as the Spring Core and Cloud Function RCE vulnerabilities (CVE-2022-22963, CVE-2022-22965). Example patterns include `(java.lang.Runtime).getRuntime().exec("whoami")`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:JavaDeserializationRCE_URIPath`  | 
| JavaDeserializationRCE\$1QUERYSTRING |  Inspects the request query string for patterns indicating Java deserialization Remote Command Execution (RCE) attempts, such as the Spring Core and Cloud Function RCE vulnerabilities (CVE-2022-22963, CVE-2022-22965). Example patterns include `(java.lang.Runtime).getRuntime().exec("whoami")`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:JavaDeserializationRCE_QueryString`  | 
| Host\$1localhost\$1HEADER |  Inspects the host header in the request for patterns indicating localhost. Example patterns include `localhost`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Host_Localhost_Header`  | 
| PROPFIND\$1METHOD |  Inspects the HTTP method in the request for `PROPFIND`, which is a method similar to `HEAD`, but with the extra intention to exfiltrate XML objects.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Propfind_Method`  | 
| ExploitablePaths\$1URIPATH |  Inspects the URI path for attempts to access exploitable web application paths. Example patterns include paths like `web-inf`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:ExploitablePaths_URIPath`  | 
| Log4JRCE\$1HEADER |  Inspects the keys and values of request headers for the presence of the Log4j vulnerability ([CVE-2021-44228](https://www.cve.org/CVERecord?id=CVE-2021-44228), [CVE-2021-45046](https://www.cve.org/CVERecord?id=CVE-2021-45046), [CVE-2021-45105](https://www.cve.org/CVERecord?id=CVE-2021-45105)) and protects against Remote Code Execution (RCE) attempts. Example patterns include `${jndi:ldap://example.com/}`.  This rule only inspects the first 8 KB of the request headers or the first 200 headers, whichever limit is reached first, and it uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Log4JRCE_Header`  | 
| Log4JRCE\$1QUERYSTRING |  Inspects the query string for the presence of the Log4j vulnerability ([CVE-2021-44228](https://www.cve.org/CVERecord?id=CVE-2021-44228), [CVE-2021-45046](https://www.cve.org/CVERecord?id=CVE-2021-45046), [CVE-2021-45105](https://www.cve.org/CVERecord?id=CVE-2021-45105)) and protects against Remote Code Execution (RCE) attempts. Example patterns include `${jndi:ldap://example.com/}`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Log4JRCE_QueryString`  | 
| Log4JRCE\$1BODY |  Inspects the body for the presence of the Log4j vulnerability ([CVE-2021-44228](https://www.cve.org/CVERecord?id=CVE-2021-44228), [CVE-2021-45046](https://www.cve.org/CVERecord?id=CVE-2021-45046), [CVE-2021-45105](https://www.cve.org/CVERecord?id=CVE-2021-45105)) and protects against Remote Code Execution (RCE) attempts. Example patterns include `${jndi:ldap://example.com/}`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Log4JRCE_Body`  | 
| Log4JRCE\$1URIPATH |  Inspects the URI path for the presence of the Log4j vulnerability ([CVE-2021-44228](https://www.cve.org/CVERecord?id=CVE-2021-44228), [CVE-2021-45046](https://www.cve.org/CVERecord?id=CVE-2021-45046), [CVE-2021-45105](https://www.cve.org/CVERecord?id=CVE-2021-45105)) and protects against Remote Code Execution (RCE) attempts. Example patterns include `${jndi:ldap://example.com/}`.  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:Log4JRCE_URIPath`  | 
| ReactJSRCE\$1BODY |  Inspects the request body for patterns indicating presence of CVE-2025-55182.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and AWS Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `CONTINUE` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:known-bad-inputs:ReactJSRCE_Body`  | 

# Use-case specific rule groups
<a name="aws-managed-rule-groups-use-case"></a>

Use-case specific rule groups provide incremental protection for many diverse AWS WAF use cases. Choose the rule groups that apply to your application. 

## SQL database managed rule group
<a name="aws-managed-rule-groups-use-case-sql-db"></a>

VendorName: `AWS`, Name: `AWSManagedRulesSQLiRuleSet`, WCU: 200

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The SQL database rule group contains rules to block request patterns associated with exploitation of SQL databases, like SQL injection attacks. This can help prevent remote injection of unauthorized queries. Evaluate this rule group for use if your application interfaces with an SQL database.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| SQLi\$1QUERYARGUMENTS |  Uses the built-in AWS WAF [SQL injection attack rule statement](waf-rule-statement-type-sqli-match.md), with sensitivity level set to Low, to inspect the values of all query parameters for patterns that match malicious SQL code.  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLi_QueryArguments`  | 
| SQLiExtendedPatterns\$1QUERYARGUMENTS |  Inspects the values of all query parameters for patterns that match malicious SQL code. The patterns this rule inspects for aren't covered by the rule `SQLi_QUERYARGUMENTS`.  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLiExtendedPatterns_QueryArguments`  | 
| SQLi\$1BODY |  Uses the built-in AWS WAF [SQL injection attack rule statement](waf-rule-statement-type-sqli-match.md), with sensitivity level set to Low, to inspect the request body for patterns that match malicious SQL code.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLi_Body`  | 
| SQLiExtendedPatterns\$1BODY |  Inspects the request body for patterns that match malicious SQL code. The patterns this rule inspects for aren't covered by the rule `SQLi_BODY`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLiExtendedPatterns_Body`  | 
| SQLi\$1COOKIE |  Uses the built-in AWS WAF [SQL injection attack rule statement](waf-rule-statement-type-sqli-match.md), with sensitivity level set to Low, to inspect the request cookie headers for patterns that match malicious SQL code.  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLi_Cookie`  | 
| SQLi\$1URIPATH |  Uses the built-in AWS WAF [SQL injection attack rule statement](waf-rule-statement-type-sqli-match.md), with sensitivity level set to Low, to inspect the request cookie headers for patterns that match malicious SQL code.  Rule action: Block Label: `awswaf:managed:aws:sql-database:SQLi_URIPath`  | 

## Linux operating system managed rule group
<a name="aws-managed-rule-groups-use-case-linux-os"></a>

VendorName: `AWS`, Name: `AWSManagedRulesLinuxRuleSet`, WCU: 200

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Linux operating system rule group contains rules that block request patterns associated with the exploitation of vulnerabilities specific to Linux, including Linux-specific Local File Inclusion (LFI) attacks. This can help prevent attacks that expose file contents or run code for which the attacker should not have had access. You should evaluate this rule group if any part of your application runs on Linux. You should use this rule group in conjunction with the [POSIX operating system](#aws-managed-rule-groups-use-case-posix-os) rule group.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| LFI\$1URIPATH |  Inspects the request path for attempts to exploit Local File Inclusion (LFI) vulnerabilities in web applications. Example patterns include files like `/proc/version`, which could provide operating system information to attackers.  Rule action: Block Label: `awswaf:managed:aws:linux-os:LFI_URIPath`  | 
| LFI\$1QUERYSTRING |  Inspects the values of querystring for attempts to exploit Local File Inclusion (LFI) vulnerabilities in web applications. Example patterns include files like `/proc/version`, which could provide operating system information to attackers.  Rule action: Block Label: `awswaf:managed:aws:linux-os:LFI_QueryString`  | 
| LFI\$1HEADER |  Inspects request headers for attempts to exploit Local File Inclusion (LFI) vulnerabilities in web applications. Example patterns include files like `/proc/version`, which could provide operating system information to attackers.  This rule only inspects the first 8 KB of the request headers or the first 200 headers, whichever limit is reached first, and it uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:linux-os:LFI_Header`  | 

## POSIX operating system managed rule group
<a name="aws-managed-rule-groups-use-case-posix-os"></a>

VendorName: `AWS`, Name: `AWSManagedRulesUnixRuleSet`, WCU: 100

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The POSIX operating system rule group contains rules that block request patterns associated with the exploitation of vulnerabilities specific to POSIX and POSIX-like operating systems, including Local File Inclusion (LFI) attacks. This can help prevent attacks that expose file contents or run code for which the attacker should not have had access. You should evaluate this rule group if any part of your application runs on a POSIX or POSIX-like operating system, including Linux, AIX, HP-UX, macOS, Solaris, FreeBSD, and OpenBSD. 

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| UNIXShellCommandsVariables\$1QUERYSTRING |  Inspects the values of the query string for attempts to exploit command injection, LFI, and path traversal vulnerabilities in web applications that run on Unix systems. Examples include patterns like `echo $HOME` and `echo $PATH`.  Rule action: Block Label: `awswaf:managed:aws:posix-os:UNIXShellCommandsVariables_QueryString`  | 
| UNIXShellCommandsVariables\$1BODY |  Inspects the request body for attempts to exploit command injection, LFI, and path traversal vulnerabilities in web applications that run on Unix systems. Examples include patterns like `echo $HOME` and `echo $PATH`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:posix-os:UNIXShellCommandsVariables_Body`  | 
| UNIXShellCommandsVariables\$1HEADER |  Inspects all request headers for attempts to exploit command injection, LFI, and path traversal vulnerabilities in web applications that run on Unix systems. Examples include patterns like `echo $HOME` and `echo $PATH`.  This rule only inspects the first 8 KB of the request headers or the first 200 headers, whichever limit is reached first, and it uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:posix-os:UNIXShellCommandsVariables_Header`  | 

## Windows operating system managed rule group
<a name="aws-managed-rule-groups-use-case-windows-os"></a>

VendorName: `AWS`, Name: `AWSManagedRulesWindowsRuleSet`, WCU: 200

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Windows operating system rule group contains rules that block request patterns associated with the exploitation of vulnerabilities specific to Windows, like remote execution of PowerShell commands. This can help prevent exploitation of vulnerabilities that permit an attacker to run unauthorized commands or run malicious code. Evaluate this rule group if any part of your application runs on a Windows operating system.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| WindowsShellCommands\$1COOKIE |  Inspects the request cookie headers for WindowsShell command injection attempts in web applications. The match patterns represent WindowsShell commands. Example patterns include `\|\|nslookup` and `;cmd`.  Rule action: Block Label: `awswaf:managed:aws:windows-os:WindowsShellCommands_Cookie`   | 
| WindowsShellCommands\$1QUERYARGUMENTS |  Inspects the values of all query parameters for WindowsShell command injection attempts in web applications. The match patterns represent WindowsShell commands. Example patterns include `\|\|nslookup` and `;cmd`.  Rule action: Block Label: `awswaf:managed:aws:windows-os:WindowsShellCommands_QueryArguments`   | 
| WindowsShellCommands\$1BODY |  Inspects the request body for WindowsShell command injection attempts in web applications. The match patterns represent WindowsShell commands. Example patterns include `\|\|nslookup` and `;cmd`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:windows-os:WindowsShellCommands_Body`   | 
| PowerShellCommands\$1COOKIE |  Inspects the request cookie headers for PowerShell command injection attempts in web applications. The match patterns represent PowerShell commands. For example, `Invoke-Expression`.  Rule action: Block Label: `awswaf:managed:aws:windows-os:PowerShellCommands_Cookie`  | 
| PowerShellCommands\$1QUERYARGUMENTS |  Inspects the values of all query parameters for PowerShell command injection attempts in web applications. The match patterns represent PowerShell commands. For example, `Invoke-Expression`.  Rule action: Block Label: `awswaf:managed:aws:windows-os:PowerShellCommands_QueryArguments`  | 
| PowerShellCommands\$1BODY |  Inspects the request body for PowerShell command injection attempts in web applications. The match patterns represent PowerShell commands. For example, `Invoke-Expression`.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:windows-os:PowerShellCommands_Body`   | 

## PHP application managed rule group
<a name="aws-managed-rule-groups-use-case-php-app"></a>

VendorName: `AWS`, Name: `AWSManagedRulesPHPRuleSet`, WCU: 100

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The PHP application rule group contains rules that block request patterns associated with the exploitation of vulnerabilities specific to the use of the PHP programming language, including injection of unsafe PHP functions. This can help prevent exploitation of vulnerabilities that permit an attacker to remotely run code or commands for which they are not authorized. Evaluate this rule group if PHP is installed on any server with which your application interfaces.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| PHPHighRiskMethodsVariables\$1HEADER |  Inspects all headers for PHP script code injection attempts. Example patterns include functions like `fsockopen` and the `$_GET` superglobal variable.  This rule only inspects the first 8 KB of the request headers or the first 200 headers, whichever limit is reached first, and it uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:php-app:PHPHighRiskMethodsVariables_Header`  | 
| PHPHighRiskMethodsVariables\$1QUERYSTRING |  Inspects everything after the first `?` in the request URL, looking for PHP script code injection attempts. Example patterns include functions like `fsockopen` and the `$_GET` superglobal variable.  Rule action: Block Label: `awswaf:managed:aws:php-app:PHPHighRiskMethodsVariables_QueryString`  | 
| PHPHighRiskMethodsVariables\$1BODY |  Inspects the values of the request body for PHP script code injection attempts. Example patterns include functions like `fsockopen` and the `$_GET` superglobal variable.  This rule only inspects the request body up to the body size limit for the protection pack (web ACL) and resource type. For Application Load Balancer and AWS AppSync, the limit is fixed at 8 KB. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, the default limit is 16 KB and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. This rule uses the `Continue` option for oversize content handling. For more information, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).  Rule action: Block Label: `awswaf:managed:aws:php-app:PHPHighRiskMethodsVariables_Body`  | 
| PHPHighRiskMethodsVariables\$1URIPATH |  Inspects the request path for PHP script code injection attempts. Example patterns include functions like `fsockopen` and the `$_GET` superglobal variable.  Rule action: Block Label: `awswaf:managed:aws:php-app:PHPHighRiskMethodsVariables_URIPath`  | 

## WordPress application managed rule group
<a name="aws-managed-rule-groups-use-case-wordpress-app"></a>

VendorName: `AWS`, Name: `AWSManagedRulesWordPressRuleSet`, WCU: 100

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The WordPress application rule group contains rules that block request patterns associated with the exploitation of vulnerabilities specific to WordPress sites. You should evaluate this rule group if you are running WordPress. This rule group should be used in conjunction with the [SQL database](#aws-managed-rule-groups-use-case-sql-db) and [PHP application](#aws-managed-rule-groups-use-case-php-app) rule groups.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| WordPressExploitableCommands\$1QUERYSTRING |  Inspects the request query string for high risk WordPress commands that can be exploited in vulnerable installations or plugins. Examples patterns include commands like `do-reset-wordpress`.  Rule action: Block Label: `awswaf:managed:aws:wordpress-app:WordPressExploitableCommands_QUERYSTRING`  | 
| WordPressExploitablePaths\$1URIPATH |  Inspects the request URI path for WordPress files like `xmlrpc.php`, which are known to have easily exploitable vulnerabilities.  Rule action: Block Label: `awswaf:managed:aws:wordpress-app:WordPressExploitablePaths_URIPATH`  | 

# IP reputation rule groups
<a name="aws-managed-rule-groups-ip-rep"></a>

IP reputation rule groups block requests based on their source IP address. 

**Note**  
These rules use the source IP address from the web request origin. If you have traffic that goes through one or more proxies or load balancers, the web request origin will contain the address of the last proxy, and not the originating address of the client. 

Choose one or more of these rule groups if you want to reduce your exposure to bot traffic or exploitation attempts, or if you are enforcing geographic restrictions on your content. For bot management, see also [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).

The rule groups in this category don't provide versioning or SNS update notifications. 

## Amazon IP reputation list managed rule group
<a name="aws-managed-rule-groups-ip-rep-amazon"></a>

VendorName: `AWS`, Name: `AWSManagedRulesAmazonIpReputationList`, WCU: 25

**Note**  
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Amazon IP reputation list rule group contains rules that are based on Amazon internal threat intelligence. This is useful if you would like to block IP addresses typically associated with bots or other threats. Blocking these IP addresses can help mitigate bots and reduce the risk of a malicious actor discovering a vulnerable application.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| AWSManagedIPReputationList |  Inspects for IP addresses that have been identified as actively engaging in malicious activities. AWS WAF collects the IP address list from various sources, including MadPot, a threat intelligence tool that Amazon uses to protect customers from cybercrime. For more information about MadPot, see [https://www.aboutamazon.com/news/aws/amazon-madpot-stops-cybersecurity-crime](https://www.aboutamazon.com/news/aws/amazon-madpot-stops-cybersecurity-crime). Rule action: Block Label: `awswaf:managed:aws:amazon-ip-list:AWSManagedIPReputationList`  | 
| AWSManagedReconnaissanceList |  Inspects for connections from IP addresses that are performing reconnaissance against AWS resources.  Rule action: Block Label: `awswaf:managed:aws:amazon-ip-list:AWSManagedReconnaissanceList`  | 
| AWSManagedIPDDoSList |  Inspects for IP addresses that have been identified as actively engaging in DDoS activities.  Rule action: Count Label: `awswaf:managed:aws:amazon-ip-list:AWSManagedIPDDoSList`  | 

## Anonymous IP list managed rule group
<a name="aws-managed-rule-groups-ip-rep-anonymous"></a>

VendorName: `AWS`, Name: `AWSManagedRulesAnonymousIpList`, WCU: 50

**Note**  
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Anonymous IP list rule group contains rules to block requests from services that permit the obfuscation of viewer identity. These include requests from VPNs, proxies, Tor nodes, and web hosting providers. This rule group is useful if you want to filter out viewers that might be trying to hide their identity from your application. Blocking the IP addresses of these services can help mitigate bots and evasion of geographic restrictions.

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 


| Rule name | Description and label | 
| --- | --- | 
| AnonymousIPList |  Inspects for a list of IP addresses of sources known to anonymize client information, like TOR nodes, temporary proxies, and other masking services.  Rule action: Block Label: `awswaf:managed:aws:anonymous-ip-list:AnonymousIPList`  | 
| HostingProviderIPList | Inspects for a list of IP addresses from web hosting and cloud providers, which are less likely to source end-user traffic. The IP list does not include AWS IP addresses. Rule action: Block Label: `awswaf:managed:aws:anonymous-ip-list:HostingProviderIPList` | 

# AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group
<a name="aws-managed-rule-groups-acfp"></a>

This section explains what the AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group does.

VendorName: `AWS`, Name: `AWSManagedRulesACFPRuleSet`, WCU: 50

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group labels and manages requests that might be part of fraudulent account creation attempts. The rule group does this by inspecting account creation requests that clients send to your application's registration and account creation endpoints. 

The ACFP rule group inspects account creation attempts in various ways, to give you visibility and control over potentially malicious interactions. The rule group uses request tokens to gather information about the client browser and about the level of human interactivity in the creation of the account creation request. The rule group detects and manages bulk account creation attempts by aggregating requests by IP address and client session, and aggregating by the provided account information such as the physical address and phone number. Additionally, the rule group detects and blocks the creation of new accounts using credentials that have been compromised, which helps protect the security posture of your application and of your new users. 

## Considerations for using this rule group
<a name="aws-managed-rule-groups-acfp-using"></a>

This rule group requires custom configuration, which includes the specification of your application's account registration and account creation paths. Except where noted, the rules in this rule group inspect all requests that your clients send to these two endpoints. To configure and implement this rule group, see the guidance at [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md). 

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

This rule group is part of the intelligent threat mitigation protections in AWS WAF. For information, see [Intelligent threat mitigation in AWS WAF](waf-managed-protections.md).

To keep your costs down and to be sure you're managing your web traffic as you want, use this rule group in accordance with the guidance at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md).

This rule group isn't available for use with Amazon Cognito user pools. You can't associate a protection pack (web ACL) that uses this rule group with a user pool, and you can't add this rule group to a protection pack (web ACL) that's already associated with a user pool.

## Labels added by this rule group
<a name="aws-managed-rule-groups-acfp-labels"></a>

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 

### Token labels
<a name="aws-managed-rule-groups-acfp-labels-token"></a>

This rule group uses AWS WAF token management to inspect and label web requests according to the status of their AWS WAF tokens. AWS WAF uses tokens for client session tracking and verification. 

For information about tokens and token management, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).

For information about the label components described here, see [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md).

**Client session label**  
The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. 

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Browser fingerprint label**  
The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client.

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Token status labels: Label namespace prefixes**  
Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. 

Each token status label begins with one of the following namespace prefixes: 
+ `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. 
+ `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. 

**Token status labels: Label names**  
Following the prefix, the rest of the label provides detailed token status information: 
+ `accepted` – The request token is present and contains the following: 
  + A valid challenge or CAPTCHA solution.
  + An unexpired challenge or CAPTCHA timestamp.
  + A domain specification that's valid for the protection pack (web ACL). 

  Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain.
+ `rejected` – The request token is present but doesn't meet the acceptance criteria. 

  Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. 
  + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. 
  + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. 
  + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. 
  + `rejected:invalid` – AWS WAF couldn't read the indicated token. 

  Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL).
+ `absent` – The request doesn't have the token or the token manager couldn't read it. 

  Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. 

### ACFP labels
<a name="aws-managed-rule-groups-acfp-labels-rg"></a>

This rule group generates labels with the namespace prefix `awswaf:managed:aws:acfp:` followed by the custom namespace and label name. The rule group might add more than one label to a request. 

You can retrieve all labels for a rule group through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the `AvailableLabels` property in the response. 

## Account creation fraud prevention rules listing
<a name="aws-managed-rule-groups-acfp-rules"></a>

This section lists the ACFP rules in `AWSManagedRulesACFPRuleSet` and the labels that the rule group's rules add to web requests.

All of the rules in this rule group require a web request token, except for the first two `UnsupportedCognitoIDP` and `AllRequests`. For a description of the information that the token provides, see [AWS WAF token characteristics](waf-tokens-details.md). 

Except where noted, the rules in this rule group inspect all requests that your clients send to the account registration and account creation page paths that you provide in the rule group configuration. For information about configuring this rule group, see [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md). 

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 


| Rule name | Description and label | 
| --- | --- | 
| UnsupportedCognitoIDP |  Inspects for web traffic going to an Amazon Cognito user pool. ACFP isn't available for use with Amazon Cognito user pools, and this rule helps to ensure that the other ACFP rule group rules are not used to evaluate user pool traffic. Rule action: Block Labels: `awswaf:managed:aws:acfp:unsupported:cognito_idp` and `awswaf:managed:aws:acfp:UnsupportedCognitoIDP`   | 
| AllRequests |  Applies the rule action to requests that access the registration page path. You configure the registration page path when you configure the rule group.  By default, this rule applies the Challenge to requests. By applying this action, the rule ensures that the client acquires a challenge token before any requests are evaluated by the rest of the rules in the rule group.  Ensure that your end users load the registration page path before they submit an account creation request.  Tokens are added to requests by the client application integration SDKs and by the rule actions CAPTCHA and Challenge. For the most efficient token acquisition, we highly recommend that you use the application integration SDKs. For more information, see [Client application integrations in AWS WAF](waf-application-integration.md).  Rule action: Challenge Labels: None  | 
| RiskScoreHigh |  Inspects for account creation requests with IP addresses or other factors that are considered to be highly suspicious. This evaluation is usually based on multiple contributing factors, which you can see in `risk_score` labels that the rule group adds to the request. Rule action: Block Labels: `awswaf:managed:aws:acfp:risk_score:high` and `awswaf:managed:aws:acfp:RiskScoreHigh`  The rule might also apply `medium` or `low` risk score labels to the request.  If AWS WAF doesn't succeed at evaluating the risk score for the web request, the rule adds the label `awswaf:managed:aws:acfp:risk_score:evaluation_failed ` Additionally, the rule adds labels with the namespace `awswaf:managed:aws:acfp:risk_score:contributor:` that include risk score evaluation status and results for specific risk score contributors, such as IP reputation and stolen credentials evaluations.  | 
| SignalCredentialCompromised |  Searches the stolen credential database for the credentials that were submitted in the account creation request.  This rule ensures that new clients initialize their accounts with positive security posture.   You can add a custom blocking response, to describe the problem to your end user and tell them how to proceed. For information, see [ACFP example: Custom response for compromised credentials](waf-acfp-control-example-compromised-credentials.md).  Rule action: Block Labels: `awswaf:managed:aws:acfp:signal:credential_compromised` and `awswaf:managed:aws:acfp:SignalCredentialCompromised`  The rule group applies the following related label, but takes no action on it, because not all requests in account creation will have credentials: `awswaf:managed:aws:acfp:signal:missing_credential`  | 
| SignalClientHumanInteractivityAbsentLow |  Inspects the account creation request's token for data that indicates abnormal human interactivity with the application. Human interactivity is detected through interactions such as mouse movements and key presses. If the page has an HTML form, human interactivity includes interactions with the form.   This rule only inspects requests to the account creation path and is only evaluated if you've implemented the application integration SDKs. The SDK implementations passively capture human interactivity and stores the information in the request token. For more information, see [AWS WAF token characteristics](waf-tokens-details.md) and [Client application integrations in AWS WAF](waf-application-integration.md).  Rule action: CAPTCHA Labels: None. The rule determines a match based on varying factors, so there is no individual label that applies for every possible match scenario. The rule group can apply one or more of the following labels to requests:  `awswaf:managed:aws:acfp:signal:client:human_interactivity:low\|medium\|high` `awswaf:managed:aws:acfp:SignalClientHumanInteractivityAbsentLow\|Medium\|High`  `awswaf:managed:aws:acfp:signal:client:human_interactivity:insufficient_data`  `awswaf:managed:aws:acfp:signal:form_detected`.  | 
| AutomatedBrowser |  Inspects for indicators that the client browser might be automated.  Rule action: Block  Labels: `awswaf:managed:aws:acfp:signal:automated_browser` and `awswaf:managed:aws:acfp:AutomatedBrowser`  | 
| BrowserInconsistency |  Inspects the request's token for inconsistent browser interrogation data. For more information, see [AWS WAF token characteristics](waf-tokens-details.md). Rule action: CAPTCHA  Labels: `awswaf:managed:aws:acfp:signal:browser_inconsistency` and `awswaf:managed:aws:acfp:BrowserInconsistency`  | 
| VolumetricIpHigh |  Inspects for high volumes of account creation requests sent from individual IP addresses. A high volume is more than 20 requests in a 10 minute window.  The thresholds that this rule applies can vary slightly due to latency. For the high volume, a few requests might make it through beyond the limit before the rule action is applied.  Rule action: CAPTCHA Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:ip:creation:high` and `awswaf:managed:aws:acfp:VolumetricIpHigh`  The rule applies the following labels to requests with medium volumes (more than 15 requests per 10 minute window) and low volumes (more than 10 requests per 10 minute window), but takes no action on them: `awswaf:managed:aws:acfp:aggregate:volumetric:ip:creation:medium` and `awswaf:managed:aws:acfp:aggregate:volumetric:ip:creation:low`.  | 
| VolumetricSessionHigh |  Inspects for high volumes of account creation requests sent from individual client sessions. A high volume is more than 10 requests in a 30 minute window.   The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:session:creation:high` and `awswaf:managed:aws:acfp:VolumetricSessionHigh`  The rule group applies the following labels to requests with medium volumes (more than 5 requests per 30 minute window) and low volumes (more than 1 request per 30 minute window), but takes no action on them: `awswaf:managed:aws:acfp:aggregate:volumetric:session:creation:medium` and `awswaf:managed:aws:acfp:aggregate:volumetric:session:creation:low`.  | 
| AttributeUsernameTraversalHigh |  Inspects for a high rate of account creation requests from a single client session that use different usernames. The threshold for a high evaluation is more than 10 requests in 30 minutes.   The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:attribute:username_traversal:creation:high` and `awswaf:managed:aws:acfp:AttributeUsernameTraversalHigh`  The rule group applies the following labels to requests with medium volumes (more than 5 requests per 30 minute window) and low volumes (more than 1 request per 30 minute window) of username traversal requests, but takes no action on them: `awswaf:managed:aws:acfp:aggregate:attribute:username_traversal:creation:medium` and `awswaf:managed:aws:acfp:aggregate:attribute:username_traversal:creation:low`.  | 
| VolumetricPhoneNumberHigh |  Inspects for high volumes of account creation requests that use the same phone number. The threshold for a high evaluation is more than 10 requests in 30 minutes.   The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:phone_number:high` and `awswaf:managed:aws:acfp:VolumetricPhoneNumberHigh` The rule group applies the following labels to requests with medium volumes (more than 5 requests per 30 minute window) and low volumes (more than 1 request per 30 minute window), but takes no action on them: `awswaf:managed:aws:acfp:aggregate:volumetric:phone_number:medium` and `awswaf:managed:aws:acfp:aggregate:volumetric:phone_number:low`.  | 
| VolumetricAddressHigh |  Inspects for high volumes of account creation requests that use the same physical address. The threshold for a high evaluation is more than 100 requests per 30 minute window.   The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:address:high` and `awswaf:managed:aws:acfp:VolumetricAddressHigh`   | 
| VolumetricAddressLow |  Inspects for low and medium volumes of account creation requests that use the same physical address. The threshold for a medium evaluation is more than 50 requests per 30 minute window, and for a low evaluation is more than 10 requests per 30 minute window.  The rule applies the action for either medium or low volumes.  The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: CAPTCHA Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:address:low\|medium` and `awswaf:managed:aws:acfp:VolumetricAddressLow\|Medium`   | 
| VolumetricIPSuccessfulResponse |  Inspects for a high volume of successful account creation requests for a single IP address. This rule aggregates success responses from the protected resource to account creation requests. The threshold for a high evaluation is more than 10 requests per 10 minute window.  This rule helps protect against bulk account creation attempts. It has a lower threshold than the rule `VolumetricIpHigh`, which counts just the requests.  If you've configured the rule group to inspect the response body or JSON components, AWS WAF can inspect the first 65,536 bytes (64 KB) of these component types for success or failure indicators.  This rule applies the rule action and labeling to new web requests from an IP address, based on the success and failure responses from the protected resource to recent login attempts from the same IP address. You define how to count successes and failures when you configure the rule group.   AWS WAF only evaluates this rule in protection packs (web ACLs) that protect Amazon CloudFront distributions.   The thresholds that this rule applies can vary slightly due to latency. It's possible for the client to send more successful account creation attempts than are allowed before the rule starts matching on subsequent attempts.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:ip:successful_creation_response:high` and `awswaf:managed:aws:acfp:VolumetricIPSuccessfulResponse`  The rule group also applies the following related labels to requests, without any associated action. All counts are for a 10-minute window. `awswaf:managed:aws:acfp:aggregate:volumetric:ip:successful_creation_response:medium` for more than 5 successful requests, `awswaf:managed:aws:acfp:aggregate:volumetric:ip:successful_creation_response:low` for more than 1 successful request, `awswaf:managed:aws:acfp:aggregate:volumetric:ip:failed_creation_response:high` for more than 10 failed requests, `awswaf:managed:aws:acfp:aggregate:volumetric:ip:failed_creation_response:medium` for more than 5 failed requests, and `awswaf:managed:aws:acfp:aggregate:volumetric:ip:failed_creation_response:low` for more than 1 failed request.   | 
| VolumetricSessionSuccessfulResponse |  Inspects for a low volume of success responses from the protected resource to account creation requests that are being sent from a single client session. This helps to protect against bulk account creation attempts. The threshold for a low evaluation is more than 1 request per 30 minute window.  This helps protect against bulk account creation attempts. This rule uses a lower threshold than the rule `VolumetricSessionHigh`, which tracks only the requests.  If you've configured the rule group to inspect the response body or JSON components, AWS WAF can inspect the first 65,536 bytes (64 KB) of these component types for success or failure indicators.  This rule applies the rule action and labeling to new web requests from a client session, based on the success and failure responses from the protected resource to recent login attempts from the same client session. You define how to count successes and failures when you configure the rule group.   AWS WAF only evaluates this rule in protection packs (web ACLs) that protect Amazon CloudFront distributions.   The thresholds that this rule applies can vary slightly due to latency. It's possible for the client to send more failed account creation attempts than are allowed before the rule starts matching on subsequent attempts.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:session:successful_creation_response:low` and `awswaf:managed:aws:acfp:VolumetricSessionSuccessfulResponse`  The rule group also applies the following related labels to requests. All counts are for a 30-minute window. `awswaf:managed:aws:acfp:aggregate:volumetric:session:successful_creation_response:high` for more than 10 successful requests, `awswaf:managed:aws:acfp:aggregate:volumetric:session:successful_creation_response:medium` for more than 5 successful requests, `awswaf:managed:aws:acfp:aggregate:volumetric:session:failed_creation_response:high` for more than 10 failed requests, `awswaf:managed:aws:acfp:aggregate:volumetric:session:failed_creation_response:medium` for more than 5 failed requests, and `awswaf:managed:aws:acfp:aggregate:volumetric:session:failed_creation_response:low` for more than 1 failed request.   | 
| VolumetricSessionTokenReuseIp |  Inspects account creation requests for the use of a single token among more than 5 distinct IP addresses.   The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:acfp:aggregate:volumetric:session:creation:token_reuse:ip` and `awswaf:managed:aws:acfp:VolumetricSessionTokenReuseIp`  | 

# AWS WAF Fraud Control account takeover prevention (ATP) rule group
<a name="aws-managed-rule-groups-atp"></a>

This section explains what the AWS WAF Fraud Control account takeover prevention (ATP) managed rule group does.

VendorName: `AWS`, Name: `AWSManagedRulesATPRuleSet`, WCU: 50

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The AWS WAF Fraud Control account takeover prevention (ATP) managed rule group labels and manages requests that might be part of malicious account takeover attempts. The rule group does this by inspecting login attempts that clients send to your application's login endpoint. 
+ **Request inspection** – ATP gives you visibility and control over anomalous login attempts and login attempts that use stolen credentials, to prevent account takeovers that might lead to fraudulent activity. ATP checks email and password combinations against its stolen credential database, which is updated regularly as new leaked credentials are found on the dark web. ATP aggregates data by IP address and client session, to detect and block clients that send too many requests of a suspicious nature. 
+ **Response inspection** – For CloudFront distributions, in addition to inspecting incoming login requests, the ATP rule group inspects your application's responses to login attempts, to track success and failure rates. Using this information, ATP can temporarily block client sessions or IP addresses that have too many login failures. AWS WAF performs response inspection asynchronously, so this doesn't increase latency in your web traffic. 

## Considerations for using this rule group
<a name="aws-managed-rule-groups-atp-using"></a>

This rule group requires specific configuration. To configure and implement this rule group, see the guidance at [AWS WAF Fraud Control account takeover prevention (ATP)](waf-atp.md). 

This rule group is part of the intelligent threat mitigation protections in AWS WAF. For information, see [Intelligent threat mitigation in AWS WAF](waf-managed-protections.md).

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

To keep your costs down and to be sure you're managing your web traffic as you want, use this rule group in accordance with the guidance at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md).

This rule group isn't available for use with Amazon Cognito user pools. You can't associate a protection pack (web ACL) that uses this rule group with a user pool, and you can't add this rule group to a protection pack (web ACL) that's already associated with a user pool.

## Labels added by this rule group
<a name="aws-managed-rule-groups-atp-labels"></a>

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 

### Token labels
<a name="aws-managed-rule-groups-atp-labels-token"></a>

This rule group uses AWS WAF token management to inspect and label web requests according to the status of their AWS WAF tokens. AWS WAF uses tokens for client session tracking and verification. 

For information about tokens and token management, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).

For information about the label components described here, see [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md).

**Client session label**  
The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. 

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Browser fingerprint label**  
The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client.

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Token status labels: Label namespace prefixes**  
Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. 

Each token status label begins with one of the following namespace prefixes: 
+ `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. 
+ `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. 

**Token status labels: Label names**  
Following the prefix, the rest of the label provides detailed token status information: 
+ `accepted` – The request token is present and contains the following: 
  + A valid challenge or CAPTCHA solution.
  + An unexpired challenge or CAPTCHA timestamp.
  + A domain specification that's valid for the protection pack (web ACL). 

  Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain.
+ `rejected` – The request token is present but doesn't meet the acceptance criteria. 

  Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. 
  + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. 
  + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. 
  + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. 
  + `rejected:invalid` – AWS WAF couldn't read the indicated token. 

  Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL).
+ `absent` – The request doesn't have the token or the token manager couldn't read it. 

  Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. 

### ATP labels
<a name="aws-managed-rule-groups-atp-labels-rg"></a>

The ATP managed rule group generates labels with the namespace prefix `awswaf:managed:aws:atp:` followed by the custom namespace and label name. 

The rule group might add any of the following labels in addition to the labels that are noted in the rules listing:
+ `awswaf:managed:aws:atp:signal:credential_compromised` – Indicates that the credentials that were submitted in the request are in the stolen credential database. 
+ `awswaf:managed:aws:atp:aggregate:attribute:suspicious_tls_fingerprint` – Available only for protected Amazon CloudFront distributions. Indicates that a client session has sent multiple requests that used a suspicious TLS fingerprint. 
+ `awswaf:managed:aws:atp:aggregate:volumetric:session:token_reuse:ip` – Indicates the use of a single token among more than 5 distinct IP addresses. The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the label is applied. 

You can retrieve all labels for a rule group through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the `AvailableLabels` property in the response. 

## Account takeover prevention rules listing
<a name="aws-managed-rule-groups-atp-rules"></a>

This section lists the ATP rules in `AWSManagedRulesATPRuleSet` and the labels that the rule group's rules add to web requests.

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 


| Rule name | Description and label | 
| --- | --- | 
| UnsupportedCognitoIDP | Inspects for web traffic going to an Amazon Cognito user pool. ATP isn't available for use with Amazon Cognito user pools, and this rule helps to ensure that the other ATP rule group rules are not used to evaluate user pool traffic. Rule action: Block Labels: `awswaf:managed:aws:atp:unsupported:cognito_idp` and `awswaf:managed:aws:atp:UnsupportedCognitoIDP`   | 
| VolumetricIpHigh | Inspects for high volumes of requests sent from individual IP addresses. A high volume is more than 20 requests in a 10 minute window.   The thresholds that this rule applies can vary slightly due to latency. For the high volume, a few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:volumetric:ip:high` and `awswaf:managed:aws:atp:VolumetricIpHigh`  The rule group applies the following labels to requests with medium volumes (more than 15 requests per 10 minute window) and low volumes (more than 10 requests per 10 minute window), but takes no action on them: `awswaf:managed:aws:atp:aggregate:volumetric:ip:medium` and `awswaf:managed:aws:atp:aggregate:volumetric:ip:low`. | 
| VolumetricSession |  Inspects for high volumes of requests sent from individual client sessions. The threshold is more than 20 requests per 30 minute window.  This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).  The thresholds that this rule applies can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:volumetric:session` and `awswaf:managed:aws:atp:VolumetricSession`   | 
| AttributeCompromisedCredentials |  Inspects for multiple requests from the same client session that use stolen credentials.  Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:attribute:compromised_credentials` and `awswaf:managed:aws:atp:AttributeCompromisedCredentials`   | 
| AttributeUsernameTraversal |  Inspects for multiple requests from the same client session that use username traversal.  Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:attribute:username_traversal` and `awswaf:managed:aws:atp:AttributeUsernameTraversal`   | 
| AttributePasswordTraversal |  Inspects for multiple requests with the same username that use password traversal.  Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:attribute:password_traversal` and `awswaf:managed:aws:atp:AttributePasswordTraversal`   | 
| AttributeLongSession |  Inspects for multiple requests from the same client session that use long lasting sessions. The threshold is more than 6 hours of traffic that has at least one login request every 30 minutes. This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:attribute:long_session` and `awswaf:managed:aws:atp:AttributeLongSession`   | 
| TokenRejected |  Inspects for requests with tokens that are rejected by AWS WAF token management.  This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: Block Labels: None. To check for token rejected, use a label match rule to match on the label: `awswaf:managed:token:rejected`.   | 
| SignalMissingCredential |  Inspects for requests with credentials that are missing the username or password.  Rule action: Block Labels: `awswaf:managed:aws:atp:signal:missing_credential` and `awswaf:managed:aws:atp:SignalMissingCredential`   | 
| VolumetricIpFailedLoginResponseHigh |  Inspects for IP addresses that have recently been the source of too high a rate of failed login attempts. A high volume is more than 10 failed login requests from an IP address in a 10 minute window.  If you've configured the rule group to inspect the response body or JSON components, AWS WAF can inspect the first 65,536 bytes (64 KB) of these component types for success or failure indicators.  This rule applies the rule action and labeling to new web requests from an IP address, based on the success and failure responses from the protected resource to recent login attempts from the same IP address. You define how to count successes and failures when you configure the rule group.   AWS WAF only evaluates this rule in protection packs (web ACLs) that protect Amazon CloudFront distributions.   The thresholds that this rule applies can vary slightly due to latency. It's possible for the client to send more failed login attempts than are allowed before the rule starts matching on subsequent attempts.   Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:volumetric:ip:failed_login_response:high` and `awswaf:managed:aws:atp:VolumetricIpFailedLoginResponseHigh`  The rule group also applies the following related labels to requests, without any associated action. All counts are for a 10-minute window. `awswaf:managed:aws:atp:aggregate:volumetric:ip:failed_login_response:medium` for more than 5 failed requests, `awswaf:managed:aws:atp:aggregate:volumetric:ip:failed_login_response:low` for more than 1 failed request, `awswaf:managed:aws:atp:aggregate:volumetric:ip:successful_login_response:high` for more than 10 successful requests, `awswaf:managed:aws:atp:aggregate:volumetric:ip:successful_login_response:medium` for more than 5 successful requests, and `awswaf:managed:aws:atp:aggregate:volumetric:ip:successful_login_response:low` for more than 1 successful request.   | 
| VolumetricSessionFailedLoginResponseHigh |  Inspects for client sessions that have recently been the source of too high a rate of failed login attempts. A high volume is more than 10 failed login requests from a client session in a 30 minute window.  If you've configured the rule group to inspect the response body or JSON components, AWS WAF can inspect the first 65,536 bytes (64 KB) of these component types for success or failure indicators.  This rule applies the rule action and labeling to new web requests from a client session, based on the success and failure responses from the protected resource to recent login attempts from the same client session. You define how to count successes and failures when you configure the rule group.   AWS WAF only evaluates this rule in protection packs (web ACLs) that protect Amazon CloudFront distributions.   The thresholds that this rule applies can vary slightly due to latency. It's possible for the client to send more failed login attempts than are allowed before the rule starts matching on subsequent attempts.   This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: Block Labels: `awswaf:managed:aws:atp:aggregate:volumetric:session:failed_login_response:high` and `awswaf:managed:aws:atp:VolumetricSessionFailedLoginResponseHigh`  The rule group also applies the following related labels to requests, without any associated action. All counts are for a 30-minute window. `awswaf:managed:aws:atp:aggregate:volumetric:session:failed_login_response:medium` for more than 5 failed requests, `awswaf:managed:aws:atp:aggregate:volumetric:session:failed_login_response:low` for more than 1 failed request, `awswaf:managed:aws:atp:aggregate:volumetric:session:successful_login_response:high` for more than 10 successful requests, `awswaf:managed:aws:atp:aggregate:volumetric:session:successful_login_response:medium` for more than 5 successful requests, and `awswaf:managed:aws:atp:aggregate:volumetric:session:successful_login_response:low` for more than 1 successful request.   | 

# AWS WAF Bot Control rule group
<a name="aws-managed-rule-groups-bot"></a>

This section explains what the Bot Control managed rule group does.

VendorName: `AWS`, Name: `AWSManagedRulesBotControlRuleSet`, WCU: 50

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need to request a new bot classification for Bot Control or require additional information not covered here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/).

The Bot Control managed rule group provides rules that manage requests from bots. Bots can consume excess resources, skew business metrics, cause downtime, and perform malicious activities. 

## Protection levels
<a name="aws-managed-rule-groups-bot-prot-levels"></a>

The Bot Control managed rule group provides two levels of protection that you can choose from: 
+ **Common** – Detects a variety of self-identifying bots, such as web scraping frameworks, search engines, and automated browsers. Bot Control protections at this level identify common bots using traditional bot detection techniques, such as static request data analysis. The rules label traffic from these bots and block the ones that they cannot verify. 
+ **Targeted** – Includes the common-level protections and adds targeted detection for sophisticated bots that do not self identify. Targeted protections mitigate bot activity using a combination of rate limiting and CAPTCHA and background browser challenges. 
  + **`TGT_`** – Rules that provide targeted protection have names that begin with `TGT_`. All targeted protections use detection techniques such as browser interrogation, fingerprinting, and behavior heuristics to identify bad bot traffic. 
  + **`TGT_ML_`** – Targeted protection rules that use machine learning have names that begin with `TGT_ML_`. These rules use automated, machine-learning analysis of website traffic statistics to detect anomalous behavior indicative of distributed, coordinated bot activity. AWS WAF analyzes statistics about your website traffic such as timestamps, browser characteristics, and previous URL visited, to improve the Bot Control machine learning model. Machine learning capabilities are enabled by default, but you can disable them in your rule group configuration. When machine learning is disabled, AWS WAF does not evaluate these rules. 

The targeted protection level and the AWS WAF rate-based rule statement both provide rate limiting. For a comparison of the two options, see [Options for rate limiting in rate-based rules and targeted Bot Control rules](waf-rate-limiting-options.md).

## Considerations for using this rule group
<a name="aws-managed-rule-groups-bot-using"></a>

This rule group is part of the intelligent threat mitigation protections in AWS WAF. For information, see [Intelligent threat mitigation in AWS WAF](waf-managed-protections.md).

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

To keep your costs down and to be sure you're managing your web traffic as you want, use this rule group in accordance with the guidance at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md).

We periodically update our machine learning (ML) models for the targeted protection level ML-based rules, to improve bot predictions. The ML-based rules have names that start with `TGT_ML_`. If you notice a sudden and substantial change in the bot predictions made by these rules, contact us through your account manager or open a case at [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

## Labels added by this rule group
<a name="aws-managed-rule-groups-bot-labels"></a>

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 

### Token labels
<a name="aws-managed-rule-groups-bot-labels-token"></a>

This rule group uses AWS WAF token management to inspect and label web requests according to the status of their AWS WAF tokens. AWS WAF uses tokens for client session tracking and verification. 

For information about tokens and token management, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).

For information about the label components described here, see [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md).

**Client session label**  
The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. 

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Browser fingerprint label**  
The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client.

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Token status labels: Label namespace prefixes**  
Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. 

Each token status label begins with one of the following namespace prefixes: 
+ `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. 
+ `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. 

**Token status labels: Label names**  
Following the prefix, the rest of the label provides detailed token status information: 
+ `accepted` – The request token is present and contains the following: 
  + A valid challenge or CAPTCHA solution.
  + An unexpired challenge or CAPTCHA timestamp.
  + A domain specification that's valid for the protection pack (web ACL). 

  Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain.
+ `rejected` – The request token is present but doesn't meet the acceptance criteria. 

  Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. 
  + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. 
  + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. 
  + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. 
  + `rejected:invalid` – AWS WAF couldn't read the indicated token. 

  Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL).
+ `absent` – The request doesn't have the token or the token manager couldn't read it. 

  Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. 

### Bot Control labels
<a name="aws-managed-rule-groups-bot-labels-rg"></a>

The Bot Control managed rule group generates labels with the namespace prefix `awswaf:managed:aws:bot-control:` followed by the custom namespace and label name. The rule group might add more than one label to a request. 

Each label reflects the Bot Control rule findings: 
+ `awswaf:managed:aws:bot-control:bot:` – Information about the bot associated with the request. 
  + `awswaf:managed:aws:bot-control:bot:name:<name>` – The bot name, if one is available, for example, the custom namespaces `bot:name:slurp`, `bot:name:googlebot`, and `bot:name:pocket_parser`. 
  + `awswaf:managed:aws:bot-control:bot:name:<rfc_name>` – Identifies the specific bot using the RFC product token from the WBA signature. This is used to create granular custom rules for specific bots. For example, allow `GoogleBot` but rate-limit other crawlers. 
  + `awswaf:managed:aws:bot-control:bot:category:<category>` – The category of bot, as defined by AWS WAF, for example, `bot:category:search_engine` and `bot:category:content_fetcher`. 
  + `awswaf:managed:aws:bot-control:bot:account:<hash>` –For bots using Amazon Bedrock Agent Core only. This label contains an opaque hash uniquely identifying the AWS account that owns the agent. Use this label to create custom rules that allow, block, or rate-limit bots from specific AWS accounts without exposing account IDs in logs.
  + `awswaf:managed:aws:bot-control:bot:web_bot_auth:<status>` – Applied when Web Bot Authentication (WBA) validation is performed on a request. The status suffix indicates the verification outcome:
    + `web_bot_auth:verified` – Signature successfully validated against public key directory
    + `web_bot_auth:invalid` – Signature present but cryptograpic validation failed
    + `web_bot_auth:expired` – Signature used an expired cryptograpic key
    + `web_bot_auth:unknown_bot` – Key ID not found in the key directory
**Note**  
When the `web_bot_auth:verified` label is present, the `CategoryAI` and `TGT_TokenAbsent` rules do not match, allowing verified WBA hosts to proceed.
  + `awswaf:managed:aws:bot-control:bot:organization:<organization>` – The bot's publisher, for example, `bot:organization:google`. 
  + `awswaf:managed:aws:bot-control:bot:verified` – Used to indicate a bot that identifies itself and that Bot Control has been able to verify. This is used for common desirable bots, and can be useful when combined with category labels like `bot:category:search_engine` or name labels like `bot:name:googlebot`. 
**Note**  
Bot Control uses the IP address from the web request origin to help determine whether a bot is verified. You can’t configure it to use the AWS WAF forwarded IP configuration, to inspect a different IP address source. If you have verified bots that route through a proxy or load balancer, you can add a rule that runs before the Bot Control rule group to help with this. Configure your new rule to use the forwarded IP address and explicitly allow requests from the verified bots. For information about using forwarded IP addresses, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md).
  + `awswaf:managed:aws:bot-control:bot:vendor:<vendor_name>` – Identifies the vendor or operator of a verified bot. Currently available only for Agentcore. Use to create custom rules that allow or block specific bot vendors regardless of individual bot names.
  + `awswaf:managed:aws:bot-control:bot:user_triggered:verified` – Used to indicate a bot that is similar to a verified bot, but that might be directly invoked by end users. This category of bot is treated by the Bot Control rules like an unverified bot. 
  + `awswaf:managed:aws:bot-control:bot:developer_platform:verified` – Used to indicate a bot that is similar to a verified bot, but that is used by developer platforms for scripting, for example Google Apps Script. This category of bot is treated by the Bot Control rules like an unverified bot. 
  + `awswaf:managed:aws:bot-control:bot:unverified` – Used to indicate a bot that identifies itself, so it can be named and categorized, but that doesn't publish information that can be used to independently verify its identify. These types of bot signatures can be falsified, and so are treated as unverified. 
+ `awswaf:managed:aws:bot-control:targeted:<additional-details> ` – Used for labels that are specific to the Bot Control targeted protections. 
+ `awswaf:managed:aws:bot-control:signal:<signal-details>` and `awswaf:managed:aws:bot-control:targeted:signal:<signal-details> `– Used to provide additional information about the request in some situations. 

  The following are examples of signal labels. This is not an exhaustive list:
  + `awswaf:managed:aws:bot-control:signal:cloud_service_provider:<CSP>` – Indicates a cloud service provider (CSP) for the request. Examples of CSPs include `aws` for Amazon Web Services infrastructure, `gcp` for Google Cloud Platform (GCP) infrastructure, `azure` for Microsoft Azure cloud services, and `oracle` for Oracle Cloud services. 
  + `awswaf:managed:aws:bot-control:targeted:signal:browser_automation_extension` – Indicates the detection of a browser extension that assists in automation, such as Selenium IDE. 

    This label is added whenever a user has this type of extension installed, even if they're not actively using it. If you implement a label match rule for this, be aware of this possibility of false positives in your rule logic and action settings. For example, you might use a CAPTCHA action instead of Block or you might combine this label match with other label matches, to increase your confidence that automation is in use.
  + `awswaf:managed:aws:bot-control:signal:automated_browser` – Indicates that the request contains indicators that the client browser might be automated.
  + `awswaf:managed:aws:bot-control:targeted:signal:automated_browser` – Indicates that the request's AWS WAF token contains indicators that the client browser might be automated.

You can retrieve all labels for a rule group through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the `AvailableLabels` property in the response. 

The Bot Control managed rule group applies labels to a set of verifiable bots that are commonly allowed. The rule group doesn't block these verified bots. If you want, you can block them, or a subset of them by writing a custom rule that uses the labels applied by the Bot Control managed rule group. For more information about this and examples, see [AWS WAF Bot Control](waf-bot-control.md).

## Bot Control rules listing
<a name="aws-managed-rule-groups-bot-rules"></a>

This section lists the Bot Control rules.

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need to request a new bot classification for Bot Control or require additional information not covered here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/).


| Rule name | Description | 
| --- | --- | 
| CategoryAdvertising |  Inspects for bots that are used for advertising purposes. For example, you might use third-party advertising services that need to programmatically access your website.  Rule action, applied only to unverified bots: Block Labels: `awswaf:managed:aws:bot-control:bot:category:advertising` and `awswaf:managed:aws:bot-control:CategoryAdvertising`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryArchiver |  Inspects for bots that are used for archiving purposes. These bots crawl the web and capture content for the purposes of creating archives. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:archiver` and `awswaf:managed:aws:bot-control:CategoryArchiver`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryContentFetcher |  Inspects for bots that visit the application's website on behalf of a user, to fetch content like RSS feeds or to verify or validate your content.  Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:content_fetcher` and `awswaf:managed:aws:bot-control:CategoryContentFetcher`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryEmailClient |  Inspects for bots that check links within emails that point to the application's website. This can include bots run by businesses and email providers, to verify links in emails and flag suspicious emails. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:email_client` and `awswaf:managed:aws:bot-control:CategoryEmailClient`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryHttpLibrary |  Inspects for requests that are generated by bots from the HTTP libraries of various programming languages. These may include API requests that you choose to allow or monitor. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:http_library` and `awswaf:managed:aws:bot-control:CategoryHttpLibrary`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryLinkChecker |  Inspects for bots that check for broken links.  Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:link_checker` and `awswaf:managed:aws:bot-control:CategoryLinkChecker`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryMiscellaneous |  Inspects for miscellaneous bots that don't match other categories.  Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:miscellaneous` and `awswaf:managed:aws:bot-control:CategoryMiscellaneous`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryMonitoring |  Inspects for bots that are used for monitoring purposes. For example, you might use bot monitoring services that periodically ping your application website to monitor things like performance and uptime. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:monitoring` and `awswaf:managed:aws:bot-control:CategoryMonitoring`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryPagePreview |  Inspects for bots that generate page previews and link previews when content is shared on messaging platforms, social media, or collaboration tools. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:page_preview` and `awswaf:managed:aws:bot-control:CategoryPagePreview`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryScrapingFramework |  Inspects for bots from web scraping frameworks, which are used to automate crawling and extracting content from websites.  Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:scraping_framework` and `awswaf:managed:aws:bot-control:CategoryScrapingFramework`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategorySearchEngine |  Inspects for search engine bots, which crawl websites to index content and make the information available for search engine results. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:search_engine` and `awswaf:managed:aws:bot-control:CategorySearchEngine`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategorySecurity |  Inspects for bots that scan web applications for vulnerabilities or that perform security audits. For example, you might use a third-party security vendor that scans, monitors, or audits your web application’s security. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:security` and `awswaf:managed:aws:bot-control:CategorySecurity`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategorySeo |  Inspects for bots that are used for search engine optimization. For example, you might use search engine tools that crawl your site to help you improve your search engine rankings.  Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:seo` and `awswaf:managed:aws:bot-control:CategorySeo`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategorySocialMedia |  Inspects for bots that are used by social media platforms to provide content summaries when users share your content. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:social_media` and `awswaf:managed:aws:bot-control:CategorySocialMedia`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryWebhooks |  Inspects for bots that deliver automated notifications and data updates from one application to another through HTTP callbacks. Rule action, applied only to unverified bots: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:webhooks` and `awswaf:managed:aws:bot-control:CategoryWebhooks`  For verified bots, the rule group does not match this rule and takes no action, but it adds the bot name and category labeling plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| CategoryAI |  Inspects for artificial intelligence (AI) bots.  This rule applies the action to all matches, regardless of whether the bots are verified or unverified. Rule action: Block  Labels: `awswaf:managed:aws:bot-control:bot:category:ai` and `awswaf:managed:aws:bot-control:CategoryAI`  For verified bots, the rule group matches this rule and takes an action. It additionally adds the bot name and category labeling, the rule labeling, plus the label `awswaf:managed:aws:bot-control:bot:verified`.   | 
| SignalAutomatedBrowser |  Inspects requests that are not from verified bots for indicators that the client browser might be automated. Automated browsers can be used for testing or scraping. For example, you might use these types of browsers to monitor or verify your application website. Rule action: Block  Labels: `awswaf:managed:aws:bot-control:signal:automated_browser` and `awswaf:managed:aws:bot-control:SignalAutomatedBrowser`  For verified bots, the rule group does not match this rule and does not apply any signal or rule labels.  | 
| SignalKnownBotDataCenter |  Inspects requests that are not from verified bots for indicators of data centers that are typically used by bots.  Rule action: Block  Labels: `awswaf:managed:aws:bot-control:signal:known_bot_data_center` and `awswaf:managed:aws:bot-control:SignalKnownBotDataCenter`  For verified bots, the rule group does not match this rule and does not apply any signal or rule labels.  | 
| SignalNonBrowserUserAgent |  Inspects requests that are not from verified bots for user agent strings that don't seem to be from a web browser. This category can include API requests.  Rule action: Block  Labels: `awswaf:managed:aws:bot-control:signal:non_browser_user_agent` and `awswaf:managed:aws:bot-control:SignalNonBrowserUserAgent`  For verified bots, the rule group does not match this rule and does not apply any signal or rule labels.  | 
| TGT\$1VolumetricIpTokenAbsent |  Inspects requests that are not from verified bots with 5 or more requests from a single client in the last 5 minutes that don't include a valid challenge token. For information about tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).  It's possible for this rule to match on a request that has a token if requests from the same client have recently been missing tokens.  The threshold that this rule applies can vary slightly due to latency.   This rule handles missing tokens differently from the token labeling: `awswaf:managed:token:absent`. The token labeling labels individual requests that don't have a token. This rule maintains a count of requests that are missing their token for each client IP, and it matches against clients that go over the limit.  Rule action: Challenge  Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:ip:token_absent` and `awswaf:managed:aws:bot-control:TGT_VolumetricIpTokenAbsent`   | 
| TGT\$1TokenAbsent |  Inspects requests that are not from verified bots that don't include a valid challenge token. For information about tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).  Rule action: Count  Labels: `awswaf:managed:aws:bot-control:TGT_TokenAbsent`   | 
| TGT\$1VolumetricSession |  Inspects for an abnormally high number of requests that are not from verified bots that come from a single client session in a 5 minute window. The evaluation is based on a comparison to standard volumetric baselines that AWS WAF maintains using historic traffic patterns.  This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).  This rule can take 5 minutes to go into effect after you enable it. Bot Control identifies anomalous behavior in your web traffic by comparing the current traffic to traffic baselines that AWS WAF computes.   Rule action: CAPTCHA  Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:high` and `awswaf:managed:aws:bot-control:TGT_VolumetricSession`  The rule group applies the following labels to medium volume and lower volume requests that are above a minimum threshold. For these levels, the rule takes no action, regardless of whether the client is verified: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:medium` and `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:low`.  | 
| TGT\$1VolumetricSessionMaximum |  Inspects for an abnormally high number of requests that are not from verified bots that come from a single client session in a 5 minute window. The evaluation is based on a comparison to standard volumetric baselines that AWS WAF maintains using historic traffic patterns.  This rule indicates the maximum confidence in the assessment. This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).  This rule can take 5 minutes to go into effect after you enable it. Bot Control identifies anomalous behavior in your web traffic by comparing the current traffic to traffic baselines that AWS WAF computes.   Rule action: Block  Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:maximum` and `awswaf:managed:aws:bot-control:TGT_VolumetricSessionMaximum`   | 
| TGT\$1SignalAutomatedBrowser |  Inspects the tokens of requests that are not from verified bots for indicators that the client browser might be automated. For more information, see [AWS WAF token characteristics](waf-tokens-details.md). This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: CAPTCHA  Labels: `awswaf:managed:aws:bot-control:targeted:signal:automated_browser` and `awswaf:managed:aws:bot-control:TGT_SignalAutomatedBrowser`   | 
| TGT\$1SignalBrowserAutomationExtension |  Inspects requests that are not from verified bots that indicate the presence of a browser extension that assists in automation, such as Selenium IDE. This rule matches whenever a user has this type of extension installed, even if they're not actively using it.  This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: CAPTCHA  Labels: `awswaf:managed:aws:bot-control:targeted:signal:browser_automation_extension` and `awswaf:managed:aws:bot-control:TGT_SignalBrowserAutomationExtension`  | 
| TGT\$1SignalBrowserInconsistency |  Inspects requests that are not from verified bots for inconsistent browser interrogation data. For more information, see [AWS WAF token characteristics](waf-tokens-details.md). This inspection only applies when the web request has a token. Tokens are added to requests by the application integration SDKs and by the rule actions CAPTCHA and Challenge. For more information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). Rule action: CAPTCHA  Labels: `awswaf:managed:aws:bot-control:targeted:signal:browser_inconsistency` and `awswaf:managed:aws:bot-control:TGT_SignalBrowserInconsistency`   | 
|  TGT\$1ML\$1CoordinatedActivityLow, TGT\$1ML\$1CoordinatedActivityMedium, TGT\$1ML\$1CoordinatedActivityHigh  |  Inspects requests that are not from verified bots for anomalous behavior that’s consistent with distributed, coordinated bot activity. The rule levels indicate the level of confidence that a group of requests are participants in a coordinated attack.   These rules only run if the rule group is configured to use machine learning (ML). For information about configuring this choice, see [Adding the AWS WAF Bot Control managed rule group to your web ACL](waf-bot-control-rg-using.md).   The thresholds that these rules apply can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   AWS WAF performs this inspection through machine learning analysis of website traffic statistics. AWS WAF analyzes web traffic every few minutes and optimizes the analysis for the detection of low intensity, long-duration bots that are distributed across many IP addresses.  These rules might match on a very small number of requests before determining that a coordinated attack is not underway. So if you see just a match or two, the results might be false positives. If you see a lot of matches coming out of these rules however, then you're probably experiencing a coordinated attack.   These rules can take up to 24 hours to go into effect after you enable the Bot Control targeted rules with the ML option. Bot Control identifies anomalous behavior in your web traffic by comparing the current traffic to traffic baselines that AWS WAF has computed. AWS WAF only computes the baselines while you're using the Bot Control targeted rules with the ML option, and it can take up to 24 hours to establish meaningful baselines.   We periodically update our machine learning models for these rules, to improve bot predictions. If you notice a sudden and substantial change in the bot predictions that these rules make, contact your account manager or open a case at [AWS Support Center](https://console.aws.amazon.com/support/home#/).  Rule actions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html) Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:coordinated_activity:low\|medium\|high` and `awswaf:managed:aws:bot-control:TGT_ML_CoordinatedActivityLow\|Medium\|High`   | 
|  TGT\$1TokenReuseIpLow, TGT\$1TokenReuseIpMedium, TGT\$1TokenReuseIpHigh  |  Inspects requests that are not from verified bots for the use of a single token among multiple IPs in the last 5 minutes. Each level has a limit on the number of distinct IPs:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html)  The thresholds that these rules apply can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule actions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html) Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:token_reuse:ip:low\|medium\|high` and `awswaf:managed:aws:bot-control:TGT_TokenReuseIpLow\|Medium\|High`   | 
|  TGT\$1TokenReuseCountryLow, TGT\$1TokenReuseCountryMedium, TGT\$1TokenReuseCountryHigh  |  Inspects requests that are not from verified bots for the use of a single token across multiple countries in the last 5 minutes. Each level has a limit on the number of distinct countries:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html)  The thresholds that these rules apply can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule actions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html) Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:token_reuse:country:low\|medium\|high` and `awswaf:managed:aws:bot-control:TGT_TokenReuseCountryLow\|Medium\|High`   | 
|  TGT\$1TokenReuseAsnLow, TGT\$1TokenReuseAsnMedium, TGT\$1TokenReuseAsnHigh  |  Inspects requests that are not from verified bots for the use of a single token across multiple networking autonomous system numbers (ASNs) in the last 5 minutes. Each level has a limit on the number of distinct ASNs:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html)  The thresholds that these rules apply can vary slightly due to latency. A few requests might make it through beyond the limit before the rule action is applied.   Rule actions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-bot.html) Labels: `awswaf:managed:aws:bot-control:targeted:aggregate:volumetric:session:token_reuse:asn:low\|medium\|high` and `awswaf:managed:aws:bot-control:TGT_TokenReuseAsnLow\|Medium\|High`   | 

# AWS WAF Distributed Denial of Service (DDoS) prevention rule group
<a name="aws-managed-rule-groups-anti-ddos"></a>

This section describes the AWS WAF managed rule group for the protection against Distributed Denial of Service (DDoS) attacks.

VendorName: `AWS`, Name: `AWSManagedRulesAntiDDoSRuleSet`, WCU: 50

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 

The Anti-DDoS managed rule group provides rules that detect and manage requests that are participating or likely to be participating in DDoS attacks. Additionally, the rule group labels all requests that it evaluates during a probable event. 

## Considerations for using this rule group
<a name="aws-managed-rule-groups-anti-ddos-using"></a>

This rule group provides soft and hard mitigations for web requests coming to resources that are under DDoS attack. To detect different threat levels, you can tune the sensitivity of both mitigation types to high, medium, or low suspicion levels.
+ **Soft mitigation** – The rule group can send silent browser challenges in response to requests that can handle the challenge interstitial. For information about the requirements for running the challenge, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md).
+ **Hard mitigation** – The rule group can block requests altogether. 

For more information about how the rule group works and how to configure it, see [Advanced Anti-DDoS protection using the AWS WAF Anti-DDoS managed rule group](waf-anti-ddos-advanced.md). 

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

This rule group is part of the intelligent threat mitigation protections in AWS WAF. For information, see [Intelligent threat mitigation in AWS WAF](waf-managed-protections.md).

To minimize costs and optimize traffic management, use this rule group in accordance with best practice guidelines. See, [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md).

## Labels added by this rule group
<a name="aws-managed-rule-groups-anti-ddos-labels"></a>

This managed rule group adds labels to the web requests that it evaluates, which are available to rules that run after this rule group in your protection pack (web ACL). AWS WAF also records the labels to Amazon CloudWatch metrics. For general information about labels and label metrics, see [Web request labeling](waf-labels.md) and [Label metrics and dimensions](waf-metrics.md#waf-metrics-label). 

### Token labels
<a name="aws-managed-rule-groups-anti-ddos-labels-token"></a>

This rule group uses AWS WAF token management to inspect and label web requests according to the status of their AWS WAF tokens. AWS WAF uses tokens for client session tracking and verification. 

For information about tokens and token management, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).

For information about the label components described here, see [Label syntax and naming requirements in AWS WAF](waf-rule-label-requirements.md).

**Client session label**  
The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. 

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Browser fingerprint label**  
The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client.

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Token status labels: Label namespace prefixes**  
Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. 

Each token status label begins with one of the following namespace prefixes: 
+ `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. 
+ `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. 

**Token status labels: Label names**  
Following the prefix, the rest of the label provides detailed token status information: 
+ `accepted` – The request token is present and contains the following: 
  + A valid challenge or CAPTCHA solution.
  + An unexpired challenge or CAPTCHA timestamp.
  + A domain specification that's valid for the protection pack (web ACL). 

  Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain.
+ `rejected` – The request token is present but doesn't meet the acceptance criteria. 

  Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. 
  + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. 
  + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. 
  + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. 
  + `rejected:invalid` – AWS WAF couldn't read the indicated token. 

  Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL).
+ `absent` – The request doesn't have the token or the token manager couldn't read it. 

  Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. 

### Anti-DDoS labels
<a name="aws-managed-rule-groups-anti-ddos-labels-rg"></a>

The Anti-DDoS managed rule group generates labels with the namespace prefix `awswaf:managed:aws:anti-ddos:` followed by any custom namespace and the label name. Each label reflects some aspect of the Anti-DDoS findings.

The rule group might add more than one of the following labels to a request, in addition to the labels that are added by individual rules. 
+ `awswaf:managed:aws:anti-ddos:event-detected` – Indicates that the request is going to a protected resource for which the managed rule group detects a DDoS event. The managed rule group detects events when the traffic to the resource has a significant deviation from the resource's traffic baseline. 

  The rule group adds this label to every request that goes to the resource while it's in this state, so legitimate traffic and attack traffic get this label. 
+ `awswaf:managed:aws:anti-ddos:ddos-request` – Indicates that the request is coming from a source suspected of participating in an event. 

  In addition to the general label, the rule group adds the following labels that indicate the level of confidence. 

  `awswaf:managed:aws:anti-ddos:low-suspicion-ddos-request` – Indicates a probable DDoS attack request.

  `awswaf:managed:aws:anti-ddos:medium-suspicion-ddos-request` – Indicates a very likely DDoS attack request.

  `awswaf:managed:aws:anti-ddos:high-suspicion-ddos-request` – Indicates a highly likely DDoS attack request.
+ `awswaf:managed:aws:anti-ddos:challengeable-request` – Indicates that the request URI is capable of handling the Challenge action. The managed rule group applies this to any request whose URI isn't exempted. URIs are exempted if they match the rule group's exempt URI regular expressions. 

  For information about the requirements for requests that can take a silent browser challenge, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md).

You can retrieve all labels for a rule group through the API by calling `DescribeManagedRuleGroup`. The labels are listed in the `AvailableLabels` property in the response. 

The Anti-DDoS managed rule group applies labels to requests, but doesn't always act on them. The request management depends on the confidence with which the rule group determines participation in an attack. If you want, you can manage requests that the rule group labels by adding a label matching rule that runs after the rule group. For more information about this and examples, see [AWS WAF Distributed Denial of Service (DDoS) prevention](waf-anti-ddos.md).

## Anti-DDoS rules listing
<a name="aws-managed-rule-groups-anti-ddos-rules"></a>

This section lists the Anti-DDoS rules.

 

**Note**  
This documentation covers the most recent static version release of this managed rule group. We report version changes in the changelog log at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md). For information about other versions, use the API command [DescribeManagedRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_DescribeManagedRuleGroup.html).   
The information that we publish for the rules in the AWS Managed Rules rule groups is intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules.   
If you need more information than you find here, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/). 


| Rule name | Description | 
| --- | --- | 
| ChallengeAllDuringEvent |  Matches requests that have the label `awswaf:managed:aws:anti-ddos:challengeable-request` for any protected resource that is currently under attack.  Rule action: Challenge You can only override this rule action to Allow or Count. The use of Allow is not recommended. For any rule action setting, the rule only matches requests that have the `challengeable-request` label. The configuration of this rule affects the evaluation of the next rule, `ChallengeDDoSRequests`. AWS WAF only evaluates that rule when the action for this rule has override set to Count, in the web ACL's configuration of the managed rule group.  If your workload is vulnerable to unexpected request volume changes, we recommend challenging all challengable requests, by keeping the default action setting of Challenge. For less sensitive applications, you can set the action for this rule to Count and then tune the sensitivity of your Challenge responses with the rule `ChallengeDDoSRequests`.  Labels: `awswaf:managed:aws:anti-ddos:ChallengeAllDuringEvent`   | 
| ChallengeDDoSRequests |  Matches requests for a protected resource that meet or exceed the rule group's configured challenge sensitivity setting, during times that the resource is under attack.  Rule action: Challenge You can only override this rule action to Allow or Count. The use of Allow is not recommended. In any case, the rule only matches requests that have the `challengeable-request` label. AWS WAF only evaluates this rule if you override the action to Count in the prior rule, `ChallengeAllDuringEvent`.  Labels: `awswaf:managed:aws:anti-ddos:ChallengeDDoSRequests`   | 
| DDoSRequests |  Matches requests for a protected resource that meet or exceed the rule group's configured block sensitivity setting, during times that the resource is under attack.  Rule action: Block Labels: `awswaf:managed:aws:anti-ddos:DDoSRequests`   | 

# Deployments for versioned AWS Managed Rules rule groups
<a name="waf-managed-rule-groups-deployments"></a>

This section introduces how AWS deploys updates to AWS Managed Rules rule groups.

AWS deploys changes to its versioned AWS Managed Rules rule groups in three standard deployments: release candidate, static version, and default version. Additionally, AWS might sometimes need to release an exception deployment or roll back a default version deployment. 

**Note**  
This section applies only to AWS Managed Rules rule groups that are versioned. The only rule groups that aren't versioned are the IP reputation rule groups. 

**Topics**
+ [

# Notifications for AWS Managed Rules rule groups deployments
](waf-managed-rule-groups-deployments-notifications.md)
+ [

# Overview of the standard deployments for AWS Managed Rules
](waf-managed-rule-groups-deployments-standard.md)
+ [

# Typical version states for AWS Managed Rules
](waf-managed-rule-groups-typical-version-states.md)
+ [

# Release candidate deployments for AWS Managed Rules
](waf-managed-rule-groups-deployments-release-candidate.md)
+ [

# Static version deployments for AWS Managed Rules
](waf-managed-rule-groups-deployments-static-version.md)
+ [

# Default version deployments for AWS Managed Rules
](waf-managed-rule-groups-deployments-default-version.md)
+ [

# Exception deployments for AWS Managed Rules
](waf-managed-rule-groups-deployments-exceptions.md)
+ [

# Default deployment rollbacks for AWS Managed Rules
](waf-managed-rule-groups-deployments-default-rollbacks.md)

# Notifications for AWS Managed Rules rule groups deployments
<a name="waf-managed-rule-groups-deployments-notifications"></a>

This section explains how Amazon SNS notifications work with AWS Managed Rules rule groups.

The versioned AWS Managed Rules rule groups all provide SNS update notifications for deployments and they all use the same SNS topic Amazon Resource Name (ARN). The only rule groups that aren't versioned are the IP reputation rule groups. 

For deployments that affect your protections, such as changes to the default version, AWS provides SNS notifications to inform you of planned deployments and to let you know when a deployment is starting. For deployments that don't affect your protections, such as release candidate and static version deployments, AWS might notify you after the deployment has started or even after it's completed. At the completion of the deployment of a new static version, AWS updates this guide, in the changelog at [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md) and in the document history page at [Document history](doc-history.md). 

To receive all updates that AWS provides for the AWS Managed Rules rule groups, subscribe to the RSS feed from any HTML page of this guide, and subscribe to the SNS topic for the AWS Managed Rules rule groups. For information about subscribing to the SNS notifications, see [Getting notified of new versions and updates to a managed rule group](waf-using-managed-rule-groups-sns-topic.md).

**Contents of the SNS notifications**  
The fields in the Amazon SNS notifications always include the Subject, Message, and MessageAttributes. Additional fields depend on the type of message and which managed rule group the notification is for. The following shows an example notification listing for `AWSManagedRulesCommonRuleSet`.

```
{
    "Type": "Notification",
    "MessageId": "4286b830-a463-5e61-bd15-e1ae72303868",
    "TopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic",
    "Subject": "New version available for rule group AWSManagedRulesCommonRuleSet",
    "Message": "Welcome to AWSManagedRulesCommonRuleSet version 1.5! We've updated the regex specification in this version to improve protection coverage, adding protections against insecure deserialization. For details about this change, see http://updatedPublicDocs.html. Look for more exciting updates in the future! ",
    "Timestamp": "2021-08-24T11:12:19.810Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEHXgJm...",
    "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem",
    "SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:123456789012:MyTopic&Token=2336412f37...",
    "MessageAttributes": {
        "major_version": {
            "Type": "String",
            "Value": "v1"
        },
        "managed_rule_group": {
            "Type": "String",
            "Value": "AWSManagedRulesCommonRuleSet"
        }
    }
}
```

# Overview of the standard deployments for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-standard"></a>

AWS rolls out new AWS Managed Rules functionality using three standard deployment stages: release candidate, static version, and default version. 

The following diagram depicts these standard deployments. Each is described in more detail in the sections that follow. 

![\[Four vertical swimlanes show different standard deployment stages. The leftmost swimlane shows the default version set to the recommended static version 1.4. The second swimlane shows the default set to a release candidate (RC) version for testing and tuning. The RC version contains 1.4 rules and RC rules. A note indicates that after testing, the default is returned to the recommended static version. The third swimlane shows the creation of a static version 1.5 from the rules in the release candidate version. The fourth swimlane shows the default version set to the new recommended static version 1.5.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-flowchart-diagram.png)


# Typical version states for AWS Managed Rules
<a name="waf-managed-rule-groups-typical-version-states"></a>

Normally, a versioned managed rule group has a number of unexpired static versions, and the default version points to the static version that AWS recommends. The following figure shows an example of the typical set of static versions and default version setting. 

![\[Three static versions Version_1.2, Version_1.3, and Version_1.4 are stacked, with Version_1.4 on the top. Version_1.4 has two rules, RuleA and RuleB, both with production action. A default version indicator points to Version_1.4.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-diagram.png)


The production action for most rules in a static version is Block, but it might be set to something different. For detailed information about rule action settings, see the rule listings for each rule group at [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md). 

# Release candidate deployments for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-release-candidate"></a>

This section explains how a temporary release candidate deployment works.

When AWS has a candidate set of rule changes for a managed rule group, it tests them in a temporary release candidate deployment. AWS evaluates the candidate rules in count mode against production traffic, and performs final tuning activities, including mitigating false positives. AWS tests release candidate rules in this way for all customers who use the default version of the rule group. Release candidate deployments don't apply to customers who use a static version of the rule group.

If you use the default version, a release candidate deployment won't alter how your web traffic is managed by the rule group. You might notice the following while the candidate rules are being tested: 
+ Default version name change from `Default (using Version_X.Y)` to `Default (using Version_X.Y_PLUS_RC_COUNT)`. 
+ Additional count metrics in Amazon CloudWatch with `RC_COUNT` in their names. These are generated by the release candidate rules.

AWS tests a release candidate for about a week, then removes it and resets the default version to the current recommended static version. 

AWS performs the following steps for a release candidate deployment: 

1. **Create the release candidate** – AWS adds a release candidate based on the current recommended static version, which is the version that the default is pointing to. 

   The name of the release candidate is the static version name appended with `_PLUS_RC_COUNT`. For example, if the current recommended static version is `Version_2.1`, then the release candidate would be named `Version_2.1_PLUS_RC_COUNT`.

   The release candidate contains the following rules: 
   + Rules copied exactly from the current recommended static version, with no changes to rule configurations. 
   + Candidate new rules with rule action set to Count and with names that end with `_RC_COUNT`. 

     Most candidate rules provide proposed improvements to rules that exist already in the rule group. The name for each of these rules is the existing rule's name appended with `_RC_COUNT`. 

1. **Set the default version to the release candidate and test** – AWS sets the default version to point to the new release candidate, to perform testing against your production traffic. Testing usually takes about a week.

    You'll see the default version's name change from the one that indicates only the static version, such as `Default (using Version_1.4)`, to one that indicates the static version plus the release candidate rules, such as `Default (using Version_1.4_PLUS_RC_COUNT)`. This naming scheme lets you identify which static version you're using to manage your web traffic. 

   The following diagram shows the state of the example rule group versions at this point.   
![\[At the top of the figure are three stacked static versions, with Version_1.4 on the top. Separate from the static versions stack is the version Version_1.4_PLUS_RC_COUNT. This version contains the rules from Version_1.4 and it also contains two release candidate rules, RuleB_RC_COUNT and RuleZ_RC_COUNT, both with count action. The default version indicator points to Version_1.4_PLUS_RC_COUNT.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-rc-diagram.png)

   The release candidate rules are always configured with Count action, so they don't alter how the rule group manages web traffic. 

   The release candidate rules generate Amazon CloudWatch count metrics that AWS uses to verify behavior and to identify false positives. AWS makes adjustments as needed, to tune the behavior of the release candidate count rules. 

   The release candidate version isn't a static version, and it's not available for you to choose from the list of static rule group versions. You can only see the name of the release candidate version in the default version specification.

1. **Return the default version to the recommended static version** – After testing the release candidate rules, AWS sets the default version back to the current recommended static version. The default version name setting drops the `_PLUS_RC_COUNT` ending, and the rule group stops generating CloudWatch count metrics for the release candidate rules. This is a silent change, and is not the same as a deployment of a default version rollback.

   The following diagram shows the state of the example rule group versions after the testing of the release candidate is complete.   
![\[This is the typical version states figure again. Three static versions Version_1.2, Version_1.3, and Version_1.4 are stacked with Version_1.4 on the top. Version_1.4 has two rules, RuleA and RuleB, both with production action. A default version indicator points to Version_1.4.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-rc-complete-diagram.png)

**Timing and notifications**  
AWS deploys release candidate versions on an as-needed basis, to test improvements to a rule group. 
+ **SNS** – AWS sends an SNS notification at the start of the deployment. The notification indicates the estimated time that the release candidate will be tested. When testing is complete, AWS silently returns the default to the static version setting, without a second notification.
+ **Change log** – AWS doesn't update the change log or other parts of this guide for this type of deployment.

# Static version deployments for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-static-version"></a>

When AWS determines that a release candidate provides valuable changes to the rule group, AWS deploys a new static version for the rule group based on the release candidate. This deployment doesn't change the default version of the rule group. 

The new static version contains the following rules from the release candidate: 
+ Rules from the prior static version that don't have a replacement candidate among the release candidate rules. 
+ Release candidate rules, with the following changes: 
  + AWS changes the rule name by removing the release candidate suffix `_RC_COUNT`.
  + AWS changes the rule actions from Count to their production rule actions. 

   For release candidate rules that are replacements of prior existing rules, this replaces the functionality of the prior rules in the new static version. 

The following diagram depicts the creation of the new static version from the release candidate. 

![\[At the top of the figure is the release candidate version Version_1.4_PLUS_RC_COUNT, with the same rules as in the prior release candidate deployment figure. The version contains the rules from Version_1.4 and it also contains release candidate rules RuleB_RC_COUNT and RuleZ_RC_COUNT, both with count action. Below this, at the bottom of the figure is a static version Version_1.5, which contains rules RuleA, RuleB, and RuleZ, all with production action. Arrows point from the RC version to Version_1.5 to indicate that RuleA is copied from the Version_1.4 rules and RuleB and RuleZ are copied from the release candidate rules. All rules in Version_1.5 have production actions.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-create-static-diagram.png)


After deployment, the new static version is available for you to test and to use in your protections if you want to. You can review new and updated rule actions and descriptions in the rule group's rule listings at [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md). 

A static version is immutable after deployment, and only changes when AWS expires it. For information about version life cycles, see [Using versioned managed rule groups in AWS WAF](waf-managed-rule-groups-versioning.md).

**Timing and notifications**  
AWS deploys a new static version as needed, in order to deploy improvements to rule group functionality. The deployment of a static version doesn't impact the default version setting.
+ **SNS** – AWS sends an SNS notification when the deployment completes.
+ **Change log** – After the deployment is complete everywhere that AWS WAF is available, AWS updates the rule group definition in this guide as needed, and then announces the release in the AWS Managed Rules rule group change log and in the documentation history page. 

# Default version deployments for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-default-version"></a>

When AWS determines that a new static version provides improved protections for the rule group compared to the current default, AWS updates the default version to the new static version. AWS might release multiple static versions before promoting one to the rule group's default version. 

The following diagram shows the state of the example rule group versions after AWS moves the default version setting to the new static version. 

![\[This is similar to the typical version states figure, but with Version_1.5 on the top of the stack and the default indicator pointing to it.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/amr-rg-versions-new-default-diagram.png)


Before deploying this change to the default version, AWS provides notifications so that you can test and prepare for the upcoming changes. If you use the default version, you can take no action and remain on it through the update. If instead you want to delay switching to the new version, before the planned start of the default version deployment, you can explicitly configure your rule group to use the static version that the default is set to. 

**Timing and notifications**  
AWS updates the default version when it recommends a different static version for the rule group than the one that's currently in use. 
+ **SNS** – AWS sends an SNS notification at least one week prior to the targeted deployment day and then another on the deployment day, at the start of the deployment. Each notification includes the rule group name, the static version that the default version is being updated to, the deployment date, and the scheduled timing of the deployment for each AWS Region where the update is being performed. 
+ **Change log** – AWS doesn't update the change log or other parts of this guide for this type of deployment.

# Exception deployments for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-exceptions"></a>

AWS might bypass the standard deployment stages in order to quickly deploy updates that address critical security risks. An exception deployment might involve any of the standard deployment types, and it might be rolled out quickly across the AWS Regions. 

AWS provides as much advance notification as possible for exception deployments. 

**Timing and notifications**  
AWS performs exception deployments only when required. 
+ **SNS** – AWS sends an SNS notification as far ahead of the targeted deployment day as possible and then another one at the start of the deployment. Each notification includes the rule group name, the change that's being made, and the deployment date. 
+ **Change log** – If the deployment is for a static version, after the deployment is complete everywhere that AWS WAF is available, AWS updates the rule group definition in this guide as needed, and then announces the release in the AWS Managed Rules rule group change log and in the documentation history page. 

# Default deployment rollbacks for AWS Managed Rules
<a name="waf-managed-rule-groups-deployments-default-rollbacks"></a>

Under certain conditions, AWS might roll back the default version to its prior setting. A rollback usually takes less than ten minutes for all AWS Regions.

AWS performs a rollback only to mitigate a significant issue in a static version, such as an unacceptably high level of false positives. 

After the rollback of the default version setting, AWS expedites both the expiration of the static version that has the issue and the release of a new static version to address the issue. 

**Timing and notifications**  
AWS performs default version rollbacks only when required. 
+ **SNS** – AWS sends a single SNS notification at the time of the rollback. The notification includes the rule group name, the version that the default version is being set to, and the deployment date. This deployment type is very quick, so the notification doesn't provide timing information for Regions. 
+ **Change log** – AWS doesn't update the change log or other parts of this guide for this type of deployment.

# AWS Managed Rules changelog
<a name="aws-managed-rule-groups-changelog"></a>

This section lists changes to the AWS Managed Rules for AWS WAF since their release in November, 2019.

**Note**  
This changelog reports changes to the rules and rule groups in AWS Managed Rules for AWS WAF.  
For the [IP reputation rule groups](aws-managed-rule-groups-ip-rep.md), this changelog reports changes to the rules and rule group, and it reports significant changes to the sources of the IP address lists that the rules use. It does not report changes to the IP address lists themselves, due to the dynamic nature of those lists. If you have questions about the IP address lists, contact your account manager or open a case at [AWS Support Center](https://console.aws.amazon.com/support/home#/). 


| Rule group and rules | Description | Date | 
| --- | --- | --- | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.21 of this rule group.  Improved detection signatures for these rules.  | 2026-04-06 | 
| [PHP application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-php-app) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) |  Released static version 2.2 of this rule group.  Improved detections and added `PHPHighRiskMethodsVariables_URIPATH` rule.  | 2026-03-24 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New rules: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 5.0 of this rule group. Added 400\$1 new bots across multiple categories, including two new bot categories with their respective rules: Page Preview and Webhooks. **Key Improvements** Improved accuracy of bot detection signals and generic bot pattern matching, resulting in more precise traffic classification.  This update changes how the managed rule group prioritizes bot detection. Specific unverified bot patterns are now evaluated before generic patterns and detection signals. This means that requests are more likely to be classified based on their most specific characteristics rather than generic indicators. **What this means for your traffic:** Generic bot pattern will now match less frequently. These patterns only apply when no more specific bot rule has already identified the traffic. This reduces over-classification and ensures that requests are labeled with the most accurate bot identification available. Detection signals such as indicators that a request originates from a cloud service provider, known bot data center, or uses a non-browser user agent, are now applied after bot identification rules. This ensures that specific bot classifications take precedence over generic traffic signals. **Impact:** You may see fewer labels for generic bot patterns in your traffic logs, as requests are now more accurately classified by specific bot rules. This provides clearer insight into the actual nature of your automated traffic and reduces noise from overly broad pattern matching. Unverified bot classifications will be more prominent and accurate, helping you better understand and manage automated requests to your applications. **Note:** This version includes the `awswaf:managed:aws:bot-control:bot:web_bot_auth` labels and rules updates from Version\$14.0, but the `Web Bot Auth` functionality is still only available in CloudFront.  | 2026-02-25 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os)  |  Released static version 3.2 of this rule group.  Improved detection signatures for all the rules.  | 2026-01-15 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.25 of this rule group. Updated the `ReactJSRCE_BODY` to improve detection.  | 2025-12-08 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os)  |  Released static version 3.1 of this rule group.  Improved detection signatures for all the rules.  | 2025-12-08 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.24 of this rule group. Updated the `ReactJSRCE_BODY` to improve detection.  | 2025-12-04 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New labels:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) Scope: CloudFront |  Deployed new static version `AWSManagedRulesBotControlRuleSet` Version\$14.0 with Web Bot Authentication (WBA) support for cryptographic bot verification. This version must be explicitly selected and does not automatically update existing deployments using the default version. New capabilities: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) Rule updates: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  Version\$14.0 is a static version only – it does not change the default version behavior. To use WBA features, explicitly select Version \$14.0 when configuring your web ACL.   | 2025-11-20 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New verified bot labels:Advertising:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)AI:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)Content Fetcher:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)Social Media:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) |  Key improvements:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  Bot category rules in Bot Control trigger only on unverified bots, except for CategoryAI which also triggers on verified bots. Version\$13.3 is a static version only – it doesn't change the default version behavior.   | 2025-11-17 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.20 of this rule group.  Improved detection signatures for the Server Side Request Forgery (SSRF) rules.  | 2025-10-02 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.19 of this rule group.  Improved detection signatures for the cross site scripting rules.  | 2025-08-14 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.18 of this rule group.  Improved detection signatures for the cross site scripting rules.  | 2025-06-18 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New labels: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 3.2 of this rule group.  Added the listed new labels.   | 2025-05-29 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.17 of this rule group.  Improved detection signatures for the cross site scripting rules.  | 2025-03-03 | 
| [SQL database managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-sql-db) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.3 of this rule group.  Added double `URL_DECODE_UNI` text transformation to the listed rules.  | 2025-01-24 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.6 of this rule group.  Added signatures to improve detection.   | 2025-01-24 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New bot name label in the Bot Control labels: `awswaf:managed:aws:bot-control:bot::name:nytimes`  | Released static version 3.1 of this rule group.  Added the New York Times label to the list of bot name labels.   | 2024-11-07 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.16 of this rule group.  Improved detection signatures for the cross site scripting rules.   | 2024-10-16 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) New rules: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) Deleted rules: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) New labels: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html) Additional labeling in existing rules.  | Released static versions 2.0 and 3.0 of this rule group. Version 2.0 is the same as version 3.0, but with rule actions for all new rules set to Count. This guide documents the latest version of each rule group.  Added the listed new rules.  Updated labeling so that all rules apply a label with the pattern `awswaf:managed:aws:bot-control:<RuleName>`.  Added cloud service provider labels to the Bot Control signal labels.  Added new bot name labels that are inspected for by bot category rules.   | 2024-09-13 | 
| [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) All rules  | Released static version 1.1 of this rule group.  Updated labeling so that all rules apply a label with the pattern `awswaf:managed:aws:atp:<RuleName>`.   | 2024-09-13 | 
| [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md) All rules  | Released static version 1.1 of this rule group.  Updated labeling so that all rules apply a label with the pattern `awswaf:managed:aws:acfp:<RuleName>`.   | 2024-09-13 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) All rules  | Released static version 2.5 of this rule group.  Added signatures to improve detection.   | 2024-09-02 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.15 of this rule group.  Improved detection signatures for the generic LFI rules.   | 2024-08-30 | 
| [Windows operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-windows-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.3 of this rule group.  Adjusted detection signatures in the listed rules to reduce false positives.   | 2024-08-28 | 
| [WordPress application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-wordpress-app) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.3 of this rule group.  Added the JS\$1DECODE text transformation to the listed rule.   | 2024-07-15 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.4 of this rule group.  Added the JS\$1DECODE text transformation to the listed rule.   | 2024-07-12 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.14 of this rule group.  Added the JS\$1DECODE text transformation to the listed rules.   | 2024-07-09 | 
| [PHP application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-php-app) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.1 of this rule group.  Added the JS\$1DECODE text transformation to the listed rules.   | 2024-07-03 | 
| [Windows operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-windows-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.2 of this rule group.  Added the JS\$1DECODE text transformation to the listed rules.   | 2024-07-03 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) All rules  | Released static version 2.3 of this rule group.  Added signatures to improve detection.   | 2024-06-06 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md)  | The bot and fraud rule groups are now versioned. If you're using any of these rule groups, this update doesn't change how they handle your web traffic.  This update sets the current rule group version to static version 1.0 and sets the default version to point to it.  For more information about versioned managed rules, see the following:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | 2024-05-29 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 3.0 of this rule group.  Removed `UNIXShellCommandsVariables_QUERYARGUMENTS` and replaced it with `UNIXShellCommandsVariables_QUERYSTRING`. If you have rules that match on the label for `UNIXShellCommandsVariables_QUERYARGUMENTS`, when you use this version, switch them to match on the label for `UNIXShellCommandsVariables_QUERYSTRING`. The new label is `awswaf:managed:aws:posix-os:UNIXShellCommandsVariables_QueryString`. Added the rule `UNIXShellCommandsVariables_HEADER`, which matches on all headers. Updated all the rules in the managed rule group with improved detection logic.  Corrected the documented capitalization of the label for `UNIXShellCommandsVariables_BODY`.   | 2024-05-28 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.12 of this rule group.  Added signatures to all of the cross site scripting rules to improve detection and reduce false positives.  | 2024-05-21 | 
| [SQL database managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-sql-db) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released static version 1.2 of this rule group. Added the `JS_DECODE` text transformation to the listed rules.   | 2024-05-14 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.22 of this rule group. Added the `JS_DECODE` text transformation to the listed rules.   | 2024-05-08 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os)  | Released static version 2.2 of this rule group.  Added the `JS_DECODE` text transformation to both rules.   | 2024-05-08 | 
| [Windows operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-windows-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.1 of this rule group.  Added signatures to `PowerShellCommands_BODY` to improve detection.   | 2024-05-03 | 
| [Amazon IP reputation list managed rule group](aws-managed-rule-groups-ip-rep.md#aws-managed-rule-groups-ip-rep-amazon) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Updated the sources of the IP reputation list, to improve identification of addresses that are actively engaging in malicious activities and to reduce false positives.  This update doesn't involve a new version because this rule group isn't versioned.   | 2024-03-13 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)  | Released static version 1.21 of this rule group. Added signatures to improve detection and reduce false positives.   | 2023-12-16 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.20 of this rule group. Updated the `ExploitablePaths_URIPATH` rule to add detection for requests that match the Atlassian Confluence CVE-2023-22518 Improper Authorization vulnerability. This vulnerability affects all versions of Confluence Data Center and Server. For more information, see [NIST: National Vulnerability Database: CVE-2023-22518 Detail](https://nvd.nist.gov/vuln/detail/CVE-2023-22518).  | 2023-12-14 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.11 of this rule group.  Added signatures to all of the cross site scripting rules to improve detection and reduce false positives.  | 2023-12-06 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added the coordinated activity low label to the rule group's targeted protection level labels. This label isn't associated with any rule. This labeling is in addition to the medium and high level rules and labels.  | 2023-12-05 | 
| [Bot Control labels](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-labels-rg) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added a signal label to the rule group that indicates the detection of a browser extension that assists in automation. This label isn't specific to an individual rule.   | 2023-11-14 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.10 of this rule group.  Updated one rule to improve detection and reduce false positives.  | 2023-11-02 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.9 of this rule group.  Updated rules to improve detection and reduce false positives.  | 2023-10-30 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.1 of this rule group.  Updated the query arguments rule to improve detection.   | 2023-10-12 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.8 of this rule group.  Updated rules to improve detection.  | 2023-10-11 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Exception deployment: released static version 1.19 of this rule group. Updated the default version to use version 1.19. Updated the `ExploitablePaths_URIPATH` rule to add detection for requests matching the Atlassian Confluence CVE-2023-22515 Privilege Escalation Vulnerability. This vulnerability affects some versions of Atlassian Confluence. For more information, see [NIST: National Vulnerability Database: CVE-2023-22515 Detail](https://nvd.nist.gov/vuln/detail/CVE-2023-22515) and [Atlassian Support: FAQ for CVE-2023-22515](https://confluence.atlassian.com/kb/faq-for-cve-2023-22515-1295682188.html). For information about this deployment type, see [Exception deployments for AWS Managed Rules](waf-managed-rule-groups-deployments-exceptions.md). | 2023-10-04 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Exception deployment: released static version 1.18 of this rule group. This is a quick rollout of this static version to accommodate the creation and rollout of version 1.19.  Updated the `Host_localhost_HEADER` rule and all Log4J and Java deserialization rules for improved detection.  For information about this deployment type, see [Exception deployments for AWS Managed Rules](waf-managed-rule-groups-deployments-exceptions.md). | 2023-10-04 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added rules to the rule group with Count action.  The token reuse IP rule detects and counts token sharing across IP addresses.  The coordinated activity rules use automated, machine-learning (ML) analysis of website traffic to detect bot-related activity. In your rule group configuration, you can opt out of the use of ML. With this release, customers who are currently using the targeted protection level are opted in to the use of ML. Opting out disables the coordinated activity rules.  | 2023-09-06 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added the rule `CategoryAI` to the rule group.  | 2023-08-30 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.7 of this rule group.  Updated restricted extensions and EC2 metadata SSRF rules to improve detection and reduce false positives.  | 2023-07-26 | 
| [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md) All rules in new rule group  | Added the rule group AWSManagedRulesACFPRuleSet.  | 2023-06-13 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.2 of this rule group.  Added signatures to improve detection.   | 2023-05-22 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.6 of this rule group.  Updated cross-site scripting (XSS) and restricted extension rules to improve detection and reduce false positives.  | 2023-04-28 | 
| [PHP application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-php-app) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.0 of this rule group.  Added signatures to improve detection in all rules.  Replaced the rule `PHPHighRiskMethodsVariables_QUERYARGUMENTS` with `PHPHighRiskMethodsVariables_QUERYSTRING`, which inspects the entire query string instead of just the query arguments.  Added the rule `PHPHighRiskMethodsVariables_HEADER`, to expand coverage to include all headers. Updated the following labels to align with standard AWS Managed Rules labeling: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | 2023-02-27 | 
| [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added login response inspection rules for use with protected Amazon CloudFront distributions. These rules can block new login attempts from IP addresses and client sessions that have recently been the source of too many failed login attempts.  | 2023-02-15 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.5 of this rule group.  Updated Cross Site Scripting (XSS) filters to improve detection.  | 2023-01-25 | 
| [Linux operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-linux-os) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 2.1 of this rule group.  Removed the rule `LFI_COOKIE` and its label `awswaf:managed:aws:linux-os:LFI_Cookie`, and replaced them with the new rule `LFI_HEADER` and its label `awswaf:managed:aws:linux-os:LFI_Header`. This change expands inspection to multiple headers.  Added text transformations and signatures to all rules to improve detection.  | 2022-12-15 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.4 of this rule group.  Added a text transformation to `NoUserAgent_HEADER` to remove all null bytes. Updated the filters in the cross-site scripting rules to improve detection.  | 2022-12-05 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.17 of this rule group.  Updated the Java deserialization rules to add detection for requests matching Apache CVE-2022-42889, a remote code execution (RCE) vulnerability in Apache Commons Text versions prior to 1.10.0. For more information, see [NIST: National Vulnerability Database: CVE-2022-42889 Detail](https://nvd.nist.gov/vuln/detail/CVE-2022-42889) and [CVE-2022-42889: Apache Commons Text prior to 1.10.0 allows RCE when applied to untrusted input due to insecure interpolation defaults](https://lists.apache.org/thread/n2bd4vdsgkqh2tm14l1wyc3jyol7s1om). Improved detection in `Host_localhost_HEADER`. | 2022-10-20 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.16 of this rule group.  Removed false positives that AWS identified in version 1.15. | 2022-10-05 | 
| [POSIX operating system managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-posix-os) [PHP application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-php-app)  [WordPress application managed rule group](aws-managed-rule-groups-use-case.md#aws-managed-rule-groups-use-case-wordpress-app)   | Corrected the documented label names.   | 2022-09-19 | 
| [IP reputation rule groups](aws-managed-rule-groups-ip-rep.md) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | This change doesn't alter how the rule group handles web traffic. Added a new rule with Count action to inspect for IP addresses that are actively engaging in DDoS activities, according to Amazon threat intelligence.  | 2022-08-30 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released static version 1.15 of this rule group.  Removed `Log4JRCE` and replaced it with `Log4JRCE_HEADER`, `Log4JRCE_QUERYSTRING`, `Log4JRCE_URI`, and `Log4JRCE_BODY`, for more granular monitoring and management of false positives.  Added signatures for improved detection and blocking to `PROPFIND_METHOD` and to all `JavaDeserializationRCE*` and `Log4JRCE*` rules.  Updated labels to correct capitalization in `Host_localhost_HEADER` and in all `JavaDeserializationRCE*` rules.  Corrected the description of `JavaDeserializationRCE_HEADER`. | 2022-08-22 | 
| [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added a rule to prevent the use of the account takeover prevention managed rule group for Amazon Cognito user pool web traffic.  | 2022-08-11 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs)  | AWS has scheduled expiration for versions `Version_1.2` and `Version_2.0` of the rule group. The versions will expire on September 9, 2022. For information about version expiration, see [Using versioned managed rule groups in AWS WAF](waf-managed-rule-groups-versioning.md). | 2022-06-09 | 
| [Core rule set (CRS) managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-crs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.3 of this rule group. This release updates the match signatures in the rules `GenericLFI_URIPATH` and `GenericRFI_URIPATH`, to improve detection.  | 2022-05-24 | 
| [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added the rule `CategoryEmailClient` to the rule group.  | 2022-04-06 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.14 of this rule group. The four `JavaDeserializtionRCE` rules are moved to Block mode. | 2022-03-31 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.13 of this rule group. Updated the text transformation for Spring Core and Cloud Function RCE vulnerabilities. These rules are in count mode to gather metrics and evaluate matched patterns. The label can be used to block requests in a custom rule. A subsequent version will be deployed with these rules in block mode. | 2022-03-31 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.12 of this rule group. Added signatures for Spring Core and Cloud Function RCE vulnerabilities. These rules are in count mode to gather metrics and evaluate matched patterns. The label can be used to block requests in a custom rule. A subsequent version will be deployed with these rules in block mode. Removed the rules `Log4JRCE_HEADER`, `Log4JRCE_QUERYSTRING`, `Log4JRCE_URI`, and `Log4JRCE_BODY` and replaced them with the rule `Log4JRCE`. | 2022-03-30 | 
| [IP reputation rule groups](aws-managed-rule-groups-ip-rep.md) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Updated the AWSManagedReconnaissanceList rule to change the action from count to block.  | 2022-02-15 | 
| [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) All rules in new rule group  | Added the rule group AWSManagedRulesATPRuleSet.  | 2022-02-11 | 
| [Known bad inputs managed rule group](aws-managed-rule-groups-baseline.md#aws-managed-rule-groups-baseline-known-bad-inputs)[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.9 of this rule group. Removed the rule `Log4JRCE` and replaced it with the rules `Log4JRCE_HEADER`, `Log4JRCE_QUERYSTRING`, `Log4JRCE_URI`, and `Log4JRCE_BODY`, for flexibility in the use of this functionality. Added signatures to improve detection and blocking. | 2022-01-28 | 
| Core rule set (CRS) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released version 2.0 of this rule group. For these rules, tuned detection signatures to reduce false positives. Replaced the `URL_DECODE` text transformation with the double `URL_DECODE_UNI` text transformation. Added the `HTML_ENTITY_DECODE` text transformation.  | 2022-01-10 | 
| Core rule set (CRS) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  As part of the release of version 2.0 of this rule group, added the `URL_DECODE_UNI` text transformation. Removed the `URL_DECODE` text transformation from `RestrictedExtensions_URIPATH`.  | 2022-01-10 | 
| SQL database [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  |  Released version 2.0 of this rule group. Replaced the `URL_DECODE` text transformation with the double `URL_DECODE_UNI` text transformation and added the `COMPRESS_WHITE_SPACE` text transformation. Added more detection signatures to `SQLiExtendedPatterns_QUERYARGUMENTS`. Added JSON inspection to `SQLi_BODY`. Added the rule `SQLiExtendedPatterns_BODY`. Removed the rule `SQLi_URIPATH`.  | 2022-01-10 | 
| Known bad inputs [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.8 of the rule `Log4JRCE` to improve header inspection and matching criteria. | 2021-12-17 | 
| Known bad inputs [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Released version 1.4 of the rule `Log4JRCE` to tune the matching criteria and to inspect additional headers. Released version 1.5 to tune the matching criteria. | 2021-12-11 | 
| Known bad inputs [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-changelog.html)  | Added the rule `Log4JRCE` version 1.2 in response to the recently disclosed security issue within Log4j. For information see [CVE-2021-44228](https://www.cve.org/CVERecord?id=CVE-2021-44228). This rule inspects common URI paths, query strings, the first 8KB of the request body, and common headers. The rule uses double `URL_DECODE_UNI` text transformations. Released version 1.3 of `Log4JRCE` to tune the matching criteria and to inspect additional headers.  Removed the rule `BadAuthToken_COOKIE_AUTHORIZATION`.  | 2021-12-10 | 

The following table lists changes prior to December, 2021. 


| Rule group and rules | Description | Date | 
| --- | --- | --- | 
| Amazon IP reputation list | `AWSManagedReconnaissanceList` | Added the AWSManagedReconnaissanceList rule in monitoring/count mode. This rule contains IP addresses that are performing reconnaissance against AWS resources. | 2021-11-23 | 
| Windows operating system |  `WindowsShellCommands` `PowerShellCommands`  |  Added three new rules for WindowsShell commands: `WindowsShellCommands_COOKIE`, `WindowsShellCommands_QUERYARGUMENTS`, and `WindowsShellCommands_BODY`. Added a new PowerShell rule: `PowerShellCommands_COOKIE`. Restructured the `PowerShellComands` rules naming by removing the string \$1Set1 and \$1Set2. Added more comprehensive detection signatures to `PowerShellRules`. Added `URL_DECODE_UNI` text transformation to all Windows operating system rules.  | 2021-11-23 | 
| Linux operating system |  `LFI_URIPATH` `LFI_QUERYSTRING` `LFI_BODY` `LFI_COOKIE`  |  Replaced double `URL_DECODE` text transformation with double `URL_DECODE_UNI`. Added `NORMALIZE_PATH_WIN` as a second text transformation. Replaced the `LFI_BODY` rule with the `LFI_COOKIE` rule. Added more comprehensive detection signatures for all `LFI` rules.  | 2021-11-23 | 
| Core rule set (CRS) |  `SizeRestrictions_BODY`  | Reduced the size limit to block web requests with body payloads larger than 8 KB. Previously, the limit was 10 KB.  | 2021-10-27 | 
| Core rule set (CRS) |  `EC2MetaDataSSRF_BODY` `EC2MetaDataSSRF_COOKIE` `EC2MetaDataSSRF_URIPATH` `EC2MetaDataSSRF_QUERYARGUMENTS`  | Added more detection signatures. Added double unicode URL decode to improve blocking.  | 2021-10-27 | 
| Core rule set (CRS) |  `GenericLFI_QUERYARGUMENTS` `GenericLFI_URIPATH` `RestrictedExtensions_URIPATH` `RestrictedExtensions_QUERYARGUMENTS`  | Added double unicode URL decode to improve blocking.  | 2021-10-27 | 
| Core rule set (CRS) |  `GenericRFI_QUERYARGUMENTS` `GenericRFI_BODY` `GenericRFI_URIPATH`  | Updated the rule signatures to reduce false positives, based on customer feedback. Added double unicode URL decode to improve blocking.  | 2021-10-27 | 
| All | All rules | Added support for AWS WAF labels to all rules that didn't already support labeling.  | 2021-10-25 | 
| Amazon IP reputation list | `AWSManagedIPReputationList_xxxx` | Restructured the IP reputation list, removed suffixes from rule name, and added support for AWS WAF labels.  | 2021-05-04 | 
| Anonymous IP list | `AnonymousIPList` `HostingProviderList` | Added support for AWS WAF labels.  | 2021-05-04 | 
| Bot Control | All | Added the Bot Control rule set.  | 2021-04-01 | 
| Core rule set (CRS) | `GenericRFI_QUERYARGUMENTS`  | Added double URL decode.  | 2021-03-03 | 
| Core rule set (CRS) | `RestrictedExtensions_URIPATH`  | Improved the configuration of the rules and added an extra URL decode.  | 2021-03-03 | 
| Admin protection | `AdminProtection_URIPATH`  | Added double URL decode.  | 2021-03-03 | 
| Known bad inputs | `ExploitablePaths_URIPATH`  | Improved the configuration of the rules and added an extra URL decode.  | 2021-03-03 | 
| Linux operating system | `LFI_QUERYARGUMENTS`  | Improved the configuration of the rules and added an extra URL decode.  | 2021-03-03 | 
| Windows operating system | All | Improved the configuration of the rules.  | 2020-09-23 | 
| PHP application | `PHPHighRiskMethodsVariables_QUERYARGUMENTS` `PHPHighRiskMethodsVariables_BODY`  | Changed the text transformation from HTML decode to URL decode, to improve blocking.  | 2020-09-16 | 
| POSIX operating system | `UNIXShellCommandsVariables_QUERYARGUMENTS` `UNIXShellCommandsVariables_BODY`  | Changed the text transformation from HTML decode to URL decode, to improve blocking.  | 2020-09-16 | 
| Core rule set | `GenericLFI_QUERYARGUMENTS` `GenericLFI_URIPATH` GenericLFI\$1BODY  | Changed the text transformation from HTML decode to URL decode, to improve blocking.  | 2020-08-07 | 
| Linux operating system | `LFI_URIPATH` `LFI_QUERYARGUMENTS` `LFI_BODY`  | Changed the text transformation from HTML entity decode to URL decode, to improve detection and blocking.  | 2020-05-19 | 
| Anonymous IP List | All | New rule group in [IP reputation rule groups](aws-managed-rule-groups-ip-rep.md) to block requests from services that permit the obfuscation of viewer identity, to help mitigate bots and evasion of geographic restrictions.  | 2020-03-06 | 
| WordPress application | `WordPressExploitableCommands_QUERYSTRING`  | New rule that checks for exploitable commands in the query string. | 2020-03-03 | 
| Core rule set (CRS) | `SizeRestrictions_QUERYSTRING` `SizeRestrictions_Cookie_HEADER` `SizeRestrictions_BODY` `SizeRestrictions_URIPATH`  | Adjusted the size value constraints for improved accuracy.  | 2020-03-03 | 
| SQL database | `SQLi_URIPATH`  | The rules now check the message URI. | 2020-01-23 | 
| SQL database | `SQLi_BODY` `SQLi_QUERYARGUMENTS` `SQLi_COOKIE`  | Updated text transformations. | 2019-12-20 | 
| Core rule set (CRS) | `CrossSiteScripting_URIPATH` `CrossSiteScripting_BODY` `CrossSiteScripting_QUERYARGUMENTS` `CrossSiteScripting_COOKIE`  | Updated text transformations. | 2019-12-20 | 

# Managing your own rule groups
<a name="waf-user-created-rule-groups"></a>

You can create your own rule group to reuse collections of rules that you either don't find in the managed rule group offerings or that you prefer to handle on your own. 

Rule groups that you create hold rules just like a protection pack (web ACL) does, and you add rules to a rule group in the same way as you do to a protection pack (web ACL). When you create your own rule group, you must set an immutable maximum capacity for it. 

**Topics**
+ [

# Creating a rule group
](waf-rule-group-creating.md)
+ [

# Editing a rule group
](waf-rule-group-editing.md)
+ [

# Using your rule group in a protection pack (web ACL)
](waf-rule-group-using.md)
+ [

# Deleting a rule group
](waf-rule-group-deleting.md)
+ [

# Sharing a rule group
](waf-rule-group-sharing.md)

# Creating a rule group
<a name="waf-rule-group-creating"></a>

To create a new rule group, follow the procedure on this page. 

**To create a rule group**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Rule groups**, and then **Create rule group**. 

1. Enter a name and description for the rule group. You'll use these to identify the rule set to manage it and use it. 

   Don't use names that start with `AWS`, `Shield`, `PreFM`, or `PostFM`. These strings are either reserved or could cause confusion with rule groups that are managed for you by other services. See [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md). 
**Note**  
You can't change the name after you create the rule group.

1. For **Region**, choose the Region where you want to store the rule group. To use a rule group in protection packs (web ACLs) that protect Amazon CloudFront distributions, you must use the global setting. You can use the global setting for regional applications, too.

1. Choose **Next**.

1. Add rules to the rule group using the **Rule builder** wizard, the same as you do in protection pack (web ACL) management. The only difference is that you can't add a rule group to another rule group. 

1. For **Capacity**, set the maximum for the rule group's use of protection pack (web ACL) capacity units (WCUs). This is an immutable setting. For information about WCUs, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md). 

   As you add rules to the rule group, the **Add rules and set capacity** pane displays the minimum required capacity, which is based on the rules that you've already added. You can use this and your future plans for the rule group to help estimate the capacity that the rule group will require. 

1. Review the settings for the rule group, and choose **Create**.

# Editing a rule group
<a name="waf-rule-group-editing"></a>

To add or remove rules from a rule group or change configuration settings, access the rule group using the procedure on this page. 

**Production traffic risk**  
If you change a rule group that you're currently using in a protection pack (web ACL), those changes will affect your protection pack (web ACL) behavior wherever it's being used. Be sure to test and tune all changes in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**To edit a rule group**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Rule groups**.

1. Choose the name of the rule group that you want to edit. The console takes you to the rule group's page. 
**Note**  
If you don't see the rule group that you want to edit, check the Region selection inside the **Rule groups** section. For rule groups used to protect Amazon CloudFront distributions, use the **Global (CloudFront)** setting. 

1. Edit the rule group as needed. You can edit the rule group's mutable properties, similar to how you did during creation. The console saves your changes as you go.
**Note**  
If you change the name of a rule and you want the rule's metric name to reflect the change, you must update the metric name as well. AWS WAF doesn't automatically update the metric name for a rule when you change the rule name. You can change the metric name when you edit the rule in the console, by using the rule JSON editor. You can also change both names through the APIs and in any JSON listing that you use to define your protection pack (web ACL) or rule group.

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

# Using your rule group in a protection pack (web ACL)
<a name="waf-rule-group-using"></a>

To use a rule group in a protection pack (web ACL), you add it to the protection pack (web ACL) in a rule group reference statement. 

**Production traffic risk**  
Before you deploy changes in your protection pack (web ACL) for production traffic, test and tune them in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune your updated rules in count mode with your production traffic before enabling them. For guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**To use a rule group**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Rule groups**.

1. Choose the name of the rule group that you want to use.

1. Choose **Add rules**, and then choose **Add my own rules and rule groups**.

1. Choose **Rule group** and select your rule group from the list. 

In your protection pack (web ACL), you can alter the behavior of a rule group and its rules by setting the individual rule actions to Count or any other action. This can help you do things like test a rule group, identify false positives from rules in a rule group, and customize how a managed rule group handles your requests. For more information, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 

If your rule group contains a rate-based statement, each protection pack (web ACL) where you use the rule group has its own separate rate tracking and management for the rate-based rule, independent of any other protection pack (web ACL) where you use the rule group. For more information, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md).

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

# Deleting a rule group
<a name="waf-rule-group-deleting"></a>

Follow the guidance in this section to delete a rule group.

**Deleting referenced sets and rule groups**  
When you delete an entity that you can use in a protection pack (web ACL), like an IP set, regex pattern set, or rule group, AWS WAF checks to see if the entity is currently being used in a protection pack (web ACL). If it finds that it is in use, AWS WAF warns you. AWS WAF is almost always able to determine if an entity is being referenced by a protection pack (web ACL). However, in rare cases it might not be able to do so. If you need to be sure that nothing is currently using the entity, check for it in your protection packs (web ACLs) before deleting it. If the entity is a referenced set, also check that no rule groups are using it.

**To delete a rule group**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Rule groups**.

1. Choose the rule group that you want to delete, and then choose **Delete**.
**Note**  
If you don't see the rule group that you want to delete, check the Region selection inside the **Rule groups** section. For rule groups used to protect Amazon CloudFront distributions, use the **Global (CloudFront)** setting. 

# Sharing a rule group
<a name="waf-rule-group-sharing"></a>

You can share a rule group with other acccounts, for use by those accounts. 

**Sharing a rule group**  
You can share with one or more specific accounts, and you can share with all accounts in an organization. 

To share a rule group, you use the AWS WAF API to create a policy for the rule group sharing that you want. For more information, see [PutPermissionPolicy](https://docs.aws.amazon.com/waf/latest/APIReference/API_PutPermissionPolicy.html) in the *AWS WAF API Reference*.

**Using a rule group that's been shared with you**  
If a rule group has been shared with your account, you can access it through the API and you can reference it when you create or update your protection packs (web ACLs) through the API. For more information, see [GetRuleGroup](https://docs.aws.amazon.com/waf/latest/APIReference/API_GetRuleGroup.html), [CreateWebACL](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateWebACL.html), and [UpdateWebACL](https://docs.aws.amazon.com/waf/latest/APIReference/API_UpdateWebACL.html) in the *AWS WAF API Reference*. Rule groups that are shared with you don't appear in your AWS WAF console rule groups listing. 

# AWS Marketplace rule groups
<a name="marketplace-rule-groups"></a>

This section explains how to use AWS Marketplace rule groups.

AWS Marketplace rule groups are available by subscription through the AWS Marketplace console at [AWS Marketplace](https://aws.amazon.com/marketplace). After you subscribe to an AWS Marketplace rule group, you can use it in AWS WAF. To use an AWS Marketplace rule group in an AWS Firewall Manager AWS WAF policy, each account in your organization must subscribe to it. 

**You can subscribe to different types of rule groups through AWS Marketplace:**
+ AWS WAF partner-managed rule groups
+ Client-side protections

Test and tune any changes to your AWS WAF protections before you use them for production traffic. For information, see [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**AWS Marketplace Rule Group Pricing**  
AWS Marketplace rule groups are available with no long-term contracts, and no minimum commitments. When you subscribe to a rule group, you're charged a monthly fee (prorated hourly) and ongoing request fees based on volume. However, you're only charged the subscription fee when you add the subscribed rule group to a web ACL and begin using it. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/) and the description for each AWS Marketplace rule group at [AWS Marketplace](https://aws.amazon.com/marketplace).

**Have questions about an AWS Marketplace rule group?**  
For questions about a rule group that's managed by an AWS Marketplace seller and to request changes in functionality, contact the provider's customer support team. To find contact information, see the provider's listing at [AWS Marketplace](https://aws.amazon.com/marketplace).

The AWS Marketplace rule group provider determines how to manage the rule group, for example how to update the rule group and whether the rule group is versioned. The provider also determines the details of the rule group, including the rules, rule actions, and any labels that the rules add to matching web requests. 

## Subscribing to AWS Marketplace rule groups
<a name="marketplace-rule-groups-subscribing"></a>

You can subscribe to and unsubscribe from AWS Marketplace rule groups on the AWS WAF console. 

**Important**  
To use an AWS Marketplace rule group in an AWS Firewall Manager policy, each account in your organization must first subscribe to that rule group. 

**To subscribe to an AWS Marketplace rule group**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Add-on protections**.

1. In the **AWS Marketplace** section, choose the name of a rule group to view the details and pricing information.
**Tip**  
Use the filters to quickly sort for the rules you're most interested in. For example, you can use the **Category** filter to view client-side protections only.

1. To subscribe to an AWS Marketplace rule group: 

   1. Navigate to a rule group, then choose **Subscribe via Marketplace**.

   1. In the Marketplace page that opens, choose **View purchase options**, then choose **Subscribe**.
**Note**  
If you decide not to subscribe to the rule group, simply close the pop-up.

After you're subscribed to an AWS Marketplace rule group, you use it in your protection packs (web ACLs) as you do other managed rule groups. For information, see [Creating a protection pack (web ACL) in AWS WAF](web-acl-creating.md). 

When adding a rule group to a protection pack (web ACL), you can override the actions of rules in the rule group and of the rule group result. For more information, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 

## Unsubscribing from AWS Marketplace rule groups
<a name="marketplace-rule-groups-unsubscribing"></a>

You can unsubscribe from AWS Marketplace rule groups on the AWS Marketplace console.

**Important**  
To stop the subscription charges for an AWS Marketplace rule group, you must remove it from all protection packs (web ACLs) in AWS WAF and in any Firewall Manager AWS WAF policies, in addition to unsubscribing from it. If you unsubscribe from an AWS Marketplace rule group but don't remove it from your protection packs (web ACLs), you will continue to be charged for the subscription. 

**To unsubscribe from an AWS Marketplace rule group**

1. Remove the rule group from all protection packs (web ACLs). For more information, see [Editing a protection pack (web ACL) in AWS WAF](web-acl-editing.md).

1. Open the AWS console at [https://console.aws.amazon.com/marketplace](https://console.aws.amazon.com/marketplace).

   The **Manage subscriptions page appears**.

1. Open the **Delivery method** list and choose **SaaS**.

1. Under **Agreement**, open the **Actions list** and choose **Cancel subscription** next to the name of the rule group that you want to unsubscribe from.

1. In the **Cancel subscription** dialog box, enter **confirm**, then choose **Yes, cancel subscription**.

## Troubleshooting AWS Marketplace rule groups
<a name="waf-managed-rule-group-troubleshooting"></a>

If you find that an AWS Marketplace rule group is blocking legitimate traffic, you can troubleshoot the problem by performing the following steps.

**To troubleshoot an AWS Marketplace rule group**

1. Override the actions to count for the rules that are blocking legitimate traffic. You can identify which rules are blocking specific requests using either the AWS WAF sampled requests or AWS WAF logs. You can identify the rules by looking at the `ruleGroupId` field in the log or the `RuleWithinRuleGroup` in the sampled request. You can identify the rule in the pattern `<Seller Name>#<RuleGroup Name>#<Rule Name>`.

1. If setting specific rules to only count requests doesn't solve the problem, you can override all of the rule actions or change the action for the AWS Marketplace rule group itself from **No override** to **Override to count**. This allows the web request to pass through, regardless of the individual rule actions within the rule group. 

1. After overriding either the individual rule action or the entire AWS Marketplace rule group action, contact the rule group provider‘s customer support team to further troubleshoot the issue. For contact information, see the rule group listing on the product listing pages on AWS Marketplace.

### Contacting AWS support
<a name="waf-managed-rule-group-troubleshooting-support"></a>

For problems with AWS WAF or a rule group that is managed by AWS, contact AWS Support. For problems with a rule group that is managed by an AWS Marketplace seller, contact the provider's customer support team. To find contact information, see the provider's listing on AWS Marketplace.

# Recognizing rule groups provided by other services
<a name="waf-service-owned-rule-groups"></a>

If you or an administrator in your organization uses AWS Firewall Manager or AWS Shield Advanced to manage resource protections using AWS WAF, you might see rule group reference statements added to protection packs (web ACLs) in your account. 

The names of these rule groups begin with the following strings: 
+ **`ShieldMitigationRuleGroup`** – These rule groups are managed by AWS Shield Advanced and used to provide automatic application layer DDoS mitigation to protected application layer (layer 7) resources. 

  When you enable automatic application layer DDoS mitigation for a protected resource, Shield Advanced adds one of these rule groups to the protection pack (web ACL) that you have associated with the resource. Shield Advanced assigns the rule group reference statement a priority setting of 10,000,000, so that it runs after the rules that you have configured in the protection pack (web ACL). For more information about these rule groups, see [Automating application layer DDoS mitigation with Shield Advanced](ddos-automatic-app-layer-response.md).
**Warning**  
Don't try to manually manage this rule group in your protection pack (web ACL). In particular, don't manually delete the `ShieldMitigationRuleGroup` rule group reference statement from your protection pack (web ACL). Doing this could have unintended consequences for all resources that are associated with the protection pack (web ACL). Instead, use Shield Advanced to disable automatic mitigation for the resources that are associated with the protection pack (web ACL). Shield Advanced will remove the rule group for you when it's not needed for automatic mitigation.
+ **`PREFMManaged` and `POSTFMManaged`** – These rule groups are managed by AWS Firewall Manager based on Firewall Manager AWS WAF policy configurations. Firewall Manager provides these rule groups inside protection packs (web ACLs) that Firewall Manager manages. 

  Firewall Manager creates protection packs (web ACLs) for you with names that begin with `FMManagedWebACLV2`. You can configure Firewall Manager to retrofit your existing protection packs (web ACLs) as well. For these, the protection pack (web ACL) name is the one that you specified when you created it. In either case, Firewall Manager will add these rule groups to the protection pack (web ACL). For more information, see [Using AWS WAF policies with Firewall Manager](waf-policies.md).

# Web ACL capacity units (WCUs) in AWS WAF
<a name="aws-waf-capacity-units"></a>

This section explains what web ACL capacity units (WCUs) are and how they work.

AWS WAF uses WCUs to calculate and control the operating resources that are required to run your rules, rule groups, and web ACLs. AWS WAF enforces WCU limits when you configure your rule groups and web ACLs. WCUs don't affect how AWS WAF inspects web traffic. 

AWS WAF manages capacity for rules, rule groups, and web ACLs. 

**Rule WCUs**  
AWS WAF calculates rule capacity when you create or update a rule. AWS WAF calculates capacity differently for each rule type, to reflect each rule's relative cost. Simple rules that cost little to run use fewer WCUs than more complex rules that use more processing power. For example, a size constraint rule statement uses fewer WCUs than a statement that inspects requests using a regex pattern set. 

Rule capacity requirements generally start at a base cost for the rule type and increase with complexity, for example, when you add text transformations before inspection or if you inspect the JSON body. For information about rule capacity requirements, see the listings for the rule statements at [Using rule statements in AWS WAF](waf-rule-statements.md). 

**Rule group WCUs**  
The WCU requirements for a rule group are determined by the rules that you define inside the rule group. The maximum capacity for a rule group is 5,000 WCUs. 

Each rule group has an immutable capacity setting, which the owner assigns at creation. This is true for managed rule groups and rule groups that you create through AWS WAF. When you modify a rule group, your changes must keep the rule group's WCUs within its capacity. This ensures that protection packs (web ACLs) or web ACLs that are using the rule group remain within their capacity requirements. 

The WCUs that are in use in a rule group is the sum of the WCUs for the rules minus any processing optimizations that AWS WAF is able to obtain by combining the behavior of the rules. For example, if you define two rules to examine the same web request component, and the rules each apply a particular transformation to the component before inspecting it, AWS WAF might be able to charge you just once for applying the transformation. The WCU cost to use a rule group in a protection pack (web ACL) is always the fixed WCU setting that you defined at the rule group creation. 

When you create a rule group, take care to set the capacity high enough to accommodate the rules that you'll want to use throughout the rule group's lifetime. 

**Protection pack or web ACL WCUs**  
The WCU requirements for a protection pack (web ACL) are determined by the rules and rule groups that you use inside the protection pack (web ACL). 
+ The cost of using a rule group in a protection pack (web ACL) is the rule group's capacity setting. 
+ The cost of using a rule is the rule's calculated WCUs minus any processing optimizations that AWS WAF is able to obtain from the protection pack (web ACL)'s combination of rules. For example, if you define two rules to examine the same web request component, and the rules each apply a particular transformation to the component before inspecting it, AWS WAF might be able to charge you just once for applying the transformation. 

The basic price for a protection pack (web ACL) includes up to 1,500 WCUs. Using more than 1,500 WCUs incurs additional fees, according to a tiered pricing model. AWS WAF automatically adjusts your protection pack (web ACL) pricing as your protection pack (web ACL) WCU usage changes. For pricing details, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). 

The maximum capacity for a protection pack (web ACL) is 5,000 WCUs. 

## Determining the WCUs for a rule group, protection pack (web ACL), or web ACL
<a name="aws-waf-capacity-units-used"></a>

As noted in prior sections, the total WCUs used in a rule group, protection pack (web ACL), or web ACL will be equal to *or less than* the sum of the WCUs for all of the rules that are defined in the rule group, protection pack (web ACL), or web ACL.

In the AWS WAF console, you can see the capacity consumed when you add rules to your protection pack (web ACL), web ACL, or rule group. The console displays the current capacity units used as you add the rules. 

Through the API, you can check the maximum capacity requirements for the rules that you want to use in a protection pack (web ACL), web ACL, or rule group. To do this, provide the JSON listing of the rules to the check capacity call. For more information, see [CheckCapacity](https://docs.aws.amazon.com/waf/latest/APIReference/API_CheckCapacity.html) in the *AWS WAFV2 API Reference*.

# Oversize web request components in AWS WAF
<a name="waf-oversize-request-components"></a>

This section explains how to manage the size limits on inspecting the web request body, headers, and cookies in AWS WAF.

AWS WAF doesn't support inspecting very large contents for the web request components body, headers, or cookies. The underlying host service has count and size limits on what it forwards to AWS WAF for inspection. For example, the host service doesn't send more than 200 headers to AWS WAF, so for a web request with 205 headers, AWS WAF can't inspect the last 5 headers. 

When AWS WAF allows a web request to proceed to your protected resource, the entire web request is sent, including any contents that are outside of the count and size limits that AWS WAF was able to inspect. 

**Component inspection size limits**  
The component inspection size limits are as follows: 
+ **`Body` and `JSON Body`** – For Application Load Balancer and AWS AppSync, AWS WAF can inspect the first 8 KB of the body of a request. For CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access, by default, AWS WAF can inspect the first 16 KB, and you can increase the limit up to 64 KB in your protection pack (web ACL) configuration. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md). 
+ **`Headers`** – AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request headers and at most the first 200 headers. The content is available for inspection by AWS WAF up to the first limit reached. 

  These limits apply when you inspect all headers in a request. When you inspect a single header, AWS WAF can inspect the full contents of that header without these size or count restrictions.
+ **`Cookies`** – AWS WAF can inspect at most the first 8 KB (8,192 bytes) of the request cookies and at most the first 200 cookies. The content is available for inspection by AWS WAF up to the first limit reached. 

**Oversize handling options for your rule statements**  
When you write a rule statement that inspects one of these request component types, you specify how to handle oversize components. Oversize handling tells AWS WAF what to do with a web request when the request component that the rule inspects is over the size limits. 

The options for handling oversize components are as follows: 
+ **Continue** – Inspect the request component normally according to the rule inspection criteria. AWS WAF will inspect the request component contents that are within the size limits. 
+ **Match** – Treat the web request as matching the rule statement. AWS WAF applies the rule action to the request without evaluating it against the rule's inspection criteria. 
+ **No match** – Treat the web request as not matching the rule statement without evaluating it against the rule's inspection criteria. AWS WAF continues its inspection of the web request using the rest of the rules in the protection pack (web ACL) like it would do for any non-matching rule. 

In the AWS WAF console, you're required to choose one of these handling options. Outside the console, the default option is Continue. 

If you use the Match option in a rule that has its action set to Block, the rule will block a request whose inspected component is oversize. With any other configuration, the final disposition of the request depends on various factors, such as the configuration of the other rules in your protection pack (web ACL) and the protection pack (web ACL)'s default action setting. 

**Oversize handling in rule groups that you don't own**  
Component size and count limitations apply to all rules that you use in your protection pack (web ACL). This includes any rules that you use but don't manage, in managed rule groups and in rule groups that are shared with you by another account. 

When you use a rule group that you don't manage, the rule group might have a rule that inspects a limited request component but that doesn't handle oversized contents the way you need them to be handled. For information about how AWS Managed Rules manage oversize components, see [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md). For information about other rule groups, ask your rule group provider.

**Guidelines for managing oversize components in your protection pack (web ACL)**  
The way you handle oversize components in your protection pack (web ACL) can depend on a number of factors such as the expected size of your request component contents, your protection pack (web ACL)'s default request handling, and how other rules in your protection pack (web ACL) match and handle requests. 

The general guidelines for managing oversized web request components are as follows: 
+ If you need to allow some requests with oversize component contents, if possible, add rules to explicitly allow only those requests. Prioritize those rules so that they run before any other rules in the protection pack (web ACL) that inspect the same component types. With this approach, you won't be able to use AWS WAF to inspect the entire contents of the oversize components that you allow to pass to your protected resource.
+ For all other requests, you can prevent any additional bytes from passing through by blocking requests that go over the limit: 
  + **Your rules and rule groups** – In your rules that inspect components with size limits, configure oversize handling so that you block requests that go over the limit. For example, if your rule blocks requests with specific header contents, set the oversize handling to match on requests that have oversize header content. Alternately, if your protection pack (web ACL) blocks requests by default and your rule allows specific header contents, then configure your rule's oversize handling to not match on any request that has oversize header content. 
  + **Rule groups that you don't manage** – To prevent rule groups that you don't manage from allowing oversize request components, you can add a separate rule that inspects the request component type and blocks requests that go over the limits. Prioritize the rule in your protection pack (web ACL) so that it runs before the rule groups. For example, you can block requests with oversize body content before any of your body inspection rules run in the protection pack (web ACL). The following procedure describes how to add this type of rule.

## Blocking oversized web request components
<a name="waf-oversize-request-components-blocking"></a>

You can add a rule in your protection pack (web ACL) that blocks requests with oversized components. 

**To add a rule that blocks oversized contents**

1. When you create or edit your protection pack (web ACL), in the rules settings, choose **Add rules**, **Add my own rules and rule groups**, **Rule builder**, then **Rule visual editor**. For guidance on creating or editing a protection pack (web ACL), see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md).

1. Enter a name for your rule, and leave the **Type** setting at **Regular rule**. 

1. Change the following match settings from their defaults: 

   1. On **Statement**, for **Inspect**, open the dropdown and choose the web request component that you need, either **Body**, **Headers**, or **Cookies**. 

   1. For **Match type**, choose **Size greater than**. 

   1. For **Size**, type a number that's at least the minimum size for the component type. For headers and cookies, type `8192`. In Application Load Balancer or AWS AppSync protection packs (web ACLs), for bodies, type `8192`. For bodies in CloudFront, API Gateway, Amazon Cognito, App Runner, or Verified Access protection packs (web ACLs), if you're using the default body size limit, type `16384`. Otherwise, type the body size limit that you've defined for your protection pack (web ACL). 

   1. For **Oversize handling**, select **Match**. 

1. For **Action**, select **Block**.

1. Choose **Add rule**.

1. After you add the rule, on the **Set rule priority** page, move it above any rules or rule groups in your protection pack (web ACL) that inspect the same component type. This gives the new rule a lower numeric priority setting, which causes AWS WAF to evaluate it first. For more information, see [Setting rule priority](web-acl-processing-order.md).

# Supported regular expression syntax in AWS WAF
<a name="waf-regex-pattern-support"></a>

AWS WAF supports the regular expression pattern syntax used by the PCRE library `libpcre`. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). 

AWS WAF doesn't support all constructs of the library. For example, it supports some zero-width assertions, but not all. We do not have comprehensive list of the constructs that are supported. However, if you provide a regex pattern that isn't valid or use unsupported constructs, the AWS WAF API reports a failure. 

AWS WAF does not support the following PCRE patterns: 
+ Backreferences and capturing subexpressions
+ Subroutine references and recursive patterns
+ Conditional patterns
+ Backtracking control verbs
+ The \$1C single-byte directive
+ The \$1R newline match directive
+ The \$1K start of match reset directive
+ Callouts and embedded code
+ Atomic grouping and possessive quantifiers

# IP sets and regex pattern sets in AWS WAF
<a name="waf-referenced-set-managing"></a>

This section introduces the topics of IP sets and regex pattern sets.

AWS WAF stores some more complex information in sets that you use by referencing them in your rules. Each of these sets has a name and is assigned an Amazon Resource Name (ARN) at creation. You can manage these sets from inside your rule statements and you can access and manage them on their own, through the console navigation pane. 

You can use a managed set in a rule group or protection pack (web ACL).
+ To use an IP set, see [IP set match rule statement](waf-rule-statement-type-ipset-match.md). 
+ To use a regex pattern set see [Regex pattern set match rule statement](waf-rule-statement-type-regex-pattern-set-match.md). 

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

**Topics**
+ [

# Creating and managing an IP set in AWS WAF
](waf-ip-set-managing.md)
+ [

# Creating and managing a regex pattern set in AWS WAF
](waf-regex-pattern-set-managing.md)

# Creating and managing an IP set in AWS WAF
<a name="waf-ip-set-managing"></a>

An IP set provides a collection of IP addresses and IP address ranges that you want to use together in a rule statement. IP sets are AWS resources. 

To use an IP set in a protection pack (web ACL) or rule group, you first create an AWS resource, `IPSet` with your address specifications. Then you reference the set when you add an IP set rule statement to a protection pack (web ACL) or rule group. 

## Creating an IP set
<a name="waf-ip-set-creating"></a>

Follow the procedure in this section to create a new IP set.

**Note**  
In addition to the procedure in this section, you have the option to add a new IP set when you add an IP match rule to your protection pack (web ACL) or rule group. Choosing that option requires you to provide the same settings as those required by this procedure. 

**To create an IP set**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **IP sets** and then **Create IP set**. 

1. Enter a name and description for the IP set. You'll use these to identify the set when you want to use it. 
**Note**  
You can't change the name after you create the IP set.

1. For **Region**, choose Global (CloudFront) or choose the Region where you want to store the IP set. You can use regional IP sets only in protection packs (web ACLs) that protect regional resources. To use an IP set in protection packs (web ACLs) that protect Amazon CloudFront distributions, you must use Global (CloudFront). 

1. For **IP version**, select the version you want to use.

1. In the **IP addresses** text box, enter one IP address or IP address range per line, in CIDR notation. AWS WAF supports all IPv4 and IPv6 CIDR ranges except for `/0`. For more information about CIDR notation, see the Wikipedia article [Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).

   Here are some examples:
   + To specify the IPv4 address 192.0.2.44, type **192.0.2.44/32**.
   + To specify the IPv6 address 2620:0:2d0:200:0:0:0:0, type **2620:0:2d0:200:0:0:0:0/128**.
   + To specify the range of IPv4 addresses from 192.0.2.0 to 192.0.2.255, type **192.0.2.0/24**.
   + To specify the range of IPv6 addresses from 2620:0:2d0:200:0:0:0:0 to 2620:0:2d0:200:ffff:ffff:ffff:ffff, enter **2620:0:2d0:200::/64**.

1. Review the settings for the IP set, and choose **Create IP set**.

## Deleting an IP set
<a name="waf-ip-set-deleting"></a>

Follow the guidance in this section to delete a referenced set.

**Deleting referenced sets and rule groups**  
When you delete an entity that you can use in a protection pack (web ACL), like an IP set, regex pattern set, or rule group, AWS WAF checks to see if the entity is currently being used in a protection pack (web ACL). If it finds that it is in use, AWS WAF warns you. AWS WAF is almost always able to determine if an entity is being referenced by a protection pack (web ACL). However, in rare cases it might not be able to do so. If you need to be sure that nothing is currently using the entity, check for it in your protection packs (web ACLs) before deleting it. If the entity is a referenced set, also check that no rule groups are using it.

**To delete an IP set**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **IP sets**.

1. Select the IP set that you want to delete and choose **Delete**.

# Creating and managing a regex pattern set in AWS WAF
<a name="waf-regex-pattern-set-managing"></a>

A regex pattern set provides a collection of regular expressions that you want to use together in a rule statement. Regex pattern sets are AWS resources. 

To use a regex pattern set in a protection pack (web ACL) or rule group, you first create an AWS resource, `RegexPatternSet` with your regex pattern specifications. Then you reference the set when you add a regex pattern set rule statement to a protection pack (web ACL) or rule group. A regex pattern set must contain at least one regex pattern. 

If your regex pattern set contains more than one regex pattern, when it's used in a rule, the pattern matching is combined with `OR` logic. That is, a web request will match the pattern set rule statement if the request component matches any of the patterns in the set.

AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

## Creating a regex pattern set
<a name="waf-regex-pattern-set-creating"></a>

Follow the procedure in this section to create a new regex pattern set.

**To create a regex pattern set**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Regex pattern sets** and then **Create regex pattern set**. 

1. Enter a name and description for the regex pattern set. You'll use these to identify it when you want to use the set. 
**Note**  
You can't change the name after you create the regex pattern set.

1. For **Region**, choose Global (CloudFront) or choose the Region where you want to store the regex pattern set. You can use regional regex pattern sets only in protection packs (web ACLs) that protect regional resources. To use a regex pattern set in protection packs (web ACLs) that protect Amazon CloudFront distributions, you must use Global (CloudFront). 

1. In the **Regular expressions** text box, enter one regex pattern per line. 

   For example, the regular expression `I[a@]mAB[a@]dRequest` matches the following strings: `IamABadRequest`, `IamAB@dRequest`, `I@mABadRequest`, and `I@mAB@dRequest`.

   AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

1. Review the settings for the regex pattern set, and choose **Create regex pattern set**.

## Deleting a regex pattern set
<a name="waf-regex-pattern-set-deleting"></a>

Follow the guidance in this section to delete a referenced set.

**Deleting referenced sets and rule groups**  
When you delete an entity that you can use in a protection pack (web ACL), like an IP set, regex pattern set, or rule group, AWS WAF checks to see if the entity is currently being used in a protection pack (web ACL). If it finds that it is in use, AWS WAF warns you. AWS WAF is almost always able to determine if an entity is being referenced by a protection pack (web ACL). However, in rare cases it might not be able to do so. If you need to be sure that nothing is currently using the entity, check for it in your protection packs (web ACLs) before deleting it. If the entity is a referenced set, also check that no rule groups are using it.

**To delete a regex pattern set**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Regex pattern sets**.

1. Select the regex pattern set that you want to delete and choose **Delete**.

# Customized web requests and responses in AWS WAF
<a name="waf-custom-request-response"></a>

This section explains how to add custom web request and response handling behavior to your AWS WAF rule actions and default protection pack (web ACL) actions. Your custom settings apply whenever the action they're attached to applies. 

You can customize web requests and responses in the following ways: 
+ With Allow, Count, CAPTCHA, and Challenge actions, you can insert custom headers into the web request. When AWS WAF forwards the web request to the protected resource, the request contains the entire original request plus the custom headers that you've inserted. For the CAPTCHA and Challenge actions, AWS WAF only applies the customization if the request passes the CAPTCHA or challenge token inspection.
+ With Block actions, you can define a complete custom response, with response code, headers, and body. The protected resource responds to the request using the custom response provided by AWS WAF. Your custom response replaces the default Block action response of `403 (Forbidden)`.

**Action settings that you can customize**  
You can specify a custom request or response when you define the following action settings: 
+ Rule action. For information, see [Using rule actions in AWS WAF](waf-rule-action.md).
+ Default action for a protection pack (web ACL). For information, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md).

**Action settings that you cannot customize**  
You *cannot* specify custom request handling in the override action for a rule group that you use in a protection pack (web ACL). See [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md). Also 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).

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

**Limits on your use of custom requests and responses**  
AWS WAF defines maximum settings for your use of custom requests and responses. For example, a maximum number of request headers per protection pack (web ACL) or rule group, and a maximum number of custom headers for a single custom response definition. For information, see [AWS WAF quotas](limits.md).

**Topics**
+ [

# Inserting custom request headers for non-blocking actions
](customizing-the-incoming-request.md)
+ [

# Sending custom responses for Block actions
](customizing-the-response-for-blocked-requests.md)
+ [

# Supported status codes for custom responses
](customizing-the-response-status-codes.md)

# Inserting custom request headers for non-blocking actions
<a name="customizing-the-incoming-request"></a>

This section explains how to instruct AWS WAF to insert custom headers into the original HTTP request when a rule action doesn't block the request. With this option, you only add to the request. You can't modify or replace any part of the original request. Use cases for custom header insertion include signaling a downstream application to process the request differently based on the inserted headers, and flagging the request for analysis.

**Important**  
This option applies to the rule actions Allow, Count, CAPTCHA, and Challenge and to protection pack (web ACL) default actions that are set to Allow. For more information about rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md). For more information about default protection pack (web ACL) actions, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md).

## Considerations when using custom request header names
<a name="using-custom-request-header-names"></a>

**Prefixes added to request headers**  
AWS WAF prefixes all request headers that it inserts with `x-amzn-waf-`, to avoid confusion with the headers that are already in the request. For example, if you specify the header name `sample`, AWS WAF inserts the header `x-amzn-waf-sample`.

**Important**  
As a security practice, you can add a string match rule that blocks requests where the header already starts with `x-amzn-waf-`. This blocks requests from non-AWS WAF sources that mimic the `x-amzn-waf-` prefix string that is inserted by AWS WAF when processing custom request headers.

The following example shows a string match rule configured to block traffic where the `x-amzn-waf-` prefix was not inserted by AWS WAF:

```
    "Rules": [
        {
          "Name": "CustomHeader",
          "Priority": 0,
          "Statement": {
            "ByteMatchStatement": {
              "SearchString": " x-amzn-waf-",
              "FieldToMatch": {
                "Headers": {
                  "MatchPattern": {
                    "All": {}
                  },
                  "MatchScope": "KEY",
                  "OversizeHandling": "MATCH"
                }
              },
              "TextTransformations": [
                {
                  "Priority": 0,
                  "Type": "NONE"
                }
              ],
              "PositionalConstraint": "STARTS_WITH"
            }
          },
          "Action": {
            "Block": {}
          },
          "VisibilityConfig": {
            "SampledRequestsEnabled": true,
            "CloudWatchMetricsEnabled": true,
            "MetricName": "CustomHeader"
          }
        }
      ]
```

For information on using string match rules, see [String match rule statement](waf-rule-statement-type-string-match.md).

**Headers with the same name**  
If the request already has a header with the same name that AWS WAF is inserting, AWS WAF overwrites the header. So, if you define headers in multiple rules with identical names, the last rule to inspect the request and find a match would have its header added, and any previous rules would not. 

## Using custom headers with non-terminating rule actions
<a name="custom-request-header-non-terminating-rule-actions"></a>

Unlike the Allow action, the Count action doesn't stop AWS WAF from processing the web request using the rest of the rules in the protection pack (web ACL). Similarly, when CAPTCHA and Challenge determine that the request token is valid, these actions don't stop AWS WAF from processing the web request. So, if you insert custom headers using a rule with one of these actions, subsequent rules might also insert custom headers. For more information about rule action behavior, see [Using rule actions in AWS WAF](waf-rule-action.md).

For example, suppose you have the following rules, prioritized in the order shown: 

1. RuleA with a Count action and a customized header named `RuleAHeader`.

1. RuleB with an Allow action and a customized header named `RuleBHeader`.

If a request matches both RuleA and RuleB, AWS WAF inserts the headers `x-amzn-waf-RuleAHeader` and `x-amzn-waf-RuleBHeader`, and then forwards the request to the protected resource. 

AWS WAF inserts custom headers into a web request when it finishes inspecting the request. So if you use custom request handling with a rule that has the action set to Count, the custom headers that you add are not inspected by subsequent rules. 

## Custom request handling example
<a name="example-custom-request-handling"></a>

You define custom request handling for a rule's action or for a protection pack (web ACL)'s default action. The following listing shows the JSON for custom handling added to the default action for a protection pack (web ACL). 

```
{
 "Name": "SampleWebACL",
 "Scope": "REGIONAL",
 "DefaultAction": {
  "Allow": {
   "CustomRequestHandling": {
    "InsertHeaders": [
     {
      "Name": "fruit",
      "Value": "watermelon"
     },
     {
      "Name": "pie",
      "Value": "apple"
     }
    ]
   }
  }
 },
 "Description": "Sample protection pack (web ACL) with custom request handling configured for default action.",
 "Rules": [],
 "VisibilityConfig": {
  "SampledRequestsEnabled": true,
  "CloudWatchMetricsEnabled": true,
  "MetricName": "SampleWebACL"
 }
}
```

# Sending custom responses for Block actions
<a name="customizing-the-response-for-blocked-requests"></a>

This section explains how to instruct AWS WAF to send a custom HTTP response back to the client for rule actions or protection pack (web ACL) default actions that are set to Block. For more information about rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md). For more information about default protection pack (web ACL) actions, see [Setting the protection pack (web ACL) default action in AWS WAF](web-acl-default-action.md).

When you define custom response handling for a Block action, you define the status code, headers, and response body. For a list of status codes that you can use with AWS WAF, see the section that follows, [Supported status codes for custom responses](customizing-the-response-status-codes.md). 

**Use cases**  
The use cases for custom responses include the following: 
+ Sending a non-default status code back to the client.
+ Sending custom response headers back to the client. You can specify any header name except for `content-type`.
+ Sending a static error page back to the client.
+ Redirecting the client to a different URL. To do this, you specify one of the `3xx` redirection status codes, like `301 (Moved Permanently)` or `302 (Found)`, and then specify a new header named `Location` with the new URL. 

**Interaction with responses that you define in your protected resource**  
Custom responses that you specify for the AWS WAF Block action take precedence over any response specifications that you define in your protected resource. 

The host service for the AWS resource that you protect with AWS WAF might permit custom response handling for web requests. Examples include the following: 
+ With Amazon CloudFront, you can customize the error page based on status code. For information, see [Generating custom error responses](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html) in the *Amazon CloudFront Developer Guide*. 
+ With Amazon API Gateway you can define the response and status code for your gateway. For information, see [Gateway responses in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gatewayResponse-definition.html) in the *Amazon API Gateway Developer Guide*. 

You can't combine AWS WAF custom response settings with custom response settings in the protected AWS resource. The response specification for any individual web request comes either completely from AWS WAF or completely from the protected resource. 

For web requests that AWS WAF blocks, the following shows the order of precedence.

1. **AWS WAF custom response** – If the AWS WAF Block action has a custom response enabled, the protected resource sends the configured custom response back to the client. Any response settings that you might have defined in the protected resource itself have no effect. 

1. **Custom response defined in the protected resource** – Otherwise, if the protected resource has custom response settings specified, the protected resource uses those settings to respond to the client. 

1. **AWS WAF default Block response** – Otherwise, the protected resource responds to the client with the AWS WAF default Block response `403 (Forbidden)`. 

For web requests that AWS WAF allows, your configuration of the protected resource determines the response that it sends back to the client. You can't configure response settings in AWS WAF for allowed requests. The only customization that you can configure in AWS WAF for allowed requests is the insertion of custom headers into the original request, before forwarding the request to the protected resource. This option is described in the preceding section, [Inserting custom request headers for non-blocking actions](customizing-the-incoming-request.md). 

**Custom response headers**  
You can specify any header name except for `content-type`.

**Custom response bodies**  
You define the body of a custom response within the context of the protection pack (web ACL) or rule group where you want to use it. After you've defined a custom response body, you can use it by reference anywhere else in the protection pack (web ACL) or rule group where you created it. In the individual Block action settings, you reference the custom body that you want to use and you define the status code and header of the custom response. 

When you create a custom response in the console, you can choose from response bodies that you've already defined or you can create a new body. Outside of the console, you define your custom response bodies at the protection pack (web ACL) or rule group level, and then reference them from the action settings within the protection pack (web ACL) or rule group. This is shown in the example JSON in the following section. 

**Custom response example**  
The following example lists the JSON for a rule group with custom response settings. The custom response body is defined for the entire rule group, then referenced by key in the rule action.

```
{
 "ARN": "test_rulegroup_arn",
 "Capacity": 1,
 
 "CustomResponseBodies": {
  "CustomResponseBodyKey1": {
   "Content": "This is a plain text response body.",
   "ContentType": "TEXT_PLAIN"
  }
 },
 
 "Description": "This is a test rule group.",
 "Id": "test_rulegroup_id",
 "Name": "TestRuleGroup",
 
 "Rules": [
  {
   "Action": {
    "Block": {
     "CustomResponse": {
      "CustomResponseBodyKey": "CustomResponseBodyKey1",
      "ResponseCode": 404,
      "ResponseHeaders": [
       {
        "Name": "BlockActionHeader1Name",
        "Value": "BlockActionHeader1Value"
       }
      ]
     }
    }
   },
   "Name": "GeoMatchRule",
   "Priority": 1,
   "Statement": {
    "GeoMatchStatement": {
     "CountryCodes": [
      "US"
     ]
    }
   },
   "VisibilityConfig": {
    "CloudWatchMetricsEnabled": true,
    "MetricName": "TestRuleGroupReferenceMetric",
    "SampledRequestsEnabled": true
   }
  }
 ],
 "VisibilityConfig": {
  "CloudWatchMetricsEnabled": true,
  "MetricName": "TestRuleGroupMetric",
  "SampledRequestsEnabled": true
 }
}
```

# Supported status codes for custom responses
<a name="customizing-the-response-status-codes"></a>

This section lists the status codes that you can use in a custom response. For detailed information about HTTP status codes, see [Status Codes](https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes) by the Internet Engineering Task Force (IETF) and [List of HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) on Wikipedia.

The following are the HTTP status codes that AWS WAF supports for custom responses. 
+ `2xx Successful`
  + `200` – `OK`
  + `201` – `Created`
  + `202` – `Accepted` 
  + `204` – `No Content` 
  + `206` – `Partial Content`
+ `3xx Redirection `
  + `300` – `Multiple Choices`
  + `301` – `Moved Permanently`
  + `302` – `Found`
  + `303` –`See Other`
  + `304` – `Not Modified`
  + `307` – `Temporary Redirect`
  + `308` – `Permanent Redirect`
+ `4xx Client Error `
  + `400` – `Bad Request`
  + `401` – `Unauthorized`
  + `403` – `Forbidden`
  + `404` – `Not Found`
  + `405` – `Method Not Allowed`
  + `408` – `Request Timeout`
  + `409` – `Conflict`
  + `411` – `Length Required`
  + `412` – `Precondition Failed`
  + `413` – `Request Entity Too Large`
  + `414` – `Request-URI Too Long`
  + `415` – `Unsupported Media Type`
  + `416` – `Requested Range Not Satisfiable`
  + `421` – `Misdirected Request`
  + `429` – `Too Many Requests`
+ `5xx Server Error`
  + `500` – `Internal Server Error`
  + `501` – `Not Implemented`
  + `502` – `Bad Gateway`
  + `503` – `Service Unavailable`
  + `504` – `Gateway Timeout`
  + `505` – `HTTP Version Not Supported`

# 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
```

# Intelligent threat mitigation in AWS WAF
<a name="waf-managed-protections"></a>

This section covers the managed intelligent threat mitigation features provided by AWS WAF. These are advanced, specialized protections that you can implement to protect against threats such as malicious bots and account takeover attempts. 

**Note**  
The features described here incur additional costs, beyond the basic fees for using AWS WAF. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

The guidance provided in this section is intended for users who know generally how to create and manage AWS WAF web ACLs, rules, and rule groups. Those topics are covered in prior sections of this guide. 

**Topics**
+ [

# Options for intelligent threat mitigation in AWS WAF
](waf-managed-protections-comparison-table.md)
+ [

# Best practices for intelligent threat mitigation in AWS WAF
](waf-managed-protections-best-practices.md)
+ [

# Token use in AWS WAF intelligent threat mitigation
](waf-tokens.md)
+ [

# AWS WAF Fraud Control account creation fraud prevention (ACFP)
](waf-acfp.md)
+ [

# AWS WAF Fraud Control account takeover prevention (ATP)
](waf-atp.md)
+ [

# AWS WAF Bot Control
](waf-bot-control.md)
+ [

# AWS WAF Distributed Denial of Service (DDoS) prevention
](waf-anti-ddos.md)
+ [

# Client application integrations in AWS WAF
](waf-application-integration.md)
+ [

# CAPTCHA and Challenge in AWS WAF
](waf-captcha-and-challenge.md)

# Options for intelligent threat mitigation in AWS WAF
<a name="waf-managed-protections-comparison-table"></a>

This section provides a detailed comparison of the options for implementing intelligent threat mitigation. 

AWS WAF offers the following types of protections for intelligent threat mitigation.
+ **AWS WAF Fraud Control account creation fraud prevention (ACFP)** – Detects and manages malicious account creation attempts on your application's sign-up page. The core functionality is provided by the ACFP managed rule group. For more information, see [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md) and [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).
+ **AWS WAF Fraud Control account takeover prevention (ATP)** – Detects and manages malicious takeover attempts on your application's login page. The core functionality is provided by the ATP managed rule group. For more information, see [AWS WAF Fraud Control account takeover prevention (ATP)](waf-atp.md) and [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).
+ **AWS WAF Bot Control** – Identifies, labels, and manages both friendly and malicious bots. This feature provides management for common bots with signatures that are unique across applications, and also for targeted bots that have signatures specific to an application. The core functionality is provided by the Bot Control managed rule group. For more information, see [AWS WAF Bot Control](waf-bot-control.md) and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).
+ **Client application integration SDKs** – Validate client sessions and end users on your web pages and acquire AWS WAF tokens for clients to use in their web requests. If you use ACFP, ATP, or Bot Control, implement the application integration SDKs in your client application if you can, to take full advantage of all of the rule group features. We only recommend using these rule groups without an SDK integration as a temporary measure, when a critical resource needs to be quickly secured and there isn’t enough time for the SDK integration. For information about implementing the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). 
+ **Challenge and CAPTCHA rule actions** – Validate client sessions and end users and acquire AWS WAF tokens for clients to use in their web requests. You can implement these anywhere that you specify a rule action, in your rules and as overrides in rule groups that you use. These actions use AWS WAF JavaScript interstitials to interrogate the client or end user, and they require client applications that support JavaScript. For more information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

The intelligent threat mitigation AWS Managed Rules rule groups ACFP, ATP, and Bot Control use tokens for advanced detection. For information about the features that tokens enable in the rule groups, see [Using application integration SDKs with ACFP](waf-acfp-with-tokens.md), [Using application integration SDKs with ATP](waf-atp-with-tokens.md), and [Using application integration SDKs with Bot Control](waf-bot-with-tokens.md). 

Your options for implementing intelligent threat mitigation run from the basic use of rule actions to run challenges and enforce token acquisition, to the advanced features offered by the intelligent threat mitigation AWS Managed Rules rule groups.

The following tables provide detailed comparisons of the options for the basic and advanced features. 

**Topics**
+ [

# Options for challenges and token acquisition
](waf-managed-protections-comparison-table-token.md)
+ [

# Options for intelligent threat mitigation managed rule groups
](waf-managed-protections-comparison-table-rg.md)
+ [

# Options for rate limiting in rate-based rules and targeted Bot Control rules
](waf-rate-limiting-options.md)

# Options for challenges and token acquisition
<a name="waf-managed-protections-comparison-table-token"></a>

This section compares challenge and token management options.

You can provide challenges and acquire tokens using the AWS WAF application integration SDKs or the rule actions Challenge and CAPTCHA. Broadly speaking, the rule actions are easier to implement, but they incur added costs, intrude more on your customer experience, and require JavaScript. The SDKs require programming in your client applications, but they can provide a better customer experience, they're free to use, and they can be used with JavaScript or in Android or iOS applications. You can only use the application integration SDKs with protection packs (web ACLs) that use one of the paid intelligent threat mitigation managed rule groups, described in the following section. 


**Comparison of options for challenges and token acquisition**  

|  | Challenge rule action | CAPTCHA rule action | JavaScript SDK challenge | Mobile SDK challenge | 
| --- | --- | --- | --- | --- | 
| What it is | Rule action that enforces acquisition of the AWS WAF token by presenting the browser client with a silent challenge interstitial  | Rule action that enforces acquisition of the AWS WAF token by presenting the client end user with a visual or audio challenge interstitial  |  Application integration layer, for client browsers and other devices that execute JavaScript. Renders the silent challenge and acquires a token  |  Application integration layer, for Android and iOS applications. Natively renders the silent challenge and acquires a token  | 
| Good choice for... | Silent validation against bot sessions and enforcement of token acquisition for clients that support JavaScript  | End user and silent validation against bot sessions and enforcement of token acquisition, for clients that support JavaScript | Silent validation against bot sessions and enforcement of token acquisition for clients that support JavaScript. The SDKs provide the lowest latency and best control over where the challenge script runs in the application. | Silent validation against bot sessions and enforcement of token acquisition for native mobile applications on Android and iOS. The SDKs provide the lowest latency and best control over where the challenge script runs in the application. | 
| Implementation considerations | Implemented as a rule action setting | Implemented as a rule action setting | Requires one of the ACFP, ATP, or Bot Control paid rule groups in the protection pack (web ACL). Requires coding in the client application. | Requires one of the ACFP, ATP, or Bot Control paid rule groups in the protection pack (web ACL). Requires coding in the client application. | 
| Runtime considerations | Intrusive flow for requests without valid tokens. Client is redirected to an AWS WAF challenge interstitial. Adds network round trips and requires a second evaluation of the web request.  | Intrusive flow for requests without valid tokens. Client is redirected to an AWS WAF CAPTCHA interstitial. Adds network round trips and requires a second evaluation of the web request.  | Can be run behind the scenes. Gives you more control over the challenge experience.  | Can be run behind the scenes. Gives you more control over the challenge experience.  | 
| Requires JavaScript | Yes | Yes | Yes | No | 
| Supported clients | Browser and devices that execute Javascript | Browser and devices that execute Javascript | Browser and devices that execute Javascript | Android and iOS devices | 
| Supports single-page applications (SPA) | Enforcement only. You can use the Challenge action in conjunction with the SDKs, to ensure that requests have a valid challenge token. You can't use the rule action to deliver the challenge script to the page.  | Enforcement only. You can use the CAPTCHA action in conjunction with the SDKs, to ensure that requests have a valid CAPTCHA token. You can't use the rule action to deliver the CAPTCHA script to the page.  | Yes | N/A | 
| Additional cost | Yes, for action settings that you explicitly specify, either in the rules that you define or as rule action overrides in rule groups that you use. No in all other cases.  | Yes, for action settings that you explicitly specify, either in the rules that you define or as rule action overrides in rule groups that you use. No in all other cases.  | No, but requires one of the paid rule groups ACFP, ATP, or Bot Control. | No, but requires one of the paid rule groups ACFP, ATP, or Bot Control . | 

For details about costs associated with these options, see the intelligent threat mitigation information at [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

It can be simpler to run challenges and provide basic token enforcement by just adding a rule with a Challenge or CAPTCHA action. You might be required to use the rule actions, for example if you don't have access to the application code. 

If you can implement the SDKs however, you can save costs and reduce latency in your protection pack (web ACL) evaluation of client web requests, compared to using the Challenge action: 
+ You can write your SDK implementation to run the challenge at any point in your application. You can acquire the token in the background, prior to any customer action that would send a web request to your protected resource. This way, the token is available to send with your client's first request. 
+ If instead you acquire tokens by implementing a rule with the Challenge action, the rule and action require additional web request evaluation and processing when the client first sends a request and anytime the token expires. The Challenge action blocks the request that doesn't have a valid, unexpired token, and sends the challenge interstitial back to the client. After the client successfully responds to the challenge, the interstitial resends the original web request with the valid token, which is then evaluated a second time by the protection pack (web ACL). 

# Options for intelligent threat mitigation managed rule groups
<a name="waf-managed-protections-comparison-table-rg"></a>

This section compares managed rule group options.

The intelligent threat mitigation AWS Managed Rules rule groups provide management of basic bots, detection and mitigation of sophisticated, malicious bots, detection and mitigation of account takeover attempts, and detection and mitigation of fraudulent account creation attempts. These rule groups, combined with the application integration SDKs described in the prior section, provide the most advanced protections and secure coupling with your client applications. 


**Comparison of the managed rules group options**  

|  | ACFP  | ATP  | Bot Control common level | Bot Control targeted level | 
| --- | --- | --- | --- | --- | 
| What it is | Manages requests that might be part of fraudulent account creation attempts on an application's registration and sign-up pages.Does not manage bots. See [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md). | Manages requests that might be part of malicious takeover attempts on an application's login page.Does not manage bots. See [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md). | Manages common bots that self-identify, with signatures that are unique across applications.See [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). | Manages targeted bots that don't self-identify, with signatures that are specific to an application.See [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). | 
| Good choice for... | Inspection of account creation traffic for fraudulent account creation attacks such creation attempts with username traversal and many new accounts created from a single IP address. | Inspection of login traffic for account takeover attacks such login attempts with password traversal and many login attempts from the same IP address. When used with tokens, also provides aggregate protections such as rate limiting of IPs and client sessions for high volumes of failed login attempts. | Basic bot protection and labeling of common, automated bot traffic. | Targeted protection against sophisticated bots, including rate limiting at the client session level and detection and mitigation of browser automation tools such as Selenium and Puppeteer.  | 
| Adds labels that indicate evaluation results | Yes | Yes | Yes | Yes | 
| Adds token labels | Yes | Yes | Yes | Yes | 
| Blocking for requests that don't have a valid token | Not included. See [Blocking requests that don't have a valid AWS WAF token](waf-tokens-block-missing-tokens.md). | Not included. See [Blocking requests that don't have a valid AWS WAF token](waf-tokens-block-missing-tokens.md). | Not included. See [Blocking requests that don't have a valid AWS WAF token](waf-tokens-block-missing-tokens.md). | Blocks client sessions that send 5 requests without a token. | 
| Requires the AWS WAF token aws-waf-token | Required for all rules.See [Using application integration SDKs with ACFP](waf-acfp-with-tokens.md). | Required for many rules.See [Using application integration SDKs with ATP](waf-atp-with-tokens.md). | No | Yes | 
| Acquires the AWS WAF token aws-waf-token | Yes, enforced by the rule AllRequests | No | No | Some rules use Challenge or CAPTCHA rule actions, which acquire tokens. | 

For details about costs associated with these options, see the intelligent threat mitigation information at [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

# Options for rate limiting in rate-based rules and targeted Bot Control rules
<a name="waf-rate-limiting-options"></a>

This section compares rate-based mitigation options.

The targeted level of the AWS WAF Bot Control rule group and the AWS WAF rate-based rule statement both provide web request rate limiting. The following table compares the two options.


**Comparison of options for rate-based detection and mitigation**  

|  | AWS WAF rate-based rule | AWS WAF Bot Control targeted rules | 
| --- | --- | --- | 
| How rate limiting is applied | Acts on groups of requests that are coming at too high a rate. You can apply any action except for Allow.  | Enforces human-like access patterns and applies dynamic rate limiting, through the use of request tokens.  | 
| Based on historical traffic baselines?  | No  | Yes  | 
| Time required to accumulate historic traffic baselines  | N/A  | Five minutes for dynamic thresholds. N/A for token absent. | 
| Mitigation lag  | Usually 30-50 seconds. Can be up to several minutes.  | Usually less than 10 seconds. Can be up to several minutes.  | 
| Mitigation targets  | Configurable. You can group requests using a scope-down statement and by one or more aggregation keys, such as IP address, HTTP method, and query string. | IP addresses and client sessions  | 
| Traffic volume level required to trigger mitigations  | Medium - can be as low as 10 requests in the specified time window  | Low - intended to detect client patterns such as slow scrapers  | 
| Customizable thresholds  | Yes  | No  | 
| Default mitigation action | Console default is Block. No default setting in the API; the setting is required. You can set this to any rule action except Allow. | The rule group rule action settings are Challenge for token absent and CAPTCHA for high volume traffic from a single client session. You can set either of these rules to any valid rule action.  | 
| Resiliency against highly distributed attacks  | Medium - 10,000 IP address maximum for IP address limiting on its own | Medium - limited to 50,000 total between IP addresses and tokens  | 
| [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/) | Included in the standard fees for AWS WAF.  | Included in the fees for the targeted level of Bot Control intelligent threat mitigation.  | 
| For more information | [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md) | [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) | 

# Best practices for intelligent threat mitigation in AWS WAF
<a name="waf-managed-protections-best-practices"></a>

Follow the best practices in this section for the most efficient, cost-effective implementation of the intelligent threat mitigation features. 
+ **Implement the JavaScript and mobile application integration SDKs** – Implement application integration to enable the full set of ACFP, ATP, or Bot Control functionality in the most effective way possible. The managed rule groups use the tokens provided by the SDKs to separate legitimate client traffic from unwanted traffic at the session level. The application integration SDKs ensure that these tokens are always available. For details, see the following: 
  + [Using application integration SDKs with ACFP](waf-acfp-with-tokens.md)
  + [Using application integration SDKs with ATP](waf-atp-with-tokens.md)
  + [Using application integration SDKs with Bot Control](waf-bot-with-tokens.md)

  Use the integrations to implement challenges in your client and, for JavaScript, to customize how CAPTCHA puzzles are presented to your end users. For details, see [Client application integrations in AWS WAF](waf-application-integration.md). 

  If you customize CAPTCHA puzzles using the JavaScript API and you use the CAPTCHA rule action anywhere in your protection pack (web ACL), follow the guidance for handling the AWS WAF CAPTCHA response in your client at [Handling a CAPTCHA response from AWS WAF](waf-js-captcha-api-conditional.md). This guidance applies to any rules that use the CAPTCHA action, including those in the ACFP managed rule group and the targeted protection level of the Bot Control managed rule group. 
+ **Limit the requests that you send to the ACFP, ATP, and Bot Control rule groups** – You incur additional fees for using the intelligent threat mitigation AWS Managed Rules rule groups. The ACFP rule group inspects requests to the account registration and creation endpoints that you specify. The ATP rule group inspects requests to the login endpoint that you specify. The Bot Control rule group inspects every request that reaches it in the protection pack (web ACL) evaluation. 

  Consider the following approaches to reduce your use of these rule groups: 
  + Exclude requests from inspection with a scope-down statement in the managed rule group statement. You can do this with any nestable statement. For information, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).
  + Exclude requests from inspection by adding rules before the rule group. For rules that you can't use in a scope-down statement and for more complex situations, such as labeling followed by label matching, you might want to add rules that run before the rule groups. For information, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md) and [Using rule statements in AWS WAF](waf-rule-statements.md).
  + Run the rule groups after less expensive rules. If you have other standard AWS WAF rules that block requests for any reason, run them before these paid rule groups. For more information about rules and rule management, see [Using rule statements in AWS WAF](waf-rule-statements.md).
  + If you're using more than one of the intelligent threat mitigation managed rule groups, run them in the following order to keep costs down: Bot Control, ATP, ACFP.

  For detailed pricing information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).
+ **Do not limit the requests that you send to the Anti-DDoS rule group ** – This rule group operates best when you configure it in to monitor all web traffic that you aren't explicitly allowing through. Position it in your web ACL to be evaluated only after rules with the Allow rule action and before all other rules. 
+ **For distributed denial of service (DDoS) protection, use either Anti-DDoS or Shield Advanced automatic application layer DDoS mitigation** – The other intelligent threat mitigation rule groups don't provide DDoS protection. ACFP protects against fraudulent account creation attempts to your application's sign-up page. ATP protects against account takeover attempts to your login page. Bot Control focuses on enforcing human-like access patterns using tokens and dynamic rate limiting on client sessions.

  Anti-DDoS allows you to monitor and control DDoS attacks, allowing for quick response and mitigation of threats. Shield Advanced with automatic application layer DDoS mitigation automatically responds to detected DDoS attacks by creating, evaluating, and deploying custom AWS WAF mitigations on your behalf.

  For more information about Shield Advanced, see [AWS Shield Advanced overview](ddos-advanced-summary.md), and [Protecting the application layer (layer 7) with AWS Shield Advanced and AWS WAF](ddos-app-layer-protections.md).

  For more information about Distributed Denial of Service (DDoS) prevention, see [Anti-DDoS rule group](aws-managed-rule-groups-anti-ddos.md) and [Distributed Denial of Service (DDoS) prevention](waf-anti-ddos.md).
+  **Enable the Anti-DDoS rule group and the targeted protection level of the Bot Control rule group during normal web traffic** – These rule categories need time to establish baselines for normal traffic. 

   **Enable the targeted protection level of the Bot Control rule group during normal web traffic** – Some rules of the targeted protection level need time to establish baselines for normal traffic patterns before they can recognize and respond to irregular or malicious traffic patterns. For example, the `TGT_ML_*` rules need up to 24 hours to warm up. 

  Add these protections when you are not experiencing an attack and give them time to establish their baselines before expecting them to respond appropriately. If you add these rules during an attack, you will need to enable the Anti-DDoS rule group in count mode. After the attack subsides, the time to establish a baseline is usually from double to triple the normal required time, because of the skewing added by the attack traffic. For additional information about the rules and any warm-up times that they require, see [Rules listing](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-rules).
+ **For distributed denial of service (DDoS) protection, use Shield Advanced automatic application layer DDoS mitigation** – The intelligent threat mitigation rule groups don't provide DDoS protection. ACFP protects against fraudulent account creation attempts to your application's sign-up page. ATP protects against account takeover attempts to your login page. Bot Control focuses on enforcing human-like access patterns using tokens and dynamic rate limiting on client sessions.

  When you use Shield Advanced with automatic application layer DDoS mitigation enabled, Shield Advanced automatically responds to detected DDoS attacks by creating, evaluating, and deploying custom AWS WAF mitigations on your behalf. For more information about Shield Advanced, see [AWS Shield Advanced overview](ddos-advanced-summary.md), and [Protecting the application layer (layer 7) with AWS Shield Advanced and AWS WAF](ddos-app-layer-protections.md).
+ **Use production traffic loads when you establish baselines for the Anti-DDoS rule group** – It is common practice to test other rule groups using artificial test traffic. However, when you test and establish baselines for the Anti-DDoS rule group, we recommend that you use traffic flows that reflect the loads in your production environment. Establishing Anti-DDoS baselines using typical traffic is the best way to ensure your resources will be protected when the rule group is enabled in a production environment.
+ **Tune and configure token handling** – Adjust the protection pack (web ACL)'s token handling for the best user experience. 
  + To reduce operating costs and improve your end user's experience, tune your token management immunity times to the longest that your security requirements permit. This keeps the use of CAPTCHA puzzles and silent challenges to a minimum. For information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).
  + To enable token sharing between protected applications, configure a token domain list for your protection pack (web ACL). For information, see [Specifying token domains and domain lists in AWS WAF](waf-tokens-domains.md).
+ **Reject requests with arbitrary host specifications** – Configure your protected resources to require that the `Host` headers in web requests match the targeted resource. You can accept one value or a specific set of values, for example `myExampleHost.com` and `www.myExampleHost.com`, but don’t accept arbitrary values for the host. 
+ **For Application Load Balancers that are origins for CloudFront distributions, configure CloudFront and AWS WAF for proper token handling** – If you associate your protection pack (web ACL) to an Application Load Balancer and you deploy the Application Load Balancer as the origin for a CloudFront distribution, see [Required configuration for Application Load Balancers that are CloudFront origins](waf-tokens-with-alb-and-cf.md).
+ **Test and tune before deploying** – Before you implement any changes to your protection pack (web ACL), follow the testing and tuning procedures in this guide to be sure that you're getting the behavior you expect. This is especially important for these paid features. For general guidance, see [Testing and tuning your AWS WAF protections](web-acl-testing.md). For information specific to the paid managed rule groups, see [Testing and deploying ACFP](waf-acfp-deploying.md), [Testing and deploying ATP](waf-atp-deploying.md), and [Testing and deploying AWS WAF Bot Control](waf-bot-control-deploying.md).

# Token use in AWS WAF intelligent threat mitigation
<a name="waf-tokens"></a>

This section explains what AWS WAF tokens do.

AWS WAF tokens are an integral part of the enhanced protections offered by AWS WAF intelligent threat mitigation. A token, sometimes called a fingerprint, is a collection of information about a single client session that the client stores and provides with every web request that it sends. AWS WAF uses tokens to identify and separate malicious client sessions from legitimate sessions, even when both originate from a single IP address. Token use imposes costs that are negligible for legitimate users, but expensive at scale for botnets. 

AWS WAF uses tokens to support its browser and end user challenge functionality, which is provided by the application integration SDKs and by the rule actions Challenge and CAPTCHA. Additionally, tokens enable features of the AWS WAF Bot Control and account takeover prevention managed rule groups.

AWS WAF creates, updates, and encrypts tokens for clients that successfully respond to silent challenges and CAPTCHA puzzles. When a client with a token sends a web request, it includes the encrypted token, and AWS WAF decrypts the token and verifies its contents. 

**Topics**
+ [

# How AWS WAF uses tokens
](waf-tokens-usage.md)
+ [

# AWS WAF token characteristics
](waf-tokens-details.md)
+ [

# Setting timestamp expiration and token immunity times in AWS WAF
](waf-tokens-immunity-times.md)
+ [

# Specifying token domains and domain lists in AWS WAF
](waf-tokens-domains.md)
+ [

# Types of token labels in AWS WAF
](waf-tokens-labeling.md)
+ [

# Blocking requests that don't have a valid AWS WAF token
](waf-tokens-block-missing-tokens.md)
+ [

# Required configuration for Application Load Balancers that are CloudFront origins
](waf-tokens-with-alb-and-cf.md)

# How AWS WAF uses tokens
<a name="waf-tokens-usage"></a>

This section explains how AWS WAF uses tokens.

AWS WAF uses tokens to record and verify the following types of client session validation: 
+ **CAPTCHA** – CAPTCHA puzzles help distinguish bots from human users. A CAPTCHA is run only by the CAPTCHA rule action. Upon successful completion of the puzzle, the CAPTCHA script updates the token's CAPTCHA timestamp. For more information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).
+ **Challenge** – Challenges run silently to help distinguish regular client sessions from bot sessions and to make it more costly for bots to operate. When the challenge completes successfully, the challenge script automatically procures a new token from AWS WAF if needed, and then updates the token's challenge timestamp. 

  AWS WAF runs challenges in the following situations: 
  + **Application integration SDKs** – The application integration SDKs run inside your client application sessions and help ensure that login attempts are only allowed after the client has successfully responded to a challenge. For more information, see [Client application integrations in AWS WAF](waf-application-integration.md).
  + **Challenge rule action** – For more information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).
  + **CAPTCHA** – When a CAPTCHA interstitial runs, if the client doesn't have a token yet, the script automatically runs a challenge first, to verify the client session and to initialize the token. 

Tokens are required by many of the rules in the intelligent threat AWS Managed Rules rule groups. The rules use tokens to do things like distinguish between clients at the session level, to determine browser characteristics, and to understand the level of human interactivity on the application web page. These rule groups invoke AWS WAF token management, which applies token labeling that the rule groups then inspect. 
+ **AWS WAF Fraud Control account creation fraud prevention (ACFP)** – The ACFP rules require web requests with valid tokens. For more information about the rules, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).
+ **AWS WAF Fraud Control account takeover prevention (ATP)** – The ATP rules that prevent high volume and long lasting client sessions require web requests that have a valid token with an unexpired challenge timestamp. For more information, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).
+ **AWS WAF Bot Control** – The targeted rules in this rule group place a limit on the number of web requests that a client can send without a valid token, and they use token session tracking for session-level monitoring and management. As needed, the rules apply the Challenge and CAPTCHA rule actions to enforce token acquisition and valid client behavior. For more information, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).

# AWS WAF token characteristics
<a name="waf-tokens-details"></a>

Each token has the following characteristics: 
+ The token is stored in a cookie named `aws-waf-token`.
+ The token is encrypted.
+ The token fingerprints the client session with a sticky granular identifier that contains the following information: 
  + The timestamp of the client's latest successful response to a silent challenge. 
  + The timestamp of the end user's latest successful response to a CAPTCHA. This is only present if you use CAPTCHA in your protections. 
  + Additional information about the client and client behavior that can help separate your legitimate clients from unwanted traffic. The information includes various client identifiers and client-side signals that can be used to detect automated activities. The information gathered is non-unique and can't be mapped to an individual human being. 
    + All tokens include data from client browser interrogation, such as indications of automation and browser setting inconsistencies. This information is retrieved by the scripts that are run by the Challenge action and by the client application SDKs. The scripts actively interrogate the browser and put the results into the token. 
    + Additionally, when you implement a client application integration SDK, the token includes passively collected information about the end user's interactivity with the application page. Interactivity includes mouse movements, key presses, and interactions with any HTML form that's present on the page. This information helps AWS WAF detect the level of human interactivity in the client, to challenge users that do not seem to be human. For information about client side integrations, see [Client application integrations in AWS WAF](waf-application-integration.md).

For security reasons, AWS doesn't provide a complete description of the contents of AWS WAF tokens or detailed information about the token encryption process. 

# Setting timestamp expiration and token immunity times in AWS WAF
<a name="waf-tokens-immunity-times"></a>

This section explains how challenge and CAPTCHA timestamps expire.

AWS WAF uses challenge and CAPTCHA immunity times to control how frequently a single client session can be presented with a challenge or CAPTCHA. After an end user successfully responds to a CAPTCHA, the CAPTCHA immunity time determines how long the end user remains immune from being presented with another CAPTCHA. Similarly, the challenge immunity time determines how long a client session remains immune from being challenged again after successfully responding to a challenge. 

**How AWS WAF token immunity times work**

AWS WAF records a successful response to a challenge or CAPTCHA by updating the corresponding timestamp inside the token. When AWS WAF inspects the token for challenge or CAPTCHA, it subtracts the timestamp from the current time. If the result is greater than the configured immunity time, the timestamp is expired. 

**Configurable aspects of AWS WAF token immunity times**

You can configure the challenge and CAPTCHA immunity times in the protection pack (web ACL) and also in any rule that uses the CAPTCHA or Challenge rule action. 
+ The default protection pack (web ACL) setting for both immunity times is 300 seconds. 
+ You can specify the immunity time for any rule that uses the CAPTCHA or Challenge action. If you don't specify the immunity time for the rule, it inherits the setting from the protection pack (web ACL). 
+ For a rule inside a rule group that uses the CAPTCHA or Challenge action, if you don't specify the immunity time for the rule, it will inherit the setting from each protection pack (web ACL) where you use the rule group.
+ The application integration SDKs use the protection pack (web ACL)'s challenge immunity time. 
+ The minimum value for the challenge immunity time is 300 seconds. The minimum value for the CAPTCHA immunity time is 60 seconds. The maximum value for both immunity times is 259,200 seconds, or three days. 

You can use the protection pack (web ACL) and rule level immunity time settings to tune the CAPTCHA action, Challenge, or SDK challenge management behavior. For example, you might configure rules that control access to highly sensitive data with low immunity times, and then set higher immunity times in your protection pack (web ACL) for your other rules and the SDKs to inherit. 

In particular for CAPTCHA, solving a puzzle can degrade your customer's website experience, so tuning the CAPTCHA immunity time can help you mitigate the impact on customer experience while still providing the protections that you want. 

For additional information about tuning the immunity times for your use of the Challenge and CAPTCHA rule actions, see [Best practices for using the CAPTCHA and Challenge actions](waf-captcha-and-challenge-best-practices.md).

# Where to set the AWS WAF token immunity times
<a name="waf-tokens-immunity-times-setting"></a>

You can set the immunity times in your protection pack (web ACL) and in your rules that use the Challenge and CAPTCHA rule actions. 

For general information about managing a protection pack (web ACL) and its rules, see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md).

**Where to set the immunity time for a protection pack (web ACL)**
+ **Console** – When you edit the protection pack (web ACL), in the **Rules** tab, edit and change the settings in the **protection pack (web ACL) CAPTCHA configuration** and **protection pack (web ACL) Challenge configuration** panes. In the console, you can configure the protection pack (web ACL) CAPTCHA and challenge immunity times only after you've created the protection pack (web ACL).
+ **Outside of the console** – The protection pack (web ACL) data type has CAPTCHA and challenge configuration parameters, which you can configure and provide to your create and update operations on the protection pack (web ACL). 

**Where to set the immunity time for a rule**
+ **Console** – When you create or edit a rule and specify the CAPTCHA or Challenge action, you can modify the rule's immunity time setting. 
+ **Outside of the console** – The rule data type has CAPTCHA and challenge configuration parameters, which you can configure when you define the rule. 

# Specifying token domains and domain lists in AWS WAF
<a name="waf-tokens-domains"></a>

This section explains how to configure the domains that AWS WAF uses in tokens and that it accepts in tokens.

When AWS WAF creates a token for a client, it configures it with a token domain. When AWS WAF inspects a token in a web request, it rejects the token as invalid if its domain doesn't match any of the domains that are considered valid for the protection pack (web ACL). 

By default, AWS WAF only accepts tokens whose domain setting exactly matches the host domain of the resource that's associated with the protection pack (web ACL). This is the value of the `Host` header in the web request. In a browser, you can find this domain in the JavaScript `window.location.hostname` property and in the address that your user sees in their address bar. 

You can also specify acceptable token domains in your protection pack (web ACL) configuration, as described in the following section. In this case, AWS WAF accepts both exact matches with the host header and matches with domains in the token domain list.

You can specify token domains for AWS WAF to use when setting the domain and when evaluating a token in a protection pack (web ACL). The domains that you specify can't be public suffixes such as `gov.au`. For the domains that you can't use, see the list [https://publicsuffix.org/list/public_suffix_list.dat](https://publicsuffix.org/list/public_suffix_list.dat) under [Public suffix list](https://publicsuffix.org/list/).

## AWS WAF protection pack (web ACL) token domain list configuration
<a name="waf-tokens-domain-lists"></a>

You can configure a protection pack (web ACL) to share tokens across multiple protected resources by providing a token domain list with the additional domains that you want AWS WAF to accept. With a token domain list, AWS WAF still accepts the resource's host domain. Additionally, it accepts all domains in the token domain list, including their prefixed subdomains. 

For example, a domain specification `example.com` in your token domain list matches `example.com` (from `http://example.com/`), `api.example.com`, (from `http://api.example.com/`), and `www.example.com` (from `http://www.example.com/`). It doesn't match `example.api.com`, (from `http://example.api.com/`), or `apiexample.com` (from `http://apiexample.com/`).

You can configure the token domain list in your protection pack (web ACL) when you create or edit it. For general information about managing a protection pack (web ACL), see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md).

## AWS WAF token domain settings
<a name="waf-tokens-domain-in-token"></a>

AWS WAF creates tokens at the request of the challenge scripts, which are run by the application integration SDKs and the Challenge and CAPTCHA rule actions. 

The domain that AWS WAF sets in a token is determined by the type of challenge script that's requesting it and any additional token domain configuration that you provide. AWS WAF sets the domain in the token to the shortest, most general setting that it can find in the configuration.
+ **JavaScript SDK** – You can configure the JavaScript SDK with a token domain specification, which can include one or more domains. The domains that you configure must be domains that AWS WAF will accept, based on the protected host domain and the protection pack (web ACL)'s token domain list. 

  When AWS WAF issues a token for the client, it sets the token domain to one that matches the host domain and is the shortest, from among the host domain and the domains in your configured list. For example, if the host domain is `api.example.com` and the token domain list has `example.com`, AWS WAF uses `example.com` in the token, because it matches the host domain and is shorter. If you don't provide a token domain list in the JavaScript API configuration, AWS WAF sets the domain to the host domain of the protected resource.

  For more information, see [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md). 
+ **Mobile SDK** – In your application code, you must configure the mobile SDK with a token domain property. This property must be a domain that AWS WAF will accept, based on the protected host domain and the protection pack (web ACL)'s token domain list. 

  When AWS WAF issues a token for the client, it uses this property as the token domain. AWS WAF doesn't use the host domain in the tokens that it issues for the mobile SDK client. 

  For more information, see the `WAFConfiguration` `domainName` setting at [AWS WAF mobile SDK specification](waf-mobile-sdk-specification.md). 
+ **Challenge action** – If you specify a token domain list in the protection pack (web ACL), AWS WAF sets the token domain to one that matches the host domain and is the shortest, from among the host domain and the domains in the list. For example, if the host domain is `api.example.com` and the token domain list has `example.com`, AWS WAF uses `example.com` in the token, because it matches the host domain and is shorter. If you don't provide a token domain list in the protection pack (web ACL), AWS WAF sets the domain to the host domain of the protected resource. 

# Types of token labels in AWS WAF
<a name="waf-tokens-labeling"></a>

This section describes the labels that AWS WAF token management adds to web requests. For general information about labels, see [Web request labeling in AWS WAF](waf-labels.md).

When you use any of the AWS WAF bot or fraud control managed rule groups, the rule groups use AWS WAF token management to inspect the web request tokens and apply token labeling to the requests. For information about the managed rule groups, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md), [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md), and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) .

**Note**  
AWS WAF applies token labels only when you use one of these intelligent threat mitigation managed rule groups. 

Token management can add the following labels to web requests.

**Client session label**  
The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. 

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Browser fingerprint label**  
The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client.

**Note**  
AWS WAF doesn't report Amazon CloudWatch metrics for this label.

**Token status labels: Label namespace prefixes**  
Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. 

Each token status label begins with one of the following namespace prefixes: 
+ `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. 
+ `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. 

**Token status labels: Label names**  
Following the prefix, the rest of the label provides detailed token status information: 
+ `accepted` – The request token is present and contains the following: 
  + A valid challenge or CAPTCHA solution.
  + An unexpired challenge or CAPTCHA timestamp.
  + A domain specification that's valid for the protection pack (web ACL). 

  Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain.
+ `rejected` – The request token is present but doesn't meet the acceptance criteria. 

  Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. 
  + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. 
  + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. 
  + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. 
  + `rejected:invalid` – AWS WAF couldn't read the indicated token. 

  Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL).
+ `absent` – The request doesn't have the token or the token manager couldn't read it. 

  Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. 

# Blocking requests that don't have a valid AWS WAF token
<a name="waf-tokens-block-missing-tokens"></a>

This section explains how to block login requests that are missing their tokens when using the AWS WAF mobile SDK.

When you use the intelligent threat AWS Managed Rules rule groups `AWSManagedRulesACFPRuleSet`, `AWSManagedRulesATPRuleSet`, and `AWSManagedRulesBotControlRuleSet`, the rule groups invoke AWS WAF token management to evaluate the status of the web request token and to label the requests accordingly. 

**Note**  
Token labeling is only applied to web requests that you evaluate using one of these managed rule groups.

For information about the labeling that token management applies, see the preceding section, [Types of token labels in AWS WAF](waf-tokens-labeling.md). 

The intelligent threat mitigation managed rule groups then handle token requirements as follows:
+ The `AWSManagedRulesACFPRuleSet` `AllRequests` rule is configured to run the Challenge action against all requests, effectively blocking any that don't have the `accepted` token label. 
+ The `AWSManagedRulesATPRuleSet` blocks requests that have the `rejected` token label, but it doesn't block requests with the `absent` token label. 
+ The `AWSManagedRulesBotControlRuleSet` targeted protection level challenges clients after they send five requests without an `accepted` token label. It doesn't block an individual request that doesn't have a valid token. The common protection level of the rule group doesn't manage token requirements. 

For additional details about the intelligent threat rule groups, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md), [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 

**To block requests that are missing tokens when using the Bot Control or ATP managed rule group**  
With the Bot Control and ATP rule groups, it's possible for a request without a valid token to exit the rule group evaluation and continue to be evaluated by the protection pack (web ACL). 

To block all requests that are missing their token or whose token is rejected, add a rule to run immediately after the managed rule group to capture and block requests that the rule group doesn't handle for you. 

The following is an example JSON listing for a protection pack (web ACL) that uses the ATP managed rule group. The protection pack (web ACL) has an added rule to capture the `awswaf:managed:token:absent` label and handle it. The rule narrows its evaluation to web requests going to the login endpoint, to match the scope of the ATP rule group. The added rule is listed in bold. 

```
{
  "Name": "exampleWebACL",
  "Id": "55555555-6666-7777-8888-999999999999",
  "ARN": "arn:aws:wafv2:us-east-1:111111111111:regional/webacl/exampleWebACL/55555555-4444-3333-2222-111111111111",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "",
  "Rules": [
    {
      "Name": "AWS-AWSManagedRulesATPRuleSet",
      "Priority": 1,
      "Statement": {
        "ManagedRuleGroupStatement": {
          "VendorName": "AWS",
          "Name": "AWSManagedRulesATPRuleSet",
          "ManagedRuleGroupConfigs": [
            {
              "AWSManagedRulesATPRuleSet": {
                "LoginPath": "/web/login",
                "RequestInspection": {
                  "PayloadType": "JSON",
                  "UsernameField": {
                    "Identifier": "/form/username"
                  },
                  "PasswordField": {
                    "Identifier": "/form/password"
                  }
                },
                "ResponseInspection": {
                  "StatusCode": {
                    "SuccessCodes": [
                      200
                    ],
                    "FailureCodes": [
                      401,
                      403,
                      500
                    ]
                  }
                }
              }  
            }
          ]
        }
      },
      "OverrideAction": {
        "None": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWS-AWSManagedRulesATPRuleSet"
      }
    },
    {
      "Name": "RequireTokenForLogins",
      "Priority": 2,
      "Statement": {
        "AndStatement": {
          "Statements": [
            {
              "Statement": {
                "LabelMatchStatement": {
                  "Scope": "LABEL",
                  "Key": "awswaf:managed:token:absent"
                }
              }
            },
            {
              "ByteMatchStatement": {
                "SearchString": "/web/login",
                "FieldToMatch": {
                  "UriPath": {}
                },
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                 }
                ],
                "PositionalConstraint": "STARTS_WITH"
              }
            },
            {
              "ByteMatchStatement": {
                "SearchString": "POST",
                "FieldToMatch": {
                  "Method": {}
                },
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                  }
                ],
                "PositionalConstraint": "EXACTLY"
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "RequireTokenForLogins"
      } 
    }
  ],
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "exampleWebACL"
  },
  "Capacity": 51,
  "ManagedByFirewallManager": false,
  "RetrofittedByFirewallManager": false,
  "LabelNamespace": "awswaf:111111111111:webacl:exampleWebACL:"
}
```

# Required configuration for Application Load Balancers that are CloudFront origins
<a name="waf-tokens-with-alb-and-cf"></a>

Read this section if you associate your protection pack (web ACL) to an Application Load Balancer and you deploy the Application Load Balancer as the origin for a CloudFront distribution.

With this architecture, you need to provide the following additional configuration in order for the token information to be handled correctly.
+ Configure CloudFront to forward the `aws-waf-token` cookie to the Application Load Balancer. By default, CloudFront removes cookies from the web request before forwarding it to the origin. To keep the token cookie with the web request, configure CloudFront cache behavior to include either just the token cookie or all cookies. For information about how to do this, see [Caching content based on cookies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html) in the *Amazon CloudFront Developer Guide*.
+ Configure AWS WAF so that it recognizes the domain of the CloudFront distribution as a valid token domain. By default, CloudFront sets the `Host` header to the Application Load Balancer origin, and AWS WAF uses that as the domain of the protected resource. The client browser, however, sees the CloudFront distribution as the host domain, and tokens that are generated for the client use the CloudFront domain as the token domain. Without any additional configuration, when AWS WAF checks the protected resource domain against the token domain, it will get a mismatch. To fix this, add the CloudFront distribution domain name to the token domain list in your protection pack (web ACL) configuration. For information about how to do this, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).

# AWS WAF Fraud Control account creation fraud prevention (ACFP)
<a name="waf-acfp"></a>

This section explains what AWS WAF Fraud Control account creation fraud prevention (ACFP) does.

Account creation fraud is an online illegal activity in which an attacker tries to create one or more fake accounts. Attackers use fake accounts for fraudulent activities such as abusing promotional and sign up bonuses, impersonating someone, and cyberattacks like phishing. The presence of fake accounts can negatively impact your business by damaging your reputation with customers and exposure to financial fraud. 

You can monitor and control account creation fraud attempts by implementing the ACFP feature. AWS WAF offers this feature in the AWS Managed Rules rule group `AWSManagedRulesACFPRuleSet` with companion application integration SDKs. 

The ACFP managed rule group labels and manages requests that might be part of malicious account creation attempts. The rule group does this by inspecting account creation attempts that clients send to your application's account sign-up endpoint. 

ACFP protects your account sign-up pages by monitoring account sign-up requests for anomalous activity and by automatically blocking suspicious requests. The rule group uses request identifiers, behavioral analysis, and machine learning to detect fraudulent requests. 
+ **Request inspection** – ACFP gives you visibility and control over anomalous account creation attempts and attempts that use stolen credentials, to prevent the creation of fraudulent accounts. ACFP checks email and password combinations against its stolen credential database, which is updated regularly as new leaked credentials are found on the dark web. ACFP evaluates the domains used in email addresses, and monitors the use of phone numbers and address fields to verify the entries and to detects fraudulent behavior. ACFP aggregates data by IP address and client session, to detect and block clients that send too many requests of a suspicious nature. 
+ **Response inspection** – For CloudFront distributions, in addition to inspecting incoming account creation requests, the ACFP rule group inspects your application's responses to account creation attempts, to track success and failure rates. Using this information, ACFP can temporarily block client sessions or IP addresses that have too many failed attempts. AWS WAF performs response inspection asynchronously, so this doesn't increase latency in your web traffic. 

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Note**  
The ACFP feature is not available for Amazon Cognito user pools.

**Topics**
+ [

# AWS WAF ACFP components
](waf-acfp-components.md)
+ [

# Using application integration SDKs with ACFP
](waf-acfp-with-tokens.md)
+ [

# Adding the ACFP managed rule group to your web ACL
](waf-acfp-rg-using.md)
+ [

# Testing and deploying ACFP
](waf-acfp-deploying.md)
+ [

# AWS WAF Fraud Control account creation fraud prevention (ACFP) examples
](waf-acfp-control-examples.md)

# AWS WAF ACFP components
<a name="waf-acfp-components"></a>

The primary components of AWS WAF Fraud Control account creation fraud prevention (ACFP) are the following: 
+ **`AWSManagedRulesACFPRuleSet`** – The rules in this AWS Managed Rules rule group detect, label, and handle various types of fraudulent account creation activity. The rule group inspects HTTP `GET` text/html requests that clients send to the specified account registration endpoint and `POST` web requests that clients send to the specified account sign-up endpoint. For protected CloudFront distributions, the rule group also inspects the responses that the distribution sends back to account creation requests. For a list of this rule group's rules, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md). You include this rule group in your protection pack (web ACL) using a managed rule group reference statement. For information about using this rule group, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md). 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).
+ **Details about your application's account registration and creation pages** – You must provide information about your account registration and creation pages when you add the `AWSManagedRulesACFPRuleSet` rule group to your protection pack (web ACL). This lets the rule group narrow the scope of the requests it inspects and properly validate account creation web requests. The registration page must accept `GET` text/html requests. The account creation path must accept `POST` requests. The ACFP rule group works with usernames that are in email format. For more information, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md). 
+ **For protected CloudFront distributions, details about how your application responds to account creation attempts** – You provide details about your application's responses to account creation attempts, and the ACFP rule group tracks and manages bulk account creation attempts from a single IP address or single client session. For information about configuring this option, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md). 
+ **JavaScript and mobile application integration SDKs** – Implement the AWS WAF JavaScript and mobile SDKs with your ACFP implementation to enable the full set of capabilities that the rule group offers. Many of the ACFP rules use the information provided by the SDKs for session level client verification and behavior aggregation, required to separate legitimate client traffic from bot traffic. For more information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md).

You can combine your ACFP implementation with the following to help you monitor, tune, and customize your protections. 
+ **Logging and metrics** – You can monitor your traffic, and understand how the ACFP managed rule group affects it, by configuring and enabling logs, Amazon Security Lake data collection, and Amazon CloudWatch metrics for your protection pack (web ACL). The labels that `AWSManagedRulesACFPRuleSet` adds to your web requests are included in the data. For information about the options, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md), [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md), and [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html).

  Depending on your needs and the traffic that you see, you might want to customize your `AWSManagedRulesACFPRuleSet` implementation. For example, you might want to exclude some traffic from ACFP evaluation, or you might want to alter how it handles some of the account creation fraud attempts that it identifies, using AWS WAF features like scope-down statements or label matching rules. 
+ **Labels and label matching rules** – For any of the rules in `AWSManagedRulesACFPRuleSet`, you can switch the blocking behavior to count, and then match against the labels that are added by the rules. Use this approach to customize how you handle web requests that are identified by the ACFP managed rule group. For more information about labeling and using label match statements, see [Label match rule statement](waf-rule-statement-type-label-match.md) and [Web request labeling in AWS WAF](waf-labels.md). 
+ **Custom requests and responses** – You can add custom headers to the requests that you allow and you can send custom responses for requests that you block. To do this, you pair your label matching with the AWS WAF custom request and response features. For more information about customizing requests and responses, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

# Using application integration SDKs with ACFP
<a name="waf-acfp-with-tokens"></a>

We highly recommend implementing the application integration SDKs, for the most efficient use of the ACFP rule group. 
+ **Complete rule group functionality** – The ACFP rule `SignalClientHumanInteractivityAbsentLow` only works with tokens that are populated by the application integrations. This rule detects and manages abnormal human interactivity with the application page. The application integration SDKs can detect normal human interactivity through mouse movements, key presses, and other measurements. The interstitials that are sent by the rule actions CAPTCHA and Challenge can't provide this type of data. 
+ **Reduced latency** – The rule group rule `AllRequests` applies the Challenge rule action to any request that doesn't already have a challenge token. When this happens, the request is evaluated by the rule group twice: once without the token, and then a second time after the token is acquired by means of the Challenge action interstitial. You aren't charged any added fees for only using the `AllRequests` rule, but this approach adds overhead to your web traffic and adds latency to your end user experience. If you acquire the token client-side using the application integrations, before sending the account creation request, the ACFP rule group evaluates the request once. 

For more information about the rule group capabilities see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).

For information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about AWS WAF tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). For information about the rule actions, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

# Adding the ACFP managed rule group to your web ACL
<a name="waf-acfp-rg-using"></a>

This section explains how to add and configure the `AWSManagedRulesACFPRuleSet` rule group.

To configure the ACFP managed rule group to recognize account creation fraud activities in your web traffic, you provide information about how clients access your registration page and send account creation requests to your application. For protected Amazon CloudFront distributions, you also provide information about how your application responds to account creation requests. This configuration is in addition to the normal configuration for a managed rule group. 

For the rule group description and rules listing, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).

**Note**  
The ACFP stolen credentials database only contains usernames in email format.

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. For basic information about how to add a managed rule group to your protection pack (web ACL), see [Adding a managed rule group to a protection pack (web ACL) through the console](waf-using-managed-rule-group.md).

**Follow best practices**  
Use the ACFP rule group in accordance with the best practices at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md). 

**To use the `AWSManagedRulesACFPRuleSet` rule group in your protection pack (web ACL)**

1. Add the AWS managed rule group, `AWSManagedRulesACFPRuleSet` to your protection pack (web ACL), and **Edit** the rule group settings before saving. 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

1. In the **Rule group configuration** pane, provide the information that the ACFP rule group uses to inspect account creation requests. 

   1. For **Use regular expression in paths**, toggle this on if you want AWS WAF to perform regular expression matching for your registration and account creation page path specifications. 

      AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

   1. For **Registration page path**, provide the path of the registration page endpoint for your application. This page must accept `GET` text/html requests. The rule group inspects only HTTP `GET` text/html requests to your specified registration page endpoint.
**Note**  
Matching for endpoints is case insensitive. Regex specifications must not contain the flag `(?-i)`, which disables case insensitive matching. String specifications must start with a forward slash `/`.

      For example, for the URL `https://example.com/web/registration`, you could provide the string path specification `/web/registration`. Registration page paths that start with the path that you provide are considered a match. For example `/web/registration` matches the registration paths `/web/registration`, `/web/registration/`, `/web/registrationPage`, and `/web/registration/thisPage`, but doesn't match the path `/home/web/registration` or `/website/registration`. 
**Note**  
Ensure that your end users load the registration page before they submit an account creation request. This helps ensure that the account creation requests from the client include valid tokens. 

   1. For **Account creation path**, provide the URI in your website that accepts completed new user details. This URI must accept `POST` requests.
**Note**  
Matching for endpoints is case insensitive. Regex specifications must not contain the flag `(?-i)`, which disables case insensitive matching. String specifications must start with a forward slash `/`.

      For example, for the URL `https://example.com/web/newaccount`, you could provide the string path specification `/web/newaccount`. Account creation paths that start with the path that you provide are considered a match. For example `/web/newaccount` matches the account creation paths `/web/newaccount`, `/web/newaccount/`, `/web/newaccountPage`, and `/web/newaccount/thisPage`, but doesn't match the path `/home/web/newaccount` or `/website/newaccount`. 

   1. For **Request inspection**, specify how your application accepts account creation attempts by providing the request payload type and the names of the fields within the request body where the username, password, and other account creation details are provided. 
**Note**  
For the primary address and phone number fields, provide the fields in the order in which they appear in the request payload.

      Your specification of the field names depends on the payload type.
      + **JSON payload type** – Specify the field names in JSON pointer syntax. For information about the JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation [JavaScript Object Notation (JSON) Pointer](https://tools.ietf.org/html/rfc6901). 

        For example, for the following example JSON payload, the username field specification is `/signupform/username` and the primary address field specifications are `/signupform/addrp1`, `/signupform/addrp2`, and `/signupform/addrp3`.

        ```
        {
            "signupform": {
                "username": "THE_USERNAME",
                "password": "THE_PASSWORD",
                "addrp1": "PRIMARY_ADDRESS_LINE_1",
                "addrp2": "PRIMARY_ADDRESS_LINE_2",
                "addrp3": "PRIMARY_ADDRESS_LINE_3",
                "phonepcode": "PRIMARY_PHONE_CODE",
                "phonepnumber": "PRIMARY_PHONE_NUMBER"
            }
        }
        ```
      + **FORM\$1ENCODED payload type** – Use the HTML form names.

        For example, for an HTML form with user and password input elements named `username1` and `password1`, the username field specification is `username1` and the password field specification is `password1`.

   1. If you're protecting Amazon CloudFront distributions, then under **Response inspection**, specify how your application indicates success or failure in its responses to account creation attempts. 
**Note**  
ACFP response inspection is available only in protection packs (web ACLs) that protect CloudFront distributions.

      Specify a single component in the account creation response that you want ACFP to inspect. For the **Body** and **JSON** component types, AWS WAF can inspect the first 65,536 bytes (64 KB) of the component. 

      Provide your inspection criteria for the component type, as indicated by the interface. You must provide both success and failure criteria to inspect for in the component. 

      For example, say your application indicates the status of an account creation attempt in the status code of the response, and uses `200 OK` for success and `401 Unauthorized` or `403 Forbidden` for failure. You would set the response inspection **Component type** to **Status code**, then in the **Success** text box enter `200` and in the **Failure** text box, enter `401` on the first line and `403` on the second.

      The ACFP rule group only counts responses that match your success or failure inspection criteria. The rule group rules act on clients while they have too high a success rate among the responses that are counted, in order to mitigate bulk account creation attempts. For accurate behavior by the rule group rules, be sure to provide complete information for both successful and failed account creation attempts. 

      To see the rules that inspect account creation responses, look for `VolumetricIPSuccessfulResponse` and `VolumetricSessionSuccessfulResponse` in the rules listing at [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md). 

1. Provide any additional configuration that you want for the rule group. 

   You can further limit the scope of requests that the rule group inspects by adding a scope-down statement to the managed rule group statement. For example, you can inspect only requests with a specific query argument or cookie. The rule group will only inspect requests that match the criteria in your scope-down statement and that are sent to the account registration and account creation paths that you specified in the rule group configuration. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

1. Save your changes to the protection pack (web ACL). 

Before you deploy your ACFP implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. See the section that follows for guidance. 

# Testing and deploying ACFP
<a name="waf-acfp-deploying"></a>

This section provides general guidance for configuring and testing an AWS WAF Fraud Control account creation fraud prevention (ACFP) implementation for your site. The specific steps that you choose to follow will depend on your needs, resources, and web requests that you receive. 

This information is in addition to the general information about testing and tuning provided at [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

**Production traffic risk**  
Before you deploy your ACFP implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. 

AWS WAF provides test credentials that you can use to verify your ACFP configuration. In the following procedure, you'll configure a test protection pack (web ACL) to use the ACFP managed rule group, configure a rule to capture the label added by the rule group, and then run an account creation attempt using these test credentials. You'll verify that your protection pack (web ACL) has properly managed the attempt by checking the Amazon CloudWatch metrics for the account creation attempt. 

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. 

**To configure and test an AWS WAF Fraud Control account creation fraud prevention (ACFP) implementation**

Perform these steps first in a test environment, then in production.

1. 

**Add the AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group in count mode**
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

   Add the AWS Managed Rules rule group `AWSManagedRulesACFPRuleSet` to a new or existing protection pack (web ACL) and configure it so that it doesn't alter the current protection pack (web ACL) behavior. For details about the rules and labels for this rule group, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).
   + When you add the managed rule group, edit it and do the following: 
     + In the **Rule group configuration** pane, provide the details of your application's account registration and creation pages. The ACFP rule group uses this information to monitor sign-in activities. For more information, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md).
     + In the **Rules** pane, open the **Override all rule actions** dropdown and choose **Count**. With this configuration, AWS WAF evaluates requests against all of the rules in the rule group and only counts the matches that result, while still adding labels to requests. For more information, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

       With this override, you can monitor the potential impact of the ACFP managed rules to determine whether you want to add exceptions, such as exceptions for internal use cases. 
   + Position the rule group so that it's evaluated after your existing rules in the protection pack (web ACL), with a priority setting that's numerically higher than any rules or rule groups that you're already using. For more information, see [Setting rule priority](web-acl-processing-order.md). 

     This way, your current handling of traffic isn't disrupted. For example, if you have rules that detect malicious traffic such as SQL injection or cross-site scripting, they'll continue to detect and log that. Alternately, if you have rules that allow known non-malicious traffic, they can continue to allow that traffic, without having it blocked by the ACFP managed rule group. You might decide to adjust the processing order during your testing and tuning activities.

1. 

**Implement the application integration SDKs**

   Integrate the AWS WAF JavaScript SDK into your browser's account registration and account creation paths. AWS WAF also provides mobile SDKs to integrate iOS and Android devices. For more information about the integration SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about this recommendation, see [Using application integration SDKs with ACFP](waf-acfp-with-tokens.md).
**Note**  
If you are unable to use the application integration SDKs, it's possible to test the ACFP rule group by editing it in your protection pack (web ACL) and removing the override that you placed on the `AllRequests` rule. This enables the rule's Challenge action setting, to ensure that requests include a valid challenge token.   
*Do this first in a test environment and then with great care in your production environment.* This approach has the potential to block users. For example, if your registration page path doesn't accept `GET` text/html requests, then this rule configuration can effectively block all requests at the registration page. 

1. 

**Enable logging and metrics for the protection pack (web ACL)**

   As needed, configure logging, Amazon Security Lake data collection, request sampling, and Amazon CloudWatch metrics for the protection pack (web ACL). You can use these visibility tools to monitor the interaction of the ACFP managed rule group with your traffic. 
   + For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
   + For information about Amazon Security Lake, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
   + For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 
   + For information about web request sampling, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

1. 

**Associate the protection pack (web ACL) with a resource**

   If the protection pack (web ACL) isn't already associated with a test resource, associate it. For information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

1. 

**Monitor traffic and ACFP rule matches**

   Make sure that your normal traffic is flowing and that the ACFP managed rule group rules are adding labels to matching web requests. You can see the labels in the logs and see the ACFP and label metrics in the Amazon CloudWatch metrics. In the logs, the rules that you've overridden to count in the rule group show up in the `ruleGroupList` with `action` set to count, and with `overriddenAction` indicating the configured rule action that you overrode. 

1. 

**Test the rule group's credential checking capabilities**

   Perform an account creation attempt with test compromised credentials and check that the rule group matches against them as expected. 

   1. Access your protected resource's account registration page and try to add a new account. Use the following AWS WAF test credential pair and enter any test 
      + User: `WAF_TEST_CREDENTIAL@wafexample.com`
      + Password: `WAF_TEST_CREDENTIAL_PASSWORD`

      These test credentials are categorized as compromised credentials, and the ACFP managed rule group will add the `awswaf:managed:aws:acfp:signal:credential_compromised` label to the account creation request, which you can see in the logs. 

   1. In your protection pack (web ACL) logs, look for the `awswaf:managed:aws:acfp:signal:credential_compromised` label in the `labels` field on the log entries for your test account creation request. For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

   After you've verified that the rule group captures compromised credentials as expected, you can take steps to configure its implementation as you need for your protected resource.

1. 

**For CloudFront distributions, test the rule group's management of bulk account creation attempts**

   Run this test for each success response criteria that you configured for the ACFP rule group. Wait at least 30 minutes between tests.

   1. For each of your success criteria, identify an account creation attempt that will succeed with that success criteria in the response. Then, from a single client session, perform at least 5 successful account creation attempts in under 30 minutes. A user would normally only create a single account on your site. 

      After the first successful account creation, the `VolumetricSessionSuccessfulResponse` rule should start matching against the rest of your account creation responses, labeling them and counting them, based on your rule action override. The rule might miss the first one or two due to latency. 

   1. In your protection pack (web ACL) logs, look for the `awswaf:managed:aws:acfp:aggregate:volumetric:session:successful_creation_response:high` label in the `labels` field on the log entries for your test account creation web requests. For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

   These tests verify that your success criteria match your responses by checking that the successful counts aggregated by the rule surpass the rule's threshold. After you've reached the threshold, if you continue to send account creation requests from the same session, the rule will continue to match until the success rate drops below the threshold. While the threshold is exceeded, the rule matches both successful or failed account creation attempts from the session address. 

1. 

**Customize ACFP web request handling**

   As needed, add your own rules that explicitly allow or block requests, to change how ACFP rules would otherwise handle them. 

   For example, you can use ACFP labels to allow or block requests or to customize request handling. You can add a label match rule after the ACFP managed rule group to filter labeled requests for the handling that you want to apply. After testing, keep the related ACFP rules in count mode, and maintain the request handling decisions in your custom rule. For an example, see [ACFP example: Custom response for compromised credentials](waf-acfp-control-example-compromised-credentials.md). 

1. 

**Remove your test rules and enable the ACFP managed rule group settings**

   Depending on your situation, you might have decided that you want to leave some ACFP rules in count mode. For the rules that you want to run as configured inside the rule group, disable count mode in the protection pack (web ACL) rule group configuration. When you're finished testing, you can also remove your test label match rules.

1. 

**Monitor and tune**

   To be sure that web requests are being handled as you want, closely monitor your traffic after you enable the ACFP functionality that you intend to use. Adjust the behavior as needed with the rules count override on the rule group and with your own rules. 

After you finish testing your ACFP rule group implementation, if you haven't already integrated the AWS WAF JavaScript SDK into your browser's account registration and account creation pages, we strongly recommend that you do so. AWS WAF also provides mobile SDKs to integrate iOS and Android devices. For more information about the integration SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about this recommendation, see [Using application integration SDKs with ACFP](waf-acfp-with-tokens.md).

# AWS WAF Fraud Control account creation fraud prevention (ACFP) examples
<a name="waf-acfp-control-examples"></a>

This section shows example configurations that satisfy common use cases for the AWS WAF Fraud Control account creation fraud prevention (ACFP) implementations. 

Each example provides a description of the use case and then shows the solution in JSON listings for the custom configured rules. 

**Note**  
You can retrieve JSON listings like the ones shown in these examples through the console protection pack (web ACL) JSON download or rule JSON editor, or through the `getWebACL` operation in the APIs and the command line interface. 

**Topics**
+ [

# ACFP example: Simple configuration
](waf-acfp-control-example-basic.md)
+ [

# ACFP example: Custom response for compromised credentials
](waf-acfp-control-example-compromised-credentials.md)
+ [

# ACFP example: Response inspection configuration
](waf-acfp-control-example-response-inspection.md)

# ACFP example: Simple configuration
<a name="waf-acfp-control-example-basic"></a>

The following JSON listing shows an example protection pack (web ACL) with an AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group. Note the additional `CreationPath` and `RegistrationPagePath` configurations, along with the payload type and the information needed to locate new account information in the payload, in order to verify it. The rule group uses this information to monitor and manage your account creation requests. This JSON includes the protection pack (web ACL)'s automatically generated settings, like the label namespace and the protection pack (web ACL)'s application integration URL.

```
{
  "Name": "simpleACFP",
  "Id": "... ",
  "ARN": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/simpleACFP/... ",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "",
  "Rules": [
    {
      "Name": "AWS-AWSManagedRulesACFPRuleSet",
      "Priority": 0,
      "Statement": {
        "ManagedRuleGroupStatement": {
          "VendorName": "AWS",
          "Name": "AWSManagedRulesACFPRuleSet",
          "ManagedRuleGroupConfigs": [
            {
              "AWSManagedRulesACFPRuleSet": {
                "CreationPath": "/web/signup/submit-registration",
                "RegistrationPagePath": "/web/signup/registration",
                "RequestInspection": {
                  "PayloadType": "JSON",
                  "UsernameField": {
                    "Identifier": "/form/username"
                  },
                  "PasswordField": {
                    "Identifier": "/form/password"
                  },
                  "EmailField": {
                    "Identifier": "/form/email"
                  },
                  "PhoneNumberFields": [
                    {
                      "Identifier": "/form/country-code"
                    },
                    {
                      "Identifier": "/form/region-code"
                    },
                    {
                      "Identifier": "/form/phonenumber"
                    }
                  ],
                  "AddressFields": [
                    {
                      "Identifier": "/form/name"
                    },
                    {
                      "Identifier": "/form/street-address"
                    },
                    {
                      "Identifier": "/form/city"
                    },
                    {
                      "Identifier": "/form/state"
                    },
                    {
                      "Identifier": "/form/zipcode"
                    }
                  ]
                },
                "EnableRegexInPath": false
              }
            }
          ]
        }
      },
      "OverrideAction": {
        "None": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWS-AWSManagedRulesACFPRuleSet"
      }
    }
  ],
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "simpleACFP"
  },
  "Capacity": 50,
  "ManagedByFirewallManager": false,
  "RetrofittedByFirewallManager": false,
  "LabelNamespace": "awswaf:111122223333:webacl:simpleACFP:"
}
```

# ACFP example: Custom response for compromised credentials
<a name="waf-acfp-control-example-compromised-credentials"></a>

By default, the credentials check that's performed by the rule group `AWSManagedRulesACFPRuleSet` handles compromised credentials by labeling the request and blocking it. For details about the rule group and rule behavior, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).

To inform the user that the account credentials they've provided have been compromised, you can do the following: 
+ **Override the `SignalCredentialCompromised` rule to Count** – This causes the rule to only count and label matching requests.
+ **Add a label match rule with custom handling** – Configure this rule to match against the ACFP label and to perform your custom handling. 

The following protection pack (web ACL) listings shows the ACFP managed rule group from the prior example, with the `SignalCredentialCompromised` rule action overridden to count. With this configuration, when this rule group evaluates any web request that uses compromised credentials, it will label the request, but not block it. 

In addition, the protection pack (web ACL) now has a custom response named `aws-waf-credential-compromised` and a new rule named `AccountSignupCompromisedCredentialsHandling`. The rule priority is a higher numeric setting than the rule group, so it runs after the rule group in the protection pack (web ACL) evaluation. The new rule matches any request with the rule group's compromised credentials label. When the rule finds a match, it applies the Block action to the request with the custom response body. The custom response body provides information to the end user that their credentials have been compromised and proposes an action to take. 

```
{
  "Name": "compromisedCreds",
  "Id": "... ",
  "ARN": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/compromisedCreds/...",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "",
  "Rules": [
    {
      "Name": "AWS-AWSManagedRulesACFPRuleSet",
      "Priority": 0,
      "Statement": {
        "ManagedRuleGroupStatement": {
          "VendorName": "AWS",
          "Name": "AWSManagedRulesACFPRuleSet",
          "ManagedRuleGroupConfigs": [
            {
              "AWSManagedRulesACFPRuleSet": {
                "CreationPath": "/web/signup/submit-registration",
                "RegistrationPagePath": "/web/signup/registration",
                "RequestInspection": {
                  "PayloadType": "JSON",
                  "UsernameField": {
                    "Identifier": "/form/username"
                  },
                  "PasswordField": {
                    "Identifier": "/form/password"
                  },
                  "EmailField": {
                    "Identifier": "/form/email"
                  },
                  "PhoneNumberFields": [
                    {
                      "Identifier": "/form/country-code"
                    },
                    {
                      "Identifier": "/form/region-code"
                    },
                    {
                      "Identifier": "/form/phonenumber"
                    }
                  ],
                  "AddressFields": [
                    {
                      "Identifier": "/form/name"
                    },
                    {
                      "Identifier": "/form/street-address"
                    },
                    {
                      "Identifier": "/form/city"
                    },
                    {
                      "Identifier": "/form/state"
                    },
                    {
                      "Identifier": "/form/zipcode"
                    }
                  ]
                },
                "EnableRegexInPath": false
              }
            }
          ],
          "RuleActionOverrides": [
            {
              "Name": "SignalCredentialCompromised",
              "ActionToUse": {
                "Count": {}
              }
            }
          ]
        }
      },
      "OverrideAction": {
        "None": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWS-AWSManagedRulesACFPRuleSet"
      }
    },
    {
      "Name": "AccountSignupCompromisedCredentialsHandling",
      "Priority": 1,
      "Statement": {
        "LabelMatchStatement": {
          "Scope": "LABEL",
          "Key": "awswaf:managed:aws:acfp:signal:credential_compromised"
        }
      },
      "Action": {
        "Block": {
          "CustomResponse": {
            "ResponseCode": 406,
            "CustomResponseBodyKey": "aws-waf-credential-compromised",
            "ResponseHeaders": [
              {
                "Name": "aws-waf-credential-compromised",
                "Value": "true"
              }
            ]
          }
        }
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AccountSignupCompromisedCredentialsHandling"
      }
    }
  ],
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "compromisedCreds"
  },
  "Capacity": 51,
  "ManagedByFirewallManager": false,
  "RetrofittedByFirewallManager": false,
  "LabelNamespace": "awswaf:111122223333:webacl:compromisedCreds:",
  "CustomResponseBodies": {
    "aws-waf-credential-compromised": {
      "ContentType": "APPLICATION_JSON",
      "Content": "{\n  \"credentials-compromised\": \"The credentials you provided have been found in a compromised credentials database.\\n\\nTry again with a different username, password pair.\"\n}"
    }
  }
}
```

# ACFP example: Response inspection configuration
<a name="waf-acfp-control-example-response-inspection"></a>

The following JSON listing shows an example protection pack (web ACL) with an AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group that is configured to inspect origin responses. Note the response inspection configuration, which specifies success and response status codes. You can also configure success and response settings based on header, body, and body JSON matches. This JSON includes the protection pack (web ACL)'s automatically generated settings, like the label namespace and the protection pack (web ACL)'s application integration URL.

**Note**  
ATP response inspection is available only in protection packs (web ACLs) that protect CloudFront distributions.

```
{
  "Name": "simpleACFP",
  "Id": "... ",
  "ARN": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/simpleACFP/... ",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "",
  "Rules": [
    {
      "Name": "AWS-AWSManagedRulesACFPRuleSet",
      "Priority": 0,
      "Statement": {
        "ManagedRuleGroupStatement": {
          "VendorName": "AWS",
          "Name": "AWSManagedRulesACFPRuleSet",
          "ManagedRuleGroupConfigs": [
            {
              "AWSManagedRulesACFPRuleSet": {
                "CreationPath": "/web/signup/submit-registration",
                "RegistrationPagePath": "/web/signup/registration",
                "RequestInspection": {
                  "PayloadType": "JSON",
                  "UsernameField": {
                    "Identifier": "/form/username"
                  },
                  "PasswordField": {
                    "Identifier": "/form/password"
                  },
                  "EmailField": {
                    "Identifier": "/form/email"
                  },
                  "PhoneNumberFields": [
                    {
                      "Identifier": "/form/country-code"
                    },
                    {
                      "Identifier": "/form/region-code"
                    },
                    {
                      "Identifier": "/form/phonenumber"
                    }
                  ],
                  "AddressFields": [
                    {
                      "Identifier": "/form/name"
                    },
                    {
                      "Identifier": "/form/street-address"
                    },
                    {
                      "Identifier": "/form/city"
                    },
                    {
                      "Identifier": "/form/state"
                    },
                    {
                      "Identifier": "/form/zipcode"
                    }
                  ]
                },
                "ResponseInspection": {
                  "StatusCode": {
                    "SuccessCodes": [
                      200
                    ],
                    "FailureCodes": [
                      401
                    ]
                  }
                },
                "EnableRegexInPath": false
              }
            }
          ]
        }
      },
      "OverrideAction": {
        "None": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "AWS-AWSManagedRulesACFPRuleSet"
      }
    }
  ],
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "simpleACFP"
  },
  "Capacity": 50,
  "ManagedByFirewallManager": false,
  "RetrofittedByFirewallManager": false,
  "LabelNamespace": "awswaf:111122223333:webacl:simpleACFP:"
  }
```

# AWS WAF Fraud Control account takeover prevention (ATP)
<a name="waf-atp"></a>

This section explains what AWS WAF Fraud Control account takeover prevention (ATP) does.

Account takeover is an online illegal activity in which an attacker gains unauthorized access to a person's account. The attacker might do this in a number of ways, such as using stolen credentials or guessing the victim's password through a series of attempts. When the attacker gains access, they might steal money, information, or services from the victim. The attacker might pose as the victim to gain access to other accounts that the victim owns, or to gain access to the accounts of other people or organizations. Additionally, they might attempt to change the user's password in order to block the victim from their own accounts. 

You can monitor and control account takeover attempts by implementing the ATP feature. AWS WAF offers this feature in the AWS Managed Rules rule group `AWSManagedRulesATPRuleSet` and companion application integration SDKs. 

The ATP managed rule group labels and manages requests that might be part of malicious account takeover attempts. The rule group does this by inspecting login attempts that clients send to your application's login endpoint. 
+ **Request inspection** – ATP gives you visibility and control over anomalous login attempts and login attempts that use stolen credentials, to prevent account takeovers that might lead to fraudulent activity. ATP checks email and password combinations against its stolen credential database, which is updated regularly as new leaked credentials are found on the dark web. ATP aggregates data by IP address and client session, to detect and block clients that send too many requests of a suspicious nature. 
+ **Response inspection** – For CloudFront distributions, in addition to inspecting incoming login requests, the ATP rule group inspects your application's responses to login attempts, to track success and failure rates. Using this information, ATP can temporarily block client sessions or IP addresses that have too many login failures. AWS WAF performs response inspection asynchronously, so this doesn't increase latency in your web traffic. 

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Note**  
The ATP feature is not available for Amazon Cognito user pools.

**Topics**
+ [

# AWS WAF ATP components
](waf-atp-components.md)
+ [

# Using application integration SDKs with ATP
](waf-atp-with-tokens.md)
+ [

# Adding the ATP managed rule group to your protection pack (web ACL)
](waf-atp-rg-using.md)
+ [

# Testing and deploying ATP
](waf-atp-deploying.md)
+ [

# AWS WAF Fraud Control account takeover prevention (ATP) examples
](waf-atp-control-examples.md)

# AWS WAF ATP components
<a name="waf-atp-components"></a>

The primary components of AWS WAF Fraud Control account takeover prevention (ATP) are the following: 
+ **`AWSManagedRulesATPRuleSet`** – The rules in this AWS Managed Rules rule group detect, label, and handle various types of account takeover activity. The rule group inspects HTTP `POST` web requests that clients send to the specified login endpoint. For protected CloudFront distributions, the rule group also inspects the responses that the distribution sends back to these requests. For a list of the rule group's rules, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md). You include this rule group in your protection pack (web ACL) using a managed rule group reference statement. For information about using this rule group, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md). 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).
+ **Details about your application's login page** – You must provide information about your login page when you add the `AWSManagedRulesATPRuleSet` rule group to your protection pack (web ACL). This lets the rule group narrow the scope of the requests it inspects and properly validate credentials usage in web requests. The ATP rule group works with usernames that are in email format. For more information, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md). 
+ **For protected CloudFront distributions, details about how your application responds to login attempts** – You provide details about your application's responses to login attempts, and the rule group tracks and manages clients that are sending too many failed login attempts. For information about configuring this option, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md). 
+ **JavaScript and mobile application integration SDKs** – Implement the AWS WAF JavaScript and mobile SDKs with your ATP implementation to enable the full set of capabilities that the rule group offers. Many of the ATP rules use the information provided by the SDKs for session level client verification and behavior aggregation, required to separate legitimate client traffic from bot traffic. For more information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md).

You can combine your ATP implementation with the following to help you monitor, tune, and customize your protections. 
+ **Logging and metrics** – You can monitor your traffic, and understand how the ACFP managed rule group affects it, by configuring and enabling logs, Amazon Security Lake data collection, and Amazon CloudWatch metrics for your protection pack (web ACL). The labels that `AWSManagedRulesATPRuleSet` adds to your web requests are included in the data. For information about the options, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md), [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md), and [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html).

  Depending on your needs and the traffic that you see, you might want to customize your `AWSManagedRulesATPRuleSet` implementation. For example, you might want to exclude some traffic from ATP evaluation, or you might want to alter how it handles some of the account takeover attempts that it identifies, using AWS WAF features like scope-down statements or label matching rules. 
+ **Labels and label matching rules** – For any of the rules in `AWSManagedRulesATPRuleSet`, you can switch the blocking behavior to count, and then match against the labels that are added by the rules. Use this approach to customize how you handle web requests that are identified by the ATP managed rule group. For more information about labeling and using label match statements, see [Label match rule statement](waf-rule-statement-type-label-match.md) and [Web request labeling in AWS WAF](waf-labels.md). 
+ **Custom requests and responses** – You can add custom headers to the requests that you allow and you can send custom responses for requests that you block. To do this, you pair your label matching with the AWS WAF custom request and response features. For more information about customizing requests and responses, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

# Using application integration SDKs with ATP
<a name="waf-atp-with-tokens"></a>

This section explains how to use application integration SDKs with ATP.

The ATP managed rule group requires the challenge tokens that the application integration SDKs generate. The tokens enable the full set of protections that the rule group offers. 

We highly recommend implementing the application integration SDKs, for the most effective use of the ATP rule group. The challenge script must run before the ATP rule group in order for the rule group to benefit from the tokens that the script acquires. This happens automatically with the application integration SDKs. If you are unable to use the SDKs, you can alternately configure your protection pack (web ACL) so that it runs the Challenge or CAPTCHA rule action against all requests that will be inspected by the ATP rule group. Using the Challenge or CAPTCHA rule action can incur additional fees. For pricing details, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). 

**Capabilities of the ATP rule group that don't require a token**  
When web requests don't have a token, the ATP managed rule group is capable of blocking the following types of traffic:
+ Single IP addresses that make a lot of login requests. 
+ Single IP addresses that make a lot of failed login requests in a short amount of time. 
+ Login attempts with password traversal, using the same username but changing passwords. 

**Capabilities of the ATP rule group that require a token**  
The information provided in the challenge token expands the capabilities of the rule group and of your overall client application security. 

The token provides client information with each web request that enables the ATP rule group to separate legitimate client sessions from ill-behaved client sessions, even when both originate from a single IP address. The rule group uses information in the tokens to aggregate client session request behavior for fine-tuned detection and mitigation. 

When the token is available in web requests, the ATP rule group can detect and block the following additional categories of clients at the session level: 
+ Client sessions that fail the silent challenge that the SDKs manage. 
+ Client sessions that traverse usernames or passwords. This is also known as credential stuffing.
+ Client sessions that repeatedly use stolen credentials to log in.
+ Client sessions that spend a long time trying to log in. 
+ Clients sessions that make a lot of login requests. The ATP rule group provides better client isolation than the AWS WAF rate-based rule, which can block clients by IP address. The ATP rule group also uses a lower threshold. 
+ Clients sessions that make a lot of failed login requests in a short amount of time. This functionality is available for protected Amazon CloudFront distributions.

For more information about the rule group capabilities see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).

For information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about AWS WAF tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). For information about the rule actions, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

# Adding the ATP managed rule group to your protection pack (web ACL)
<a name="waf-atp-rg-using"></a>

This section explains how to add and configure the `AWSManagedRulesATPRuleSet` rule group.

To configure the ATP managed rule group to recognize account takeover activities in your web traffic, you provide information about how clients send login requests to your application. For protected Amazon CloudFront distributions, you also provide information about how your application responds to login requests. This configuration is in addition to the normal configuration for a managed rule group. 

For the rule group description and rules listing, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).

**Note**  
The ATP stolen credentials database only contains usernames in email format.

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. For basic information about how to add a managed rule group to your protection pack (web ACL), see [Adding a managed rule group to a protection pack (web ACL) through the console](waf-using-managed-rule-group.md).

**Follow best practices**  
Use the ATP rule group in accordance with the best practices at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md). 

**To use the `AWSManagedRulesATPRuleSet` rule group in your protection pack (web ACL)**

1. Add the AWS managed rule group, `AWSManagedRulesATPRuleSet` to your protection pack (web ACL), and **Edit** the rule group settings before saving. 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

1. In the **Rule group configuration** pane, provide the information that the ATP rule group uses to inspect login requests. 

   1. For **Use regular expression in paths**, toggle this on if you want AWS WAF to perform regular expression matching for your login page path specifications. 

      AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

   1. For **Login path**, provide the path of the login endpoint for your application. The rule group inspects only HTTP `POST` requests to your specified login endpoint.
**Note**  
Matching for endpoints is case insensitive. Regex specifications must not contain the flag `(?-i)`, which disables case insensitive matching. String specifications must start with a forward slash `/`.

      For example, for the URL `https://example.com/web/login`, you could provide the string path specification `/web/login`. Login paths that start with the path that you provide are considered a match. For example `/web/login` matches the login paths `/web/login`, `/web/login/`, `/web/loginPage`, and `/web/login/thisPage`, but doesn't match the login path `/home/web/login` or `/website/login`. 

   1. For **Request inspection**, specify how your application accepts login attempts by providing the request payload type and the names of the fields within the request body where the username and password are provided. Your specification of the field names depends on the payload type.
      + **JSON payload type** – Specify the field names in JSON pointer syntax. For information about the JSON Pointer syntax, see the Internet Engineering Task Force (IETF) documentation [JavaScript Object Notation (JSON) Pointer](https://tools.ietf.org/html/rfc6901). 

        For example, for the following example JSON payload, the username field specification is `/login/username` and the password field specification is `/login/password`.

        ```
        {
            "login": {
                "username": "THE_USERNAME",
                "password": "THE_PASSWORD"
            }
        }
        ```
      + **FORM\$1ENCODED payload type** – Use the HTML form names.

        For example, for an HTML form with input elements named `username1` and `password1`, the username field specification is `username1` and the password field specification is `password1`.

   1. If you're protecting Amazon CloudFront distributions, then under **Response inspection**, specify how your application indicates success or failure in its responses to login attempts. 
**Note**  
ATP response inspection is available only in protection packs (web ACLs) that protect CloudFront distributions.

      Specify a single component in the login response that you want ATP to inspect. For the **Body** and **JSON** component types, AWS WAF can inspect the first 65,536 bytes (64 KB) of the component. 

      Provide your inspection criteria for the component type, as indicated by the interface. You must provide both success and failure criteria to inspect for in the component. 

      For example, say your application indicates the status of a login attempt in the status code of the response, and uses `200 OK` for success and `401 Unauthorized` or `403 Forbidden` for failure. You would set the response inspection **Component type** to **Status code**, then in the **Success** text box enter `200` and in the **Failure** text box, enter `401` on the first line and `403` on the second.

      The ATP rule group only counts responses that match your success or failure inspection criteria. The rule group rules act on clients while they have too high a failure rate among the responses that are counted. For accurate behavior by the rule group rules, be sure to provide complete information for both successful and failed login attempts. 

      To see the rules that inspect login responses, look for `VolumetricIpFailedLoginResponseHigh` and `VolumetricSessionFailedLoginResponseHigh` in the rules listing at [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md). 

1. Provide any additional configuration that you want for the rule group. 

   You can further limit the scope of requests that the rule group inspects by adding a scope-down statement to the managed rule group statement. For example, you can inspect only requests with a specific query argument or cookie. The rule group will inspect only HTTP `POST` requests to your specified login endpoint that match the criteria in your scope-down statement. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

1. Save your changes to the protection pack (web ACL). 

Before you deploy your ATP implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. See the section that follows for guidance. 

# Testing and deploying ATP
<a name="waf-atp-deploying"></a>

This section provides general guidance for configuring and testing an AWS WAF Fraud Control account takeover prevention (ATP) implementation for your site. The specific steps that you choose to follow will depend on your needs, resources, and web requests that you receive. 

This information is in addition to the general information about testing and tuning provided at [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

**Production traffic risk**  
Before you deploy your ATP implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. 

AWS WAF provides test credentials that you can use to verify your ATP configuration. In the following procedure, you'll configure a test protection pack (web ACL) to use the ATP managed rule group, configure a rule to capture the label added by the rule group, and then run a login attempt using these test credentials. You'll verify that your web ACL has properly managed the attempt by checking the Amazon CloudWatch metrics for the login attempt. 

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. 

**To configure and test an AWS WAF Fraud Control account takeover prevention (ATP) implementation**

Perform these steps first in a test environment, then in production.

1. 

**Add the AWS WAF Fraud Control account takeover prevention (ATP) managed rule group in count mode**
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

   Add the AWS Managed Rules rule group `AWSManagedRulesATPRuleSet` to a new or existing protection pack (web ACL) and configure it so that it doesn't alter the current protection pack (web ACL) behavior. For details about the rules and labels for this rule group, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).
   + When you add the managed rule group, edit it and do the following: 
     + In the **Rule group configuration** pane, provide the details of your application's login page. The ATP rule group uses this information to monitor sign-in activities. For more information, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md).
     + In the **Rules** pane, open the **Override all rule actions** dropdown and choose **Count**. With this configuration, AWS WAF evaluates requests against all of the rules in the rule group and only counts the matches that result, while still adding labels to requests. For more information, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

       With this override, you can monitor the potential impact of the ATP managed rules to determine whether you want to add exceptions, such as exceptions for internal use cases. 
   + Position the rule group so that it's evaluated after your existing rules in the protection pack (web ACL), with a priority setting that's numerically higher than any rules or rule groups that you're already using. For more information, see [Setting rule priority](web-acl-processing-order.md). 

     This way, your current handling of traffic isn't disrupted. For example, if you have rules that detect malicious traffic such as SQL injection or cross-site scripting, they'll continue to detect and log that. Alternately, if you have rules that allow known non-malicious traffic, they can continue to allow that traffic, without having it blocked by the ATP managed rule group. You might decide to adjust the processing order during your testing and tuning activities.

1. 

**Enable logging and metrics for the protection pack (web ACL)**

   As needed, configure logging, Amazon Security Lake data collection, request sampling, and Amazon CloudWatch metrics for the protection pack (web ACL). You can use these visibility tools to monitor the interaction of the ATP managed rule group with your traffic. 
   + For information about configuring and using logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
   + For information about Amazon Security Lake, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
   + For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 
   + For information about web request sampling, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

1. 

**Associate the protection pack (web ACL) with a resource**

   If the protection pack (web ACL) isn't already associated with a test resource, associate it. For information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

1. 

**Monitor traffic and ATP rule matches**

   Make sure that your normal traffic is flowing and that the ATP managed rule group rules are adding labels to matching web requests. You can see the labels in the logs and see the ATP and label metrics in the Amazon CloudWatch metrics. In the logs, the rules that you've overridden to count in the rule group show up in the `ruleGroupList` with `action` set to count, and with `overriddenAction` indicating the configured rule action that you overrode. 

1. 

**Test the rule group's credential checking capabilities**

   Perform a login attempt with test compromised credentials and check that the rule group matches against them as expected. 

   1. Log in to your protected resource's login page using the following AWS WAF test credential pair: 
      + User: `WAF_TEST_CREDENTIAL@wafexample.com`
      + Password: `WAF_TEST_CREDENTIAL_PASSWORD`

      These test credentials are categorized as compromised credentials, and the ATP managed rule group will add the `awswaf:managed:aws:atp:signal:credential_compromised` label to the login request, which you can see in the logs. 

   1. In your protection pack (web ACL) logs, look for the `awswaf:managed:aws:atp:signal:credential_compromised` label in the `labels` field on the log entries for your test login web requests. For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

   After you've verified that the rule group captures compromised credentials as expected, you can take steps to configure its implementation as you need for your protected resource.

1. 

**For CloudFront distributions, test the rule group's login failure management**

   

   1. Run a test for each failure response criteria that you configured for the ATP rule group. Wait at least 10 minutes between tests.

      To test a single failure criteria, identify a login attempt that will fail with that criteria in the response. Then, from a single client IP address, perform at least 10 failed login attempts in under 10 minutes.

      After the first 6 failures, the volumetric failed login rule should start matching against the rest of your attempts, labeling and counting them. The rule might miss the first one or two due to latency. 

   1. In your protection pack (web ACL) logs, look for the `awswaf:managed:aws:atp:aggregate:volumetric:ip:failed_login_response:high` label in the `labels` field on the log entries for your test login web requests. For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

   These tests verify that your failure criteria match your responses by checking that the failed login counts surpass the thresholds for the rule `VolumetricIpFailedLoginResponseHigh`. After you've reached the thresholds, if you continue to send login requests from the same IP address, the rule will continue to match until the failure rate drops below the threshold. While the thresholds are exceeded, the rule matches both successful or failed logins from the IP address. 

1. 

**Customize ATP web request handling**

   As needed, add your own rules that explicitly allow or block requests, to change how ATP rules would otherwise handle them. 

   For example, you can use ATP labels to allow or block requests or to customize request handling. You can add a label match rule after the ATP managed rule group to filter labeled requests for the handling that you want to apply. After testing, keep the related ATP rules in count mode, and maintain the request handling decisions in your custom rule. For an example, see [ATP example: Custom handling for missing and compromised credentials](waf-atp-control-example-user-agent-exception.md). 

1. 

**Remove your test rules and enable the ATP managed rule group settings**

   Depending on your situation, you might have decided that you want to leave some ATP rules in count mode. For the rules that you want to run as configured inside the rule group, disable count mode in the protection pack (web ACL) rule group configuration. When you're finished testing, you can also remove your test label match rules.

1. 

**Monitor and tune**

   To be sure that web requests are being handled as you want, closely monitor your traffic after you enable the ATP functionality that you intend to use. Adjust the behavior as needed with the rules count override on the rule group and with your own rules. 

After you finish testing your ATP rule group implementation, if you haven't already done so, we strongly recommend that you integrate the AWS WAF JavaScript SDK into your browser login page, for enhanced detection capabilities. AWS WAF also provides mobile SDKs to integrate iOS and Android devices. For more information about the integration SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about this recommendation, see [Using application integration SDKs with ATP](waf-atp-with-tokens.md).

# AWS WAF Fraud Control account takeover prevention (ATP) examples
<a name="waf-atp-control-examples"></a>

This section shows example configurations that satisfy common use cases for the AWS WAF Fraud Control account takeover prevention (ATP) implementations. 

Each example provides a description of the use case and then shows the solution in JSON listings for the custom configured rules. 

**Note**  
You can retrieve JSON listings like the ones shown in these examples through the console protection pack (web ACL) JSON download or rule JSON editor, or through the `getWebACL` operation in the APIs and the command line interface. 

**Topics**
+ [

# ATP example: Simple configuration
](waf-atp-control-example-basic.md)
+ [

# ATP example: Custom handling for missing and compromised credentials
](waf-atp-control-example-user-agent-exception.md)
+ [

# ATP example: Response inspection configuration
](waf-atp-control-example-response-inspection.md)

# ATP example: Simple configuration
<a name="waf-atp-control-example-basic"></a>

The following JSON listing shows an example protection pack (web ACL) with an AWS WAF Fraud Control account takeover prevention (ATP) managed rule group. Note the additional sign-in page configuration, which gives the rule group the information it needs to monitor and manage your login requests. This JSON includes the protection pack (web ACL)'s automatically generated settings, like the label namespace and the protection pack (web ACL)'s application integration URL.

```
{
    "WebACL": {
        "LabelNamespace": "awswaf:111122223333:webacl:ATPModuleACL:",
        "Capacity": 50,
        "Description": "This is a test protection pack (web ACL) for ATP.",
        "Rules": [
            {
                "Priority": 1,
                "OverrideAction": {
                    "None": {}
                },
                "VisibilityConfig": {
                    "SampledRequestsEnabled": true,
                    "CloudWatchMetricsEnabled": true,
                    "MetricName": "AccountTakeOverValidationRule"
                },
                "Name": "DetectCompromisedUserCredentials",
                "Statement": {
                    "ManagedRuleGroupStatement": {
                        "VendorName": "AWS",
                        "Name": "AWSManagedRulesATPRuleSet",
                        "ManagedRuleGroupConfigs": [
                          {
                            "AWSManagedRulesATPRuleSet": {
                              "LoginPath": "/web/login",
                              "RequestInspection": {
                                "PayloadType": "JSON",
                                "UsernameField": {
                                  "Identifier": "/form/username"
                                },
                                "PasswordField": {
                                  "Identifier": "/form/password"
                                }
                              },
                              "EnableRegexInPath": false
                            }
                          }
                        ]
                    }
                }
            }
        ],
        "VisibilityConfig": {
            "SampledRequestsEnabled": true,
            "CloudWatchMetricsEnabled": true,
            "MetricName": "ATPValidationAcl"
        },
        "DefaultAction": {
            "Allow": {}
        },
        "ManagedByFirewallManager": false,
        "RetrofittedByFirewallManager": false,
        "Id": "32q10987-65rs-4tuv-3210-98765wxyz432",
        "ARN": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/ATPModuleACL/32q10987-65rs-4tuv-3210-98765wxyz432",
        "Name": "ATPModuleACL"
    },
    "ApplicationIntegrationURL": "https://9z87abce34ea.us-east-1.sdk.awswaf.com/9z87abce34ea/1234567a1b10/",
    "LockToken": "6d0e6966-95c9-48b6-b51d-8e82e523b847"
}
```

# ATP example: Custom handling for missing and compromised credentials
<a name="waf-atp-control-example-user-agent-exception"></a>

By default, the credentials checks that are performed by the rule group `AWSManagedRulesATPRuleSet` handle web requests as follows: 
+ **Missing credentials** – Label and block request.
+ **Compromised credentials** – Label request but don't block or count it.

For details about the rule group and rule behavior, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).

You can add custom handling for web requests that have missing or compromised credentials by doing the following: 
+ **Override the `MissingCredential` rule to Count** – This rule action override causes the rule to only count and label matching requests.
+ **Add a label match rule with custom handling** – Configure this rule to match against both of the ATP labels and to perform your custom handling. For example, you might redirect the customer to your sign-up page.

The following rule shows the ATP managed rule group from the prior example, with the `MissingCredential` rule action overridden to count. This causes the rule to apply its label to matching requests, and then only count the requests, instead of blocking them. 

```
"Rules": [
    {
        "Priority": 1,
        "OverrideAction": {
            "None": {}
        },
        "VisibilityConfig": {
            "SampledRequestsEnabled": true,
            "CloudWatchMetricsEnabled": true,
            "MetricName": "AccountTakeOverValidationRule"
        },
        "Name": "DetectCompromisedUserCredentials",
        "Statement": {
            "ManagedRuleGroupStatement": {
                "ManagedRuleGroupConfigs": [
                  {
                    "AWSManagedRulesATPRuleSet": {
                      "LoginPath": "/web/login",
                      "RequestInspection": {
                        "PayloadType": "JSON",
                        "UsernameField": {
                          "Identifier": "/form/username"
                        },
                        "PasswordField": {
                          "Identifier": "/form/password"
                        }
                      },
                      "EnableRegexInPath": false
                    }
                  }
                ]
                "VendorName": "AWS",
                "Name": "AWSManagedRulesATPRuleSet",
                "RuleActionOverrides": [
                  {
                    "ActionToUse": {
                      "Count": {}
                    },
                    "Name": "MissingCredential"
                  }
                ],
                "ExcludedRules": []
            }
        }
    }
],
```

With this configuration, when this rule group evaluates any web request that has missing or compromised credentials, it will label the request, but not block it. 

The following rule has a priority setting that is higher numerically than the preceding rule group. AWS WAF evaluates rules in numeric order, starting from the lowest, so this rule will be evaluated after the rule group evaluation. The rule is configured to match either of the credentials labels and to send a custom response for matching requests. 

```
"Name": "redirectToSignup",
      "Priority": 10,
      "Statement": {
        "OrStatement": {
          "Statements": [
            {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:managed:aws:atp:signal:missing_credential"
              }
            },
            {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:managed:aws:atp:signal:credential_compromised"
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {
          "CustomResponse": {
             your custom response settings 
          }
        }
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "redirectToSignup"
      }
```

# ATP example: Response inspection configuration
<a name="waf-atp-control-example-response-inspection"></a>

The following JSON listing shows an example protection pack (web ACL) with an AWS WAF Fraud Control account takeover prevention (ATP) managed rule group that is configured to inspect origin responses. Note the response inspection configuration, which specifies success and response status codes. You can also configure success and response settings based on header, body, and body JSON matches. This JSON includes the protection pack (web ACL)'s automatically generated settings, like the label namespace and the protection pack (web ACL)'s application integration URL.

**Note**  
ATP response inspection is available only in protection packs (web ACLs) that protect CloudFront distributions.

```
{
    "WebACL": {
        "LabelNamespace": "awswaf:111122223333:webacl:ATPModuleACL:",
        "Capacity": 50,
        "Description": "This is a test protection pack (web ACL) for ATP.",
        "Rules": [
            {
                "Priority": 1,
                "OverrideAction": {
                    "None": {}
                },
                "VisibilityConfig": {
                    "SampledRequestsEnabled": true,
                    "CloudWatchMetricsEnabled": true,
                    "MetricName": "AccountTakeOverValidationRule"
                },
                "Name": "DetectCompromisedUserCredentials",
                "Statement": {
                    "ManagedRuleGroupStatement": {
                        "VendorName": "AWS",
                        "Name": "AWSManagedRulesATPRuleSet",
                        "ManagedRuleGroupConfigs": [
                          {
                            "AWSManagedRulesATPRuleSet": {
                              "LoginPath": "/web/login",
                              "RequestInspection": {
                                "PayloadType": "JSON",
                                "UsernameField": {
                                  "Identifier": "/form/username"
                                },
                                "PasswordField": {
                                  "Identifier": "/form/password"
                                }
                              },
                              "ResponseInspection": {
                                "StatusCode": {
                                  "SuccessCodes": [
                                    200
                                  ],
                                  "FailureCodes": [
                                    401
                                  ]
                                }
                              },
                              "EnableRegexInPath": false
                            }
                          }
                        ]
                    }
                }
            }
        ],
        "VisibilityConfig": {
            "SampledRequestsEnabled": true,
            "CloudWatchMetricsEnabled": true,
            "MetricName": "ATPValidationAcl"
        },
        "DefaultAction": {
            "Allow": {}
        },
        "ManagedByFirewallManager": false,
        "RetrofittedByFirewallManager": false,
        "Id": "32q10987-65rs-4tuv-3210-98765wxyz432",
        "ARN": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/ATPModuleACL/32q10987-65rs-4tuv-3210-98765wxyz432",
        "Name": "ATPModuleACL"
    },
    "ApplicationIntegrationURL": "https://9z87abce34ea.us-east-1.sdk.awswaf.com/9z87abce34ea/1234567a1b10/",
    "LockToken": "6d0e6966-95c9-48b6-b51d-8e82e523b847"
}
```

# AWS WAF Bot Control
<a name="waf-bot-control"></a>

This section explains what Bot Control does.

With Bot Control, you can easily monitor, block, or rate limit bots such as scrapers, scanners, crawlers, status monitors, and search engines. If you use the targeted inspection level of the rule group, you can also challenge bots that don't self identify, making it harder and more expensive for malicious bots to operate against your website. You can protect your applications using the Bot Control managed rule group alone, or in combination with other AWS Managed Rules rule groups and your own custom AWS WAF rules. 

Bot Control includes a console dashboard that shows how much of your current traffic is coming from bots, based on request sampling. With the Bot Control managed rule group added to your protection pack (web ACL), you can take action against bot traffic and receive detailed, real-time information about common bot traffic coming to your applications. 

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

The Bot Control managed rule group provides a basic, common protection level that adds labels to self-identifying bots, verifies generally desirable bots, and detects high confidence bot signatures. This gives you the ability to monitor and control common categories of bot traffic. 

The Bot Control rule group also provides a targeted protection level that adds detection for sophisticated bots that don't self identify. Targeted protections use detection techniques such as browser interrogation, fingerprinting, and behavior heuristics to identify bad bot traffic. Additionally, targeted protections provide optional automated, machine-learning analysis of website traffic statistics to detect bot-related activity. When you enable machine learning, AWS WAF uses statistics about website traffic, such as timestamps, browser characteristics, and previous URL visited, to improve the Bot Control machine learning model. 

When AWS WAF evaluates a web request against the Bot Control managed rule group, the rule group adds labels to requests that it detects as bot related, for example the category of bot and the bot name. You can match against these labels in your own AWS WAF rules to customize handling. The labels that are generated by the Bot Control managed rule group are included in Amazon CloudWatch metrics and your protection pack (web ACL) logs. 

You can also use AWS Firewall Manager AWS WAF policies to deploy the Bot Control managed rule group across your applications in multiple accounts that are part of your organization in AWS Organizations.

For more information about the Bot Control managed rule group, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 

## Web bot authentication for AI agents
<a name="waf-bot-ai-agents"></a>

AWS WAF Bot Control now supports Web Bot Authentication (WBA) as a cryptographic verification method for bots and AI agents accessing your CloudFront distributions. This feature enables legitimate AI crawlers and agents to prove their identity without requiring traditional challenge-response mechanisms.

Version requirement: `AWSManagedRulesBotControlRuleSet` Version\$14.0 or later. (The static version must be explicitly selected.) For detailed label taxonomy and rule behavior, see: 
+ [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md)
+ [Web request labeling in AWS WAF](waf-labels.md)
+ [AWS Managed Rules changelog](aws-managed-rule-groups-changelog.md)

# AWS WAF Bot Control components
<a name="waf-bot-control-components"></a>

The main components of a Bot Control implementation are the following:
+ **`AWSManagedRulesBotControlRuleSet`** – The Bot Control managed rule group whose rules detect and handle various categories of bots. This rule group add labels to web requests that it detects as bot traffic. 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

The Bot Control managed rule group provides two levels of protection that you can choose from: 
  + **Common** – Detects a variety of self-identifying bots, such as web scraping frameworks, search engines, and automated browsers. Bot Control protections at this level identify common bots using traditional bot detection techniques, such as static request data analysis. The rules label traffic from these bots and block the ones that they cannot verify. 
  + **Targeted** – Includes the common-level protections and adds targeted detection for sophisticated bots that do not self identify. Targeted protections mitigate bot activity using a combination of rate limiting and CAPTCHA and background browser challenges. 
    + **`TGT_`** – Rules that provide targeted protection have names that begin with `TGT_`. All targeted protections use detection techniques such as browser interrogation, fingerprinting, and behavior heuristics to identify bad bot traffic. 
    + **`TGT_ML_`** – Targeted protection rules that use machine learning have names that begin with `TGT_ML_`. These rules use automated, machine-learning analysis of website traffic statistics to detect anomalous behavior indicative of distributed, coordinated bot activity. AWS WAF analyzes statistics about your website traffic such as timestamps, browser characteristics, and previous URL visited, to improve the Bot Control machine learning model. Machine learning capabilities are enabled by default, but you can disable them in your rule group configuration. When machine learning is disabled, AWS WAF does not evaluate these rules. 

  For details including information about the rule group's rules, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 

  You include this rule group in your protection pack (web ACL) using a managed rule group reference statement and indicating the inspection level that you want to use. For the targeted level, you also indicate whether to enable machine learning. For more information about adding this managed rule group to your protection pack (web ACL), see [Adding the AWS WAF Bot Control managed rule group to your web ACL](waf-bot-control-rg-using.md). 
+ **Bot Control dashboard** – The bot monitoring dashboard for your protection pack (web ACL), available through the protection pack (web ACL) Bot Control tab. Use this dashboard to monitor your traffic and understand how much of it comes from various types of bots. This can be a starting point for customizing your bot management, as described in this topic. You can also use it to verify your changes and monitor activity for various bots and bot categories. 
+ **AI Traffic Analysis dashboard** – Specialized dashboard for detailed AI bot and agent activity analysis, available through the protection pack (web ACL) AI Traffic Analysis tab. Provides enhanced visibility into AI-specific traffic patterns, bot intent, and access behaviors beyond standard Bot Control metrics.
+ **JavaScript and mobile application integration SDKs** – You should implement the AWS WAF JavaScript and mobile SDKs if you use the targeted protection level of the Bot Control rule group. The targeted rules use information provided by the SDKs in the client tokens for enhanced detection against malicious bots. For more information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md).
+ **Logging and metrics** – You can monitor your bot traffic and understand how the Bot Control managed rule group evaluates and handles your traffic by studying the data that's collected for your protection pack (web ACL) by AWS WAF logs, Amazon Security Lake, and Amazon CloudWatch. The labels that Bot Control adds to your web requests are included in the data. For information about these options, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md), [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md), and [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html). 

  Depending on your needs and the traffic that you see, you might want to customize your Bot Control implementation. The following are some of the most commonly used options.
+ **Scope-down statements** – You can exclude some traffic from the web requests that the Bot Control managed rule group evaluates by adding a scope-down statement inside the Bot Control managed rule group reference statement. A scope-down statement can be any nestable rule statement. When a request doesn't match the scope-down statement, AWS WAF evaluates it as not matching the rule group reference statement without evaluating it against the rule group. For more information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

  Your costs for using the Bot Control managed rule group increase with the number of web requests that AWS WAF evaluates with it. You can help reduce these costs by using a scope-down statement to limit the requests that the rule group evaluates. For example, you might want to allow your homepage to load for everyone, including bots, and then apply the rule group rules to requests that are going to your application APIs or that contain a particular type of content. 
+ **Labels and label matching rules** – You can customize how the Bot Control rule group handles some of the bot traffic that it identifies using the AWS WAF label match rule statement. The Bot Control rule group adds labels to your web requests. You can add label matching rules after the Bot Control rule group that match on Bot Control labels and apply the handling that you need. For more information about labeling and using label match statements, see [Label match rule statement](waf-rule-statement-type-label-match.md) and [Web request labeling in AWS WAF](waf-labels.md). 
+ **Custom requests and responses** – You can add custom headers to requests that you allow and you can send custom responses for requests that you block by pairing label matching with the AWS WAF custom request and response features. For more information about customizing requests and responses, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

# Using application integration SDKs with Bot Control
<a name="waf-bot-with-tokens"></a>

This section explains how to use application integration SDKs with Bot Control.

Most of the targeted protections of the Bot Control managed rule group require the challenge tokens that the application integration SDKs generate. The rules that don't require a challenge token on the request are the Bot Control common level protections and the targeted level machine learning rules. For descriptions of the protection levels and rules in the rule group, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 

We highly recommend implementing the application integration SDKs, for the most effective use of the Bot Control rule group. The challenge script must run before the Bot Control rule group in order for the rule group to benefit from the tokens that the script acquires. 
+ With the application integration SDKs, the script runs automatically.
+ If you're unable to use the SDKs, you can configure your protection pack (web ACL) so that it runs the Challenge or CAPTCHA rule action against all requests that will be inspected by the Bot Control rule group. Using the Challenge or CAPTCHA rule action can incur additional fees. For pricing details, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). 

When you implement the application integration SDKs in your clients or use one of the rule actions that runs the challenge script, you expand the capabilities of the rule group and of your overall client application security. 

Tokens provide client information with each web request. This additional information enables the Bot Control rule group to separate legitimate client sessions from ill-behaved client sessions, even when both originate from a single IP address. The rule group uses information in the tokens to aggregate client session request behavior for the fine-tuned detection and mitigation that the targeted protections level provide. 

For information about the SDKs, see [Client application integrations in AWS WAF](waf-application-integration.md). For information about AWS WAF tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). For information about the rule actions, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md).

# Adding the AWS WAF Bot Control managed rule group to your web ACL
<a name="waf-bot-control-rg-using"></a>

This section explains how to add and configure the `AWSManagedRulesBotControlRuleSet` rule group.

The Bot Control managed rule group `AWSManagedRulesBotControlRuleSet` requires additional configuration to identify the protection level that you want to implement. 

For the rule group description and rules listing, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. For basic information about how to add a managed rule group to your protection pack (web ACL), see [Adding a managed rule group to a protection pack (web ACL) through the console](waf-using-managed-rule-group.md).

**Follow best practices**  
Use the Bot Control rule group in accordance with the best practices at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md). 

**To use the `AWSManagedRulesBotControlRuleSet` rule group in your protection pack (web ACL)**

1. Add the AWS managed rule group, `AWSManagedRulesBotControlRuleSet` to your protection pack (web ACL). For the full rule group description, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

   When you add the rule group, edit it to open the configuration page for the rule group. 

1. On the rule group's configuration page, in the **Inspection level** pane, select the inspection level that you want to use. 
   + **Common** – Detects a variety of self-identifying bots, such as web scraping frameworks, search engines, and automated browsers. Bot Control protections at this level identify common bots using traditional bot detection techniques, such as static request data analysis. The rules label traffic from these bots and block the ones that they cannot verify. 
   + **Targeted** – Includes the common-level protections and adds targeted detection for sophisticated bots that do not self identify. Targeted protections mitigate bot activity using a combination of rate limiting and CAPTCHA and background browser challenges. 
     + **`TGT_`** – Rules that provide targeted protection have names that begin with `TGT_`. All targeted protections use detection techniques such as browser interrogation, fingerprinting, and behavior heuristics to identify bad bot traffic. 
     + **`TGT_ML_`** – Targeted protection rules that use machine learning have names that begin with `TGT_ML_`. These rules use automated, machine-learning analysis of website traffic statistics to detect anomalous behavior indicative of distributed, coordinated bot activity. AWS WAF analyzes statistics about your website traffic such as timestamps, browser characteristics, and previous URL visited, to improve the Bot Control machine learning model. Machine learning capabilities are enabled by default, but you can disable them in your rule group configuration. When machine learning is disabled, AWS WAF does not evaluate these rules. 

1. If you're using the targeted protection level and you don't want AWS WAF to use machine learning (ML) to analyze web traffic for distributed, coordinated bot activity, disable the machine learning option. Machine learning is required for the Bot Control rules whose names start with `TGT_ML_`. For details about these rules, see [Bot Control rules listing](aws-managed-rule-groups-bot.md#aws-managed-rule-groups-bot-rules).

1. Add a scope-down statement for the rule group, to contain the costs of using it. A scope-down statement narrows the set of requests that the rule group inspects. For example use cases, start with [Bot Control example: Using Bot Control only for the login page](waf-bot-control-example-scope-down-login.md) and [Bot Control example: Using Bot Control only for dynamic content](waf-bot-control-example-scope-down-dynamic-content.md). 

1. Provide any additional configuration that you need for the rule group. 

1. Save your changes to the protection pack (web ACL). 

Before you deploy your Bot Control implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. See the sections that follow for guidance. 

# Example scenarios of false positives with AWS WAF Bot Control
<a name="waf-bot-control-false-positives"></a>

 This section provides example situations where you might encounter false positives with AWS WAF Bot Control.

We have carefully selected the rules in the AWS WAF Bot Control managed rule group to minimize false positives. We test the rules against global traffic and monitor their impact on test protection packs (web ACLs). However, it's still possible to get false positives due to changes in traffic patterns. Additionally, some use cases are known to cause false positives and will require customization specific to your web traffic. 

Situations where you might encounter false positives include the following: 
+ Mobile apps typically have non-browser user agents, which the `SignalNonBrowserUserAgent` rule blocks by default. If you expect traffic from mobile apps, or any other legitimate traffic with non-browser user agents, you'll need to add an exception to allow it. 
+ You might rely on some specific bot traffic for things like uptime monitoring, integration testing, or marketing tools. If Bot Control identifies and blocks the bot traffic that you want to allow, you need to alter the handling by adding your own rules. While this isn't a false positive scenario for all customers, if it is for you, you will need to handle it the same as for a false positive. 
+ The Bot Control managed rule group verifies bots using the IP addresses from AWS WAF. If you use Bot Control and you have verified bots that route through a proxy or load balancer, you might need to explicitly allow them using a custom rule. For information about how to create a custom rule of this type, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md). 
+ A Bot Control rule with a low global false positive rate might heavily impact specific devices or applications. For example, in testing and validation, we might not have observed requests from applications with low traffic volumes or from less common browsers or devices. 
+ A Bot Control rule that has a historically low false positive rate might have increased false positives for valid traffic. This might be due to new traffic patterns or request attributes that emerge with valid traffic, causing it to match the rule where it didn't before. These changes might be due to situations like the following:
  + Traffic details that are altered as traffic flows through network appliances, such as load balancers or content distribution networks (CDN).
  + Emerging changes in traffic data, for example new browsers or new versions for existing browsers.

For information about how to handle false positives that you might get from the AWS WAF Bot Control managed rule group, see the guidance in the section that follows, [Testing and deploying AWS WAF Bot Control](waf-bot-control-deploying.md).

# Testing and deploying AWS WAF Bot Control
<a name="waf-bot-control-deploying"></a>

This section provides general guidance for configuring and testing an AWS WAF Bot Control implementation for your site. The specific steps that you choose to follow will depend on your needs, resources, and the web requests that you receive. 

This information is in addition to the general information about testing and tuning provided at [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

**Production traffic risk**  
Before you deploy your Bot Control implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. 

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. 

**To configure and test a Bot Control implementation**

Perform these steps first in a test environment, then in production.

1. 

**Add the Bot Control managed rule group**
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

   Add the managed AWS rule group `AWSManagedRulesBotControlRuleSet` to a new or existing protection pack (web ACL) and configure it so that it doesn't alter current protection pack (web ACL) behavior. 
   + When you add the managed rule group, edit it and do the following: 
     + In the **Inspection level** pane, select the inspection level that you want to use. 
       + **Common** – Detects a variety of self-identifying bots, such as web scraping frameworks, search engines, and automated browsers. Bot Control protections at this level identify common bots using traditional bot detection techniques, such as static request data analysis. The rules label traffic from these bots and block the ones that they cannot verify. 
       + **Targeted** – Includes the common-level protections and adds targeted detection for sophisticated bots that do not self identify. Targeted protections mitigate bot activity using a combination of rate limiting and CAPTCHA and background browser challenges. 
         + **`TGT_`** – Rules that provide targeted protection have names that begin with `TGT_`. All targeted protections use detection techniques such as browser interrogation, fingerprinting, and behavior heuristics to identify bad bot traffic. 
         + **`TGT_ML_`** – Targeted protection rules that use machine learning have names that begin with `TGT_ML_`. These rules use automated, machine-learning analysis of website traffic statistics to detect anomalous behavior indicative of distributed, coordinated bot activity. AWS WAF analyzes statistics about your website traffic such as timestamps, browser characteristics, and previous URL visited, to improve the Bot Control machine learning model. Machine learning capabilities are enabled by default, but you can disable them in your rule group configuration. When machine learning is disabled, AWS WAF does not evaluate these rules. 

       For more information about this choice, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). 
     + In the **Rules** pane, open the **Override all rule actions** dropdown and choose **Count**. With this configuration, AWS WAF evaluates requests against all of the rules in the rule group and only counts the matches that result, while still adding labels to requests. For more information, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

       With this override, you can monitor the potential impact of the Bot Control rules on your traffic, to determine whether you want to add exceptions for things like internal use cases or desired bots. 
   + Position the rule group so that it's evaluated last in the protection pack (web ACL), with a priority setting that's numerically higher than any other rules or rule groups that you're already using. For more information, see [Setting rule priority](web-acl-processing-order.md). 

     This way, your current handling of traffic isn't disrupted. For example, if you have rules that detect malicious traffic such as SQL injection or cross-site scripting, they'll continue to detect and log those requests. Alternately, if you have rules that allow known non-malicious traffic, they can continue to allow that traffic, without having it blocked by the Bot Control managed rule group. You might decide to adjust the processing order during your testing and tuning activities, but this is a good way to start.

1. 

**Enable logging and metrics for the protection pack (web ACL)**

   As needed, configure logging, Amazon Security Lake data collection, request sampling, and Amazon CloudWatch metrics for the protection pack (web ACL). You can use these visibility tools to monitor the interaction of the Bot Control managed rule group with your traffic. 
   + For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
   + For information about Amazon Security Lake, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
   + For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 
   + For information about web request sampling, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

1. 

**Associate the protection pack (web ACL) with a resource**

   If the protection pack (web ACL) isn't already associated with a resource, associate it. For information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

1. 

**Monitor traffic and Bot Control rule matches**

   Make sure that traffic is flowing and that the Bot Control managed rule group rules are adding labels to matching web requests. You can see the labels in the logs and see bot and label metrics in the Amazon CloudWatch metrics. In the logs, the rules that you've overridden to count in the rule group show up in the `ruleGroupList` with `action` set to count, and with `overriddenAction` indicating the configured rule action that you overrode.
**Note**  
The Bot Control managed rule group verifies bots using the IP addresses from AWS WAF. If you use Bot Control and you have verified bots that route through a proxy or load balancer, you might need to explicitly allow them using a custom rule. For information about how to create a custom rule, see [Using forwarded IP addresses in AWS WAF](waf-rule-statement-forwarded-ip-address.md). For information about how you can use the rule to customize Bot Control web request handling, see the next step. 

   Carefully review the web request handling for any false positives that you might need to mitigate with custom handling. For examples of false positives, see [Example scenarios of false positives with AWS WAF Bot Control](waf-bot-control-false-positives.md).

1. 

**Customize Bot Control web request handling**

   As needed, add your own rules that explicitly allow or block requests, to change how Bot Control rules would otherwise handle them. 

   How you do this depends on your use case, but the following are common solutions:
   + Explicitly allow requests with a rule that you add before the Bot Control managed rule group. With this, the allowed requests never reach the rule group for evaluation. This can help contain the cost of using the Bot Control managed rule group. 
   + Exclude requests from Bot Control evaluation by adding a scope-down statement inside the Bot Control managed rule group statement. This functions the same as the preceding option. It can help contain the cost of using the Bot Control managed rule group because the requests that don't match the scope-down statement never reach rule group evaluation. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md). 

     For examples, see the following: 
     + [Excluding IP range from bot management](waf-bot-control-example-scope-down-ip.md)
     + [Allowing traffic from a bot that you control](waf-bot-control-example-scope-down-your-bot.md)
   + Use Bot Control labels in request handling to allow or block requests. Add a label match rule after the Bot Control managed rule group to filter out labeled requests that you want to allow from those that you want to block. 

     After testing, keep the related Bot Control rules in count mode, and maintain the request handling decisions in your custom rule. For information about label match statements, see [Label match rule statement](waf-rule-statement-type-label-match.md). 

     For examples of this type of customization, see the following: 
     + [Creating an exception for a blocked user agent](waf-bot-control-example-user-agent-exception.md)
     + [Allowing a specific blocked bot](waf-bot-control-example-allow-blocked-bot.md)
     + [Blocking verified bots](waf-bot-control-example-block-verified-bots.md)

   For additional examples, see [AWS WAF Bot Control examples](waf-bot-control-examples.md).

1. 

**As needed, enable the Bot Control managed rule group settings**

   Depending on your situation, you might have decided that you want to leave some Bot Control rules in count mode or with a different action override. For the rules that you want to have run as they are configured inside the rule group, enable the regular rule configuration. To do this, edit the rule group statement in your protection pack (web ACL) and make your changes in the **Rules** pane. 

# AWS WAF Bot Control examples
<a name="waf-bot-control-examples"></a>

This section shows example configurations that satisfy a variety of common use cases for AWS WAF Bot Control implementations. 

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**
+ [

# Bot Control example: Simple configuration
](waf-bot-control-example-basic.md)
+ [

# Bot Control example: Explicitly allowing verified bots
](waf-bot-control-example-allow-verified-bots.md)
+ [

# Bot Control example: Blocking verified bots
](waf-bot-control-example-block-verified-bots.md)
+ [

# Bot Control example: Allowing a specific blocked bot
](waf-bot-control-example-allow-blocked-bot.md)
+ [

# Bot Control example: Creating an exception for a blocked user agent
](waf-bot-control-example-user-agent-exception.md)
+ [

# Bot Control example: Using Bot Control only for the login page
](waf-bot-control-example-scope-down-login.md)
+ [

# Bot Control example: Using Bot Control only for dynamic content
](waf-bot-control-example-scope-down-dynamic-content.md)
+ [

# Bot Control example: Excluding IP range from bot management
](waf-bot-control-example-scope-down-ip.md)
+ [

# Bot Control example: Allowing traffic from a bot that you control
](waf-bot-control-example-scope-down-your-bot.md)
+ [

# Bot Control example: Enabling targeted inspection level
](waf-bot-control-example-targeted-inspection-level.md)
+ [

# Bot Control example: Using two statements to limit the use of the targeted inspection level
](waf-bot-control-example-common-and-targeted-inspection-level.md)

# Bot Control example: Simple configuration
<a name="waf-bot-control-example-basic"></a>

The following JSON listing shows an example protection pack (web ACL) with an AWS WAF Bot Control managed rule group. Note the visibility configuration, which causes AWS WAF to store request samples and metrics for monitoring purposes. 

```
{
  "Name": "Bot-WebACL",
  "Id": "...",
  "ARN": "...",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "Bot-WebACL",
  "Rules": [
      {
        ...
      },
      {
         "Name": "AWS-AWSBotControl-Example",
         "Priority": 5,
         "Statement": {
            "ManagedRuleGroupStatement": {
               "VendorName": "AWS",
               "Name": "AWSManagedRulesBotControlRuleSet",
               "ManagedRuleGroupConfigs": [
                 {
                   "AWSManagedRulesBotControlRuleSet": {
                     "InspectionLevel": "COMMON"
                   }
                 }
               ],
               "RuleActionOverrides": [],
               "ExcludedRules": []
            },
            "VisibilityConfig": {
               "SampledRequestsEnabled": true,
               "CloudWatchMetricsEnabled": true,
               "MetricName": "AWS-AWSBotControl-Example"
             }
          }
      }
    ],
    "VisibilityConfig": {
      ...
    },
    "Capacity": 1496,
    "ManagedByFirewallManager": false,
    "RetrofittedByFirewallManager": false
}
```

# Bot Control example: Explicitly allowing verified bots
<a name="waf-bot-control-example-allow-verified-bots"></a>

AWS WAF Bot Control doesn't block bots that are known by AWS to be common and verifiable bots. When Bot Control identifies a web request as coming from a verified bot, it adds a label that names the bot and a label that indicates that it's a verified bot. Bot Control doesn't add any other labels, such as signals labels, in order to prevent known good bots from being blocked.

You might have other AWS WAF rules that block verified bots. If you want to ensure that verified bots are allowed, add a custom rule to allow them based on the Bot Control labels. Your new rule must run after the Bot Control managed rule group, so that the labels are available to match against. 

The following rule explicitly allows verified bots.

```
{
    "Name": "match_rule",
    "Statement": {
      "LabelMatchStatement": {
        "Scope": "LABEL",
        "Key": "awswaf:managed:aws:bot-control:bot:verified"
      }
    },
    "RuleLabels": [],
    "Action": {
      "Allow": {}
    }
}
```

# Bot Control example: Blocking verified bots
<a name="waf-bot-control-example-block-verified-bots"></a>

In order to block verified bots, you must add a rule to block them that runs after the AWS WAF Bot Control managed rule group. To do this, identify the bot names that you want to block and use a label match statement to identify and block them. If you want to just block all verified bots, you can omit the match against the `bot:name:` label. 

The following rule blocks only the `bingbot` verified bot. This rule must run after the Bot Control managed rule group.

```
{
    "Name": "match_rule",
    "Statement": {
      "AndStatement": {
        "Statements": [
          {
            "LabelMatchStatement": {
              "Scope": "LABEL",
              "Key": "awswaf:managed:aws:bot-control:bot:name:bingbot"
            }
          },
          {
            "LabelMatchStatement": {
              "Scope": "LABEL",
              "Key": "awswaf:managed:aws:bot-control:bot:verified"
            }
          }
        ]
      }
    },
    "RuleLabels": [],
    "Action": {
      "Block": {}
    }
  }
```

The following rule blocks all verified bots.

```
{
    "Name": "match_rule",
    "Statement": {
      "LabelMatchStatement": {
        "Scope": "LABEL",
        "Key": "awswaf:managed:aws:bot-control:bot:verified"
      }
    },
    "RuleLabels": [],
    "Action": {
      "Block": {}
    }
}
```

# Bot Control example: Allowing a specific blocked bot
<a name="waf-bot-control-example-allow-blocked-bot"></a>

It's possible for a bot to be blocked by more than one of the Bot Control rules. Run through the following procedure for each blocking rule. 

If an AWS WAF Bot Control rule is blocking a bot that you do not want to block, do the following:

1. Identify the Bot Control rule that's blocking the bot by checking the logs. The blocking rule will be specified in the logs in the fields whose names start with `terminatingRule`. For information about the protection pack (web ACL) logs, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). Note the label that the rule is adds to the requests. 

1. In your protection pack (web ACL), override the action of the blocking rule to count. To do this in the console, edit the rule group rule in the protection pack (web ACL) and choose a rule action override of Count for the rule. This ensures that the bot is not blocked by the rule, but the rule will still apply its label to matching requests. 

1. Add a label matching rule to your protection pack (web ACL), after the Bot Control managed rule group. Configure the rule to match against the overridden rule's label and to block all matching requests except for the bot that you don't want to block. 

   Your protection pack (web ACL) is now configured so that the bot you want to allow is no longer blocked by the blocking rule that you identified through the logs. 

Check traffic and your logs again, to be sure that the bot is being allowed through. If not, run through the above procedure again.

For example, suppose you want to block all monitoring bots except for `pingdom`. In this case, you override the `CategoryMonitoring` rule to count and then write a rule to block all monitoring bots except for those with the bot name label `pingdom`. 

The following rule uses the Bot Control managed rule group but overrides the rule action for `CategoryMonitoring` to count. The category monitoring rule applies its labels as usual to matching requests, but only counts them instead of performing its usual action of block. 

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
      "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
	  "RuleActionOverrides": [
        {
          "ActionToUse": {
            "Count": {}
          },
          "Name": "CategoryMonitoring"
        }
      ],
      "ExcludedRules": []
    }
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "AWS-AWSBotControl-Example"
  }
}
```

The following rule matches against the category monitoring label that the preceding `CategoryMonitoring` rule adds to matching web requests. Among the category monitoring requests, this rule blocks all but those that have a label for the bot name `pingdom`. 

The following rule must run after the preceding Bot Control managed rule group in the protection pack (web ACL) processing order. 

```
{
      "Name": "match_rule",
      "Priority": 10,
      "Statement": {
        "AndStatement": {
          "Statements": [
            {
              "LabelMatchStatement": {
                "Scope": "LABEL",
                "Key": "awswaf:managed:aws:bot-control:bot:category:monitoring"
              }
            },
            {
              "NotStatement": {
                "Statement": {
                  "LabelMatchStatement": {
                    "Scope": "LABEL",
                    "Key": "awswaf:managed:aws:bot-control:bot:name:pingdom"
                  }
                }
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "match_rule"
      }
}
```

# Bot Control example: Creating an exception for a blocked user agent
<a name="waf-bot-control-example-user-agent-exception"></a>

If traffic from some non-browser user agents is being erroneously blocked, you can create an exception by setting the offending AWS WAF Bot Control rule `SignalNonBrowserUserAgent` to Count and then combining the rule's labeling with your exception criteria. 

**Note**  
Mobile apps typically have non-browser user agents, which the `SignalNonBrowserUserAgent` rule blocks by default. 

The following rule uses the Bot Control managed rule group but overrides the rule action for `SignalNonBrowserUserAgent` to Count. The signal rule applies its labels as usual to matching requests, but only counts them instead of performing its usual action of block. 

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
      "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
	  "RuleActionOverrides": [
        {
          "ActionToUse": {
            "Count": {}
          },
          "Name": "SignalNonBrowserUserAgent"
        }
      ],
      "ExcludedRules": []
    }
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "AWS-AWSBotControl-Example"
  }
}
```

The following rule matches against the signal label that the Bot Control `SignalNonBrowserUserAgent` rule adds to its matching web requests. Among the signal requests, this rule blocks all but those that have the user agent that we want to allow. 

The following rule must run after the preceding Bot Control managed rule group in the protection pack (web ACL) processing order. 

```
{
    "Name": "match_rule",
    "Statement": {
      "AndStatement": {
        "Statements": [
          {
            "LabelMatchStatement": {
              "Scope": "LABEL",
              "Key": "awswaf:managed:aws:bot-control:signal:non_browser_user_agent"
            }
          },
          {
            "NotStatement": {
              "Statement": {
                "ByteMatchStatement": {
                  "FieldToMatch": {
                    "SingleHeader": {
                      "Name": "user-agent"
                    }
                  },
                  "PositionalConstraint": "EXACTLY",
                  "SearchString": "PostmanRuntime/7.29.2",
                  "TextTransformations": [
                    {
                      "Priority": 0,
                      "Type": "NONE"
                    }
                  ]
                }
              }
            }
          }
        ]
      }
    },
    "RuleLabels": [],
    "Action": {
      "Block": {}
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "match_rule"
    }
}
```

# Bot Control example: Using Bot Control only for the login page
<a name="waf-bot-control-example-scope-down-login"></a>

The following example uses a scope-down statement to apply AWS WAF Bot Control only for traffic that's coming to a website's login page, which is identified by the URI path `login`. The URI path to your login page might be different from the example, depending on your application and environment.

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
	  "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
      "RuleActionOverrides": [],
      "ExcludedRules": []
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSBotControl-Example"
    },
    "ScopeDownStatement": {
      "ByteMatchStatement": {
        "SearchString": "login",
        "FieldToMatch": {
          "UriPath": {}
        },
        "TextTransformations": [
          {
            "Priority": 0,
            "Type": "NONE"
          }
        ],
        "PositionalConstraint": "CONTAINS"
      }
    }
  }
}
```

# Bot Control example: Using Bot Control only for dynamic content
<a name="waf-bot-control-example-scope-down-dynamic-content"></a>

This example uses a scope-down statement to apply AWS WAF Bot Control only to dynamic content. 

The scope-down statement excludes static content by negating the match results for a regex pattern set: 
+ The regex pattern set is configured to match extensions of *static content*. For example, the regex pattern set specification might be `(?i)\.(jpe?g|gif|png|svg|ico|css|js|woff2?)$`. For information about regex pattern sets and statements, see [Regex pattern set match rule statement](waf-rule-statement-type-regex-pattern-set-match.md). 
+ In the scope-down statement, we exclude the matching static content by nesting the regex pattern set statement inside a `NOT` statement. For information about the `NOT` statement, see [NOT rule statement](waf-rule-statement-type-not.md).

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
	  "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
      "RuleActionOverrides": [],
      "ExcludedRules": []
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSBotControl-Example"
    },
    "ScopeDownStatement": {
      "NotStatement": {
        "Statement": {
          "RegexPatternSetReferenceStatement": {
            "ARN": "arn:aws:wafv2:us-east-1:123456789:regional/regexpatternset/excludeset/00000000-0000-0000-0000-000000000000",
            "FieldToMatch": {
              "UriPath": {}
            },
            "TextTransformations": [
              {
                "Priority": 0,
                "Type": "NONE"
              }
            ]
          }
        }
      }
    }
  }
}
```

# Bot Control example: Excluding IP range from bot management
<a name="waf-bot-control-example-scope-down-ip"></a>

If you want to exclude a subset of web traffic from AWS WAF Bot Control management, and you can identify that subset using a rule statement, then exclude it by adding a scope-down statement to your Bot Control managed rule group statement. 

The following rule performs normal Bot Control bot management on all web traffic except for web requests coming from a specific IP address range.

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
      "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
      "RuleActionOverrides": [],
      "ExcludedRules": []
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSBotControl-Example"
    },
    "ScopeDownStatement": {
      "NotStatement": {
        "Statement": {
          "IPSetReferenceStatement": {
            "ARN": "arn:aws:wafv2:us-east-1:123456789:regional/ipset/friendlyips/00000000-0000-0000-0000-000000000000"
          }
        }
      }
    }
  }
}
```

# Bot Control example: Allowing traffic from a bot that you control
<a name="waf-bot-control-example-scope-down-your-bot"></a>

You can configure some site monitoring bots and custom bots to send custom headers. If you want to allow traffic from these types of bots, you can configure them to add a shared secret in a header. You then can exclude messages that have the header by adding a scope-down statement to the AWS WAF Bot Control managed rule group statement. 

The following example rule excludes traffic with a secret header from Bot Control inspection.

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
      "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "COMMON"
          }
        }
      ],
      "RuleActionOverrides": [],
      "ExcludedRules": []
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSBotControl-Example"
    },
    "ScopeDownStatement": {
      "NotStatement": {
        "Statement": {
          "ByteMatchStatement": {
            "SearchString": "YSBzZWNyZXQ=",
            "FieldToMatch": {
              "SingleHeader": {
                "Name": "x-bypass-secret"
              }
            },
            "TextTransformations": [
              {
                "Priority": 0,
                "Type": "NONE"
              }
            ],
            "PositionalConstraint": "EXACTLY"
          }
        }
      }
    }
  }
}
```

# Bot Control example: Enabling targeted inspection level
<a name="waf-bot-control-example-targeted-inspection-level"></a>

For an enhanced level of protection, you can enable the targeted inspection level in your AWS WAF Bot Control managed rule group.

In the following example, machine learning features are enabled. You can opt out of this behavior by setting `EnableMachineLearning` to `false`.

```
{
  "Name": "AWS-AWSBotControl-Example",
  "Priority": 5,
  "Statement": {
    "ManagedRuleGroupStatement": {
      "VendorName": "AWS",
      "Name": "AWSManagedRulesBotControlRuleSet",
      "ManagedRuleGroupConfigs": [
        {
          "AWSManagedRulesBotControlRuleSet": {
            "InspectionLevel": "TARGETED",
            "EnableMachineLearning": true
          }
        }
      ],
      "RuleActionOverrides": [],
      "ExcludedRules": []
    },
    "VisibilityConfig": {
      "SampledRequestsEnabled": true,
      "CloudWatchMetricsEnabled": true,
      "MetricName": "AWS-AWSBotControl-Example"
    }
  }
}
```

# Bot Control example: Using two statements to limit the use of the targeted inspection level
<a name="waf-bot-control-example-common-and-targeted-inspection-level"></a>

As a cost optimization, you can use two AWS WAF Bot Control managed rule group statements in your protection pack (web ACL), with separate inspection levels and scoping. For instance, you could scope the targeted inspection level statement only to more sensitive application endpoints.

The two statements in the following example have mutually exclusive scoping. Without this configuration, a request could result in two billed Bot Control evaluations.

**Note**  
Multiple statements referencing `AWSManagedRulesBotControlRuleSet` are not supported in the visual editor in the console. Instead, use the JSON editor.

```
{
  "Name": "Bot-WebACL",
  "Id": "...",
  "ARN": "...",
  "DefaultAction": {
    "Allow": {}
  },
  "Description": "Bot-WebACL",
  "Rules": [
      {
        ...
      },
      {
       "Name": "AWS-AWSBotControl-Common",
       "Priority": 5,
       "Statement": {
          "ManagedRuleGroupStatement": {
             "VendorName": "AWS",
             "Name": "AWSManagedRulesBotControlRuleSet",
             "ManagedRuleGroupConfigs": [
               {
                 "AWSManagedRulesBotControlRuleSet": {
                   "InspectionLevel": "COMMON"
                 }
               }
             ],
             "RuleActionOverrides": [],
             "ExcludedRules": []
          },
          "VisibilityConfig": {
             "SampledRequestsEnabled": true,
             "CloudWatchMetricsEnabled": true,
             "MetricName": "AWS-AWSBotControl-Common"
           },
           "ScopeDownStatement": {
              "NotStatement": {
                "Statement": {
                  "ByteMatchStatement": {
                    "FieldToMatch": {
                      "UriPath": {}
                    },
                    "PositionalConstraint": "STARTS_WITH",
                    "SearchString": "/sensitive-endpoint",
                    "TextTransformations": [
                      {
                        "Type": "NONE",
                        "Priority": 0
                      }
                    ]
                  }
                }
              }
            }
        }
      },
      {
       "Name": "AWS-AWSBotControl-Targeted",
       "Priority": 6,
       "Statement": {
          "ManagedRuleGroupStatement": {
             "VendorName": "AWS",
             "Name": "AWSManagedRulesBotControlRuleSet",
             "ManagedRuleGroupConfigs": [
               {
                 "AWSManagedRulesBotControlRuleSet": {
                   "InspectionLevel": "TARGETED",
                   "EnableMachineLearning": true
                 }
               }
             ],
             "RuleActionOverrides": [],
             "ExcludedRules": []
          },
          "VisibilityConfig": {
             "SampledRequestsEnabled": true,
             "CloudWatchMetricsEnabled": true,
             "MetricName": "AWS-AWSBotControl-Targeted"
           },
           "ScopeDownStatement": {
              "Statement": {
                "ByteMatchStatement": {
                  "FieldToMatch": {
                    "UriPath": {}
                  },
                  "PositionalConstraint": "STARTS_WITH",
                  "SearchString": "/sensitive-endpoint",
                  "TextTransformations": [
                    {
                      "Type": "NONE",
                      "Priority": 0
                    }
                  ]
                }
              }
            }
        }
      }
    ],
    "VisibilityConfig": {
      ...
    },
    "Capacity": 1496,
    "ManagedByFirewallManager": false,
    "RetrofittedByFirewallManager": false
}
```

# AWS WAF Distributed Denial of Service (DDoS) prevention
<a name="waf-anti-ddos"></a>

AWS WAF offers sophisticated and customizable protection against DDoS attacks in your AWS resources. Review the options described in this section and select the level of Anti-DDoS protection that meets your security and business needs.

You can choose from two tiers of DDoS protection in AWS WAF:

Resource-level DDoS protection  
The standard tier works within Application Load Balancers to defend against known malicious sources through on-host filtering. You can configure the protective behavior to best react to potential DDoS events.  
Resource-level DDoS protection:  
+ Monitors your traffic patterns automatically.
+ Updates threat intelligence in real time.
+ Protects against known malicious sources.
**To optimize web ACL request costs for your Application Load Balancer**  
You must associate a web ACL with your Application Load Balancer to enable resource-level protection. If your Application Load Balancer is associated with a web ACL that has no configuration, you will not incur charges from AWS WAF requests, however, AWS WAF will not provide sampled requests or report on the Application Load Balancer in CloudWatch metrics. You can take the following actions to enable observability features for the Application Load Balancer:  
+ Use the `Block` action or `Allow` action with custom request headers in the `DefaultAction`. For information, see [Inserting custom request headers for non-blocking actions](customizing-the-incoming-request.md).
+ Add any rules to the web ACL. For information, see [AWS WAF rules](waf-rules.md).
+ Enable a logging destination. For information, see [Configuring logging for a protection pack (web ACL)](logging-management-configure.md).
+ Associate the web ACL with an AWS Firewall Manager policy. For information, see [Creating an AWS Firewall Manager policy for AWS WAF](create-policy.md#creating-firewall-manager-policy-for-waf).
AWS WAF will not provide sampled requests or publish CloudWatch metrics without these configurations.

AWS managed rule group DDoS protection  
The advanced tier of DDoS protections is offered through the `AWSManagedRulesAntiDDoSRuleSet`. The managed rule group complements the resource-level tier of protection, with the following notable differences:  
+ Protection extends to both Application Load Balancers and CloudFront distributions
+ Traffic baselines are created for your protected resources to improve detection of novel attack patterns.
+ Protective behavior is activated according to sensitivity levels you select.
+ Manages and labels requests to protected resources during probable DDoS events.
For a comprehensive list of the rules and functionality included, see [AWS WAF Distributed Denial of Service (DDoS) prevention rule group](aws-managed-rule-groups-anti-ddos.md).

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Topics**
+ [

# Resource-level DDoS protection for Application Load Balancers
](waf-anti-ddos-alb.md)
+ [

# Advanced Anti-DDoS protection using the AWS WAF Anti-DDoS managed rule group
](waf-anti-ddos-advanced.md)

# Resource-level DDoS protection for Application Load Balancers
<a name="waf-anti-ddos-alb"></a>

**Resource level DDoS protection** adds immediate defense to Application Load Balancers without incurring charges of deploying AWS WAF managed rule groups. This standard tier of Anti-DDoS protection uses AWS threat intelligence and traffic pattern analysis to protect Application Load Balancers. To identify known malicous sources, Anti-DDoS protection performs on-host filtering of both direct client IP addresses and X-Forwarded-For (XFF) headers. After a known malicious source is identified, protection is activated through one of two modes:

**Active under DDoS** is the default protective mode and is recommended for most use cases. 

This mode:
+ Activates protection automatically when detecting high load conditions or potential DDoS events
+ Rate-limits traffic from known malicious sources only during attack conditions
+ Minimizes impact on legitimate traffic during normal operations
+ Uses Application Load Balancer health metrics and AWS WAF response data to determine when to engage protection

**Always on** is an optional mode that is always active once enabled.

This mode: 
+ Maintains continuous protection against known malicious sources
+ Rate-limits traffic from known malicious sources in real time
+ Applies protection to both direct connections and requests with malicious IPs in XFF headers
+ May have higher impact on legitimate traffic but provides maximum security

Requests blocked by resource-level DDoS protection are recorded in CloudWatch logs as either `LowReputationPacketsDropped` or `LowReputationRequestsDenied` metrics. For information, see [AWS WAF core metrics and dimensions](waf-metrics.md#waf-metrics-general).

## Enable standard DDoS protection on an existing webACL
<a name="enabling-protection-alb"></a>

You can enable DDoS protection when you create a web ACL or update an existing web ACL associated with Application Load Balancer.

**Note**  
If you have an existing web ACL that is associated with an Application Load Balancer, Anti-DDoS protection is enabled by default with **Active under DDoS** mode.

**To enable Anti-DDoS protection in the AWS WAF console**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choose **Web ACLs** in the navigation pane, and then open any web ACL that is associated with an Application Load Balancer.

1. Choose **Associated AWS resources**.

1. Under **Resource level DDoS protection**, choose **Edit**.

1. Select one of the following protection modes:
   + **Active under DDoS** (recommended) - Protection engages only during high load conditions
   + **Always on** - Always-on protection against known malicious sources

1. Choose **Save changes**.

**Note**  
For information about creating a web ACL, see [Creating a protection pack (web ACL) in AWS WAF](web-acl-creating.md).

**To optimize web ACL request costs for your Application Load Balancer**  
You must associate a web ACL with your Application Load Balancer to enable resource-level protection. If your Application Load Balancer is associated with a web ACL that has no configuration, you will not incur charges from AWS WAF requests, however, AWS WAF will not provide sampled requests or report on the Application Load Balancer in CloudWatch metrics. You can take the following actions to enable observability features for the Application Load Balancer:  
Use the `Block` action or `Allow` action with custom request headers in the `DefaultAction`. For information, see [Inserting custom request headers for non-blocking actions](customizing-the-incoming-request.md).
Add any rules to the web ACL. For information, see [AWS WAF rules](waf-rules.md).
Enable a logging destination. For information, see [Configuring logging for a protection pack (web ACL)](logging-management-configure.md).
Associate the web ACL with an AWS Firewall Manager policy. For information, see [Creating an AWS Firewall Manager policy for AWS WAF](create-policy.md#creating-firewall-manager-policy-for-waf).
AWS WAF will not provide sampled requests or publish CloudWatch metrics without these configurations.

# Advanced Anti-DDoS protection using the AWS WAF Anti-DDoS managed rule group
<a name="waf-anti-ddos-advanced"></a>

The `AWSManagedRulesAntiDDoSRuleSet` managed rule group is the most advanced tier of Anti-DDoS protections available in AWS WAF.

**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

## AWS WAF Anti-DDoS protection components
<a name="waf-anti-ddos-components"></a>

The main components for implementing advanced Anti-DDoS protection in AWS WAF include the following:

**`AWSManagedRulesAntiDDoSRuleSet`** – Detects, labels, and challenges requests that are likely participating in a DDoS attack. It also labels all requests to a protected resource during an event. For details about the rule group's rules and labels, see [AWS WAF Distributed Denial of Service (DDoS) prevention rule group](aws-managed-rule-groups-anti-ddos.md). To use this rule group, include it in your protection pack (web ACL) using a managed rule group reference statement. For information, see [Adding the Anti-DDoS managed rule group to your protection pack (web ACL)](waf-anti-ddos-rg-using.md).
+ **Web ACL traffic overview dashboards** – Provide monitoring for DDoS activity and anti-DDoS responses in the console. For more information, see [Traffic overview dashboards for protection packs (web ACLs)](web-acl-dashboards.md).
+ **Logging and metrics** – Allow you to monitor traffic and understand Anti-DDoS protection effects. Configure logs, Amazon Security Lake data collection, and Amazon CloudWatch metrics for your protection pack (web ACL). For information about these options, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md), [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md), and [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html).
+ **Labels and label matching rules** – Allow you to customize handling of web requests identified by the Anti-DDoS managed rule group. For any rule in `AWSManagedRulesAntiDDoSRuleSet`, you can switch to count mode and match against added labels. For more information, see [Label match rule statement](waf-rule-statement-type-label-match.md) and [Web request labeling in AWS WAF](waf-labels.md).
+ **Custom requests and responses** – Allow you to add custom headers to allowed requests and send custom responses for blocked requests. Pair label matching with AWS WAF custom request and response features. For more information, see [Customized web requests and responses in AWS WAF](waf-custom-request-response.md).

# Adding the Anti-DDoS managed rule group to your protection pack (web ACL)
<a name="waf-anti-ddos-rg-using"></a>

This section explains how to add and configure the `AWSManagedRulesAntiDDoSRuleSet` rule group.

To configure the Anti-DDoS managed rule group, you provide settings that include how sensitive the rule group is to DDoS attacks and the actions that it takes on requests that are or might be participating in the attacks. This configuration is in addition to the normal configuration for a managed rule group. 

For the rule group description and rules and labels listing, see [AWS WAF Distributed Denial of Service (DDoS) prevention rule group](aws-managed-rule-groups-anti-ddos.md).

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. For basic information about how to add a managed rule group to your protection pack (web ACL), see [Adding a managed rule group to a protection pack (web ACL) through the console](waf-using-managed-rule-group.md).

**Follow best practices**  
Use the Anti-DDoS rule group in accordance with the best practices at [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md). 

**To use the `AWSManagedRulesAntiDDoSRuleSet` rule group in your protection pack (web ACL)**

1. Add the AWS managed rule group, `AWSManagedRulesAntiDDoSRuleSet` to your protection pack (web ACL), and **Edit** the rule group settings before saving. 
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

1. In the **Rule group configuration** pane, provide any custom configuration for the `AWSManagedRulesAntiDDoSRuleSet` rule group. 

   1. For **Block sensitivity level**, specify how sensitive you want the rule `DDoSRequests` to be when matching on the rule group's DDoS suspicion labeling. The higher the sensitivity, the lower the levels of labeling that the rule matches: 
      + Low sensitivity is less sensitive, causing the rule to match only on the most obvious participants in an attack, which have the high suspicion label `awswaf:managed:aws:anti-ddos:high-suspicion-ddos-request`.
      + Medium sensitivity causes the rule to match on the medium and high suspicion labels.
      + High sensitivity causes the rule to match on all of the suspicion labels: low, medium, and high.

      This rule provides the most severe handling of web requests that are suspected of participating in DDoS attacks. 

   1. For **Enable challenge**, choose whether to enable the rules `ChallengeDDoSRequests` and `ChallengeAllDuringEvent`, which by default apply the Challenge action to matching requests. 

      These rules provide request handling that's intended to permit legitimate users to proceed with their requests while blocking participants in the DDoS attack. You can override their action settings to Allow or Count or you can disable their use entirely.

      If you enable these rules, then provide any additional configuration that you want: 
      + For **Challenge sensitivity level**, specify how sensitive you want the rule `ChallengeDDoSRequests` to be. 

        The higher the sensitivity, the lower the levels of labeling that the rule matches: 
        + Low sensitivity is less sensitive, causing the rule to match only on the most obvious participants in an attack, which have the high suspicion label `awswaf:managed:aws:anti-ddos:high-suspicion-ddos-request`.
        + Medium sensitivity causes the rule to match on the medium and high suspicion labels.
        + High sensitivity causes the rule to match on all of the suspicion labels: low, medium, and high.
      + For **Exempt URI regular expressions**, provide a regular expression that matches against URIs for web requests that can't handle a silent browser challenge. The Challenge action will effectively block requests from URIs that are missing the challenge token unless they can handle the silent browser challenge. 

        The Challenge action can only be handled properly by a client that's expecting HTML content. For more information about how the action works, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md). 

        Review the default regular expression and update it as needed. The rules use the specified regular expression to identify request URIs that can't handle the Challenge action and prevent the rules from sending a challenge back. Requests that you exclude in this way can only be blocked by the rule group with the rule `DDoSRequests`. 

        The default expression that's provided in the console covers most use cases, but you should review and adapt it for your application. 

        AWS WAF supports the pattern syntax used by the PCRE library `libpcre` with some exceptions. The library is documented at [PCRE - Perl Compatible Regular Expressions](http://www.pcre.org/). For information about AWS WAF support, see [Supported regular expression syntax in AWS WAF](waf-regex-pattern-support.md).

1. Provide any additional configuration that you want for the rule group and save the rule. 
**Note**  
AWS recommends against using a scope-down statement with this managed rule group. The scope-down statement limits the requests that the rule group observes, and so can result in an inaccurate traffic baseline and diminished DDoS event detection. The scope-down statement option is available for all of the managed rule group statements, but should not be used for this one. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md).

1. In the **Set rule priority** page, move the new anti-DDoS managed rule group rule up so that it runs only after any Allow action rules that you have and before any other rules. This gives the rule group the ability to track the most traffic for Anti-DDoS protection. 

1. Save your changes to the protection pack (web ACL). 

Before you deploy your anti-DDoS implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. See the section that follows for guidance. 

# Testing and deploying Anti-DDoS
<a name="waf-anti-ddos-deploying"></a>

You will want to configure and test AWS WAF Distributed Denial of Service (DDoS) prevention before deploying the feature. This section provides general guidance for configuring and testing, however the specific steps that you choose to follow will depend on your needs, resources, and web requests that you receive. 

This information is in addition to the general information about testing and tuning provided at [Testing and tuning your AWS WAF protections](web-acl-testing.md).

**Note**  
AWS Managed Rules are designed to protect you from common web threats. When used in accordance with the documentation, AWS Managed Rules rule groups add another layer of security for your applications. However, AWS Managed Rules rule groups aren't intended as a replacement for your security responsibilities, which are determined by the AWS resources that you select. Refer to the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) to ensure that your resources in AWS are properly protected. 

**Production traffic risk**  
Test and tune your anti-DDoS implementation in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. 

This guidance is intended for users who know generally how to create and manage AWS WAF protection packs (web ACLs), rules, and rule groups. Those topics are covered in prior sections of this guide. 

**To configure and test an AWS WAF Distributed Denial of Service (DDoS) prevention implementation**

Perform these steps first in a test environment, then in production.

1. 

**Add the AWS WAF Distributed Denial of Service (DDoS) prevention managed rule group in count mode**
**Note**  
You are charged additional fees when you use this managed rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

   Add the AWS Managed Rules rule group `AWSManagedRulesAntiDDoSRuleSet` to a new or existing protection pack (web ACL) and configure it so that it doesn't alter the current protection pack (web ACL) behavior. For details about the rules and labels for this rule group, see [AWS WAF Distributed Denial of Service (DDoS) prevention rule group](aws-managed-rule-groups-anti-ddos.md).
   + When you add the managed rule group, edit it and do the following: 
     + In the **Rule group configuration** pane, provide the details needed to perform anti-DDoS activities for your web traffic. For more information, see [Adding the Anti-DDoS managed rule group to your protection pack (web ACL)](waf-anti-ddos-rg-using.md).
     + In the **Rules** pane, open the **Override all rule actions** dropdown and choose **Count**. With this configuration, AWS WAF evaluates requests against all of the rules in the rule group and only counts the matches that result, while still adding labels to requests. For more information, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

       With this override, you can monitor the potential impact of the Anti-DDoS managed rules to determine whether you want to make modifications, such as expanding the regex for the URIs that can't handle a silent browser challenge. 
   + Position the rule group so that it's evaluated as early as possible, immediately after any rules that allow traffic. Rules are evaluated in ascending numeric priority order. The console sets the order for you, starting at the top of your rule list. For more information, see [Setting rule priority](web-acl-processing-order.md). 

1. 

**Enable logging and metrics for the protection pack (web ACL)**

   As needed, configure logging, Amazon Security Lake data collection, request sampling, and Amazon CloudWatch metrics for the protection pack (web ACL). You can use these visibility tools to monitor the interaction of the Anti-DDoS managed rule group with your traffic. 
   + For information about configuring and using logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
   + For information about Amazon Security Lake, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
   + For information about Amazon CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 
   + For information about web request sampling, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

1. 

**Associate the protection pack (web ACL) with a resource**

   If the protection pack (web ACL) isn't already associated with a test resource, associate it. For information, see [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

1. 

**Monitor traffic and Anti-DDoS rule matches**

   Make sure that your normal traffic is flowing and that the Anti-DDoS managed rule group rules are adding labels to matching web requests. You can see the labels in the logs and see the Anti-DDoS and label metrics in the Amazon CloudWatch metrics. In the logs, the rules that you've overridden to count in the rule group show up in the `ruleGroupList` with `action` set to count, and with `overriddenAction` indicating the configured rule action that you overrode. 

1. 

**Customize Anti-DDoS web request handling**

   As needed, add your own rules that explicitly allow or block requests, to change how Anti-DDoS rules would otherwise handle them. 

   For example, you can use Anti-DDoS labels to allow or block requests or to customize request handling. You can add a label match rule after the Anti-DDoS managed rule group to filter labeled requests for the handling that you want to apply. After testing, keep the related Anti-DDoS rules in count mode, and maintain the request handling decisions in your custom rule. 

1. 

**Remove test rules and configure Anti-DDoS settings**

   Review your testing results to determine which Anti-DDoS rules you want to keep in count mode for monitoring only. For any rules you want to run with active protection, disable count mode in the protection pack (web ACL) rule group configuration to allow them to perform their configured actions. Once you've finalized these settings, remove any temporary test label match rules while retaining any custom rules you created for production use. For additional Anti-DDoS configuration considerations, see [Best practices for intelligent threat mitigation in AWS WAF](waf-managed-protections-best-practices.md).

1. 

**Monitor and tune**

   To be sure that web requests are being handled as you want, closely monitor your traffic after you enable the Anti-DDoS functionality that you intend to use. Adjust the behavior as needed with the rules count override on the rule group and with your own rules. 

# Best Practices for Anti-DDoS
<a name="waf-anti-ddos-best-practices"></a>
+ **Enable protection during normal traffic periods** – This allows the protection to establish baseline traffic patterns before responding to attacks. Add protection when you are not experiencing an attack and allow time for baseline establishment.
+ **Monitor metrics regularly** – Review CloudWatch metrics to understand traffic patterns and protection effectiveness.
+ **Consider proactive mode for critical applications** – While reactive mode is recommended for most use cases, consider using proactive mode for applications that require continuous protection against known threats.
+ **Test in staging environments** – Before enabling protection in production, test and tune settings in a staging environment to understand the impact on legitimate traffic.

# Client application integrations in AWS WAF
<a name="waf-application-integration"></a>

This section explains how to use the intelligent threat integration APIs and JavaScript CAPTCHA integration API with your AWS WAF features. 

Use AWS WAF client application integration APIs to couple client-side protections with your AWS server-side protection pack (web ACL) protections, to help verify that the client applications that send web requests to your protected resources are the intended clients and that your end users are human beings. 

Use the client integrations to manage silent browser challenges and CAPTCHA puzzles, obtain tokens with proof of successful browser and end user responses, and to include these tokens in requests to your protected endpoints. For general information about AWS WAF tokens, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). 

Combine your client integrations with protection pack (web ACL) protections that require valid tokens for access to your resources. You can use rule groups that check and monitor challenge tokens, like the ones listed in the next section, at [Intelligent threat integration and AWS Managed Rules](waf-application-integration-with-AMRs.md), and you can use the CAPTCHA and Challenge rule actions to check, as described in [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md). 

AWS WAF provides two levels of integration for JavaScript applications, and one for mobile applications: 
+ **Intelligent threat integration** – Verify the client application and provide AWS token acquisition and management. This is similar to the functionality provided by the AWS WAF Challenge rule action. This functionality fully integrates your client application with the `AWSManagedRulesACFPRuleSet` managed rule group, the `AWSManagedRulesATPRuleSet` managed rule group, and the targeted protection level of the `AWSManagedRulesBotControlRuleSet` managed rule group. 

  The intelligent threat integration APIs use the AWS WAF silent browser challenge to help ensure that login attempts and other calls to your protected resource are only allowed after the client has acquired a valid token. The APIs manage token authorization for your client application sessions and gather information about the client to help determine whether it's being operated by a bot or by a human being. 
**Note**  
This is available for JavaScript and for Android and iOS mobile applications. 
+ **CAPTCHA integration** – Verify end users with customized CAPTCHA puzzle that you manage in your application. This is similar to the functionality provided by the AWS WAF CAPTCHA rule action, but with added control over the puzzle placement and behavior. 

  This integration leverages the JavaScript intelligent threat integration to run silent challenges and provide AWS WAF tokens to the customer's page. 
**Note**  
This is available for JavaScript applications. 

**Topics**
+ [

# Intelligent threat integration and AWS Managed Rules
](waf-application-integration-with-AMRs.md)
+ [

# Accessing the AWS WAF client application integration APIs
](waf-application-integration-location-in-console.md)
+ [

# AWS WAF JavaScript integrations
](waf-javascript-api.md)
+ [

# AWS WAF mobile application integration
](waf-mobile-sdk.md)

# Intelligent threat integration and AWS Managed Rules
<a name="waf-application-integration-with-AMRs"></a>

This section explains how the intelligent threat integration APIs work with the AWS Managed Rules rule groups.

The intelligent threat integration APIs work with protection packs (web ACLs) that use the intelligent threat rule groups to enable the full functionality of these advanced managed rule groups. 
+ AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group `AWSManagedRulesACFPRuleSet`. 

  Account creation fraud is an online illegal activity in which an attacker creates invalid accounts in your application for purposes such as receiving sign-up bonuses or impersonating someone. The ACFP managed rule group provides rules to block, label, and manage requests that might be part of fraudulent account creation attempts. The APIs enable fine-tuned client browser verification and human interactivity information that the ACFP rules use to separate valid client traffic from malicious traffic.

  For more information, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md) and [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md).
+ AWS WAF Fraud Control account takeover prevention (ATP) managed rule group `AWSManagedRulesATPRuleSet`. 

  Account takeover is an online illegal activity in which an attacker gains unauthorized access to a person's account. The ATP managed rule group provides rules to block, label, and manage requests that might be part of malicious account takeover attempts. The APIs enable fine-tuned client verification and behavior aggregation that the ATP rules use to separate valid client traffic from malicious traffic.

  For more information, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) and [AWS WAF Fraud Control account takeover prevention (ATP)](waf-atp.md).
+ Targeted protection level of the AWS WAF Bot Control managed rule group `AWSManagedRulesBotControlRuleSet`. 

  Bots run from self-identifying and useful ones, such as most search engines and crawlers, to malicious bots that operate against your website and don't self-identify. The Bot Control managed rule group provides rules to monitor, label, and manage the bot activity in your web traffic. When you use the targeted protection level of this rule group, the targeted rules use the client session information that the APIs provide to better detect malicious bots. 

  For more information, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) and [AWS WAF Bot Control](waf-bot-control.md).

To add one of these managed rule groups to your protection pack (web ACL), see the procedures [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md), [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md), and [Adding the AWS WAF Bot Control managed rule group to your web ACL](waf-bot-control-rg-using.md).

**Note**  
The managed rule groups currently don't block requests that are missing tokens. In order to block requests that are missing tokens, after you implement your application integration APIs, follow the guidance at [Blocking requests that don't have a valid AWS WAF token](waf-tokens-block-missing-tokens.md). 

# Accessing the AWS WAF client application integration APIs
<a name="waf-application-integration-location-in-console"></a>

This section explains where to find the application integration APIs in the AWS WAF console.

The JavaScript integration APIs are generally available, and you can use them for your browsers and other devices that execute JavaScript. 

AWS WAF offers custom intelligent threat integration SDKs for Android and iOS mobile apps. 
+ For Android mobile and TV apps, the SDKs work for Android API version 23 (Android version 6) and later. For information about Android versions, see [SDK Platform release notes](https://developer.android.com/tools/releases/platforms).
+ For iOS mobile apps, the SDKs work for iOS version 13 and later. For information about iOS versions, see [iOS & iPadOS Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ For Apple TV apps, the SDKs work for tvOS version 14 or later. For information about tvOS versions, see [tvOS Release Notes](https://developer.apple.com/documentation/tvos-release-notes).

**To access the integration APIs through the console**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choose **Application integration** in the navigation pane, and then choose the tab you're interested in.
   + **Intelligent threat integration** is available for JavaScript and mobile applications. 

     The tab contains the following:
     + A list of the protection packs (web ACLs) that are enabled for intelligent threat application integration. The list includes each protection pack (web ACL) that uses the `AWSManagedRulesACFPRuleSet` managed rule group, the `AWSManagedRulesATPRuleSet` managed rule group, or the targeted protection level of the `AWSManagedRulesBotControlRuleSet` managed rule group. When you implement the intelligent threat APIs, you use the integration URL for the protection pack (web ACL) that you want to integrate with.
     + The APIs that you have access to. The JavaScript APIs are always available. For access to the mobile SDKs, contact support at [Contact AWS](https://aws.amazon.com/contact-us).
   + **CAPTCHA integration** is available for JavaScript applications. 

     The tab contains the following: 
     + The integration URL for use in your integration. 
     + The API keys that you've created for your client application domains. Your use of the CAPTCHA API requires an encrypted API key that gives clients the right to access AWS WAF CAPTCHA from their domains. For each client that you integrate with, use an API key that contains the client's domain. For more information these requirements and about managing these keys, see [Managing API keys for the JS CAPTCHA API](waf-js-captcha-api-key.md).

# AWS WAF JavaScript integrations
<a name="waf-javascript-api"></a>

This section explains how to use the AWS WAF JavaScript integrations.

You can use the JavaScript integration APIs to implement AWS WAF application integrations in your browsers and other devices that execute JavaScript. 

CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. 
+ The intelligent threat APIs let you manage token authorization through a silent client-side browser challenge, and to include the tokens in the requests that you send to your protected resources. 
+ The CAPTCHA integration API adds to the intelligent threat APIs, and lets you customize the placement and characteristics of the CAPTCHA puzzle in your client applications. This API leverages the intelligent threat APIs to acquire AWS WAF tokens for use in the page after the end user successfully completes the CAPTCHA puzzle. 

By using these integrations, you ensure that the remote procedure calls by your client contain a valid token. When these integration APIs are in place on your application's pages, you can implement mitigating rules in your protection pack (web ACL), such as blocking requests that don't contain a valid token. You can also implement rules that enforce the use of the tokens that your client applications obtain, by using the Challenge or CAPTCHA actions in your rules. 

**Example implementation of intelligent threat APIs**  
The following listing shows basic components of a typical implementation of the intelligent threat APIs in a web application page. 

```
<head>
<script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js" defer></script>
</head>
<script>
const login_response = await AwsWafIntegration.fetch(login_url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: login_body
  });
</script>
```

**Example implementation of CAPTCHA JavaScript API**  
The CAPTCHA integration API lets you customize your end users' CAPTCHA puzzle experience. The CAPTCHA integration leverages the JavaScript intelligent threat integration, for browser verification and token management, and adds a function for configuring and rendering the CAPTCHA puzzle. 

The following listing shows basic components of a typical implementation of the CAPTCHA JavaScript API in a web application page. 

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            ...
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Topics**
+ [

# Providing domains for use in the tokens
](waf-js-challenge-api-set-token-domain.md)
+ [

# Using the JavaScript API with content security policies
](waf-javascript-api-csp.md)
+ [

# Using the intelligent threat JavaScript API
](waf-js-challenge-api.md)
+ [

# Using the CAPTCHA JavaScript API
](waf-js-captcha-api.md)

# Providing domains for use in the tokens
<a name="waf-js-challenge-api-set-token-domain"></a>

This section explains how to provide additional domains for tokens.

By default, when AWS WAF creates a token, it uses the host domain of the resource that’s associated with the protection pack (web ACL). You can provide additional domains for the tokens that AWS WAF creates for the JavaScript APIs. To do this, configure the global variable `window.awsWafCookieDomainList`, with one or more token domains. 

When AWS WAF creates a token, it uses the most appropriate, shortest domain from among the combination of the domains in `window.awsWafCookieDomainList` and the host domain of the resource that’s associated with the protection pack (web ACL). 

Example settings: 

```
window.awsWafCookieDomainList = ['.aws.amazon.com']
```

```
window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com']
```

You can't use public suffixes in this list. For example, you can't use `gov.au` or `co.uk` as token domains in the list.

The domains that you specify in this list must be compatible with your other domains and domain configurations: 
+ The domains must be ones that AWS WAF will accept, based on the protected host domain and the token domain list that's configured for the protection pack (web ACL). For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ If you use the JavaScript CAPTCHA API, at least one domain in your CAPTCHA API key must be an exact match for one of the token domains in `window.awsWafCookieDomainList` or it must be the apex domain of one of those token domains. 

  For example, for the token domain `mySubdomain.myApex.com`, the API key `mySubdomain.myApex.com` is an exact match and the API key `myApex.com` is the apex domain. Either key matches the token domain. 

  For more information about the API keys, see [Managing API keys for the JS CAPTCHA API](waf-js-captcha-api-key.md). 

If you use the `AWSManagedRulesACFPRuleSet` managed rule group, you might configure a domain that matches the one in the account creation path that you provided to the rule group configuration. For more information about this configuration, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md).

If you use the `AWSManagedRulesATPRuleSet` managed rule group, you might configure a domain that matches the one in the login path that you provided to the rule group configuration. For more information about this configuration, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md).

# Using the JavaScript API with content security policies
<a name="waf-javascript-api-csp"></a>

This section provides an example configuration to allowlist the AWS WAF apex domain.

If you apply content security policies (CSP) to your resources, for your JavaScript implementation to work, you need to allowlist the AWS WAF apex domain `awswaf.com`. The JavaScript SDKs make calls to different AWS WAF endpoints, so allowlisting this domain provides the permissions that the SDKs need to operate.

The following shows an example configuration to allowlist the AWS WAF apex domain: 

```
connect-src 'self' https://*.awswaf.com;
script-src 'self' https://*.awswaf.com;
script-src-elem 'self' https://*.awswaf.com;
```

If you try to use the JavaScript SDKs with resources that use CSP, and you haven't allowlisted the AWS WAF domain, you'll receive errors like the following: 

```
Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’
```

# Using the intelligent threat JavaScript API
<a name="waf-js-challenge-api"></a>

This section provides instructions for using the intelligent threat JavaScript API in your client application.

The intelligent threat APIs provide operations for running silent challenges against the user's browser, and for handling the AWS WAF tokens that provide proof of successful challenge and CAPTCHA responses. 

Implement the JavaScript integration first in a test environment, then in production. For additional coding guidance, see the sections that follow. 

 

**To use the intelligent threat APIs**

1. **Install the APIs** 

   If you use the CAPTCHA API, you can skip this step. When you install the CAPTCHA API, the script automatically installs the intelligent threat APIs.

   1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. In the navigation pane, choose **Application integration**. On the **Application integration** page, you can see tabbed options. 

   1. Select **Intelligent threat integration**

   1. In the tab, select the protection pack (web ACL) that you want to integrate with. The protection pack (web ACL) list includes only protection packs (web ACLs) that use the `AWSManagedRulesACFPRuleSet` managed rule group, the `AWSManagedRulesATPRuleSet` managed rule group, or the targeted protection level of the `AWSManagedRulesBotControlRuleSet` managed rule group. 

   1. Open the **JavaScript SDK** pane, and copy the script tag for use in your integration. 

   1. In your application page code, in the `<head>` section, insert the script tag that you copied for the protection pack (web ACL). This inclusion causes your client application to automatically retrieve a token in the background on page load. 

      ```
      <head>
          <script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js” defer></script>
      <head>
      ```

      This `<script>` listing is configured with the `defer` attribute, but you can change the setting to `async` if you want a different behavior for your page. 

1. **(Optional) Add domain configuration for the client's tokens** – By default, when AWS WAF creates a token, it uses the host domain of the resource that’s associated with the protection pack (web ACL). To provide additional domains for the JavaScript APIs, follow the guidance at [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Code your intelligent threat integration** – Write your code to ensure that token retrieval completes before the client sends its requests to your protected endpoints. If you are already using the `fetch` API to make your call, you can substitute the AWS WAF integration `fetch` wrapper. If you don't use the `fetch` API, you can use the AWS WAF integration `getToken` operation instead. For coding guidance, see the following sections. 

1. **Add token verification in your protection pack (web ACL)** – Add at least one rule to your protection pack (web ACL) that checks for a valid challenge token in the web requests that your client sends. You can use rule groups that check and monitor challenge tokens, like the targeted level of the Bot Control managed rule group, and you can use the Challenge rule action to check, as described in [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md). 

   The protection pack (web ACL) additions verify that requests to your protected endpoints include the token that you've acquired in your client integration. Requests that include a valid, unexpired token pass the Challenge inspection and do not send another silent challenge to your client. 

1. **(Optional) Block requests that are missing tokens** – If you use the APIs with the ACFP managed rule group, the ATP managed rule group, or the targeted rules of the Bot Control rule group, these rules don't block requests that are missing tokens. To block requests that are missing tokens, follow the guidance at [Blocking requests that don't have a valid AWS WAF token](waf-tokens-block-missing-tokens.md). 

**Topics**
+ [

# Intelligent threat API specification
](waf-js-challenge-api-specification.md)
+ [

# How to use the integration `fetch` wrapper
](waf-js-challenge-api-fetch-wrapper.md)
+ [

# How to use the integration `getToken`
](waf-js-challenge-api-get-token.md)

# Intelligent threat API specification
<a name="waf-js-challenge-api-specification"></a>

This section lists the specification for the methods and properties of the intelligent threat mitigation JavaScript APIs. Use these APIs for intelligent threat and CAPTCHA integrations.

**`AwsWafIntegration.fetch()`**  
Sends the HTTP `fetch` request to the server using the AWS WAF integration implementation. 

**`AwsWafIntegration.getToken()`**  
Retrieves the stored AWS WAF token and stores it in a cookie on the current page with name `aws-waf-token`, and the value set to the token value. 

**`AwsWafIntegration.hasToken()`**  
Returns a boolean indicating whether the `aws-waf-token` cookie currently holds an unexpired token. 

If you're also using the CAPTCHA integration, see the specification for that at [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md).

# How to use the integration `fetch` wrapper
<a name="waf-js-challenge-api-fetch-wrapper"></a>

This section provides instructions for using the integration `fetch` wrapper.

You can use the AWS WAF `fetch` wrapper by changing your normal `fetch` calls to the `fetch` API under the `AwsWafIntegration` namespace. The AWS WAF wrapper supports all of the same options as the standard JavaScript `fetch` API call and adds the token handling for the integration. This approach is generally the simplest way to integrate your application. 

**Before the wrapper implementation**  
The following example listing shows standard code before implementing the `AwsWafIntegration` `fetch` wrapper.

```
const login_response = await fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

**After the wrapper implementation**  
The following listing shows the same code with the `AwsWafIntegration` `fetch` wrapper implementation.

```
const login_response = await AwsWafIntegration.fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

# How to use the integration `getToken`
<a name="waf-js-challenge-api-get-token"></a>

This section explains how to use the `getToken` operation.

AWS WAF requires your requests to protected endpoints to include the cookie named `aws-waf-token` with the value of your current token. 

The `getToken` operation is an asynchronous API call that retrieves the AWS WAF token and stores it in a cookie on the current page with name `aws-waf-token`, and the value set to the token value. You can use this token cookie as needed in your page. 

When you call `getToken`, it does the following: 
+ If an unexpired token is already available, the call returns it immediately.
+ Otherwise, the call retrieves a new token from the token provider, waiting for up to 2 seconds for the token acquisition workflow to complete before timing out. If the operation times out, it throws an error, which your calling code must handle. 

The `getToken` operation has an accompanying `hasToken` operation, which indicates whether the `aws-waf-token` cookie currently holds an unexpired token. 

`AwsWafIntegration.getToken()` retrieves a valid token and stores it as a cookie. Most client calls automatically attach this cookie, but some don't. For example, calls made across host domains don't attach the cookie. In the implementation details that follow, we show how to work with both types of client calls. 

**Basic `getToken` implementation, for calls that attach the `aws-waf-token` cookie**  
The following example listing shows standard code for implementing the `getToken` operation with a login request.

```
const login_response = await AwsWafIntegration.getToken()
	    .catch(e => {
	        // Implement error handling logic for your use case
	    })
	    // The getToken call returns the token, and doesn't typically require special handling
	    .then(token => {
	        return loginToMyPage()
	    })
	
	async function loginToMyPage() {
	    // Your existing login code
	}
```

**Submit form only after token is available from `getToken`**  
The following listing shows how to register an event listener to intercept form submissions until a valid token is available for use. 

```
<body>
	  <h1>Login</h1>
	  <p></p>
	  <form id="login-form" action="/web/login" method="POST" enctype="application/x-www-form-urlencoded">
	    <label for="input_username">USERNAME</label>
	    <input type="text" name="input_username" id="input_username"><br>
	    <label for="input_password">PASSWORD</label>
	    <input type="password" name="input_password" id="input_password"><br>
	    <button type="submit">Submit<button>
	  </form>
	
	<script>
	  const form = document.querySelector("#login-form");
	
	  // Register an event listener to intercept form submissions
	  form.addEventListener("submit", (e) => {
	      // Submit the form only after a token is available 
	      if (!AwsWafIntegration.hasToken()) {
	          e.preventDefault();
	          AwsWafIntegration.getToken().then(() => {
	              e.target.submit();
	          }, (reason) => { console.log("Error:"+reason) });
	        }
	    });
	</script>
	</body>
```

**Attaching the token when your client doesn't attach the `aws-waf-token` cookie by default**  
`AwsWafIntegration.getToken()` retrieves a valid token and stores it as a cookie, but not all client calls attach this cookie by default. For example, calls made across host domains don't attach the cookie. 

The `fetch` wrapper handles these cases automatically, but if you aren't able to use the `fetch` wrapper, you can handle this by using a custom `x-aws-waf-token` header. AWS WAF reads tokens from this header, in addition to reading them from the `aws-waf-token` cookie. The following code shows an example of setting the header. 

```
const token = await AwsWafIntegration.getToken();
const result = await fetch('/url', {
    headers: {
        'x-aws-waf-token': token,
    },
});
```

By default, AWS WAF only accepts tokens that contain the same domain as the requested host domain. Any cross-domain tokens require corresponding entries in the protection pack (web ACL) token domain list. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists). 

For additional information about cross-domain token use, see [aws-samples/aws-waf-bot-control-api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha).

# Using the CAPTCHA JavaScript API
<a name="waf-js-captcha-api"></a>

This section provides instructions for using the CAPTCHA integration API.

The CAPTCHA JavaScript API allows you to configure the CAPTCHA puzzle and place it where you want in your client application. This API leverages the features of the intelligent threat JavaScript APIs to acquire and use AWS WAF tokens after an end user successfully completes a CAPTCHA puzzle. 

Implement the JavaScript integration first in a test environment, then in production. For additional coding guidance, see the sections that follow. 

**To use the CAPTCHA integration API**

1. **Install the API**

   1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. In the navigation pane, choose **Application integration**. On the **Application integration** page, you can see tabbed options. 

   1. Select **CAPTCHA integration**.

   1. Copy the listed JavaScript integration script tag for use in your integration.

   1. In your application page code, in the `<head>` section, insert the script tag that you copied. This inclusion makes the CAPTCHA puzzle available for configuration and use. 

      ```
      <head>
          <script type="text/javascript" src="integrationURL/jsapi.js" defer></script>
      </head>
      ```

      This `<script>` listing is configured with the `defer` attribute, but you can change the setting to `async` if you want a different behavior for your page. 

      The CAPTCHA script also automatically loads the intelligent threat integration script if it isn't already present. The intelligent threat integration script causes your client application to automatically retrieve a token in the background on page load, and provides other token management functionality that you need for your use of the CAPTCHA API. 

1. **(Optional) Add domain configuration for the client's tokens** – By default, when AWS WAF creates a token, it uses the host domain of the resource that’s associated with the protection pack (web ACL). To provide additional domains for the JavaScript APIs, follow the guidance at [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Get the encrypted API key for the client** – The CAPTCHA API requires an encrypted API key that contains a list of valid client domains. AWS WAF uses this key to verify that the client domain you're using with the integration is approved to use AWS WAF CAPTCHA. To generate your API key, follow the guidance at [Managing API keys for the JS CAPTCHA API](waf-js-captcha-api-key.md).

1. **Code your CAPTCHA widget implementation** – Implement the `renderCaptcha()` API call in your page, at the location where you want to use it. For information about configuring and using this function, see the following sections, [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md) and [How to render the CAPTCHA puzzle](waf-js-captcha-api-render.md). 

   The CAPTCHA implementation integrates with the intelligent threat integration APIs for token management and to run fetch calls that use the AWS WAF tokens. For guidance about using these APIs, see [Using the intelligent threat JavaScript API](waf-js-challenge-api.md).

1. **Add token verification in your protection pack (web ACL)** – Add at least one rule to your protection pack (web ACL) that checks for a valid CAPTCHA token in the web requests that your client sends. You can use the CAPTCHA rule action to check, as described in [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md). 

   The protection pack (web ACL) additions verify that requests going to your protected endpoints include the token that you've acquired in your client integration. Requests that include a valid, unexpired CAPTCHA token pass the CAPTCHA rule action inspection and do not present your end user with another CAPTCHA puzzle. 

After you've implemented the JavaScript API, you can review the CloudWatch metrics for CAPTCHA puzzle attempts and solutions. For metrics and dimension details, see [Account metrics and dimensions](waf-metrics.md#waf-metrics-account).

**Topics**
+ [

# CAPTCHA JavaScript API specification
](waf-js-captcha-api-specification.md)
+ [

# How to render the CAPTCHA puzzle
](waf-js-captcha-api-render.md)
+ [

# Handling a CAPTCHA response from AWS WAF
](waf-js-captcha-api-conditional.md)
+ [

# Managing API keys for the JS CAPTCHA API
](waf-js-captcha-api-key.md)

# CAPTCHA JavaScript API specification
<a name="waf-js-captcha-api-specification"></a>

This section lists the specification for the methods and properties of the CAPTCHA JavaScript APIs. Use the CAPTCHA JavaScript APIs to run custom CAPTCHA puzzles in your client applications. 

This API builds on the intelligent threat APIs, which you use to configure and manage AWS WAF token acquisition and use. See [Intelligent threat API specification](waf-js-challenge-api-specification.md). .

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Presents an AWS WAF CAPTCHA puzzle to the end user and, upon success, updates the client token with the CAPTCHA validation. This is available only with the CAPTCHA integration. Use this call along with the intelligent threat APIs to manage token retrieval and to provide the token in your `fetch` calls. See the intelligent threat APIs at [Intelligent threat API specification](waf-js-challenge-api-specification.md).  
Unlike the CAPTCHA interstitial that AWS WAF sends, the CAPTCHA puzzle rendered by this method displays the puzzle immediately, without an initial title screen.     
**`container`**  
The `Element` object for the target container element on the page. This is commonly retrieved by calling `document.getElementById()` or `document.querySelector()`.  
Required: Yes  
Type: `Element`  
**configuration**  
An object containing CAPTCHA configuration settings, as follows****:    
**`apiKey`**   
The encrypted API key that enables permissions for the client's domain. Use the AWS WAF console to generate your API keys for your client domains. You can use one key for up to five domains. For information, see [Managing API keys for the JS CAPTCHA API](waf-js-captcha-api-key.md).   
Required: Yes  
Type: `string`  
**`onSuccess: (wafToken: string) => void;`**   
Called with a valid AWS WAF token when the end user successfully completes a CAPTCHA puzzle. Use the token in the requests that you send to the endpoints that you protect with an AWS WAF protection pack (web ACL). The token provides proof and the timestamp of the latest successful puzzle completion.   
Required: Yes  
**`onError?: (error: CaptchaError) => void;`**   
Called with an error object when an error occurs during the CAPTCHA operation.   
Required: No  
**`CaptchaError` class definition** – The `onError` handler supplies an error type with the following class definition.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind` – The kind of error returned. 
+ `statusCode` – The HTTP status code, if available. This is used by `network_error` if the error is due to an HTTP error.  
**`onLoad?: () => void;`**   
Called when a new CAPTCHA puzzle loads.  
Required: No  
**`onPuzzleTimeout?: () => void;`**   
Called when a CAPTCHA puzzle isn't completed before it expires.  
Required: No  
**`onPuzzleCorrect?: () => void;`**   
Called when a correct answer is provided to a CAPTCHA puzzle.  
Required: No  
**`onPuzzleIncorrect?: () => void;`**   
Called when an incorrect answer is provided to a CAPTCHA puzzle.  
Required: No  
**`defaultLocale`**   
The default locale to use for the CAPTCHA puzzle. The written instructions for CAPTCHA puzzles are available in Arabic (ar-SA), simplified Chinese (zh-CN), Dutch (nl-NL), English (en-US), French (fr-FR), German (de-DE), Italian (it-IT), Japanese (ja-JP), Brazilian Portuguese (pt-BR), Spanish (es-ES), and Turkish (tr-TR). Audio instructions are available for all of the written languages except Chinese and Japanese, which default to English. To change the default language, provide the international language and locale code, for example, `ar-SA`.  
Default: The language currently in use in the end user's browser  
Required: No  
Type: `string`  
**`disableLanguageSelector`**   
If set to `true`, the CAPTCHA puzzle hides the language selector.   
Default: `false`  
Required: No  
Type: `boolean`  
**`dynamicWidth`**   
If set to `true`, the CAPTCHA puzzle changes width for compatibility with the browser window width.   
Default: `false`  
Required: No  
Type: `boolean`  
**`skipTitle`**   
If set to `true`, the CAPTCHA puzzle doesn't display the puzzle title heading **Solve the puzzle**.   
Default: `false`  
Required: No  
Type: `boolean`

# How to render the CAPTCHA puzzle
<a name="waf-js-captcha-api-render"></a>

This section provides an example `renderCaptcha` implementation.

You can use the AWS WAF `renderCaptcha` call where you want to in your client interface. The call retrieves a CAPTCHA puzzle from AWS WAF, renders it, and sends the results to AWS WAF for verification. When you make the call, you provide the puzzle rendering configuration and the callbacks that you want to run when your end users complete the puzzle. For details about the options, see the preceding section, [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md).

Use this call in conjunction with the token management functionality of the intelligent threat integration APIs. This call gives your client a token that verifies the successful completion of the CAPTCHA puzzle. Use the intelligent threat integration APIs to manage the token and to provide the token in your client's calls to the endpoints that are protected with AWS WAF protection packs (web ACLs). For information about the intelligent threat APIs, see [Using the intelligent threat JavaScript API](waf-js-challenge-api.md).

**Example implementation**  
The following example listing shows a standard CAPTCHA implementation, including the placement of the AWS WAF integration URL in the `<head>` section. 

This listing configures the `renderCaptcha` function with a success callback that uses the `AwsWafIntegration.fetch` wrapper of the intelligent threat integration APIs. For information about this function, see [How to use the integration `fetch` wrapper](waf-js-challenge-api-fetch-wrapper.md).

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Captcha completed. wafToken contains a valid WAF token. Store it for
        // use later or call AwsWafIntegration.fetch() to use it easily.
        // It will expire after a time, so calling AwsWafIntegration.getToken()
        // again is advised if the token is needed later on, outside of using the
        // fetch wrapper.
        
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: "{ ... }" /* body content */
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Example configuration settings**  
The following example listing shows the `renderCaptcha` with non-default settings for the width and the title options. 

```
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            dynamicWidth: true, 
            skipTitle: true
        });
```

For full information about the configuration options, see [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md).

# Handling a CAPTCHA response from AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

This section provides an example of handling a CAPTCHA response.

An AWS WAF rule with a CAPTCHA action terminates the evaluation of a matching web request if the request doesn't have a token with a valid CAPTCHA timestamp. If the request is a `GET` text/html call, the CAPTCHA action then serves the client an interstitial with a CAPTCHA puzzle. When you don't integrate the CAPTCHA JavaScript API, the interstitial runs the puzzle and, if the end user successfully solves it, automatically resubmits the request. 

When you integrate the CAPTCHA JavaScript API and customize your CAPTCHA handling, you need to detect the terminating CAPTCHA response, serve your custom CAPTCHA, and then if the end user successfully solves the puzzle, resubmit the client's web request. 

The following code example shows how to do this. 

**Note**  
The AWS WAF CAPTCHA action response has a status code of HTTP 405, which we use to recognize the CAPTCHA response in this code. If your protected endpoint uses an HTTP 405 status code to communicate any other type of response for the same call, this example code will render a CAPTCHA puzzle for those responses as well. 

```
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>
<body>
    <div id="my-captcha-box"></div>
    <div id="my-output-box"></div>

    <script type="text/javascript">
    async function loadData() {
        // Attempt to fetch a resource that's configured to trigger a CAPTCHA
        // action if the rule matches. The CAPTCHA response has status=HTTP 405.
        const result = await AwsWafIntegration.fetch("/protected-resource");

        // If the action was CAPTCHA, render the CAPTCHA and return

        // NOTE: If the endpoint you're calling in the fetch call responds with HTTP 405
        // as an expected response status code, then this check won't be able to tell the
        // difference between that and the CAPTCHA rule action response.

        if (result.status === 405) {
            const container = document.querySelector("#my-captcha-box");
            AwsWafCaptcha.renderCaptcha(container, {
                apiKey: "...API key goes here...",
                onSuccess() {
                    // Try loading again, now that there is a valid CAPTCHA token
                    loadData();
                },
            });
            return;
        }

        const container = document.querySelector("#my-output-box");
        const response = await result.text();
        container.innerHTML = response;
    }

    window.addEventListener("load", () => {
        loadData();
    });
    </script>
</body>
</html>
```

# Managing API keys for the JS CAPTCHA API
<a name="waf-js-captcha-api-key"></a>

This section provides instructions for generating and deleting API keys.

To integrate AWS WAF CAPTCHA into a a client application with the JavaScript API, you need the JavaScript API integration tag and the encrypted API key for the client domain where you want to run your CAPTCHA puzzle. 

The CAPTCHA application integration for JavaScript uses the encrypted API keys to verify that the client application domain has permission to use the AWS WAF CAPTCHA API. When you call the CAPTCHA API from your JavaScript client, you provide an API key with a domain list that includes a domain for the current client. You can list up to 5 domains in a single encrypted key. 

**API key requirements**  
The API key that you use in your CAPTCHA integration must contain a domain that applies to the client where you use the key. 
+ If you specify a `window.awsWafCookieDomainList` in your client's intelligent threat integration, then at least one domain in your API key must be an exact match for one of the token domains in `window.awsWafCookieDomainList` or it must be the apex domain of one of those token domains. 

  For example, for the token domain `mySubdomain.myApex.com`, the API key `mySubdomain.myApex.com` is an exact match and the API key `myApex.com` is the apex domain. Either key matches the token domain. 

  For information about the setting the token domain list, see [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md).
+ Otherwise, the current domain must be contained in the API key. The current domain is the domain that you can see in the browser address bar. 

The domains that you use must be ones that AWS WAF will accept, based on the protected host domain and the token domain list that's configured for the web ACL. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).

**How to choose the Region for your API key**  
AWS WAF can generate CAPTCHA API keys in any Region where AWS WAF is available. 

As a general rule, you should use the same Region for your CAPTCHA API key as you use for your protection pack (web ACL). If you expect a global audience for a regional protection pack (web ACL), however, you can obtain a CAPTCHA JavaScript integration tag that's scoped to CloudFront and an API key that's scoped to CloudFront, and use them with a regional protection pack (web ACL). This approach allows clients to load a CAPTCHA puzzle from the Region that's closest to them, which reduces latency. 

CAPTCHA API keys that are scoped to Regions other than CloudFront are not supported for use across multiple Regions. They can only be used in the Region they are scoped to. 

**To generate an API key for your client domains**  
To obtain the integration URL and generate and retrieve the API keys through the console. 

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Application integration**. 

1. In the pane, **protection packs (web ACLs) that are enabled for application integration**, select the Region that you want to use for your API key. You can also select the Region in the **API keys** pane of the **CAPTCHA integration** tab.

1. Choose the tab **CAPTCHA integration**. This tab provides the CAPTCHA JavaScript integration tag, which you can use in your integration, and the API keys listing. Both are scoped to the selected Region.

1. In the **API keys** pane, choose **Generate key**. The key generation dialogue appears. 

1. Enter the client domains that you want to include in the key. You can enter up to 5. When you're finished, choose **Generate key**. The interface returns to the CAPTCHA integration tab, where your new key is listed. 

   Once created, an API key is immutable. If you need to make changes to a key, generate a new key and use that instead. 

1. (Optional) Copy the newly generated key for use in your integration. 

You can also use the REST APIs or one of the language-specific AWS SDKs for this work. The REST API calls are [CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) and [ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html). 

**To delete an API key**  
To delete an API key, you must use the REST API or one of the language specific AWS SDKs. The REST API call is [DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). You can't use the console to delete a key. 

After you delete a key, it can take up to 24 hours for AWS WAF to disallow use of the key in all regions. 

# AWS WAF mobile application integration
<a name="waf-mobile-sdk"></a>

This section introduces the topic of using the AWS WAF mobile SDKs to implement AWS WAF intelligent threat integration SDKs for Android and iOS mobile and TV apps. For TV apps, the SDKs are compatible with major smart TV platforms, including Android TV and Apple TV.
+ For Android mobile and TV apps, the SDKs work for Android API version 23 (Android version 6) and later. For information about Android versions, see [SDK Platform release notes](https://developer.android.com/tools/releases/platforms).
+ For iOS mobile apps, the SDKs work for iOS version 13 and later. For information about iOS versions, see [iOS & iPadOS Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ For Apple TV apps, the SDKs work for tvOS version 14 or later. For information about tvOS versions, see [tvOS Release Notes](https://developer.apple.com/documentation/tvos-release-notes).

With the mobile AWS WAF SDK, you can manage token authorization, and include the tokens in the requests that you send to your protected resources. By using the SDKs, you ensure that these remote procedure calls by your client contain a valid token. Additionally, when this integration is in place on your application's pages, you can implement mitigating rules in your protection pack (web ACL), such as blocking requests that don't contain a valid token.

For access to the mobile SDKs, contact support at [Contact AWS](https://aws.amazon.com/contact-us).

**Note**  
The AWS WAF mobile SDKs aren't available for CAPTCHA customization.

The basic approach for using the SDK is to create a token provider using a configuration object, then to use the token provider to retrieve tokens from AWS WAF. By default, the token provider includes the retrieved tokens in your web requests to your protected resource. 

The following is a partial listing of an SDK implementation, which shows the main components. For more detailed examples, see [Code examples for the AWS WAF mobile SDK](waf-mobile-sdk-coding-examples.md).

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
	let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
	let tokenProvider = WAFTokenProvider(configuration)
	let token = tokenProvider.getToken()
```

------
#### [ Android ]

```
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");
	String domainName = "Domain name";
	WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
	WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);
	WAFToken token = tokenProvider.getToken();
```

------

# Installing the AWS WAF mobile SDK
<a name="waf-mobile-sdk-installing"></a>

This section provides instructions for installing the AWS WAF mobile SDK.

For access to the mobile SDKs, contact support at [Contact AWS](https://aws.amazon.com/contact-us).

Implement the mobile SDK first in a test environment, then in production.

**To install the AWS WAF mobile SDK**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **Application integration**. 

1. In the **Intelligent threat integrations** tab, do the following: 

   1. In the pane **protection packs (web ACLs) that are enabled for application integration**, locate the protection pack (web ACL) that you're integrating with. Copy and save the protection pack (web ACL) integration URL for use in your implementation. You can also obtain this URL through the API call `GetWebACL`.

   1. Choose the mobile device type and version, then choose **Download**. You can choose any version you like, but we recommend using the latest version. AWS WAF downloads the `zip` file for your device to your standard download location.

1. In your app development environment, unzip the file to a work location of your choice. In the top-level directory of the zip file, locate and open the `README`. Follow the instructions in the `README` file to install the AWS WAF mobile SDK for use in your mobile app code. 

1. Program your app according to the guidance in the following sections.

# AWS WAF mobile SDK specification
<a name="waf-mobile-sdk-specification"></a>

This section lists the SDK objects, operations, and configuration settings for the latest available version of the AWS WAF mobile SDK. For detailed information about how the token provider and operations work for the various combinations of configuration settings, see [How the AWS WAF mobile SDK works](waf-mobile-sdk-how-it-works.md). 

**`WAFToken`**  
Holds an AWS WAF token.    
**`getValue()`**  
Retrieves the `String` representation of the `WAFToken`. 

**`WAFTokenProvider`**  
Manages tokens in your mobile app. Implement this using a `WAFConfiguration` object.    
**`getToken()`**  
If background refresh is enabled, this returns the cached token. If background refresh is disabled, this makes a synchronous, blocking call to AWS WAF to retrieve a new token.   
**`loadTokenIntoProvider(WAFToken)`**  
Loads the specified token into the `WAFTokenProvider`, replacing any token that the provider was managing. The token provider takes ownership of the new token and handles refreshing it going forward. This operation also updates the token in the cookie store, if `setTokenCookie` is enabled in the `WAFConfiguration`.  
**`onTokenReady(WAFTokenResultCallback)`**  
Instructs the token provider to refresh the token and invoke the provided callback when an active token is ready. The token provider will invoke your callback in a background thread when the token is cached and ready. Call this when your app first loads and also when it comes back to an active state. For more information about returning to an active state, see [Retrieving a token following app inactivity](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
For Android or iOS apps, you can set `WAFTokenResultCallback` to the operation that you want the token provider to invoke when a requested token is ready. Your implementation of `WAFTokenResultCallback` must take the parameters `WAFToken`, `SdkError`. For iOS apps, you can alternately create an inline function.   
**`storeTokenInCookieStorage(WAFToken)`**  
Instructs the `WAFTokenProvider` to store the specified AWS WAF token into the SDK’s cookie manager. By default, the token is only added to the cookie store when it's first acquired and when it's refreshed. If the application clears the shared cookie store for any reason, the SDK doesn't automatically add the AWS WAF token back until the next refresh. 

**`WAFConfiguration`**  
Holds the configuration for the implementation of the `WAFTokenProvider`. When you implement this, you provide your protection pack (web ACL)’s integration URL, the domain name to use in the token, and any non-default settings that you want the token provider to use.   
The following list specifies the configuration settings that you can manage in the `WAFConfiguration` object.    
**`applicationIntegrationUrl`**   
The application integration URL. Get this from the AWS WAF console or through the `getWebACL` API call.  
Required: Yes  
Type: App-specific URL. For iOS, see [iOS URL](https://developer.apple.com/documentation/foundation/url). For Android, see [java.net URL](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html).   
**`backgroundRefreshEnabled`**   
Indicates whether you want the token provider to refresh the token in the background. If you set this, the token provider refreshes your tokens in the background according to the configuration settings that govern automatic token refresh activities.   
Required: No  
Type: `Boolean`  
Default value: `TRUE`  
**`domainName`**   
The domain to use in the token, which is used in token acquisition and cookie storage. For example, `example.com` or `aws.amazon.com`. This is usually the host domain of your resource that’s associated with the protection pack (web ACL), where you’ll be sending web requests. For the ACFP managed rule group, `AWSManagedRulesACFPRuleSet`, this will usually be a single domain that matches the domain in the account creation path that you provided in the rule group configuration. For the ATP managed rule group, `AWSManagedRulesATPRuleSet`, this will usually be a single domain that matches the domain in the login path that you provided in the rule group configuration.   
Public suffixes aren't allowed. For example, you can't use `gov.au` or `co.uk` as the token domain.  
The domain must be one that AWS WAF will accept, based on the protected host domain and the protection pack (web ACL)'s token domain list. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).  
Required: Yes  
Type: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
The maximum time in milliseconds to wait before repeating a token refresh after a failed attempt. For each auto-retry for a failed attempt, it will add an exponential backoff up until the given input delay time. This value is used after token retrieval has failed and been retried `maxRetryCount` times.   
Required: No  
Type: `Integer`  
Default value: `5000` (5 seconds)  
Minimum value allowed: `1` (1 millisecond)  
Maximum value allowed: `30000` (30 seconds)  
**`maxRetryCount`**   
The maximum number of retries to perform with exponential backoff when a token is requested.   
Required: No  
Type: `Integer`  
Default value: `Infinity`  
Minimum value allowed: `0`  
Maximum value allowed: `100`  
**`setTokenCookie`**   
Indicates whether you want the SDK’s cookie manager to add a token cookie into requests and in other areas.   
With a `TRUE` value:   
+ The cookie manager adds a token cookie to all requests whose path is under the path specified in `tokenCookiePath`. 
+ The `WAFTokenProvider` operation `loadTokenIntoProvider()` updates the token in the cookie store, in addition to loading it into the token provider.
Required: No  
Type: `Boolean`  
Default value: `TRUE`  
**`tokenCookiePath`**   
Used when `setTokenCookie` is `TRUE`. Indicates the top-level path where you want the SDK’s cookie manager to add a token cookie. The manager adds a token cookie to all requests that you send to this path and to all child paths.   
For example, if you set this to `/web/login`, then the manager includes the token cookie for everything sent to `/web/login` and any of its child paths, like `/web/login/help`. It doesn't include the token for requests sent to other paths, like `/`, `/web`, or `/web/order`.   
Required: No  
Type: `String`  
Default value: `/`  
**`tokenRefreshDelaySec`**   
Used for background refresh. The maximum amount of time in seconds between background token refreshes.  
Required: No  
Type: `Integer`  
Default value: `88`  
Minimum value allowed: `88`  
Maximum value allowed: `300` (5 minutes)

## AWS WAF mobile SDK errors
<a name="waf-mobile-sdk-errors"></a>

This section lists the possible errors for the current AWS WAF mobile SDK version.

**`SdkError`**  
The error type returned when failing to retrieve a token. The Android and iOS SDK have the same error types.  
The AWS WAF mobile SDK has the following error types:    
**`invalidChallenge`**  
This error is returned when the token server returns invalid challenge data, or the response blob is mutated by an attacker.  
**`errorInvokingGetChallengeEndpoint`**  
This error is returned when the token server sends a non-success response code back to the client or when a network error occurs.  
**`invalidVerifyChallengeResponse`**  
This error is returned when there is an error retrieving the `aws-waf-token` from the AWS WAF server's verification response, or the server response was tampered with.  
**`errorInvokingVerifyEndpoint`**  
This error is returned when the client receives a bad response from the AWS WAF server or network error when verifying the solved challenge.  
**`internalError`**  
This error is returned on all other errors that might occur within the SDK itself.

**`socketTimeoutException`**  
This error is often returned when encountering network errors during token retrieval.  
This error might be caused by the following:  
+ Low network bandwidth: Confirm your network connectivity settings
+ Mutated Application Integration URL: Confirm that the integration URL is not modified from what appears on the AWS WAF console

# How the AWS WAF mobile SDK works
<a name="waf-mobile-sdk-how-it-works"></a>

This section explains how the AWS WAF mobile SDK classes, properties, and operations work together.

The mobile SDKs provide you with a configurable token provider that you can use for token retrieval and use. The token provider verifies that the requests that you allow are from legitimate customers. When you send requests to the AWS resources that you protect with AWS WAF, you include the token in a cookie, to validate the request. You can handle the token cookie manually or have the token provider do it for you.

This section covers the interactions between the classes, properties, and methods that are included in the mobile SDK. For the SDK specification, see [AWS WAF mobile SDK specification](waf-mobile-sdk-specification.md). 

## Token retrieval and caching
<a name="waf-mobile-sdk-how-token-basics"></a>

When you create the token provider instance in your mobile app, you configure how you want it to manage tokens and token retrieval. Your main choice is how to maintain valid, unexpired tokens for use in your app’s web requests:
+ **Background refresh enabled** – This is the default. The token provider automatically refreshes the token in the background and caches it. With background refresh enabled, when you call `getToken()`, the operation retrieves the cached token. 

  The token provider performs the token refresh at configurable intervals, so that an unexpired token is always available in the cache while the application is active. Background refresh is paused while your application is in an inactive state. For information about this, see [Retrieving a token following app inactivity](#waf-mobile-sdk-how-back-from-inactive).
+ **Background refresh disabled** – You can disable background token refresh, and then retrieve tokens only on demand. Tokens retrieved on demand aren't cached, and you can retrieve more than one if you want. Each token is independent of any others that you retrieve, and each has its own timestamp that's used to calculate expiration.

  You have the following choices for token retrieval when background refresh is disabled: 
  + **`getToken()`** – When you call `getToken()` with background refresh disabled, the call synchronously retrieves a new token from AWS WAF. This is a potentially blocking call that might affect app responsiveness if you invoke it on the main thread. 
  + **`onTokenReady(WAFTokenResultCallback)`** – This call asynchronously retrieves a new token and then invokes the provided result callback in a background thread when a token is ready. 

### How the token provider retries failed token retrievals
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

The token provider automatically retries token retrieval when retrieval fails. Retries are initially performed using exponential backoff with a starting retry wait time of 100 ms. For information about exponential retries, see [Error retries and exponential backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html).

When the number of retries reaches the configured `maxRetryCount`, the token provider either stops trying or switches to trying every `maxErrorTokenRefreshDelayMsec` milliseconds, depending on the type of token retrieval: 
+ **`onTokenReady()`** – The token provider switches to waiting `maxErrorTokenRefreshDelayMsec` milliseconds between attempts, and continues trying to retrieve the token. 
+ **Background refresh** – The token provider switches to waiting `maxErrorTokenRefreshDelayMsec` milliseconds between attempts, and continues trying to retrieve the token. 
+ **On-demand `getToken()` calls, when background refresh is disabled** – The token provider stops trying to retrieve a token and returns the previous token value, or a null value if there is no previous token. 

## Token retrieval retry scenarios
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

When the token provider tries to retrieve a token, it might result in auto-retries depending on where token retrieval fails in the token acquisition flow. This section lists the possible places where you might see an auto-retry.
+ **Obtaining or verifying the AWS WAF Challenge through /inputs or /verify:**
  + When a request to obtain and verify a AWS WAF challenge is made and fails, it can result in an auto-retry.
  + You might observe auto-retries happening here along with a `socketTimeoutException` error. This can have multiple causes including:
    + Low network bandwidth: Confirm your network connectivity settings
    + Mutated Application Integration URL: Confirm that the integration URL is not modified from what appears on the AWS WAF console
  + The auto-retry count is configurable with the `maxRetryCount()` function
+ **Refreshing the token:**
  + When a request to refresh the token is made through the token handler, it might result in an auto-retry.
  + The auto-retry count here is configurable with the `maxRetryCount()` function.

A configuration with no auto-retries is possible by setting `maxRetryCount(0)`.

## Token immunity time and background refresh
<a name="waf-mobile-sdk-how-token-immunity"></a>

The token immunity time that you configure in the Web ACL is independent of the token refresh interval you set in the AWS WAF mobile SDK. When you enable background refresh, the SDK refreshes the token at the interval you specify using `tokenRefreshDelaySec()`. This can result in multiple valid tokens existing simultaneously, depending on your configured immunity time.

To prevent multiple valid tokens, you can disable background refresh and use the `getToken()` function to manage the token lifecycle in your mobile app.

## Retrieving a token following app inactivity
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

Background refresh is only performed while your app is considered active for your app type: 
+ **iOS** – Background refresh is performed when the app is in the foreground.
+ **Android** – Background refresh is performed when the app isn't closed, whether it's in the foreground or background.

If your app remains in any state that doesn’t support background refresh for longer than your configured `tokenRefreshDelaySec` seconds, the token provider pauses background refresh. For example, for an iOS app, if `tokenRefreshDelaySec` is 300 and the app closes or goes into the background for more than 300 seconds, the token provider stops refreshing the token. When the app returns to an active state, the token provider automatically restarts background refresh. 

When your app comes back to an active state, call `onTokenReady()` so you can be notified when the token provider has retrieved and cached a new token. Don't just call `getToken()`, because the cache might not yet contain a current, valid token. 

## Application Integration URL
<a name="waf-mobile-sdk-application-integration-url"></a>

The AWS WAF mobile SDK application integration URL points to a Web ACL that you've enabled for application integration. This URL routes requests to the correct backend server and associates them with your customer. It doesn't serve as a hard security control, so exposing an integration URL doesn't pose a security risk.

You can technically modify the provided integration URL and still obtain a token. However, we don't recommend this because you might lose visibility into challenge solve rates or encounter token retrieval failures with `socketTimeoutException` errors.

## Dependencies
<a name="waf-mobile-sdk-dependencies"></a>

Each downloadable AWS WAF mobile SDK includes a README file that lists out the dependencies for its specific version of the SDK. Refer to the README for the dependencies for your version of the mobile SDK.

## Obfuscation/ProGuard (Android SDK Only)
<a name="waf-mobile-sdk-obfuscation"></a>

If you use an obfuscation or minification product like ProGuard, you might need to exclude certain namespaces to ensure the mobile SDK works correctly. Check the README for your version of the mobile SDK to find the list of namespaces and exclusion rules.

# Code examples for the AWS WAF mobile SDK
<a name="waf-mobile-sdk-coding-examples"></a>

This section provides code examples for using the mobile SDK. 

## Initializing the token provider and getting tokens
<a name="waf-mobile-sdk-coding-basic"></a>

You initiate your token provider instance using a configuration object. Then you can retrieve tokens using the available operations. The following shows the basic components of the required code.

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
let tokenProvider = WAFTokenProvider(configuration)

//onTokenReady can be add as an observer for UIApplication.willEnterForegroundNotification
self.tokenProvider.onTokenReady() { token, error in
	if let token = token {
	//token available
	}

	if let error = error {
	//error occurred after exhausting all retries
	}
}

//getToken()
let token = tokenProvider.getToken()
```

------
#### [ Android ]

Java example:

```
String applicationIntegrationURL = "protection pack (web ACL) integration URL";
//Or
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");

String domainName = "Domain name";

WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);

// implement a token result callback
WAFTokenResultCallback callback = (wafToken, error) -> {
	if (wafToken != null) {
	// token available
	} else {  
	// error occurred in token refresh  
	}
};

// Add this callback to application creation or activity creation where token will be used
tokenProvider.onTokenReady(callback);

// Once you have token in token result callback
// if background refresh is enabled you can call getToken() from same tokenprovider object
// if background refresh is disabled you can directly call getToken()(blocking call) for new token
WAFToken token = tokenProvider.getToken();
```

Kotlin example:

```
import com.amazonaws.waf.mobilesdk.token.WAFConfiguration
import com.amazonaws.waf.mobilesdk.token.WAFTokenProvider

private lateinit var wafConfiguration: WAFConfiguration
private lateinit var wafTokenProvider: WAFTokenProvider

private val WAF_INTEGRATION_URL = "protection pack (web ACL) integration URL"
private val WAF_DOMAIN_NAME = "Domain name"

fun initWaf() {
	// Initialize the tokenprovider instance
	val applicationIntegrationURL = URL(WAF_INTEGRATION_URL)
	wafConfiguration =
		WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL)
			.domainName(WAF_DOMAIN_NAME).backgroundRefreshEnabled(true).build()
	wafTokenProvider = WAFTokenProvider(getApplication(), wafConfiguration)
	
		// getToken from tokenprovider object
		println("WAF: "+ wafTokenProvider.token.value)
	
		// implement callback for where token will be used
		wafTokenProvider.onTokenReady {
			wafToken, sdkError ->
		run {
			println("WAF Token:" + wafToken.value)
		}
	}
}
```

------

## Allowing the SDK to provide the token cookie in your HTTP requests
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

If `setTokenCookie` is `TRUE`, the token provider includes the token cookie for you in your web requests to all locations under the path that's specified in `tokenCookiePath`. By default,`setTokenCookie` is `TRUE` and `tokenCookiePath` is `/`. 

You can narrow the scope of the requests that include a token cookie by specifying the token cookie path, for example, `/web/login`. If you do this, check that your AWS WAF rules don't inspect for tokens in the requests that you send to other paths. When you use the `AWSManagedRulesACFPRuleSet` rule group, you configure the account registration and creation paths, and the rule group checks for tokens in requests that are sent to those paths. For more information, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md). Similarly, when you use the `AWSManagedRulesATPRuleSet` rule group, you configure the login path, and the rule group checks for tokens in requests that are sent to that path. For more information, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md). 

------
#### [ iOS ]

When `setTokenCookie` is `TRUE`, the token provider stores the AWS WAF token in a `HTTPCookieStorage.shared` and automatically includes the cookie in requests to the domain that you specified in `WAFConfiguration`.

```
let request = URLRequest(url: URL(string: domainEndpointUrl)!)
//The token cookie is set automatically as cookie header
let task = URLSession.shared.dataTask(with: request) { data, urlResponse, error  in
}.resume()
```

------
#### [ Android ]

When `setTokenCookie` is `TRUE`, the token provider stores the AWS WAF token in a `CookieHandler` instance that's shared application wide. The token provider automatically includes the cookie in requests to the domain that you specified in `WAFConfiguration`.

Java example:

```
URL url = new URL("Domain name");
//The token cookie is set automatically as cookie header
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.getResponseCode();
```

Kotlin example:

```
val url = URL("Domain name")
//The token cookie is set automatically as cookie header
val connection = (url.openConnection() as HttpsURLConnection)
connection.responseCode
```

If you already have the `CookieHandler` default instance initialized, the token provider will use it to manage cookies. If not, the token provider will initialize a new `CookieManager` instance with the AWS WAF token and `CookiePolicy.ACCEPT_ORIGINAL_SERVER` and then set this new instance as the default instance in `CookieHandler`.

The following code shows how the SDK initializes the cookie manager and cookie handler when they aren't available in your app. 

Java example:

```
CookieManager cookieManager = (CookieManager) CookieHandler.getDefault();
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = new CookieManager();
	CookieHandler.setDefault(cookieManager);
}
```

Kotlin example:

```
var cookieManager = CookieHandler.getDefault() as? CookieManager
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = CookieManager()
	CookieHandler.setDefault(cookieManager)
}
```

------

## Manually providing the token cookie in your HTTP requests
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

If you set `setTokenCookie` to `FALSE`, then you need to provide the token cookie manually, as a Cookie HTTP request header, in your requests to your protected endpoint. The following code shows how to do this.

------
#### [ iOS ]

```
var request = URLRequest(url: wafProtectedEndpoint)
request.setValue("aws-waf-token=token from token provider", forHTTPHeaderField: "Cookie")
request.httpShouldHandleCookies = true
URLSession.shared.dataTask(with: request) { data, response, error in }
```

------
#### [ Android ]

Java example:

```
URL url = new URL("Domain name");
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
String wafTokenCookie = "aws-waf-token=token from token provider";
connection.setRequestProperty("Cookie", wafTokenCookie);
connection.getInputStream();
```

Kotlin example:

```
val url = URL("Domain name")
val connection = (url.openConnection() as HttpsURLConnection)
val wafTokenCookie = "aws-waf-token=token from token provider"
connection.setRequestProperty("Cookie", wafTokenCookie)
connection.inputStream
```

------

# CAPTCHA and Challenge in AWS WAF
<a name="waf-captcha-and-challenge"></a>

This section explains how CAPTCHA and Challenge work with AWS WAF.

You can configure your AWS WAF rules to run a CAPTCHA or Challenge action against web requests that match your rule's inspection criteria. You can also program your JavaScript client applications to run CAPTCHA puzzles and browser challenges locally. 

CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. 
+ **CAPTCHA** – Requires the end user to solve a CAPTCHA puzzle to prove that a human being is sending the request. CAPTCHA puzzles are intended to be fairly easy and quick for humans to complete successfully and hard for computers to either complete successfully or to randomly complete with any meaningful rate of success. 

  In protection pack (web ACL) rules, CAPTCHA is commonly used when a Block action would stop too many legitimate requests, but letting all traffic through would result in unacceptably high levels of unwanted requests, such as from bots. For information about the rule action behavior, see [How the AWS WAF CAPTCHA and Challenge rule actions work](waf-captcha-and-challenge-how-it-works.md).

  You can also program a CAPTCHA puzzle implementation in your client application integration APIs. When you do this, you can customize the behavior and placement of the puzzle in your client application. For more information, see [Client application integrations in AWS WAF](waf-application-integration.md). 
+ **Challenge** – Runs a silent challenge that requires the client session to verify that it's a browser, and not a bot. The verification runs in the background without involving the end user. This is a good option for verifying clients that you suspect of being invalid without negatively impacting the end user experience with a CAPTCHA puzzle. For information about the rule action behavior, see [How the AWS WAF CAPTCHA and Challenge rule actions work](waf-captcha-and-challenge-how-it-works.md).

  The Challenge rule action is similar to the challenge run by the client intelligent threat integration APIs, described at [Client application integrations in AWS WAF](waf-application-integration.md).

**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

For descriptions of all of the rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md). 

**Topics**
+ [

# AWS WAF CAPTCHA puzzles
](waf-captcha-puzzle.md)
+ [

# How the AWS WAF CAPTCHA and Challenge rule actions work
](waf-captcha-and-challenge-how-it-works.md)
+ [

# Best practices for using the CAPTCHA and Challenge actions
](waf-captcha-and-challenge-best-practices.md)

# AWS WAF CAPTCHA puzzles
<a name="waf-captcha-puzzle"></a>

This section explains the features and functionality of the AWS WAF CAPTCHA puzzle.

AWS WAF provides standard CAPTCHA functionality that challenges users to confirm that they are human beings. CAPTCHA stands for Completely Automated Public Turing test to tell Computers and Humans Apart. CAPTCHA puzzles are designed to verify that a human is sending requests and to prevent activity like web scraping, credential stuffing, and spam. CAPTCHA puzzles can't weed out all unwanted requests. Many puzzles have been solved using machine learning and artificial intelligence. In an effort to circumvent CAPTCHA, some organizations supplement automated techniques with human intervention. In spite of this, CAPTCHA continues to be a useful tool to prevent less sophisticated bot traffic and to increase the resources required for large-scale operations. 

AWS WAF randomly generates its CAPTCHA puzzles and rotates through them to ensure that users are presented with unique challenges. AWS WAF regularly adds new types and styles of puzzles to remain effective against automation techniques. In addition to the puzzles, the AWS WAF CAPTCHA script gathers data about the client to ensure that the task is being completed by a human and to prevent replay attacks. 

Each CAPTCHA puzzle includes a standard set of controls for the end user to request a new puzzle, switch between audio and visual puzzles, access additional instructions, and submit a puzzle solution. All puzzles include support for screen readers, keyboard controls, and contrasting colors. 

The AWS WAF CAPTCHA puzzles meet the requirements of the Web Content Accessibility Guidelines (WCAG). For information, see [Web Content Accessibility Guidelines (WCAG) Overview](https://www.w3.org/WAI/standards-guidelines/wcag/) at the World Wide Web Consortium (W3C) website.

**Topics**
+ [

# CAPTCHA puzzle language support
](waf-captcha-puzzle-language-support.md)
+ [

# CAPTCHA puzzle examples
](waf-captcha-puzzle-examples.md)

# CAPTCHA puzzle language support
<a name="waf-captcha-puzzle-language-support"></a>

This section lists what languages are supported in AWS WAF CAPTCHA puzzles.

The CAPTCHA puzzle starts with written instructions in the client browser language or, if the browser language is unsupported, in English. The puzzle provides alternate language options through a dropdown menu.

The user can switch to audio instructions by selecting the headphone icon at the bottom of the page. The audio version of the puzzle provides spoken instructions about text that the user should type into a text box, overlaid by background noise. 

The following table lists the languages that you can select for the written instructions in a CAPTCHA puzzle and the audio support for each selection. 


**AWS WAF CAPTCHA puzzle supported languages**  

| Written instructions support | Locale code | Audio instructions support | 
| --- | --- | --- | 
|  Arabic  |  ar-SA  |  Arabic  | 
|  Simplified Chinese  |  zh-CN  |  Audio in English  | 
|  Dutch  |  nl-NL  |  Dutch  | 
|  English  |  en-US  |  English  | 
|  French  |  fr-FR  |  French  | 
|  German  |  de-DE  |  German  | 
|  Italian  |  it-IT  |  Italian  | 
|  Japanese  |  ja-JP  |  Audio in English  | 
|  Brazilian Portuguese  |  pt-BR  |  Brazilian Portuguese  | 
|  Spanish  |  es-ES  |  Spanish  | 
|  Turkish  |  tr-TR  |  Turkish  | 

# CAPTCHA puzzle examples
<a name="waf-captcha-puzzle-examples"></a>

A typical visual CAPTCHA puzzle requires interaction to show that the user can comprehend and interact with one or more images. 

The following screenshot shows an example of a picture grid puzzle. This puzzle requires you to select all of the pictures in the grid that include a specific type of object. 

![\[A screen contains the title "Let's confirm you are human" and the text "Choose all the chairs". Below the text is a 3x3 grid of images, some of which contain chairs and others that contain non-chair objects, like beds and windows. At the bottom of the screen are options to load a different puzzle, toggle the information box into and out of view, toggle to an audio puzzle, and change the language. Also at the bottom is the button "Confirm".\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/CAPTCHAPuzzleGrid.png)


An audio puzzle provides background noise overlaid with spoken instructions about text that the user should type into a text box.

The following screenshot shows the display for the audio puzzle choice. 

![\[A screen contains the title "Solve the puzzle" and the text "Click play to listen to instructions". Below the text is an image that shows a Play button. Below the image is the text "Keyboard audio toggle: alt + space". Below is a title "Enter your response" with a text entry box below it. An open information box has the text "Solve by listening to the recording and typing your answer into the text box." At the bottom of the screen are options to load a different puzzle, toggle the information box into and out of view, and toggle to a visual puzzle. Also at the bottom is the button "Submit".\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/CAPTCHAPuzzleAudio.png)




# How the AWS WAF CAPTCHA and Challenge rule actions work
<a name="waf-captcha-and-challenge-how-it-works"></a>

This section explains how CAPTCHA and Challenge work.

AWS WAF CAPTCHA and Challenge are standard rule actions, so they're relatively easy to implement. To use either of them, you create the inspection criteria for your rule that identifies the requests that you want to inspect, and then specify one of the two rule actions. For general information about rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md).

In addition to implementing silent challenges and CAPTCHA puzzles from the server side, you can integrate silent challenges in your JavaScript and iOS and Android client applications, and you can render CAPTCHA puzzles in your JavaScript clients. These integrations allow you to provide your end users with better performance and CAPTCHA puzzle experiences, and they can reduce costs associated with using the rule actions and the intelligent threat mitigation rule groups. For more information about these options, see [Client application integrations in AWS WAF](waf-application-integration.md). For pricing information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**Topics**
+ [

# CAPTCHA and Challenge action behavior
](waf-captcha-and-challenge-actions.md)
+ [

# CAPTCHA and Challenge actions in the logs and metrics
](waf-captcha-and-challenge-logs-metrics.md)

# CAPTCHA and Challenge action behavior
<a name="waf-captcha-and-challenge-actions"></a>

This section explains what the CAPTCHA and Challenge actions do.

When a web request matches the inspection criteria of a rule with CAPTCHA or Challenge action, AWS WAF determines how to handle the request according to the state of its token and immunity time configuration. AWS WAF also considers whether the request can handle the CAPTCHA puzzle or challenge script interstitials. The scripts are designed to be handled as HTML content, and they can only be handled properly by a client that's expecting HTML content. 

**Note**  
You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

**How the action handles the web request**  
AWS WAF applies the CAPTCHA or Challenge action to a web request as follows:
+ **Valid token** – AWS WAF handles this similar to a Count action. AWS WAF applies any labels and request customizations that you've configured for the rule action, and then continues evaluating the request using the remaining rules in the protection pack (web ACL). 
+ **Missing, invalid, or expired token** – AWS WAF discontinues the protection pack (web ACL) evaluation of the request and blocks it from going to its intended destination. 

  AWS WAF generates a response that it sends back to the client, according to the rule action type: 
  + **Challenge** – AWS WAF includes the following in the response:
    + The header `x-amzn-waf-action` with a value of `challenge`.
**Note**  
For Javascript applications running in the client browser, this header is only available within the application's domain. The header isn't available for cross-domain retrieval. For details, see the section that follows.
    + The HTTP status code `202 Request Accepted`.
    + If the request contains an `Accept` header with a value of `text/html`, the response includes a JavaScript page interstitial with a challenge script.
  + **CAPTCHA** – AWS WAF includes the following in the response:
    + The header `x-amzn-waf-action` with a value of `captcha`.
**Note**  
For Javascript applications running in the client browser, this header is only available within the application's domain. The header isn't available for cross-domain retrieval. For details, see the section that follows.
    + The HTTP status code `405 Method Not Allowed`.
    + If the request contains an `Accept` header with a value of `text/html`, the response includes a JavaScript page interstitial with a CAPTCHA script. 

To configure the timing of token expiration at the protection pack (web ACL) or rule level, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).

**Headers are unavailable to JavaScript applications that run in the client browser**  
When AWS WAF responds to a client request with a CAPTCHA or challenge response, it doesn't include cross-origin resource sharing (CORS) headers. CORS headers are a set of access control headers that tell the client web browser which domains, HTTP methods, and HTTP headers can be used by JavaScript applications. Without CORS headers, JavaScript applications running in a client browser are not granted access to HTTP headers and so are unable to read the `x-amzn-waf-action` header that's provided in the CAPTCHA and Challenge responses. 

**What the challenge and CAPTCHA interstitials do**  
When a challenge interstitial runs, after the client responds successfully, if it doesn't already have a token, the interstitial initializes one for it. Then it updates the token with the challenge solve timestamp.

When a CAPTCHA interstitial runs, if the client doesn't have a token yet, the CAPTCHA interstitial invokes the challenge script first to challenge the browser and initialize the token. Then the interstitial runs its CAPTCHA puzzle. When the end user successfully completes the puzzle, the interstitial updates the token with the CAPTCHA solve timestamp. 

In either case, after the client responds successfully and the script updates the token, the script resubmits the original web request using the updated token. 

You can configure how AWS WAF handles tokens. For information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md).

# CAPTCHA and Challenge actions in the logs and metrics
<a name="waf-captcha-and-challenge-logs-metrics"></a>

This section explains how AWS WAF handles logging and metrics for the CAPTCHA and Challenge actions.

The CAPTCHA and Challenge actions can be non-terminating, like Count, or terminating, like Block. The outcome depends on whether the request has a valid token with an unexpired timestamp for the action type. 
+ **Valid token** – When the action finds a valid token and doesn't block the request, AWS WAF captures metrics and logs as follows:
  + Increments the metrics for either `CaptchaRequests` and `RequestsWithValidCaptchaToken` or `ChallengeRequests` and `RequestsWithValidChallengeToken`. 
  + Logs the match as a `nonTerminatingMatchingRules` entry with action of CAPTCHA or Challenge. The following listing shows the section of a log for this type of match with the CAPTCHA action.

    ```
        "nonTerminatingMatchingRules": [
        {
          "ruleId": "captcha-rule",
          "action": "CAPTCHA",
          "ruleMatchDetails": [],
          "captchaResponse": {
            "responseCode": 0,
            "solveTimestamp": 1632420429
          }
        }
      ]
    ```
+ **Missing, invalid, or expired token** – When the action blocks the request due to a missing or invalid token, AWS WAF captures metrics and logs as follows:
  + Increments the metric for `CaptchaRequests` or `ChallengeRequests`. 
  + Logs the match as a `CaptchaResponse` entry with HTTP `405` status code or as a `ChallengeResponse` entry with HTTP `202` status code. The log indicates whether the request was missing the token or had an expired timestamp. The log also indicates whether AWS WAF sent a CAPTCHA interstitial page to the client or a silent challenge to the client browser. The following listing shows the sections of a log for this type of match with the CAPTCHA action.

    ```
        "terminatingRuleId": "captcha-rule",
        "terminatingRuleType": "REGULAR",
        "action": "CAPTCHA",
        "terminatingRuleMatchDetails": [],
        ...
        "responseCodeSent": 405,
        ...
        "captchaResponse": {
          "responseCode": 405,
          "solveTimestamp": 0,
          "failureReason": "TOKEN_MISSING"
        }
    ```

For information about the AWS WAF logs, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

For information about AWS WAF metrics, see [AWS WAF metrics and dimensions](waf-metrics.md).

For general information about rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md).

**Requests with no token seem to show up twice in logs and metrics**  
Based on the [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md) and the logging and metrics described in this section, a request with no token will generally be represented twice in the logs and metrics. This is because the one intended request is actually sent twice by the client.
+ The first request, with no token, receives the logging and metrics handling described above for missing, invalid, or expired token. The CAPTCHA or Challenge action terminates this first request, and then responds back to the client with either a silent challenge or CAPTCHA puzzle. 
+ The client evaluates the challenge or puzzle and, if the client browser or end user responds successfully, sends the request a second time with the newly acquired token. This second request receives the logging and metrics handling described above for a request with a valid token. 

# Best practices for using the CAPTCHA and Challenge actions
<a name="waf-captcha-and-challenge-best-practices"></a>

Follow the guidance in this section to plan and implement AWS WAF CAPTCHA or challenge.

**Plan your CAPTCHA and challenge implementation**  
Determine where to place CAPTCHA puzzles or silent challenges based on your website usage, the sensitivity of the data that you want to protect, and the type of requests. Select the requests where you'll apply CAPTCHA so that you present the puzzles as needed, but avoid presenting them where they wouldn't be useful and might degrade the user experience. Use the Challenge action to run silent challenges that have less impact on the end user, but still help verify that the request is coming from a JavaScript enabled browser. 

CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. 

**Decide where to run CAPTCHA puzzles and silent challenges on your clients**  
Identify requests that you don't want to have impacted by CAPTCHA, for example, requests for CSS or images. Use CAPTCHA only when necessary. For example, if you plan to have a CAPTCHA check at login, and the user is always taken directly from the login to another screen, requiring a CAPTCHA check at the second screen would probably not be needed and might degrade your end user experience. 

Configure your Challenge and CAPTCHA use so that AWS WAF only sends CAPTCHA puzzles and silent challenges in response to `GET` `text/html` requests. You can't run either the puzzle or the challenge in response to `POST` requests, Cross-Origin Resource Sharing (CORS) preflight `OPTIONS` requests, or any other non-`GET` request types. Browser behavior for other request types can vary and might not be able to handle the interstitials properly. 

It's possible for a client to accept HTML but still not be able to handle the CAPTCHA or challenge interstitial. For example, a widget on a webpage with a small iFrame might accept HTML but not be able to display a CAPTCHA or process it. Avoid placing the rule actions for these types of requests, the same as for requests that don't accept HTML.

**Use CAPTCHA or Challenge to verify prior token acquisition**  
You can use the rule actions solely to verify the existence of a valid token, at locations where legitimate users should always have one. In these situations, it doesn't matter whether the request can handle the interstitials. 

For example, if you implement the JavaScript client application CAPTCHA API, and run the CAPTCHA puzzle on the client immediately before you send the first request to your protected endpoint, your first request should always include a token that's valid for both challenge and CAPTCHA. For information about JavaScript client application integration, see [AWS WAF JavaScript integrations](waf-javascript-api.md). 

For this situation, in your protection pack (web ACL), you can add a rule that matches against this first call and configure it with the Challenge or CAPTCHA rule action. When the rule matches for a legitimate end user and browser, the action will find a valid token, and therefore will not block the request or send a challenge or CAPTCHA puzzle in response. For more information about how the rule actions work, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md).

**Protect your sensitive non-HTML data with CAPTCHA and Challenge**  
You can use CAPTCHA and Challenge protections for sensitive non-HTML data, like APIs, with the following approach. 

1. Identify requests that take HTML responses and that are run in close proximity to the requests for your sensitive, non-HTML data. 

1. Write CAPTCHA or Challenge rules that match against the requests for HTML and that match against the requests for your sensitive data. 

1. Tune your CAPTCHA and Challenge immunity time settings so that, for normal user interactions, the tokens that clients obtain from the HTML requests are available and unexpired in their requests for your sensitive data. For tuning information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).

When a request for your sensitive data matches a CAPTCHA or Challenge rule, it won't be blocked if the client still has a valid token from the prior puzzle or challenge. If the token isn't available or the timestamp is expired, the request to access your sensitive data will fail. For more information about how the rule actions work, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md).

**Use CAPTCHA and Challenge to tune your existing rules**  
Review your existing rules, to see if you want to alter or add to them. The following are some common scenarios to consider. 
+ If you have a rate-based rule that blocks traffic, but you keep the rate limit relatively high to avoid blocking legitimate users, consider adding a second rate-based rule after the blocking rule. Give the second rule a lower limit than the blocking rule and set the rule action to CAPTCHA or Challenge. The blocking rule will still block requests that are coming at too high a rate, and the new rule will block most automated traffic at an even lower rate. For information about rate-based rules, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md).
+ If you have a managed rule group that blocks requests, you can switch the behavior for some or all of the rules from Block to CAPTCHA or Challenge. To do this, in the managed rule group configuration, override the rule action setting. For information about overriding rule actions, see [Rule group rule action overrides](web-acl-rule-group-override-options.md#web-acl-rule-group-override-options-rules). 

**Test your CAPTCHA and challenge implementations before you deploy them**  
As for all new functionality, follow the guidance at [Testing and tuning your AWS WAF protections](web-acl-testing.md).

During testing, review your token timestamp expiration requirements and set your web ACL and rule level immunity time configurations so that you achieve a good balance between controlling access to your website and providing a good experience for your customers. For information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).

# Data protection and logging for AWS WAF protection pack (web ACL) traffic
<a name="waf-data-protection-and-logging"></a>

This section explains the data logging, collection, and protection options that you can use with AWS WAF. The options are the following: 
+ **Logging** – You can configure your protection pack (web ACL) to send logs for web request traffic to a logging destination of your choice. You can configure field redaction and filtering for this choice. Logging uses the data that's available after any data protection setting are applied. 

  For information about this option, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
+ **Request sampling** – You can configure your protection pack (web ACL) to sample the web requests that it evaluates, to get an idea of the type of traffic that your application is receiving. Request sampling uses the data that's available after any data protection settings are applied. 

  For information about this option, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 
+ **Amazon Security Lake** – You can configure Security Lake to collect protection pack (web ACL) data. Security Lake collects log and event data from various AWS sources for normalization, analysis, and management. Security Lake collects from the data that's available after any data protection settings are applied. 

  For information about this option, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 

  AWS WAF doesn't charge you for using this option. For pricing information, see [Security Lake Pricing](https://aws.amazon.com/security-lake/pricing/) and [How Security Lake pricing is determined](https://docs.aws.amazon.com/security-lake/latest/userguide/estimating-costs.html) in the *Amazon Security Lake user guide*.
+ **Data protection** – You can configure data protections for web traffic data at two levels: 
  + **Data protection for the protection pack (web ACL)** – You can configure data protection for each protection pack (web ACL), which enables you to substitute certain web traffic data with static strings or cryptographic hashing. Data protection at this level can be configured centrally, and applies across all logging and data collection options.

    For information about this option, see [Data protection](data-protection-masking.md). 
  + **Logging redaction and filtering** – For logging only, you can configure some of the web traffic data for redaction from the logs, and you can filter the data that you log. This option is in addition to any data protection setting you've configured, and it only affects the data that AWS WAF sends to the configured logging destination. 

**Topics**
+ [

# Logging AWS WAF protection pack (web ACL) traffic
](logging.md)
+ [

# Data protection
](data-protection-masking.md)

# Logging AWS WAF protection pack (web ACL) traffic
<a name="logging"></a>

This section explains the logging options for your AWS WAF protection packs (web ACLs). 

You can enable logging to get detailed information about traffic that is analyzed by your web ACL. Logged information includes the time that AWS WAF received a web request from your AWS resource, detailed information about the request, and details about the rules that the request matched. You can send protection pack (web ACL) logs to an Amazon CloudWatch Logs log group, an Amazon Simple Storage Service (Amazon S3) bucket, or an Amazon Data Firehose delivery stream.

In addition to logs that you can enable for your protection packs (web ACLs), AWS also uses service logs of website or application traffic processed by AWS WAF to provide support for and protect the security of AWS customers and services.

**Note**  
The protection pack (web ACL) logging configuration only affects the AWS WAF logs. In particular, the redacted fields configuration for logging has no impact on request sampling or Security Lake data collection. You can exclude fields from collection or sampling by configuring protection pack (web ACL) data protection. Other than data protection, Security Lake data collection is configured entirely through the Security Lake service. 

**Topics**
+ [

# Pricing for logging protection pack (web ACL) traffic information
](logging-pricing.md)
+ [

# AWS WAF logging destinations
](logging-destinations.md)
+ [

# Configuring logging for a protection pack (web ACL)
](logging-management-configure.md)
+ [

# Finding your protection pack (web ACL) records
](logging-management.md)
+ [

# Log fields for protection pack (web ACL) traffic
](logging-fields.md)
+ [

# Log examples for protection pack (web ACL) traffic
](logging-examples.md)

**Other data collection and analysis options**  
In addition to logging, you can enable the following options for data collection and analysis: 
+ **Amazon Security Lake** – You can configure Security Lake to collect protection pack (web ACL) data. Security Lake collects log and event data from various sources for normalization, analysis, and management. For information about this option, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 

  AWS WAF doesn't charge you for using this option. For pricing information, see [Security Lake Pricing](https://aws.amazon.com/security-lake/pricing/) and [How Security Lake pricing is determined](https://docs.aws.amazon.com/security-lake/latest/userguide/estimating-costs.html) in the *Amazon Security Lake user guide*. 
+ **Request sampling** – You can configure your protection pack (web ACL) to sample the web requests that it evaluates, to get an idea of the type of traffic that your application is receiving. For information about this option, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

# Pricing for logging protection pack (web ACL) traffic information
<a name="logging-pricing"></a>

This section explains the pricing considerations for using protection pack (web ACL) traffic logs.

You are charged for logging protection pack (web ACL) traffic information according to the costs associated with each log destination type. These charges are in addition to the charges for using AWS WAF. Your costs can vary depending on factors such as the destination type that you choose and the amount of data that you log. 

The following provides links to the pricing information for each logging destination type:
+ **CloudWatch Logs** – The charges are for vended log delivery. See [Amazon CloudWatch Logs Pricing](https://aws.amazon.com/cloudwatch/pricing/). Under **Paid Tier**, choose the **Logs** tab, and then under **Vended Logs**, see the information for **Delivery to CloudWatch Logs**.
+ **Amazon S3 buckets** – The Amazon S3 charges are the combined charges for CloudWatch Logs vended log delivery to the Amazon S3 buckets and for using Amazon S3. 
  + For Amazon S3, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/). 
  + For CloudWatch Logs vended log delivery to the Amazon S3, see [Amazon CloudWatch Logs Pricing](https://aws.amazon.com/cloudwatch/pricing/). Under **Paid Tier**, choose the **Logs** tab, and then under **Vended Logs**, see the information for **Delivery to S3**
+ **Firehose** – See [Amazon Data Firehose Pricing](https://aws.amazon.com/kinesis/data-firehose/pricing/).

For information about AWS WAF pricing, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). 

# AWS WAF logging destinations
<a name="logging-destinations"></a>

This section describes the logging options that you can choose from for your AWS WAF logs. Each section provides guidance for configuring logging including information about any behavior that's specific to the destination type. After you've configured the logging destination, you can provide its specifications to your protection pack (web ACL) logging configuration to start logging to it.

**Topics**
+ [CloudWatch Logs](logging-cw-logs.md)
+ [Amazon S3](logging-s3.md)
+ [Firehose](logging-kinesis.md)

# Sending protection pack (web ACL) traffic logs to a Amazon CloudWatch Logs log group
<a name="logging-cw-logs"></a>

This topic provides information for sending your protection pack (web ACL) traffic logs to a CloudWatch Logs log group. 

**Note**  
You are charged for logging in addition to the charges for using AWS WAF. For information, see [Pricing for logging protection pack (web ACL) traffic information](logging-pricing.md).

To send logs to Amazon CloudWatch Logs, you create a CloudWatch Logs log group. When you enable logging in AWS WAF, you provide the log group ARN. After you enable logging for your protection pack (web ACL), AWS WAF delivers logs to the CloudWatch Logs log group in log streams. 

When you use CloudWatch Logs, you can explore the logs for your protection pack (web ACL) in the AWS WAF console. In your protection pack (web ACL) page, select the tab **Logging insights**. This option is in addition to the logging insights that are provided for CloudWatch Logs through the CloudWatch console. 

Configure the log group for AWS WAF protection pack (web ACL) logs in the same Region as the protection pack (web ACL) and using the same account as you use to manage the protection pack (web ACL). For information about configuring a CloudWatch Logs log group, see [Working with Log Groups and Log Streams](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).

## Quotas for CloudWatch Logs log groups
<a name="logging-cw-logs-quotas"></a>

CloudWatch Logs has a default maximum quota for throughput, shared across all log groups within a region, which you can request to increase. If your logging requirements are too high for the current throughput setting, you'll see throttling metrics for `PutLogEvents` for your account. To view the limit in the Service Quotas console and request an increase, see the [CloudWatch Logs PutLogEvents quota](https://console.aws.amazon.com/servicequotas/home/services/logs/quotas/L-7E1FAE88).

## Log group naming
<a name="logging-cw-logs-naming"></a>

Your log group names must start with `aws-waf-logs-` and can end with any suffix you like, for example, `aws-waf-logs-testLogGroup2`.

The resulting ARN format is as follows: 

```
arn:aws:logs:Region:account-id:log-group:aws-waf-logs-log-group-suffix
```

The log streams have the following naming format: 

```
Region_web-acl-name_log-stream-number
```

The following shows an example log stream for protection pack (web ACL) `TestWebACL` in Region `us-east-1`. 

```
us-east-1_TestWebACL_0
```

## Permissions required to publish logs to CloudWatch Logs
<a name="logging-cw-logs-permissions"></a>

Configuring protection pack (web ACL) traffic logging for a CloudWatch Logs log group requires the permissions settings described in this section. The permissions are set for you when you use one of the AWS WAF full access managed policies, `AWSWAFConsoleFullAccess` or `AWSWAFFullAccess`. If you want to manage finer-grained access to your logging and AWS WAF resources, you can set the permissions yourself. For information about managing permissions, see [Access management for AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*. For information about the AWS WAF managed policies, see [AWS managed policies for AWS WAF](security-iam-awsmanpol.md). 

These permissions allow you to change the protection pack (web ACL) logging configuration, to configure log delivery for CloudWatch Logs, and to retrieve information about your log group. These permissions must be attached to the user that you use to manage AWS WAF. 

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "wafv2:PutLoggingConfiguration",
                "wafv2:DeleteLoggingConfiguration"
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow",
            "Sid": "LoggingConfigurationAPI"
        },
        {
            "Sid": "WebACLLoggingCWL",
            "Action": [
                "logs:CreateLogDelivery",
                "logs:DeleteLogDelivery",
                "logs:PutResourcePolicy",
                "logs:DescribeResourcePolicies",
                "logs:DescribeLogGroups"
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow"
        }
    ]
}
```

------

When actions are permitted on all AWS resources, it's indicated in the policy with a `"Resource"` setting of `"*"`. This means that the actions are permitted on all AWS resources *that each action supports*. For example, the action `wafv2:PutLoggingConfiguration` is supported only for `wafv2` logging configuration resources. 

# Sending protection pack (web ACL) traffic logs to an Amazon Simple Storage Service bucket
<a name="logging-s3"></a>

This topic provides information for sending your protection pack (web ACL) traffic logs to an Amazon S3 bucket. 

**Note**  
You are charged for logging in addition to the charges for using AWS WAF. For information, see [Pricing for logging protection pack (web ACL) traffic information](logging-pricing.md).

To send your protection pack (web ACL) traffic logs to Amazon S3, you set up an Amazon S3 bucket from the same account as you use to manage the protection pack (web ACL), and you name the bucket starting with `aws-waf-logs-`. When you enable logging in AWS WAF, you provide the bucket name. For information about creating a logging bucket, see [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service User Guide*.

You can access and analyze your Amazon S3 logs using the Amazon Athena interactive query service. Athena makes it easy to analyze data directly in Amazon S3 using standard SQL. With a few actions in the AWS Management Console, you can point Athena at data stored in Amazon S3 and quickly begin using standard SQL to run ad-hoc queries and get results. For more information, see [Querying AWS WAF logs](https://docs.aws.amazon.com/athena/latest/ug/waf-logs.html) in the *Amazon Athena user guide*. For additional sample Amazon Athena queries, see [aws-samples/waf-log-sample-athena-queries](https://github.com/aws-samples/waf-log-sample-athena-queries) on the GitHub website.

**Note**  
AWS WAF supports encryption with Amazon S3 buckets for key type Amazon S3 key (SSE-S3) and for AWS Key Management Service (SSE-KMS) AWS KMS keys. AWS WAF doesn't support encryption for AWS Key Management Service keys that are managed by AWS.

Log files from your protection pack (web ACL) are published to the Amazon S3 bucket at 5-minute intervals. Each log file contains log records for the traffic recorded in the previous 5 minutes.

The maximum file size for a log file is 75 MB. If the log file reaches the file size limit within the 5-minute period, the log stops adding records to it, publishes it to the Amazon S3 bucket, and then creates a new log file.

The log files are compressed. If you open the files using the Amazon S3 console, Amazon S3 decompresses the log records and displays them. If you download the log files, you must decompress them to view the records.

A single log file contains interleaved entries with multiple records. To see all the log files for a protection pack (web ACL), look for entries aggregated by the protection pack (web ACL) name, Region, and your account ID.

## Naming requirements and syntax
<a name="logging-s3-naming"></a>

Bucket names for AWS WAF logging must start with `aws-waf-logs-` and can end with any suffix you want. For example, `aws-waf-logs-LOGGING-BUCKET-SUFFIX`. 

**Bucket location**  
The bucket locations use the following syntax: 

```
s3://aws-waf-logs-LOGGING-BUCKET-SUFFIX/
```

**Bucket ARN**  
The format of the bucket Amazon Resource Name (ARN) is as follows: 

```
arn:aws:s3:::aws-waf-logs-LOGGING-BUCKET-SUFFIX
```

**Bucket locations with prefixes**  
If you use prefixes in your object keys name to organize the data that you store in your buckets, you can provide your prefixes in your logging bucket names.

**Note**  
This option is not available through the console. Use the AWS WAF APIs, CLI, or AWS CloudFormation.

For information about using prefixes in Amazon S3, see [Organizing objects using prefixes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html) in the *Amazon Simple Storage Service User Guide*. 

The bucket locations with prefixes use the following syntax: 

```
s3://aws-waf-logs-LOGGING-BUCKET-SUFFIX/KEY-NAME-PREFIX/
```

**Bucket folders and file names**  
Inside your buckets, and following any prefixes that you provide, your AWS WAF logs are written under a folder structure that's determined by your account ID, the Region, the protection pack (web ACL) name, and the date and time. 

```
AWSLogs/account-id/WAFLogs/Region/web-acl-name/YYYY/MM/dd/HH/mm
```

Inside the folders, the log file names follow a similar format: 

```
account-id_waflogs_Region_web-acl-name_timestamp_hash.log.gz
```

The time specifications used in the folder structure and in the log file name adhere to the timestamp format specification `YYYYMMddTHHmmZ`.

The following shows an example log file in an Amazon S3 bucket for a bucket named `aws-waf-logs-LOGGING-BUCKET-SUFFIX`. The AWS account is `11111111111`. The protection pack (web ACL) is `TEST-WEBACL` and the Region is `us-east-1`.

```
s3://aws-waf-logs-LOGGING-BUCKET-SUFFIX/AWSLogs/11111111111/WAFLogs/us-east-1/TEST-WEBACL/2021/10/28/19/50/11111111111_waflogs_us-east-1_TEST-WEBACL_20211028T1950Z_e0ca43b5.log.gz
```

**Note**  
Your bucket names for AWS WAF logging must start with `aws-waf-logs-` and can end with any suffix you want. 

## Permissions required to publish logs to Amazon S3
<a name="logging-s3-permissions"></a>

Configuring protection pack (web ACL) traffic logging for an Amazon S3 bucket requires the following permissions settings. These permissions are set for you when you use one of the AWS WAF full access managed policies, `AWSWAFConsoleFullAccess` or `AWSWAFFullAccess`. If you want to further manage access to your logging and AWS WAF resources, you can set these permissions yourself. For information about managing permissions, see [Access management for AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*. For information about the AWS WAF managed policies, see [AWS managed policies for AWS WAF](security-iam-awsmanpol.md). 

The following permissions allow you to change the protection pack (web ACL) logging configuration and to configure log delivery to your Amazon S3 bucket. These permissions must be attached to the user that you use to manage AWS WAF. 

**Note**  
When you set the permissions listed below, you might see errors in your AWS CloudTrail logs that indicate access denied, but the permissions are correct for AWS WAF logging. 

------
#### [ JSON ]

****  

```
{
   "Version":"2012-10-17",		 	 	 
   "Statement":[
      {
         "Action":[
            "wafv2:PutLoggingConfiguration",
            "wafv2:DeleteLoggingConfiguration"
         ],
         "Resource":[
            "*"
         ],
         "Effect":"Allow",
         "Sid":"LoggingConfigurationAPI"
      },
    {                                                                                                                                                                
       "Sid":"WebACLLogDelivery",                                                                                                                                    
       "Action":[                                                                                                                                                    
          "logs:CreateLogDelivery",                                                                                                                                  
          "logs:DeleteLogDelivery"                                                                                                                                   
       ],                                                                                                                                                            
       "Resource": "*",                                                                                                                                              
       "Effect":"Allow"                                                                                                                                              
    },  
      {
         "Sid":"WebACLLoggingS3",
         "Action":[
            "s3:PutBucketPolicy",
            "s3:GetBucketPolicy"
         ],
         "Resource": [
         "arn:aws:s3:::aws-waf-logs-amzn-s3-demo-destination-bucket-suffix"
         ],
         "Effect":"Allow"
      }
   ]
}
```

------

When actions are permitted on all AWS resources, it's indicated in the policy with a `"Resource"` setting of `"*"`. This means that the actions are permitted on all AWS resources *that each action supports*. For example, the action `wafv2:PutLoggingConfiguration` is supported only for `wafv2` logging configuration resources. 

By default, Amazon S3 buckets and the objects that they contain are private. Only the bucket owner can access the bucket and the objects stored in it. The bucket owner, however, can grant access to other resources and users by writing an access policy.

If the user creating the log owns the bucket, the service automatically attaches the following policy to the bucket to give the log permission to publish logs to it: 

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AWSLogDeliveryWrite",
      "Effect": "Allow",
      "Principal": {
        "Service": "delivery.logs.amazonaws.com"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::aws-waf-logs-amzn-s3-demo-destination-bucket-suffix/AWSLogs/123456789012/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "bucket-owner-full-control",
          "aws:SourceAccount": ["123456789012"]
        },
        "ArnLike": {
        "aws:SourceArn": ["arn:aws:logs:us-east-2:123456789012:*"]
        }
      }
    },
    {
      "Sid": "AWSLogDeliveryAclCheck",
      "Effect": "Allow",
      "Principal": {
        "Service": "delivery.logs.amazonaws.com"
      },
      "Action": "s3:GetBucketAcl",
      "Resource": "arn:aws:s3:::aws-waf-logs-amzn-s3-demo-destination-bucket-suffix",
      "Condition": {
        "StringEquals": {
        "aws:SourceAccount": ["123456789012"]
        },
        "ArnLike": {
        "aws:SourceArn": ["arn:aws:logs:us-east-2:123456789012:*"]
        }
      }
    }
  ]
}
```

------

**Note**  
Your bucket names for AWS WAF logging must start with `aws-waf-logs-` and can end with any suffix you want. 

If the user creating the log doesn't own the bucket, or doesn't have the `GetBucketPolicy` and `PutBucketPolicy` permissions for the bucket, the log creation fails. In this case, the bucket owner must manually add the preceding policy to the bucket and specify the log creator's AWS account ID. For more information, see [How Do I Add an S3 Bucket Policy?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html) in the *Amazon Simple Storage Service User Guide*. If the bucket receives logs from multiple accounts, add a `Resource` element entry to the `AWSLogDeliveryWrite` policy statement for each account. 

For example, the following bucket policy allows AWS account `111122223333` to publish logs to a bucket named `aws-waf-logs-LOGGING-BUCKET-SUFFIX`:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Id": "AWSLogDeliveryWrite20150319",
    "Statement": [
        {
            "Sid": "AWSLogDeliveryWrite",
            "Effect": "Allow",
            "Principal": {
                "Service": "delivery.logs.amazonaws.com"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::aws-waf-logs-amzn-s3-demo-destination-bucket-suffix/AWSLogs/111122223333/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control",
                    "aws:SourceAccount": ["111122223333"]
                },
                "ArnLike": {
                    "aws:SourceArn": ["arn:aws:logs:us-east-1:111122223333:*"]
                }
            }
        },
        {
            "Sid": "AWSLogDeliveryAclCheck",
            "Effect": "Allow",
            "Principal": {
                "Service": "delivery.logs.amazonaws.com"
            },
            "Action": "s3:GetBucketAcl",
            "Resource": "arn:aws:s3:::aws-waf-logs-amzn-s3-demo-destination-bucket-suffix",
            "Condition": {
                "StringEquals": {
                "aws:SourceAccount": ["111122223333"]
                },
                "ArnLike": {
                "aws:SourceArn": ["arn:aws:logs:us-east-1:111122223333:*"]
                }
            }
        }
    ]
}
```

------

**Note**  
In some cases, you may see `AccessDenied` errors in AWS CloudTrail if the `s3:ListBucket` permission has not been granted to `delivery.logs.amazonaws.com`. To avoid these errors in your CloudTrail logs, you must grant the `s3:ListBucket` permission to `delivery.logs.amazonaws.com` and you must include the `Condition` parameters shown with the `s3:GetBucketAcl `permission set in the preceding bucket policy. To make this simpler, instead of creating a new `Statement`, you can directly update the `AWSLogDeliveryAclCheck` to be `“Action”: [“s3:GetBucketAcl”, “s3:ListBucket”]`.

## Permissions for using AWS Key Management Service with a KMS key
<a name="logging-s3-permissions-encrypt-kms"></a>

If your logging destination uses server-side encryption with keys that are stored in AWS Key Management Service (SSE-KMS) and you use a customer managed key (KMS key), you must give AWS WAF permission to use your KMS key. To do this, you add a key policy to the KMS key for your chosen destination. This permits AWS WAF logging to write your log files to your destination. 

Add the following key policy to your KMS key to allow AWS WAF to log to your Amazon S3 bucket.

```
{
    "Sid": "Allow AWS WAF to use the key",
    "Effect": "Allow",
    "Principal": {
        "Service": [
            "delivery.logs.amazonaws.com"
        ]
    },
    "Action": "kms:GenerateDataKey*",
    "Resource": "*"
}
```

## Permissions required to access Amazon S3 log files
<a name="logging-s3-log-file-access"></a>

Amazon S3 uses access control lists (ACLs) to manage access to the log files created by an AWS WAF log. By default, the bucket owner has `FULL_CONTROL` permissions on each log file. The log delivery owner, if different from the bucket owner, has no permissions. The log delivery account has `READ` and `WRITE` permissions. For more information, see [Access Control List (ACL) Overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) in the *Amazon Simple Storage Service User Guide*.

# Sending protection pack (web ACL) traffic logs to an Amazon Data Firehose delivery stream
<a name="logging-kinesis"></a>

This section provides information for sending your protection pack (web ACL) traffic logs to an Amazon Data Firehose delivery stream. 

**Note**  
You are charged for logging in addition to the charges for using AWS WAF. For information, see [Pricing for logging protection pack (web ACL) traffic information](logging-pricing.md).

To send logs to Amazon Data Firehose, you send logs from your protection pack (web ACL) to an Amazon Data Firehose delivery stream which you configure in Firehose. After you enable logging, AWS WAF delivers logs to your storage destination through the HTTPS endpoint of Firehose. 

One AWS WAF log is equivalent to one Firehose record. If you typically receive 10,000 requests per second and you enable full logs, you should have a 10,000 records per second setting in Firehose. If you don't configure Firehose correctly, AWS WAF won't record all logs. For more information, see [Amazon Kinesis Data Firehose quotas](https://docs.aws.amazon.com/firehose/latest/dev/limits.html). 

For information about how to create an Amazon Data Firehose delivery stream and review your stored logs, see [What is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) 

For information about creating your delivery stream, see [Creating an Amazon Data Firehose delivery stream](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html).

## Configuring an Amazon Data Firehose delivery stream for your protection pack (web ACL)
<a name="logging-kinesis-configuration"></a>

Configure an Amazon Data Firehose delivery stream for your protection pack (web ACL) as follows.
+ Create it using the same account as you use to manage the protection pack (web ACL).
+ Create it in the same Region as the protection pack (web ACL). If you are capturing logs for Amazon CloudFront, create the firehose in US East (N. Virginia) Region, `us-east-1`.
+ Give the data firehose a name that starts with the prefix `aws-waf-logs-`. For example, `aws-waf-logs-us-east-2-analytics`.
+ Configure it for direct put, which allows applications to access the delivery stream directly. In the [Amazon Data Firehose console](https://console.aws.amazon.com/firehose), for the delivery stream **Source** setting, choose **Direct PUT or other sources**. Through the API, set the delivery stream property `DeliveryStreamType` to `DirectPut`.
**Note**  
Do not use a `Kinesis stream` as your source.

## Permissions required to publish logs to an Amazon Data Firehose delivery stream
<a name="logging-kinesis-permissions"></a>

To understand the permissions required for your Kinesis Data Firehose configuration, see [Controlling Access with Amazon Kinesis Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html).

You must have the following permissions to successfully enable protection pack (web ACL) logging with an Amazon Data Firehose delivery stream.
+ `iam:CreateServiceLinkedRole`
+ `firehose:ListDeliveryStreams`
+ `wafv2:PutLoggingConfiguration`

For information about service-linked roles and the `iam:CreateServiceLinkedRole` permission, see [Using service-linked roles for AWS WAF](using-service-linked-roles.md).

# Configuring logging for a protection pack (web ACL)
<a name="logging-management-configure"></a>

This section provides instructions for configuring data protection for a protection pack (web ACL).

**Note**  
You are charged for logging in addition to the charges for using AWS WAF. For information, see [Pricing for logging protection pack (web ACL) traffic information](logging-pricing.md).

To enable logging for a protection pack (web ACL), you must have already configured the logging destination that you're going to use. For information about your destination choices and the requirements for each, see [AWS WAF logging destinations](logging-destinations.md).

**To configure logging for a protection pack (web ACL)**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **protection packs (web ACLs)**.

1. Choose the name of the protection pack (web ACL) that you want to enable logging for. The console takes you to the protection pack (web ACL)'s description, where you can edit it.

1. On the **Logging and metrics** tab, choose **Enable logging**.

1. Choose the logging destination type, and then choose the logging destination that you configured. You must choose a logging destination whose name begins with `aws-waf-logs-`.

1. (Optional) If you don't want some fields included in the logs, redact them. Choose the field to redact, and then choose **Add**. Repeat as necessary to redact additional fields. Redacted fields appear in the logs as `xxx`.
**Note**  
This setting has no impact on request sampling. You can exclude fields from request sampling by configuring protection pack (web ACL) data protection or by disabling sampling for the protection pack (web ACL). 

1. (Optional) If you don't want to send all requests to the logs, add your filtering criteria and behavior. Under **Filter logs**, for each filter that you want to apply, choose **Add filter**, then choose your filtering criteria and specify whether you want to keep or drop requests that match the criteria. When you finish adding filters, if needed, modify the **Default logging behavior**. 
**Note**  
If you add multiple filters, AWS WAF evaluates them starting from the top.

1. Choose **Enable logging**.
**Note**  
When you successfully enable logging, AWS WAF will create a service-linked role with the necessary permissions to write logs to the logging destination. For more information, see [Using service-linked roles for AWS WAF](using-service-linked-roles.md).

# Finding your protection pack (web ACL) records
<a name="logging-management"></a>

This section explains how to find your protection pack (web ACL) records.

**Note**  
You are charged for logging in addition to the charges for using AWS WAF. For information, see [Pricing for logging protection pack (web ACL) traffic information](logging-pricing.md).

**If you can't find a log record in your logs**  
On rare occasions, it's possible for AWS WAF log delivery to fall below 100%, with logs delivered on a best effort basis. The AWS WAF architecture prioritizes the security of your applications over all other considerations. In some situations, such as when logging flows experience traffic throttling, this can result in records being dropped. This shouldn't affect more than a few records. If you notice a number of missing log entries, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/).

In the logging configuration for your protection pack (web ACL), you can customize what AWS WAF sends to the logs.
+ **Field redaction** – You can redact the following fields from the log records for the rules that use the corresponding match settings: **URI path**, **Query string**, **Single header**, and **HTTP method**. Redacted fields appear as `REDACTED` in the logs. For example, if you redact the **Query string** field, in the logs, it will be listed as `REDACTED` for all rules that use the **Query string** match component setting. Redaction applies only to the request component that you specify for matching in the rule, so the redaction of the **Single header** component doesn't apply to rules that match on **Headers**. For a list of the log fields, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).
**Note**  
This setting has no impact on request sampling. You can exclude fields from request sampling by configuring protection pack (web ACL) data protection or by disabling sampling for the protection pack (web ACL). 
+ **Log filtering** – You can add filtering to specify which web requests are kept in the logs and which are dropped. You filter on the settings that AWS WAF applies during the web request evaluation. You can filter on the following settings: 
  + **Fully qualified label** – Fully qualified labels have 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. For information about labels, see [Web request labeling in AWS WAF](waf-labels.md).
  + **Rule action** – You can filter on any normal rule action setting and also on the legacy `EXCLUDED_AS_COUNT` override option for rule group rules. For information about rule action settings, see [Using rule actions in AWS WAF](waf-rule-action.md). For information about current and legacy rule action overrides for rule group rules, see [Overriding rule group actions in AWS WAF](web-acl-rule-group-override-options.md). 
    + The normal rule action filters apply to actions that are configured in rules and also to actions that are configured using the current option for overriding a rule group rule action. 
    + The `EXCLUDED_AS_COUNT` log filter overlaps with the `Count` action log filter. `EXCLUDED_AS_COUNT` filters both the current and legacy options for overriding a rule group rule action to Count. 

# Log fields for protection pack (web ACL) traffic
<a name="logging-fields"></a>

The following list describes the possible log fields. 

**action**  
The terminating action that AWS WAF applied to the request. This indicates either allow, block, CAPTCHA, or challenge. The CAPTCHA and Challenge actions are terminating when the web request doesn't contain a valid token.

**args**  
The query string.

**captchaResponse**  
The CAPTCHA action status for the request, populated when a CAPTCHA action is applied to the request. This field is populated for any CAPTCHA action, whether terminating or non-terminating. If a request has the CAPTCHA action applied multiple times, this field is populated from the last time the action was applied.   
The CAPTCHA action terminates web request inspection when the request either doesn't include a token or the token is invalid or expired. If the CAPTCHA action is terminating, this field includes a response code and failure reason. If the action is non-terminating, this field includes a solve timestamp. To differentiate between a terminating and non-terminating action, you can filter for a non-empty `failureReason` attribute in this field.

**cfDistributionTenantId**  
The identifier for the CloudFront distribution tenant associated with the web request. This field is optional and only applies to protection packs (web ACLs) associated with CloudFront distribution tenants.

**challengeResponse**  
The challenge action status for the request, populated when a Challenge action is applied to the request. This field is populated for any Challenge action, whether terminating or non-terminating. If a request has the Challenge action applied multiple times, this field is populated from the last time the action was applied.   
The Challenge action terminates web request inspection when the request either doesn't include a token or the token is invalid or expired. If the Challenge action is terminating, this field includes a response code and failure reason. If the action is non-terminating, this field includes a solve timestamp. To differentiate between a terminating and non-terminating action, you can filter for a non-empty `failureReason` attribute in this field.

**clientAsn**  
The Autonomous System Number (ASN) associated with the IP address of the web request's origin.  
**clientAsn** is logged in AWS WAF logs only when an ASN match statement is used. This field is not logged otherwise.

**clientIp**  
The IP address of the client sending the request.

**country**  
The source country of the request. If AWS WAF is unable to determine the country of origin, it sets this field to `-`. 

**country**  
The source country of the request. If AWS WAF is unable to determine the country of origin, it sets this field to `-`. 

**excludedRules**  
Used only for rule group rules. The list of rules in the rule group that you have excluded. The action for these rules is set to Count.   
If you override a rule to count using the override rule action option, matches aren't listed here. They're listed as the action pairs `action` and `overriddenAction`.    
exclusionType  
A type that indicates that the excluded rule has the action Count.  
ruleId  
The ID of the rule within the rule group that is excluded.

**formatVersion**  
The format version for the log.

**forwardedAsn**  
The Autonomous System Number (ASN) associated with the IP address of from the entity that forwarded the web request.

**headers**  
The list of headers.

**httpMethod**  
The HTTP method in the request.

**httpRequest**  
The metadata about the request.

**httpSourceId**  
The ID of the associated resource:   
+ For an Amazon CloudFront distribution, the ID is the `distribution-id` in the ARN syntax: 

  `arn:partitioncloudfront::account-id:distribution/distribution-id` 
+ For an Application Load Balancer, the ID is the `load-balancer-id` in the ARN syntax: 

  `arn:partition:elasticloadbalancing:region:account-id:loadbalancer/app/load-balancer-name/load-balancer-id`
+ For an Amazon API Gateway REST API, the ID is the `api-id` in the ARN syntax: 

  `arn:partition:apigateway:region::/restapis/api-id/stages/stage-name`
+ For an AWS AppSync GraphQL API, the ID is the `GraphQLApiId` in the ARN syntax: 

  `arn:partition:appsync:region:account-id:apis/GraphQLApiId`
+ For an Amazon Cognito user pool, the ID is the `user-pool-id` in the ARN syntax: 

  `arn:partition:cognito-idp:region:account-id:userpool/user-pool-id`
+ For an AWS App Runner service, the ID is the `apprunner-service-id` in the ARN syntax: 

  `arn:partition:apprunner:region:account-id:service/apprunner-service-name/apprunner-service-id`

**httpSourceName**  
The source of the request. Possible values: `CF` for Amazon CloudFront, `APIGW` for Amazon API Gateway, `ALB` for Application Load Balancer, `APPSYNC` for AWS AppSync, `COGNITOIDP` for Amazon Cognito, `APPRUNNER` for App Runner, and `VERIFIED_ACCESS` for Verified Access.

**httpVersion**  
The HTTP version.

**ja3Fingerprint**  
The JA3 fingerprint of the request.  
JA3 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers.
The JA3 fingerprint is a 32-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation.   
You provide this value when you configure a JA3 fingerprint match in your protection pack (web ACL) rules. For information about creating a match against the JA3 fingerprint, see [JA3 fingerprint](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja3-fingerprint) in the [Request components in AWS WAF](waf-rule-statement-fields-list.md) for a rule statement.

**ja4Fingerprint**  
The JA4 fingerprint of the request.  
JA4 fingerprint inspection is available only for Amazon CloudFront distributions and Application Load Balancers.
The JA4 fingerprint is a 36-character hash derived from the TLS Client Hello of an incoming request. This fingerprint serves as a unique identifier for the client's TLS configuration. AWS WAF calculates and logs this fingerprint for each request that has enough TLS Client Hello information for the calculation.   
You provide this value when you configure a JA4 fingerprint match in your protection pack (web ACL) rules. For information about creating a match against the JA4 fingerprint, see [JA4 fingerprint](waf-rule-statement-fields-list.md#waf-rule-statement-request-component-ja4-fingerprint) in the [Request components in AWS WAF](waf-rule-statement-fields-list.md) for a rule statement.

**labels**  
The labels on the web request. These labels were applied by rules that were used to evaluate the request. AWS WAF logs the first 100 labels. 

**nonTerminatingMatchingRules**  
The list of non-terminating rules that matched the request. Each item in the list contains the following information.     
action  
The action that AWS WAF applied to the request. This indicates either count, CAPTCHA, or challenge. The CAPTCHA and Challenge are non-terminating when the web request contains a valid token.  
ruleId  
The ID of the rule that matched the request and was non-terminating.   
ruleMatchDetails  
Detailed information about the rule that matched the request. This field is only populated for SQL injection and cross-site scripting (XSS) match rule statements. A matching rule might require a match for more than one inspection criteria, so these match details are provided as an array of match criteria. 
Any additional information provided for each rule varies according factors such as the rule configuration, rule match type, and details of the match. For example for rules with a CAPTCHA or Challenge action, the `captchaResponse` or `challengeResponse` will be listed. If the matching rule is in a rule group and you've overridden its configured rule action, the configured action will be provided in `overriddenAction`. 

**oversizeFields**  
The list of fields in the web request that were inspected by the protection pack (web ACL) and that are over the AWS WAF inspection limit. If a field is oversize but the protection pack (web ACL) doesn't inspect it, it won't be listed here.   
This list can contain zero or more of the following values: `REQUEST_BODY`, `REQUEST_JSON_BODY`, `REQUEST_HEADERS`, and `REQUEST_COOKIES`. For more information about oversize fields, see [Oversize web request components in AWS WAF](waf-oversize-request-components.md).

**rateBasedRuleList**  
The list of rate-based rules that acted on the request. For information about rate-based rules, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md).    
rateBasedRuleId  
The ID of the rate-based rule that acted on the request. If this has terminated the request, the ID for `rateBasedRuleId` is the same as the ID for `terminatingRuleId`.  
rateBasedRuleName  
The name of the rate-based rule that acted on the request.   
limitKey  
The type of aggregation that the rule is using. Possible values are `IP` for web request origin, `FORWARDED_IP` for an IP forwarded in a header in the request, `CUSTOMKEYS` for custom aggregate key settings. and `CONSTANT` for count all requests together, with no aggregation.   
limitValue  
Used only when rate limiting by a single IP address type. If a request contains an IP address that isn't valid, the `limitvalue` is `INVALID`.  
maxRateAllowed  
The maximum number of requests allowed in the specified time window for a specific aggregation instance. The aggregation instance is defined by the `limitKey` plus any additional key specifications that you've provided in the rate-based rule configuration.   
evaluationWindowSec  
The amount of time that AWS WAF included in its request counts, in seconds.   
customValues  
Unique values identified by the rate-based rule in the request. For string values, the logs print the first 32 characters of the string value. Depending on the key type, these values might be for just a key, such as for HTTP method or query string, or they might be for a key and name, such as for header and the header name. 

**requestHeadersInserted**  
The list of headers inserted for custom request handling.

**requestId**  
The ID of the request, which is generated by the underlying host service. For Application Load Balancer, this is the trace ID. For all others, this is the request ID. 

**responseCodeSent**  
The response code sent with a custom response.

**ruleGroupId**  
The ID of the rule group. If the rule blocked the request, the ID for `ruleGroupID` is the same as the ID for `terminatingRuleId`. 

**ruleGroupList**  
The list of rule groups that acted on this request, with match information.

**terminatingRule**  
The rule that terminated the request. If this is present, it contains the following information.     
action  
The terminating action that AWS WAF applied to the request. This indicates either allow, block, CAPTCHA, or challenge. The CAPTCHA and Challenge actions are terminating when the web request doesn't contain a valid token.  
ruleId  
The ID of the rule that matched the request.   
ruleMatchDetails  
Detailed information about the rule that matched the request. This field is only populated for SQL injection and cross-site scripting (XSS) match rule statements. A matching rule might require a match for more than one inspection criteria, so these match details are provided as an array of match criteria. 
Any additional information provided for each rule varies according factors such as the rule configuration, rule match type, and details of the match. For example for rules with a CAPTCHA or Challenge action, the `captchaResponse` or `challengeResponse` will be listed. If the matching rule is in a rule group and you've overridden its configured rule action, the configured action will be provided in `overriddenAction`. 

**terminatingRuleId**  
The ID of the rule that terminated the request. If nothing terminates the request, the value is `Default_Action`.

**terminatingRuleMatchDetails**  
Detailed information about the terminating rule that matched the request. A terminating rule has an action that ends the inspection process against a web request. Possible actions for a terminating rule include Allow, Block, CAPTCHA, and Challenge. During the inspection of a web request, at the first rule that matches the request and that has a terminating action, AWS WAF stops the inspection and applies the action. The web request might contain other threats, in addition to the one that's reported in the log for the matching terminating rule.  
This is only populated for SQL injection and cross-site scripting (XSS) match rule statements. The matching rule might require a match for more than one inspection criteria, so these match details are provided as an array of match criteria. 

**terminatingRuleType**  
The type of rule that terminated the request. Possible values: RATE\$1BASED, REGULAR, GROUP, and MANAGED\$1RULE\$1GROUP.

**timestamp**  
The timestamp in milliseconds.

**uri**  
The URI of the request. 

**fragment**  
The part of a URL that follows the "\$1" symbol, providing additional information about the resource, for example, \$1section2.

**webaclId**  
The GUID of the protection pack (web ACL).

# Log examples for protection pack (web ACL) traffic
<a name="logging-examples"></a>

This section provides examples for logging protection pack (web ACL) traffic.

**Example Rate-based rule 1: Rule configuration with one key, set to `Header:dogname`**  

```
    {
      "Name": "RateBasedRule",
      "Priority": 1,
      "Statement": {
        "RateBasedStatement": {
          "Limit": 100,
          "AggregateKeyType": "CUSTOM_KEYS",
          "CustomKeys": [
            {
              "Header": {
                "Name": "dogname",
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                  }
                ]
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "RateBasedRule"
      }
    }
```

**Example Rate-based rule 1: Log entry for request blocked by rate-based rule**  

```
{
   "timestamp":1683355579981,
   "formatVersion":1,
   "webaclId": ...,
   "terminatingRuleId":"RateBasedRule",
   "terminatingRuleType":"RATE_BASED",
   "action":"BLOCK",
   "terminatingRuleMatchDetails":[
      
   ],
   "httpSourceName":"APIGW",
   "httpSourceId":"EXAMPLE11:rjvegx5guh:CanaryTest",
   "ruleGroupList":[
      
   ],
   "rateBasedRuleList":[
      {
         "rateBasedRuleId": ...,
         "rateBasedRuleName":"RateBasedRule",
         "limitKey":"CUSTOMKEYS",
         "maxRateAllowed":100,
         "evaluationWindowSec":"120",
         "customValues":[
            {
               "key":"HEADER",
               "name":"dogname",
               "value":"ella"
            }
         ]
      }
   ],
   "nonTerminatingMatchingRules":[
      
   ],
   "requestHeadersInserted":null,
   "responseCodeSent":null,
   "httpRequest":{
      "clientIp":"52.46.82.45",
      "country":"FR",
      "headers":[
         {
            "name":"X-Forwarded-For",
            "value":"52.46.82.45"
         },
         {
            "name":"X-Forwarded-Proto",
            "value":"https"
         },
         {
            "name":"X-Forwarded-Port",
            "value":"443"
         },
         {
            "name":"Host",
            "value":"rjvegx5guh.execute-api.eu-west-3.amazonaws.com"
         },
         {
            "name":"X-Amzn-Trace-Id",
            "value":"Root=1-645566cf-7cb058b04d9bb3ee01dc4036"
         },
         {
            "name":"dogname",
            "value":"ella"
         },
         {
            "name":"User-Agent",
            "value":"RateBasedRuleTestKoipOneKeyModulePV2"
         },
         {
            "name":"Accept-Encoding",
            "value":"gzip,deflate"
         }
      ],
      "uri":"/CanaryTest",
      "args":"",
      "httpVersion":"HTTP/1.1",
      "httpMethod":"GET",
      "requestId":"Ed0AiHF_CGYF-DA="
   }
}
```

**Example Rate-based rule 2: Rule configuration with two keys, set to `Header:dogname` and `Header:catname`**  

```
    {
      "Name": "RateBasedRule",
      "Priority": 1,
      "Statement": {
        "RateBasedStatement": {
          "Limit": 100,
          "AggregateKeyType": "CUSTOM_KEYS",
          "CustomKeys": [
            {
              "Header": {
                "Name": "dogname",
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                  }
                ]
              }
            },
            {
              "Header": {
                "Name": "catname",
                "TextTransformations": [
                  {
                    "Priority": 0,
                    "Type": "NONE"
                  }
                ]
              }
            }
          ]
        }
      },
      "Action": {
        "Block": {}
      },
      "VisibilityConfig": {
        "SampledRequestsEnabled": true,
        "CloudWatchMetricsEnabled": true,
        "MetricName": "RateBasedRule"
      }
    }
```

**Example Rate-based rule 2: Log entry for request blocked by rate-based rule**  

```
{
   "timestamp":1633322211194,
   "formatVersion":1,
   "webaclId":...,
   "terminatingRuleId":"RateBasedRule",
   "terminatingRuleType":"RATE_BASED",
   "action":"BLOCK",
   "terminatingRuleMatchDetails":[
      
   ],
   "httpSourceName":"APIGW",
   "httpSourceId":"EXAMPLE11:rjvegx5guh:CanaryTest",
   "ruleGroupList":[
      
   ],
   "rateBasedRuleList":[
      {
         "rateBasedRuleId":...,
         "rateBasedRuleName":"RateBasedRule",
         "limitKey":"CUSTOMKEYS",
         "maxRateAllowed":100,
         "evaluationWindowSec":"120",
         "customValues":[
            {
               "key":"HEADER",
               "name":"dogname",
               "value":"ella"
            },
            {
               "key":"HEADER",
               "name":"catname",
               "value":"goofie"
            }
         ]
      }
   ],
   "nonTerminatingMatchingRules":[
      
   ],
   "requestHeadersInserted":null,
   "responseCodeSent":null,
   "httpRequest":{
      "clientIp":"52.46.82.35",
      "country":"FR",
      "headers":[
         {
            "name":"X-Forwarded-For",
            "value":"52.46.82.35"
         },
         {
            "name":"X-Forwarded-Proto",
            "value":"https"
         },
         {
            "name":"X-Forwarded-Port",
            "value":"443"
         },
         {
            "name":"Host",
            "value":"23llbyn8v3.execute-api.eu-west-3.amazonaws.com"
         },
         {
            "name":"X-Amzn-Trace-Id",
            "value":"Root=1-64556629-17ac754c2ed9f0620e0f2a0c"
         },
         {
            "name":"catname",
            "value":"goofie"
         },
         {
            "name":"dogname",
            "value":"ella"
         },
         {
            "name":"User-Agent",
            "value":"Apache-HttpClient/UNAVAILABLE (Java/11.0.19)"
         },
         {
            "name":"Accept-Encoding",
            "value":"gzip,deflate"
         }
      ],
      "uri":"/CanaryTest",
      "args":"",
      "httpVersion":"HTTP/1.1",
      "httpMethod":"GET",
      "requestId":"EdzmlH5OCGYF1vQ="
   }
}
```

**Example Log output for a rule that triggered on SQLi detection (terminating)**  

```
{
    "timestamp": 1576280412771,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:ap-southeast-2:111122223333:regional/webacl/STMTest/1EXAMPLE-2ARN-3ARN-4ARN-123456EXAMPLE",
    "terminatingRuleId": "STMTest_SQLi_XSS",
    "terminatingRuleType": "REGULAR",
    "action": "BLOCK",
    "terminatingRuleMatchDetails": [
        {
            "conditionType": "SQL_INJECTION",
            "sensitivityLevel": "HIGH",
            "location": "HEADER",
            "matchedData": [
                "10",
                "AND",
                "1"
            ]
        }
    ],
    "httpSourceName": "-",
    "httpSourceId": "-",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [],
    "httpRequest": {
        "clientIp": "1.1.1.1",
        "country": "AU",
        "headers": [
            {
                "name": "Host",
                "value": "localhost:1989"
            },
            {
                "name": "User-Agent",
                "value": "curl/7.61.1"
            },
            {
                "name": "Accept",
                "value": "*/*"
            },
            {
                "name": "x-stm-test",
                "value": "10 AND 1=1"
            }
        ],
        "uri": "/myUri",
        "args": "",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "rid"
    },
    "labels": [
        {
            "name": "value"
        }
    ]
}
```

**Example Log output for a rule that triggered on SQLi detection (non-terminating)**  

```
{
    "timestamp":1592357192516
    ,"formatVersion":1
    ,"webaclId":"arn:aws:wafv2:us-east-1:123456789012:global/webacl/hello-world/5933d6d9-9dde-js82-v8aw-9ck28nv9"
    ,"terminatingRuleId":"Default_Action"
    ,"terminatingRuleType":"REGULAR"
    ,"action":"ALLOW"
    ,"terminatingRuleMatchDetails":[]
    ,"httpSourceName":"-"
    ,"httpSourceId":"-"
    ,"ruleGroupList":[]
    ,"rateBasedRuleList":[]
    ,"nonTerminatingMatchingRules":
    [{
        "ruleId":"TestRule"
        ,"action":"COUNT"
        ,"ruleMatchDetails":
        [{
            "conditionType":"SQL_INJECTION"
            ,"sensitivityLevel": "HIGH"
            ,"location":"HEADER"
            ,"matchedData":[
                "10"
                ,"and"
                ,"1"]
            }]
    }]
    ,"httpRequest":{
        "clientIp":"3.3.3.3"
        ,"country":"US"
        ,"headers":[
            {"name":"Host","value":"localhost:1989"}
            ,{"name":"User-Agent","value":"curl/7.61.1"}
            ,{"name":"Accept","value":"*/*"}
            ,{"name":"myHeader","myValue":"10 AND 1=1"}
            ]
            ,"uri":"/myUri","args":""
            ,"httpVersion":"HTTP/1.1"
            ,"httpMethod":"GET"
            ,"requestId":"rid"
    },
    "labels": [
        {
            "name": "value"
        }
    ]
}
```

**Example Log output for multiple rules that triggered inside a rule group (RuleA-XSS is terminating and Rule-B is non-terminating)**  

```
{
    "timestamp":1592361810888,
    "formatVersion":1,
    "webaclId":"arn:aws:wafv2:us-east-1:123456789012:global/webacl/hello-world/5933d6d9-9dde-js82-v8aw-9ck28nv9"
    ,"terminatingRuleId":"RG-Reference"
    ,"terminatingRuleType":"GROUP"
    ,"action":"BLOCK",
    "terminatingRuleMatchDetails":
    [{
        "conditionType":"XSS"
        ,"location":"HEADER"
        ,"matchedData":["<","frameset"]
    }]
    ,"httpSourceName":"-"
    ,"httpSourceId":"-"
    ,"ruleGroupList":
    [{
        "ruleGroupId":"arn:aws:wafv2:us-east-1:123456789012:global/rulegroup/hello-world/c05lb698-1f11-4m41-aef4-99a506d53f4b"
        ,"terminatingRule":{
            "ruleId":"RuleA-XSS"
            ,"action":"BLOCK"
            ,"ruleMatchDetails":null
            }
        ,"nonTerminatingMatchingRules":
        [{
            "ruleId":"RuleB-SQLi"
            ,"action":"COUNT"
            ,"ruleMatchDetails":
            [{
                "conditionType":"SQL_INJECTION"
                ,"sensitivityLevel": "LOW"
                ,"location":"HEADER"
                ,"matchedData":[
                    "10"
                    ,"and"
                    ,"1"]
            }]
        }]
        ,"excludedRules":null
    }]
    ,"rateBasedRuleList":[]
    ,"nonTerminatingMatchingRules":[]
    ,"httpRequest":{
        "clientIp":"3.3.3.3"
        ,"country":"US"
        ,"headers":
        [
            {"name":"Host","value":"localhost:1989"}
            ,{"name":"User-Agent","value":"curl/7.61.1"}
            ,{"name":"Accept","value":"*/*"}
            ,{"name":"myHeader1","value":"<frameset onload=alert(1)>"}
            ,{"name":"myHeader2","value":"10 AND 1=1"}
            ]
        ,"uri":"/myUri"
        ,"args":""
        ,"httpVersion":"HTTP/1.1"
        ,"httpMethod":"GET"
        ,"requestId":"rid"
    },
    "labels": [
        {
            "name": "value"
        }
    ]
}
```

**Example Log output for a rule that triggered for the inspection of the request body with content type JSON**  
AWS WAF currently reports the location for JSON body inspection as `UNKNOWN`.  

```
{
    "timestamp": 1576280412771,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:ap-southeast-2:123456789012:regional/webacl/test/111",
    "terminatingRuleId": "STMTest_SQLi_XSS",
    "terminatingRuleType": "REGULAR",
    "action": "BLOCK",
    "terminatingRuleMatchDetails": [
        {
            "conditionType": "SQL_INJECTION",
            "sensitivityLevel": "LOW",
            "location": "UNKNOWN",
            "matchedData": [
                "10",
                "AND",
                "1"
            ]
        }
    ],
    "httpSourceName": "ALB",
    "httpSourceId": "alb",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [],
    "requestHeadersInserted":null,
    "responseCodeSent":null,
    "httpRequest": {
        "clientIp": "1.1.1.1",
        "country": "AU",
        "headers": [],
        "uri": "",
        "args": "",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "POST",
        "requestId": "null"
    },
    "labels": [
        {
            "name": "value"
        }
    ]
}
```

**Example Log output for a CAPTCHA rule against a web request with a valid, unexpired CAPTCHA token**  
The following log listing is for a web request that matched a rule with CAPTCHA action. The web request has a valid and unexpired CAPTCHA token, and is only noted as a CAPTCHA match by AWS WAF, similar to the behavior for the Count action. This CAPTCHA match is noted under `nonTerminatingMatchingRules`.  

```
{
  "timestamp": 1632420429309,
  "formatVersion": 1,
  "webaclId": "arn:aws:wafv2:us-east-1:123456789012:regional/webacl/captcha-web-acl/585e38b5-afce-4d2a-b417-14fb08b66c67",
  "terminatingRuleId": "Default_Action",
  "terminatingRuleType": "REGULAR",
  "action": "ALLOW",
  "terminatingRuleMatchDetails": [],
  "httpSourceName": "APIGW",
  "httpSourceId": "123456789012:b34myvfw0b:pen-test",
  "ruleGroupList": [],
  "rateBasedRuleList": [],
  "nonTerminatingMatchingRules": [
    {
      "ruleId": "captcha-rule",
      "action": "CAPTCHA",
      "ruleMatchDetails": [],
      "captchaResponse": {
        "responseCode": 0,
        "solveTimestamp": 1632420429
      }
    }
  ],
  "requestHeadersInserted": [
    {
      "name": "x-amzn-waf-test-header-name",
      "value": "test-header-value"
    }
  ],
  "responseCodeSent": null,
  "httpRequest": {
    "clientIp": "72.21.198.65",
    "country": "US",
    "headers": [
      {
        "name": "X-Forwarded-For",
        "value": "72.21.198.65"
      },
      {
        "name": "X-Forwarded-Proto",
        "value": "https"
      },
      {
        "name": "X-Forwarded-Port",
        "value": "443"
      },
      {
        "name": "Host",
        "value": "b34myvfw0b.gamma.execute-api.us-east-1.amazonaws.com"
      },
      {
        "name": "X-Amzn-Trace-Id",
        "value": "Root=1-614cc24d-5ad89a09181910c43917a888"
      },
      {
        "name": "cache-control",
        "value": "max-age=0"
      },
      {
        "name": "sec-ch-ua",
        "value": "\"Chromium\";v=\"94\", \"Google Chrome\";v=\"94\", \";Not A Brand\";v=\"99\""
      },
      {
        "name": "sec-ch-ua-mobile",
        "value": "?0"
      },
      {
        "name": "sec-ch-ua-platform",
        "value": "\"Windows\""
      },
      {
        "name": "upgrade-insecure-requests",
        "value": "1"
      },
      {
        "name": "user-agent",
        "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.54 Safari/537.36"
      },
      {
        "name": "accept",
        "value": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9"
      },
      {
        "name": "sec-fetch-site",
        "value": "same-origin"
      },
      {
        "name": "sec-fetch-mode",
        "value": "navigate"
      },
      {
        "name": "sec-fetch-user",
        "value": "?1"
      },
      {
        "name": "sec-fetch-dest",
        "value": "document"
      },
      {
        "name": "referer",
        "value": "https://b34myvfw0b.gamma.execute-api.us-east-1.amazonaws.com/pen-test/pets"
      },
      {
        "name": "accept-encoding",
        "value": "gzip, deflate, br"
      },
      {
        "name": "accept-language",
        "value": "en-US,en;q=0.9"
      },
      {
        "name": "cookie",
        "value": "aws-waf-token=51c71352-41f5-4f6d-b676-c24907bdf819:EQoAZ/J+AAQAAAAA:t9wvxbw042wva7E2Y6lgud/bS6YG0CJKVAJqaRqDZ140ythKW0Zj9wKB2O8lSkYDRqf1yONcVBFo5u0eYi0tvT4rtQCXsu+KanAardW8go4QSLw4yoED59lgV7oAhGyCalAzE7ra29j+RvvZPsQyoQuDCrtoY/TvQyMTXIXzGPDC/rKBbg=="
      }
    ],
    "uri": "/pen-test/pets",
    "args": "",
    "httpVersion": "HTTP/1.1",
    "httpMethod": "GET",
    "requestId": "GINMHHUgoAMFxug="
  }
}
```

**Example Log output for a CAPTCHA rule against a web request that doesn't have a CAPTCHA token**  
The following log listing is for a web request that matched a rule with CAPTCHA action. The web request didn't have a CAPTCHA token, and was blocked by AWS WAF.  

```
{
  "timestamp": 1632420416512,
  "formatVersion": 1,
  "webaclId": "arn:aws:wafv2:us-east-1:123456789012:regional/webacl/captcha-web-acl/585e38b5-afce-4d2a-b417-14fb08b66c67",
  "terminatingRuleId": "captcha-rule",
  "terminatingRuleType": "REGULAR",
  "action": "CAPTCHA",
  "terminatingRuleMatchDetails": [],
  "httpSourceName": "APIGW",
  "httpSourceId": "123456789012:b34myvfw0b:pen-test",
  "ruleGroupList": [],
  "rateBasedRuleList": [],
  "nonTerminatingMatchingRules": [],
  "requestHeadersInserted": null,
  "responseCodeSent": 405,
  "httpRequest": {
    "clientIp": "72.21.198.65",
    "country": "US",
    "headers": [
      {
        "name": "X-Forwarded-For",
        "value": "72.21.198.65"
      },
      {
        "name": "X-Forwarded-Proto",
        "value": "https"
      },
      {
        "name": "X-Forwarded-Port",
        "value": "443"
      },
      {
        "name": "Host",
        "value": "b34myvfw0b.gamma.execute-api.us-east-1.amazonaws.com"
      },
      {
        "name": "X-Amzn-Trace-Id",
        "value": "Root=1-614cc240-18b57ff33c10e5c016b508c5"
      },
      {
        "name": "sec-ch-ua",
        "value": "\"Chromium\";v=\"94\", \"Google Chrome\";v=\"94\", \";Not A Brand\";v=\"99\""
      },
      {
        "name": "sec-ch-ua-mobile",
        "value": "?0"
      },
      {
        "name": "sec-ch-ua-platform",
        "value": "\"Windows\""
      },
      {
        "name": "upgrade-insecure-requests",
        "value": "1"
      },
      {
        "name": "user-agent",
        "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.54 Safari/537.36"
      },
      {
        "name": "accept",
        "value": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9"
      },
      {
        "name": "sec-fetch-site",
        "value": "cross-site"
      },
      {
        "name": "sec-fetch-mode",
        "value": "navigate"
      },
      {
        "name": "sec-fetch-user",
        "value": "?1"
      },
      {
        "name": "sec-fetch-dest",
        "value": "document"
      },
      {
        "name": "accept-encoding",
        "value": "gzip, deflate, br"
      },
      {
        "name": "accept-language",
        "value": "en-US,en;q=0.9"
      }
    ],
    "uri": "/pen-test/pets",
    "args": "",
    "httpVersion": "HTTP/1.1",
    "httpMethod": "GET",
    "requestId": "GINKHEssoAMFsrg="
  },
  "captchaResponse": {
    "responseCode": 405,
    "solveTimestamp": 0,
    "failureReason": "TOKEN_MISSING"
  }
}
```

# Data protection
<a name="data-protection-masking"></a>

AWS WAF data protection settings let you implement customized and granular protection of sensitive information (passwords, API keys, authentication tokens, and other confidential data) on specific data fields such as headers, parameters, and body content.

You can configure data protection at either:
+ The protection pack (web ACL) level, which applies across all output destinations.
+ Logging only, which only affects the data that AWS WAF sends to the configured logging destination. 

Data protection can be specified as either a substitution or hashing. 

Substitution refers to replacing content with the word `REDACTED`. 

 Hashing refers to replacing content, from string to SHA-256 binary to Base64:

1. First, the algorithm builds a string from account\$1number and content.

1. It then applies SHA-256 to produce a binary hash.

1. Finally, it encodes those bytes using Base64.

**Tip**  
 You should review the characteristics of SHA-256 hashing to determine if it meets your requirements before you select the appropriate data protection method. We do not recommend relying on SHA-256 hashing if you intend to achieve an outcome equivalent to encryption or tokenization.

**Topics**
+ [

# Enabling data protection
](enable-protection.md)
+ [

# Data protection exceptions
](data-protection-exceptions.md)
+ [

# Data protection limitations
](data-protection-limitations.md)
+ [

# Examples of data protection
](data-protection-examples.md)
+ [

# Configuring data protection for a protection pack (web ACL)
](data-protection-configure.md)

# Enabling data protection
<a name="enable-protection"></a>

This section explains the data protection and log configuration options you can select from the console. You can protect data that appears in logs by enabling data protection on certain fields. Data protection can be applied to transform sensitive information in various types of outputs, including full logs, sample requests, and Security Lake.

**To enable data protection in the AWS WAF console**

Navigate to the **protection packs (web ACLs)** page in the console to **enable protection settings**. To enable data protection for your logs, choose whether to apply it to all logs or to a specific logging destination. For information, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).

**Note**  
You don't need to enable logging to apply data protection on all logging. Data protection will be applied across all output destinations, regardless of whether logging is enabled. 

At the bottom of the **Enable protection settings** page, select the **Add field** button on the **Data protection fields** panel. Select the field type from the drop down menu. For information about how each field's data is protected with data protection, see the table below.


| Field type | Details | 
| --- | --- | 
|  `Single header`  |  Permanently transform the specified header key value according to the specified option (hashing or subsitution). The transformed value will also be reflected in full Logs.  | 
|  `Body`  |  Permanently transforms the body value. Only applicable for `RuleMatchDetails` in the log.  | 
|  `Query string`  |  Permanently transform the query string according to the specified option (hashing or subsitution). The transformed value will also be reflected in full Logs.  | 
|  `Single query argument`  |  Permanently transform the specified query arg value according to the specified option (hashing or subsitution). The transformed value will also be reflected in full Logs.  | 
|  `Single cookie`  |  Permanently transform the cookie value according to the specified option (hashing or subsitution). The transformed value will also be reflected in full Logs.  | 

# Data protection exceptions
<a name="data-protection-exceptions"></a>

When enabled, data protection will apply to the fields it is enabled on, including `RuleMatchDetails` and `rateBasedRuleList`. However, there are instances when you may want to include the protected data and content in `RuleMatchDetails` and `rateBasedRuleList` for troubleshooting and visibility purposes. In these scenarios, you can specify exceptions to the data protection for that field.
+ **`ExcludeRuleMatchDetails`**: If you specify this exception for a specific field, `RuleMatchDetails` will show the value of the field and won't be in scope for data protection. 
+ **`ExcludeRateBasedDetails`**: If you specify this exception for a specific field, `rateBasedRuleList` will show the value of the field and won't be in scope for data protection.

  Example: The `ExcludeRateBasedDetails` rule is enabled on **SINGLE\$1HEADER** and **HEADER\$1NAME** for "dogname".

  If an exception is not applied to the rule, the value for "dogname" will appear as `REDACTED`.

  ```
  "rateBasedRuleList":[ {"rateBasedRuleId": ...,
                          "rateBasedRuleName":"RateBasedRule", "limitKey":"CUSTOMKEYS",
                          "maxRateAllowed":100, "evaluationWindowSec":"120", "customValues":[
                          {"key":"HEADER", "name":"dogname", "value":"REDACTED" } ] } ]
  ```

  If an exception is enabled on the rule, the "dogname" value will appear in the log.

  ```
   "rateBasedRuleList":[ {"rateBasedRuleId": ...,
                          "rateBasedRuleName":"RateBasedRule", "limitKey":"CUSTOMKEYS",
                          "maxRateAllowed":100, "evaluationWindowSec":"120", "customValues":[
                          {"key":"HEADER", "name":"dogname", "value":"ELLA" } ] } ]
  ```

**Warning**  
The data protection feature may potentially affect troubleshooting AWS WAF capabilities. These settings can cause unexpected detection and mitigation behaviors. Limit data protection for specific parameters to only those that are absolutely necessary.

# Data protection limitations
<a name="data-protection-limitations"></a>

The following are limitations to consider when using data protection.

## QueryString and SingleQueryArg
<a name="queries"></a>

**QueryString Protection**
+ Data protection on `QueryString` applies to all query arguments, substituting/hashing both keys and values according to the specified settings.

**QueryString in `RuleMatch` details and `RateBased` rule lists**
+ If data protection is applied to a single-query argument, then the entire query string will be substituted/hashed in the `RuleMatchDetails` and `RateBasedRule` section in full logs.
+ If different protection methods are specified (substitution and hashing) in multiple single-query arguments, the stricter method, substitution, will be applied to the entire query string in the `RuleMatchDetails` and `RateBasedRule` section in full logs.

## Cookies
<a name="cookies"></a>

**Note**  
 Data protection is only applied to the values of the cookie when the single header cookie is protected. 

**Single cookie in `RuleMatchDetails` and `RateBasedRule` lists**
+ If data protection is applied to a single cookie, then the entire cookie header will be substituted/hashed in the `RuleMatchDetails` and `RateBasedRule` section in full logs.
+ If different protection methods are specified (substitution and hashing), the stricter method, substitution, will be applied to the entire cookie in the `RuleMatchDetails` and `RateBasedRule` section in full logs.

# Examples of data protection
<a name="data-protection-examples"></a>

This section provides log examples of data protection logging of protection pack (web ACL) traffic.

## DataProtection hashing
<a name="dataprotection-hashing"></a>

Webacl config

```
"data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "SINGLE_QUERY_ARGUMENT",
                        "field_keys": [
                            "hoppy"
                        ]
                    },
                    "action": "HASH",
                    "exclude_rule_match_details": false,
                    "exclude_rate_based_details": false
                }
             ]
           }
```

Example DataProtection hashing: Log entry with the SingleQuery argument "hoppy" protected.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [{
        "ruleId": "ProtectedSQLIHeadersVisibleInSTM",
        "action": "COUNT",
        "ruleMatchDetails": [{
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": [ "z6hpYAFaMYdtiTeHhxnN5ydgRE5E1WgyVIdgqH0D3iM=" ],
                "matchedFieldName": "hoppy"
        }]
    }],
"requestHeadersInserted": null,
"responseCodeSent": null,
"httpRequest": {
    "clientIp": "54.239.98.137",
    "country": "US",
    "headers": [{
        "name": "X-Forwarded-For",
        "value": "54.239.98.137"
    }, {
        "name": "X-Forwarded-Proto",
        "value": "https"
    }, {
        "name": "X-Forwarded-Port",
        "value": "443"
    }, {
        "name": "Host",
        "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
    }, {
        "name": "X-Amzn-Trace-Id",
        "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
    }, {
        "name": "Accept-Encoding",
        "value": "gzip"
    }, {
        "name": "User-Agent",
        "value": "okhttp/3.12.1"
    }],
    "uri": "/CanaryTest",
    "args": "hoppy=z6hpYAFaMYdtiTeHhxnN5ydgRE5E1WgyVIdgqH0D3iM=&yellow=hello&x-hoppy-extra=generic-%3Cwords%3E-in-angle-brackets",
    "httpVersion": "HTTP/1.1",
    "httpMethod": "GET",
    "requestId": "FepO0F8fIAMEqoQ="
},
"labels": [{
    "name": "awswaf:forwardedip:geo:country:US"
}, {
    "name": "awswaf:forwardedip:geo:region:US-VA"
}]
}
```

## DataProtection substitution
<a name="dataprotection-substitution"></a>

Webacl Config

```
"data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "SINGLE_QUERY_ARGUMENT",
                        "field_keys": [
                            "hoppy"
                        ]
                    },
                    "action": "SUBSTITUTION",
                    "exclude_rule_match_details": false,
                    "exclude_rate_based_details": false
                }
             ]
           }
```

Example DataProtection substitution: Log entry with Single Query Argument “hoppy” protected

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": []
"requestHeadersInserted": null,
"responseCodeSent": null,
"httpRequest": {
    "clientIp": "54.239.98.137",
    "country": "US",
    "headers": [{
        "name": "X-Forwarded-For",
        "value": "54.239.98.137"
    }, {
        "name": "X-Forwarded-Proto",
        "value": "https"
    }, {
        "name": "X-Forwarded-Port",
        "value": "443"
    }, {
        "name": "Host",
        "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
    }, {
        "name": "X-Amzn-Trace-Id",
        "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
    }, {
        "name": "Accept-Encoding",
        "value": "gzip"
    }, {
        "name": "User-Agent",
        "value": "okhttp/3.12.1"
    }],
    "uri": "/CanaryTest",
    "args": "hoppy=REDACTED&yellow=hello&x-hoppy-extra=generic-%3Cwords%3E-in-angle-brackets",
    "httpVersion": "HTTP/1.1",
    "httpMethod": "GET",
    "requestId": "FepO0F8fIAMEqoQ="
},
"labels": [{
    "name": "awswaf:forwardedip:geo:country:US"
}, {
    "name": "awswaf:forwardedip:geo:region:US-VA"
}]
}
```

## Retaining data in RuleMatchDetails
<a name="rulematchdetails-retain-data"></a>

Webacl config

```
"data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "SINGLE_HEADER",
                        "field_keys": [
                            "hoppy"
                        ]
                    },
                    "action": "HASH",
                    "exclude_rule_match_details": true,
                    "exclude_rate_based_details": false
                }
             ]
           }
```

Example of retaining data in RuleMatchDetails: Log entry with single `Header` “hoppy” protected but the value is retained only in `RuleMatchDetails`.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [{
        "ruleId": "ProtectedSQLIHeadersVisibleInSTM",
        "action": "COUNT",
        "ruleMatchDetails": [{
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "HEADER",
                "matchedData": [ "10", "AND", "1" ],
                "matchedFieldName": "hoppy"
        }]
    }],
"requestHeadersInserted": null,
"responseCodeSent": null,
"httpRequest": {
    "clientIp": "54.239.98.137",
    "country": "US",
    "headers": [{
        "name": "X-Forwarded-For",
        "value": "54.239.98.137"
    }, {
        "name": "X-Forwarded-Proto",
        "value": "https"
    }, {
        "name": "X-Forwarded-Port",
        "value": "443"
    }, {
        "name": "Host",
        "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
    }, {
        "name": "X-Amzn-Trace-Id",
        "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
    }, {
        "name": "hoppy",
        "value": "zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE="
    }, {
        "name": "Accept-Encoding",
        "value": "gzip"
    }, {
        "name": "User-Agent",
        "value": "okhttp/3.12.1"
    }, {
        "name": "hoppy",
        "value": "z6hpYAFaMYdtiTeHhxnN5ydgRE5E1WgyVIdgqH0D3iM="
    }],
    "uri": "/CanaryTest",
    "args": "happy=true",
    "httpVersion": "HTTP/1.1",
    "httpMethod": "GET",
    "requestId": "FepO0F8fIAMEqoQ="
},
"labels": [{
    "name": "awswaf:forwardedip:geo:country:US"
}, {
    "name": "awswaf:forwardedip:geo:region:US-VA"
}]
}
```

## Retaining data in rateBasedRule
<a name="ratebasedrule-retain-data"></a>

```
 "data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "SINGLE_HEADER",
                        "field_keys": [
                            "hoppy"
                        ]
                    },
                    "action": "HASH",
                    "exclude_rule_match_details": false,
                    "exclude_rate_based_details": true
                }
             ]
           }
```

Example Retaining data in rateBasedRuleList: Log entry with the Single `Header` “hoppy” protected but the value is retained only in `rateBasedRuleList`

```
{
    "timestamp": 1683355579981,
    "formatVersion": 1,
    "webaclId": ...,
    "terminatingRuleId": "RateBasedRule",
    "terminatingRuleType": "RATE_BASED",
    "action": "BLOCK",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "EXAMPLE11:rjvegx5guh:CanaryTest",
    "ruleGroupList": [],
    "rateBasedRuleList": [{
        "rateBasedRuleId": ...,
        "rateBasedRuleName": "RateBasedRule",
        "limitKey": "CUSTOMKEYS",
        "maxRateAllowed": 100,
        "evaluationWindowSec": "120",
        "customValues": [{
            "key": "HEADER",
            "name": "hoppy",
            "value": "ella"
        }]
    }],
    "nonTerminatingMatchingRules": [],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "52.46.82.45",
        "country": "FR",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "52.46.82.45"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "rjvegx5guh.execute-api.eu-west-3.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-645566cf-7cb058b04d9bb3ee01dc4036"
        }, {
            "name": "hoppy",
            "value": "zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE="
        }, {
            "name": "User-Agent",
            "value": "RateBasedRuleTestKoipOneKeyModulePV2"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip,deflate"
        }],
        "uri": "/CanaryTest",
        "args": "",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "Ed0AiHF_CGYF-DA="
    }
}
```

## Data protection for Body
<a name="dataprotection-body"></a>

AWS WAF only log subsets of Body in `RuleMatchDetails`.

Webacl config

```
 "data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "BODY"
                    },
                    "action": "SUBSTITUTE",
                    "exclude_rule_match_details": false,
                    "exclude_rate_based_details": false
                }
             ]
           }
```

Example DataProtection for Body: Log entry with Body Subsituted in `ruleMatchDetails`.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [{
        "ruleId": "ProtectedSQLIBody",
        "action": "COUNT",
        "ruleMatchDetails": [{
            "conditionType": "SQL_INJECTION",
            "sensitivityLevel": "HIGH",
            "location": "BODY",
            "matchedData": ["REDACTED"]
        }]
    }],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }, {
            "name": "cookie",
            "value": "hoppy=dog;"
        }],
        "uri": "/CanaryTest",
        "args": "baloo=abc&hoppy-query=xyz&x-hoppy-extra=generic-%3Cwords%3E-in-angle-brackets",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

## Data protection for `SINGLE_COOKIE`
<a name="single-cookie-data-protection"></a>

Webacl config

```
 "data_protection_config": {
            "data_protections": [
                {
                    "field": {
                        "field_type": "SINGLE_COOKIE",
                        "field_keys": [
                            "MILO"
                        ]
                    },
                    "action": "HASH",
                    "exclude_rule_match_details": false,
                    "exclude_rate_based_details": false
                }
             ]
           }
```

Example DataProtection for `SINGLE_COOKIE`: Log entry with a `SINGLE_COOKIE` named "MILO" protected.

The full Log shows the Cookie named MILO is protected in `ruleMatchDetails` and the cookie header. Only cookie values are protected and key names are excluded.

**Note**  
All protected fields (single header, cookie, query arg) are not case sensitive. So, for this example, "MILO" matches "milo".

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [{
        "ruleId": "ProtectedSQLIHeadersVisibleInSTM",
        "action": "COUNT",
        "ruleMatchDetails": [{
            "conditionType": "SQL_INJECTION",
            "sensitivityLevel": "HIGH",
            "location": "COOKIE",
            "matchedData": ["zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE="],
            "matchedFieldName": "milo"
        }]
    }],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }, {
            "name": "cookie",
            "value": "hoppy=dog;milo=zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE=;aws-waf-token=51c71352-41f5-4f6d-b676-c24907bdf819:EQoAZ/J+AAQAAAAA:t9wvxbw042wva7E2Y6lgud/bS6YG0CJKVAJqaRqDZ140ythKW0Zj9wKB2O8lSkYDRqf1yONcVBFo5u0eYi0tvT4rtQCXsu+KanAardW8go4QSLw4yoED59lgV7oAhGyCalAzE7ra29j+RvvZPsQyoQuDCrtoY/TvQyMTXIXzGPDC/rKBbg=="
        }],
        "uri": "/CanaryTest",
        "args": "baloo=abc&hoppy-query=xyz&x-hoppy-extra=generic-%3Cwords%3E-in-angle-brackets",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

## Data protection for all cookies
<a name="all-cookies-data-protection"></a>

You can configure data protection for cookies by using `SINGLE_HEADER`. Only cookie values are protected and key names are excluded.

```
"DataProtectionConfig": {
    "DataProtections": [
        {
            "Field": {
                "FieldType": "SINGLE_HEADER",
                "FieldKeys": ["cookie"]
            },
            "Action": "SUBSTITUTION",
            "ExcludeRuleMatchDetails": false,
            "ExcludeRateBasedDetails": false
        }
    ]
}
```

Example DataProtection for the `header ` "COOKIE": Log entry with the cookie header protected.

**Note**  
The cookie name `AWS-WAF-TOKEN` is out of scope for data protection.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionhashACL/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }, {
            "name": "cookie",
            "value": "hoppy=REDACTED;milo=REDACTED;aws-waf-token=51c71352-41f5-4f6d-b676-c24907bdf819:EQoAZ/J+AAQAAAAA:t9wvxbw042wva7E2Y6lgud/bS6YG0CJKVAJqaRqDZ140ythKW0Zj9wKB2O8lSkYDRqf1yONcVBFo5u0eYi0tvT4rtQCXsu+KanAardW8go4QSLw4yoED59lgV7oAhGyCalAzE7ra29j+RvvZPsQyoQuDCrtoY/TvQyMTXIXzGPDC/rKBbg=="
        }],
        "uri": "/CanaryTest",
        "args": "baloo=xyz=&hoppy-query=abc&x-hoppy-extra=abc",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

## Data protection for single query arguments
<a name="single-query-argument"></a>

You can configure data protection for a query string by using `SINGLE_QUERY_ARGUMENT`. This affects the keys and values of all query args. For the following examples, the original query string was `baloo=10 AND 1=1&hoppy=10 AND 1=1&x-hoppy-extra=generic-%3Cwords`.

Webacl config

```
"DataProtectionConfig": {
   "DataProtections": [
        {
            "Field": {
                "FieldType": "SINGLE_QUERY_ARGUMENT",
                "FieldKeys": ["hoppy"]
            },
            "Action": "SUBSTITUTION",
            "ExcludeRuleMatchDetails": false,
            "ExcludeRateBasedDetails": false
        }
    ]
}
```

Example DataProtection for `SINGLE_QUERY_ARGUEMENT`: Log entry with "hoppy" query string protected with substitution.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionSubstituteQueryString/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [
      {
        "ruleId": "ProtectedHoppyQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": ["REDACTED"],
                "matchedFieldName": "hoppy"
            }]
      },
      {
        "ruleId": "FullQueryStringInspectionWhichDetectsTheFirstFieldWithSQLi_Baloo_IsAlsoMaskedMasked",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "QUERY_ARGS",
                "matchedData": ["REDACTED"],
            }]
      },
      {
        "ruleId": "ProtectedBalooQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": [ "10", "AND", "1" ],
                "matchedFieldName": "baloo"
            }]
      }
    ],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }],
        "uri": "/CanaryTest",
        "args": "baloo=10 AND 1=1&hoppy=REDACTED&x-hoppy-extra=generic-%3Cwords",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

## Data protection for query strings
<a name="data-protection-query-string"></a>

You can configure data protection for a query string by using `QUERY_STRING`. This affects the keys and values of all query args. For the following examples, the original query string was `baloo=10 AND 1=1&hoppy-query=10 AND 1=1&x-hoppy-extra=generic-%3Cwords`.

Webacl config

```
"DataProtectionConfig": {
 "DataProtections": [
 {
 "Field": {
 "FieldType": "QUERY_STRING"
 },
 "Action": "SUBSTITUTION",
 "ExcludeRuleMatchDetails": false,
 "ExcludeRateBasedDetails": false
 }
 ]
}
```

Example DataProtection for `QUERY_STRING`: Log entry with query string protected with substitution.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionSubstituteQueryString/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [
      {
        "ruleId": "ProtectedHoppyQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "QUERY_STRING",
                "matchedData": ["REDACTED"]
            }]
      },
      {
        "ruleId": "ProtectedBalooQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": [ "REDACTED" ],
                "matchedFieldName": "REDACTED"
            }]
      }
    ],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }],
        "uri": "/CanaryTest",
        "args": "REDACTED",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

## Data protection for multiple query arguments
<a name="data-protection-multiple-query-arguments"></a>

You can configure data protection for individual query args by using `SINGLE_QUERY_ARGUMENT`. When reporting local information we use local protections. However, strings that matched in query string and cookie header have many protection configs that could apply. To simplify, the strictest protection for `RuleMatchDetails` is applied, even if it doesn't overlap with the specific data range that matched.

For the following examples, the original query string was `baloo=is_a_good_boy&hoppy=likes_to_sleep&x-hoppy-extra=10 AND 1=1`.

```
"DataProtectionConfig": {
    "DataProtections": [
        {
            "Field": {
                "FieldType": "SINGLE_QUERY_ARGUMENT",
                "FieldKeys": ["hoppy"]
            },
            "Action": "SUBSTITUTION",
            "ExcludeRuleMatchDetails": false,
            "ExcludeRateBasedDetails": false
        },
        {
            "Field": {
                "FieldType": "SINGLE_QUERY_ARGUMENT",
                "FieldKeys": ["baloo"]
            },
            "Action": "HASH",
            "ExcludeRuleMatchDetails": false,
            "ExcludeRateBasedDetails": false
        }
    ]
}
```

Example DataProtection for multiple query arguments.

```
{
    "timestamp": 1738705092889,
    "formatVersion": 1,
    "webaclId": "arn:aws:wafv2:us-east-1:111122223333:regional/webacl/DataProtectionSubstituteQueryString/4eede063-e611-44f5-b357-ffc9d7b7fed5",
    "terminatingRuleId": "Default_Action",
    "terminatingRuleType": "REGULAR",
    "action": "ALLOW",
    "terminatingRuleMatchDetails": [],
    "httpSourceName": "APIGW",
    "httpSourceId": "746533260405:xt7v59bhn7:ABC",
    "ruleGroupList": [],
    "rateBasedRuleList": [],
    "nonTerminatingMatchingRules": [
      {
        "ruleId": "ProtectedHoppyQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": ["REDACTED"],
                "matchedFieldName": "hoppy"
            }]
      },
      {
        "ruleId": "ProtectedBalooQueryArg",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "SINGLE_QUERY_ARG",
                "matchedData": ["zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE="],
                "matchedFieldName": "baloo"
            }]
      },
      {
        "ruleId": "FullQueryStringDetects_x-hoppy-extra_IsSubstituted",
        "action": "COUNT",
        "ruleMatchDetails": [
            {
                "conditionType": "SQL_INJECTION",
                "sensitivityLevel": "HIGH",
                "location": "QUERY_ARGS",
                "matchedData": ["REDACTED"],  // Harshest of Protection Config
            }]
      }
    ],
    "requestHeadersInserted": null,
    "responseCodeSent": null,
    "httpRequest": {
        "clientIp": "54.239.98.137",
        "country": "US",
        "headers": [{
            "name": "X-Forwarded-For",
            "value": "54.239.98.137"
        }, {
            "name": "X-Forwarded-Proto",
            "value": "https"
        }, {
            "name": "X-Forwarded-Port",
            "value": "443"
        }, {
            "name": "Host",
            "value": "xt7xxx9bhn7.gamma.execute-api.us-east-1.amazonaws.com"
        }, {
            "name": "X-Amzn-Trace-Id",
            "value": "Root=1-67a288c4-27acb3cd5795dd8456b7e3c3"
        }, {
            "name": "Accept-Encoding",
            "value": "gzip"
        }, {
            "name": "User-Agent",
            "value": "okhttp/3.12.1"
        }],
        "uri": "/CanaryTest",
        "args": "baloo=zuomr2mxQxofg6EI6f7hMNGaJhhPxt0rFVAXog6FLxE=&hoppy=REDACTED&x-hoppy-extra=10 AND 1=1",
        "httpVersion": "HTTP/1.1",
        "httpMethod": "GET",
        "requestId": "FepO0F8fIAMEqoQ="
    },
    "labels": [{
        "name": "awswaf:forwardedip:geo:country:US"
    }, {
        "name": "awswaf:forwardedip:geo:region:US-VA"
    }]
}
```

**Note**  
You cannot specify both **QueryString Masking** and **Single Query Arg Masking** in the same webACL.

# Configuring data protection for a protection pack (web ACL)
<a name="data-protection-configure"></a>

This section provides instructions for configuring data protection for a protection pack (web ACL).

**To configure data protection for a protection pack (web ACL)**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **protection packs (web ACLs)**.

1. Choose the name of the protection pack (web ACL) that you want to enable data protection for. The console takes you to the protection pack (web ACL)'s description, where you can edit it.

1. On the **Logging and metrics** tab, in the **Data protection settings** pane, choose **Enable** or **Edit**.

1. Choose the scope **Global** and then make your field data protection selections. For each field data protection configuration, you can also specify exceptions to exclude from the protection behavior. 

1. When you've completed your selections, choose **Save**. The interface returns to the **Logging and metrics** tab where your selections are summarized.

# Testing and tuning your AWS WAF protections
<a name="web-acl-testing"></a>

This section provides guidance for testing and tuning your AWS WAF protection packs (web ACLs), rules, rule groups, IP sets, and regex pattern sets.

We recommend that you test and tune any changes to your AWS WAF protection pack (web ACL) before applying them to your website or web application traffic. 

**Production traffic risk**  
Before you deploy your protection pack (web ACL) implementation for production traffic, test and tune it in a staging or testing environment until you are comfortable with the potential impact to your traffic. Then test and tune the rules in count mode with your production traffic before enabling them. 

This section also provides general guidance for testing your use of rule groups that are managed by someone else. These include AWS Managed Rules rule groups, AWS Marketplace managed rule groups, and rule groups that are shared with you by another account. For these rule groups, also follow any guidance that you get from the rule group provider.
+ For the Bot Control AWS Managed Rules rule group, also see [Testing and deploying AWS WAF Bot Control](waf-bot-control-deploying.md). 
+ For the account takeover prevention AWS Managed Rules rule group, also see [Testing and deploying ATP](waf-atp-deploying.md). 
+ For the account creation fraud prevention AWS Managed Rules rule group, also see [Testing and deploying ACFP](waf-acfp-deploying.md). 

**Temporary inconsistencies during updates**  
When you create or change a protection pack (web ACL) or other AWS WAF resources, the changes take a small amount of time to propagate to all areas where the resources are stored. The propagation time can be from a few seconds to a number of minutes. 

The following are examples of the temporary inconsistencies that you might notice during change propagation: 
+ After you create a protection pack (web ACL), if you try to associate it with a resource, you might get an exception indicating that the protection pack (web ACL) is unavailable. 
+ After you add a rule group to a protection pack (web ACL), the new rule group rules might be in effect in one area where the protection pack (web ACL) is used and not in another.
+ After you change a rule action setting, you might see the old action in some places and the new action in others. 
+ After you add an IP address to an IP set that is in use in a blocking rule, the new address might be blocked in one area while still allowed in another.

# Testing and tuning high-level steps
<a name="web-acl-testing-high-level"></a>

This section provides a checklist of the steps for testing changes to your web ACL, including any rules or rule groups that it uses. 

**Note**  
To follow the guidance in this section, you need to understand how to create and manage AWS WAF protections like protection packs (web ACLs), rules, and rule groups. That information is covered in earlier sections of this guide.

**To test and tune your protection pack (web ACL)**

Perform these steps first in a test environment, then in production.

1. 

**Prepare for testing**

   Prepare your monitoring environment, switch your new AWS WAF protections to count mode for testing, and create any resource associations that you need. 

   See [Preparing for testing your AWS WAF protections](web-acl-testing-prep.md). 

1. 

**Monitor and tune in test and production environments**

   Monitor and adjust your AWS WAF protections first in a test or staging environment, then in production, until you're satisfied that they can handle traffic as you need them to. 

   See [Monitoring and tuning your AWS WAF protections](web-acl-testing-activities.md). 

1. 

**Enable your protections in production**

   When you're satisfied with your test protections, switch them to production mode, clean up any unnecessary testing artifacts, and continue monitoring.

   See [Enabling your protections in production](web-acl-testing-enable-production.md). 

After you've finished implementing your changes, continue monitoring your web traffic and protections in production to make sure that they're working as you want them to. Web traffic patterns can change over time, so you might need to adjust the protections occasionally.

# Preparing for testing your AWS WAF protections
<a name="web-acl-testing-prep"></a>

This section describes how to get set up to test and tune your AWS WAF protections. 

**Note**  
To follow the guidance in this section, you need to understand generally how to create and manage AWS WAF protections like protection packs (web ACLs), rules, and rule groups. That information is covered in earlier sections of this guide.

**To prepare for testing**

1. 

**Enable protection pack (web ACL) logging, Amazon CloudWatch metrics, and web request sampling for the protection pack (web ACL)**

   Use logging, metrics, and sampling to monitor the interaction of the protection pack (web ACL) rules with your web traffic. 
   + **Logging** – You can configure AWS WAF to log the web requests that a protection pack (web ACL) evaluates. You can send logs to CloudWatch logs, an Amazon S3 bucket, or an Amazon Data Firehose delivery stream. You can redact fields and apply filtering. For more information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 
   + **Amazon Security Lake** – You can configure Security Lake to collect protection pack (web ACL) data. Security Lake collects log and event data from various sources for normalization, analysis, and management. For information about this option, see [What is Amazon Security Lake?](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) and [Collecting data from AWS services](https://docs.aws.amazon.com/security-lake/latest/userguide/internal-sources.html) in the *Amazon Security Lake user guide*. 
   + **Amazon CloudWatch metrics** – In your protection pack (web ACL) configuration, provide metric specifications for everything that you want to monitor. You can view metrics through the AWS WAF and CloudWatch consoles. For more information, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 
   + **Web request sampling** – You can view a sample of all web requests that your protection pack (web ACL) evaluates. For information about web request sampling, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

1. 

**Set your protections to Count mode**

   In your protection pack (web ACL) configuration, switch anything that you want to test to count mode. This causes the test protections to record matches against web requests without altering how the requests are handled. You'll be able to see the matches in your metrics, logs, and sampled requests, to verify the match criteria and to understand what the effects might be on your web traffic. Rules that add labels to matching requests will add labels regardless of the rule action. 
   + **Rule defined in the protection pack (web ACL)** – Edit the rules in the protection pack (web ACL) and set their actions to Count. 
   + **Rule group** – In your protection pack (web ACL) configuration, edit the rule statement for the rule group and, in the **Rules** pane, open the **Override all rule actions** dropdown and choose **Count**. If you manage the protection pack (web ACL) in JSON, add the rules to the `RuleActionOverrides` settings in the rule group reference statement, with `ActionToUse` set to Count. The following example listing shows overrides for two rules in the `AWSManagedRulesAnonymousIpList` AWS Managed Rules rule group. 

     ```
       "ManagedRuleGroupStatement": {
         "VendorName": "AWS",
         "Name": "AWSManagedRulesAnonymousIpList",
           "RuleActionOverrides": [
             {
               "ActionToUse": {
                 "Count": {}
               },
               "Name": "AnonymousIPList"
             },
             {
               "ActionToUse": {
                 "Count": {}
               },
               "Name": "HostingProviderIPList"
             }
           ],
           "ExcludedRules": []
         }
       },
     ```

     For more information about rule action overrides, see [Overriding rule actions in a rule group](web-acl-rule-group-settings.md#web-acl-rule-group-rule-action-override).

     For your own rule group, don't modify the rule actions in the rule group itself. Rule group rules with Count action don't generate the metrics or other artifacts that you need for your testing. In addition, changing a rule group affects all protection packs (web ACLs) that use it, while the changes inside the protection pack (web ACL) configuration only affect the single protection pack (web ACL). 
   + **protection pack (web ACL)** – If you're testing a new protection pack (web ACL), set the default action for the protection pack (web ACL) to allow requests. This lets you try out the web ACL without affecting traffic in any way. 

   In general, count mode generates more matches than production. This is because a rule that counts requests doesn't stop the evaluation of the request by the protection pack (web ACL), so rules that run later in the protection pack (web ACL) might also match the request. When you change your rule actions to their production settings, rules that allow or block requests will terminate the evaluation of requests that they match. As a result, matching requests will generally be inspected by fewer rules in the protection pack (web ACL). For more information about the effects of rule actions on the overall evaluation of a web request, see [Using rule actions in AWS WAF](waf-rule-action.md). 

   With these settings, your new protections won't alter web traffic, but will generate match information in metrics, protection pack (web ACL) logs, and request samples. 

1. 

**Associate the protection pack (web ACL) with a resource**

   If the protection pack (web ACL) isn't already associated with the resource, associate it. 

   See [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md).

You're now ready to monitor and tune your protection pack (web ACL). 

# Monitoring and tuning your AWS WAF protections
<a name="web-acl-testing-activities"></a>

Monitor and tune your AWS WAF protections.

**Note**  
To follow the guidance in this section, you need to understand generally how to create and manage AWS WAF protections like protection packs (web ACLs), rules, and rule groups. That information is covered in earlier sections of this guide.

Monitor web traffic and rule matches to verify the behavior of the protection pack (web ACL). If you find problems, adjust your rules to correct and then monitor to verify the adjustments. 

Repeat the following procedure until the protection pack (web ACL) is managing your web traffic as you need it to. 

**To monitor and tune**

1. 

**Monitor traffic and rule matches**

   Make sure that traffic is flowing and that your test rules are finding matching requests. 

   Look for the following information for the protections that you're testing: 
   + **Logs** – Access information about the rules that match a web request: 
     + **Your rules** - Rules in the protection pack (web ACL) that have Count action are listed under `nonTerminatingMatchingRules`. Rules with Allow or Block are listed as the `terminatingRule`. Rules with CAPTCHA or Challenge can be either terminating or non-terminating, and so are listed under one of the two categories, according to the result of the rule match.
     + **Rule groups** - Rule groups are identified in the `ruleGroupId` field, with their rule matches categorized the same as for standalone rules. 
     + **Labels** - Labels that rules have applied to the request are listed in the `Labels` field.

     For more information, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).
   + **Amazon CloudWatch metrics** – You can access the following metrics for your protection pack (web ACL) request evaluation. 
     + **Your rules** – Metrics are grouped by the rule action. For example, when you test a rule in Count mode, its matches are listed as `Count` metrics for the protection pack (web ACL). 
     + **Your rule groups** – The metrics for your rule groups are listed under the rule group metrics. 
     + **Rule groups owned by another account** – Rule group metrics are generally visible only to the rule group owner. However, if you override the rule action for a rule, the metrics for that rule will be listed under your protection pack (web ACL) metrics. Additionally, labels added by any rule group are listed in your protection pack (web ACL) metrics. 

       Count action rules in rule groups do NOT emit web ACL dimension metrics - only Rule, RuleGroup, and Region dimensions. This applies even when the rule group is referenced in a web ACL.

       Rule groups in this category are [AWS Managed Rules for AWS WAF](aws-managed-rule-groups.md), [AWS Marketplace rule groups](marketplace-rule-groups.md), [Recognizing rule groups provided by other services](waf-service-owned-rule-groups.md), and rule groups that are shared with you by another account. When a protection pack (web ACL) is deployed through Firewall Manager, any rules within the WebACL that have a Count action will not display their metrics in the member account.
     + **Labels** - Labels that were added to a web request during evaluation are listed in the protection pack (web ACL) label metrics. You can access the metrics for all labels, regardless of whether they were added by your rules and rule groups or by rules in a rule group that another account owns. 

     For more information, see [Viewing metrics for your web ACL](web-acl-testing-view-metrics.md).
   + **protection pack (web ACL) traffic overview dashboards** – Access summaries of the web traffic that a protection pack (web ACL) has evaluated by going to the protection pack (web ACL)'s page in the AWS WAF console and opening the **Traffic overview** tab. 

     The traffic overview dashboards provide near real-time summaries of the Amazon CloudWatch metrics that AWS WAF collects when it evaluates your application web traffic. 

     For more information, see [Traffic overview dashboards for protection packs (web ACLs)](web-acl-dashboards.md).
   + **Sampled web requests** – Access information for the rules that match a sampling of the web requests. The sample information identifies matching rules by the metric name for the rule in the protection pack (web ACL). For rule groups, the metric identifies the rule group reference statement. For rules inside rule groups, the sample lists the matching rule name in `RuleWithinRuleGroup`. 

     For more information, see [Viewing a sample of web requests](web-acl-testing-view-sample.md).

1. 

**Configure mitigations to address false positives**

   If you determine that a rule is generating false positives, by matching web requests when it shouldn't, the following options can help you tune your protection pack (web ACL) protections to mitigate. 

**Correcting rule inspection criteria**  
For your own rules, you often just need to adjust the settings that you're using to inspect web requests. Examples include changing the specifications in a regex pattern set, adjusting the text transformations that you apply to a request component before inspection, or switching to using a forwarded IP address. See the guidance for the rule type that's causing problems, under [Using rule statements in AWS WAF](waf-rule-statements.md). 

**Correcting more complex problems**  
For inspection criteria that you don't control and for some complex rules, you might need to make other changes, like adding rules that explicitly allow or block requests or that eliminate requests from evaluation by the problematic rule. Managed rule groups most commonly need this type of mitigation, but other rules can too. Examples include the rate-based rule statement and the SQL injection attack rule statement. 

   What you do to mitigate false positives depends on your use case. The following are common approaches:
   + **Add a mitigating rule** – Add a rule that runs before the new rule and that explicitly allows requests that are causing false positives. For information about rule evaluation order in a web ACL, see [Setting rule priority](web-acl-processing-order.md).

     With this approach, the allowed requests are sent to the protected resource, so they never reach the new rule for evaluation. If the new rule is a paid managed rule group, this approach can also help contain the cost of using the rule group. 
   + **Add a logical rule with a mitigating rule** – Use logical rule statements to combine the new rule with a rule that excludes the false positives. For information, see [Using logical rule statements in AWS WAF](waf-rule-statements-logical.md).

     For example, say you're adding an SQL injection attack match statement that's generating false positives for a category of requests. Create a rule that matches those requests, and then combine the rules using logical rule statements so that you match only on requests that both don't match the false positives criteria and do match the SQL injection attack criteria. 
   + **Add a scope-down statement** – For rate-based statements and managed rule group reference statements, exclude requests that result in false positives from evaluation by adding a scope-down statement inside the main statement. 

     A request that doesn't match the scope-down statement never reaches the rule group or rate-based evaluation. For information about scope-down statements, see [Using scope-down statements in AWS WAF](waf-rule-scope-down-statements.md). For an example, see [Excluding IP range from bot management](waf-bot-control-example-scope-down-ip.md). 
   + **Add a label match rule** – For rule groups that use labeling, identify the label that the problematic rule is applying to requests. You might need to set the rule group rules in count mode first, if you haven't already done that. Add a label match rule, positioned to run after the rule group, that matches against the label that's being added by the problematic rule. In the label match rule, you can filter the requests that you want to allow from those that you want to block. 

     If you use this approach, when you're finished testing, keep the problematic rule in count mode in the rule group, and keep your custom label match rule in place. For information about label match statements, see [Label match rule statement](waf-rule-statement-type-label-match.md). For examples, see [Allowing a specific blocked bot](waf-bot-control-example-allow-blocked-bot.md) and [ATP example: Custom handling for missing and compromised credentials](waf-atp-control-example-user-agent-exception.md). 
   + **Change the version of a managed rule group** – For versioned managed rule groups, change the version that you're using. For example, you could switch back to the last static version that you were using successfully. 

     This is usually a temporary fix. You might change the version for your production traffic while you continue testing the latest version in your test or staging environment, or while you wait for a more compatible version from the provider. For information about managed rule group versions, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md).

When you're satisfied that the new rules are matching requests as you need them to, move to the next stage of your testing and repeat this procedure. Perform the final stage of testing and tuning in your production environment.

# Viewing metrics for your web ACL
<a name="web-acl-testing-view-metrics"></a>

This section describes how to view metrics for your protection pack (web ACL).

After you've associated a protection pack (web ACL) with one or more AWS resources, you can view the resulting metrics for the association in an Amazon CloudWatch graph. 

For information about AWS WAF metrics, see [AWS WAF metrics and dimensions](waf-metrics.md). For information about CloudWatch metrics, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html). 

For each of your rules in a protection pack (web ACL) and for all the requests that an associated resource forwards to AWS WAF for a protection pack (web ACL), CloudWatch lets you do the following:
+ View data for the preceding hour or preceding three hours.
+ Change the interval between data points.
+ Change the calculation that CloudWatch performs on the data, such as maximum, minimum, average, or sum.

**Note**  
AWS WAF with CloudFront is a global service and metrics are available only when you choose the **US East (N. Virginia)** Region in the AWS Management Console. If you choose another Region, no AWS WAF metrics will appear in the CloudWatch console.

**To view data for the rules in a protection pack (web ACL)**

1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. If necessary, change the Region to the one where your AWS resources are located. For CloudFront, choose the US East (N. Virginia) Region.

1. In the navigation pane, under **Metrics**, choose **All metrics** and then search under the **Browse** tab for `AWS::WAFV2`. 

1. Select the check box for the protection pack (web ACL) that you want to view data for.

1. Change the applicable settings:  
**Statistic**  
Choose the calculation that CloudWatch performs on the data.  
**Time range**  
Choose whether you want to view data for the preceding hour or the preceding three hours.  
**Period**  
Choose the interval between data points in the graph.  
**Rules**  
Choose the rules for which you want to view data.  
If you change the name of a rule and you want the rule's metric name to reflect the change, you must update the metric name as well. AWS WAF doesn't automatically update the metric name for a rule when you change the rule name. You can change the metric name when you edit the rule in the console, by using the rule JSON editor. You can also change both names through the APIs and in any JSON listing that you use to define your protection pack (web ACL) or rule group.

   Note the following:
   + If you recently associated a protection pack (web ACL) with an AWS resource, you might need to wait a few minutes for data to appear in the graph and for the metric for the protection pack (web ACL) to appear in the list of available metrics.
   + If you associate more than one resource with a protection pack (web ACL), the CloudWatch data will include requests for all of them.
   + You can hover the cursor over a data point to get more information.
   + The graph doesn't refresh itself automatically. To update the display, choose the refresh (![\[Icon to refresh the CloudWatch graph\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/cloudwatch-refresh-icon.png)) icon.

For more information about CloudWatch metrics, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). 

# Traffic overview dashboards for protection packs (web ACLs)
<a name="web-acl-dashboards"></a>

This section describes the protection pack (web ACL) traffic overview dashboards in the AWS WAF console. After you associate a protection pack (web ACL) with one or more AWS resources and enable metrics for the protection pack (web ACL), you can access summaries of the web traffic that the protection pack (web ACL) evaluates by going to the protection pack (web ACL)'s **Traffic overview** tab in the AWS WAF console. The dashboards include near real-time summaries of the Amazon CloudWatch metrics that AWS WAF collects when it evaluates your application web traffic, including specialized AI bot and agent activity analysis.

**Note**  
If you don't see anything on the dashboards, make sure you have metrics enabled for the protection pack (web ACL). 

The protection pack (web ACL)'s **Traffic overview** tab contains tabbed dashboards with the following categories of information: 
+ **Top security insights** – Insights into your AWS WAF protections that AWS WAF obtains by directly querying the Amazon CloudWatch logs. The rest of the dashboard uses the CloudWatch metrics. These insights provide richer information, but incur the added costs of querying the CloudWatch logs. For information about the additional costs, see [Amazon CloudWatch Logs Pricing](https://aws.amazon.com/cloudwatch/pricing/). 
+ **AI Traffic Analysis** – Web requests analyzed for AI bot and agent activity, including bot identification, intent classification, access patterns, and temporal trends. This tab is available when your protection pack (web ACL) receives AI bot traffic
+ **All traffic** – All web requests that the protection pack (web ACL) evaluates. 

  The dashboard focus is on terminating actions, but you can view the matches for count rules in the following locations: 
  + **Top 10 rules** pane of this dashboard. Toggle **Switch to count action** to show count rule matches. 
  + **Sampled requests** tab of the protection pack (web ACL) page. This new tab includes a graph of all rule matches. For information, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 
+ **Anti-DDoS** – Web requests that the protection pack (web ACL) evaluates using the `AntiDDoSRuleSet` Anti-DDoS managed rule group.

  This tab is only available if you're using this rule group in your protection pack (web ACL).
+ **Bot Control** – Web requests that the protection pack (web ACL) evaluates using the Bot Control managed rule group. 
+ If you aren't using this rule group in your protection pack (web ACL), this tab shows the results of evaluating a sampling of your web traffic against the Bot Control rules. This gives you an idea of the bot traffic that your application receives and it's free of charge. 

  This rule group is part of the intelligent threat mitigation options that AWS WAF offers. For more information, see [AWS WAF Bot Control](waf-bot-control.md) and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md).
+ **Account takeover prevention** – Web requests that the protection pack (web ACL) evaluates using the AWS WAF Fraud Control account takeover prevention (ATP) managed rule group. This tab is only available if you're using this rule group in your protection pack (web ACL). 

  The ATP rule group is part of the AWS WAF intelligent threat mitigation offerings. For more information, see [AWS WAF Fraud Control account takeover prevention (ATP)](waf-atp.md) and [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md).
+ **Account creation fraud prevention** – Web requests that the protection pack (web ACL) evaluates using the AWS WAF Fraud Control account creation fraud prevention (ACFP) managed rule group. This tab is only available if you're using this rule group in your protection pack (web ACL). 

  The ACFP rule group is part of the AWS WAF intelligent threat mitigation offerings. For more information, see [AWS WAF Fraud Control account creation fraud prevention (ACFP)](waf-acfp.md) and [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md).

The dashboards are based on the protection pack (web ACL)'s CloudWatch metrics, and the graphs provide access to the corresponding metrics in CloudWatch. For the intelligent threat mitigation dashboards, like Bot Control, the metrics used are primarily the label metrics. 
+ For a list of the metrics that AWS WAF provides, see [AWS WAF metrics and dimensions](waf-metrics.md).
+ For information about CloudWatch metrics, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html). 

The dashboards provide summaries of your traffic patterns for the terminating actions and date range that you select. The intelligent threat mitigation dashboards include requests that the corresponding managed rule group evaluated, regardless of whether the managed rule group itself applied the terminating action. For example, if Block is selected, the **Account takeover prevention** dashboard includes information for all web requests that were both evaluated by the ATP managed rule group and blocked at some point during the protection pack (web ACL) evaluation. The requests can be blocked by the ATP managed rule group, by a rule that ran after the rule group in the protection pack (web ACL), or by the protection pack (web ACL) default action. 

# Viewing the dashboards for a protection pack (web ACL)
<a name="web-acl-dashboards-accessing"></a>

Follow the procedure in this section to access the protection pack (web ACL) dashboards and set the data filtering criteria. If you recently associated a protection pack (web ACL) with an AWS resource, you might need to wait a few minutes for data to become available in the dashboards.

The dashboards include the requests for all of the resources that you've associated with the protection pack (web ACL). 

**To view the **Traffic overview** dashboards for a protection pack (web ACL)**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **protection packs (web ACLs)** and then search for the web ACL that you're interested in. 

1. Select the protection pack (web ACL). The console takes you to the protection pack (web ACL)'s page. The **Traffic overview** tab is selected by default.

1. Change the **Data filters** settings as needed. 
   + **Terminating rule actions** – Select the terminating actions to include in the dashboards. The dashboards summarize the metrics for the web requests that had one of the selected actions applied by the protection pack (web ACL) evaluation. If you select all of the available actions, the dashboards include all evaluated web requests. For information about the actions, see [How AWS WAF handles rule and rule group actions](web-acl-rule-actions.md). 
   + **Time range** – Select the time interval to view in the dashboards. You can choose to view a time frame relative to now, for example the last 3 hours or the last week, and you can select an absolute time range from a calendar. 
   + **Time zone** – This setting applies when you specify an absolute time range. You can use your browser's local time zone or UTC (Coordinated Universal Time). 

Review the information in the tabs that you're interested in. The data filter selections apply to all of the dashboards. In the graph panes, you can hover the cursor over a data point or an area to see any additional details. 

**Count action rules**  
You can view information for count action matches in one of two places. 
+ In this **Traffic overview** tab, on the **All traffic** dashboard, find the **Top 10 rules** pane and toggle **Switch to count action**. With this toggle on, the pane shows count rule matches instead of terminating rule matches.
+ In the protection pack (web ACL)'s **Sampled requests** tab, see a graph of all rule matches and actions for the time range that you've set on the **Traffic overview** tab. For information about the **Sampled requests** tab, see [Viewing a sample of web requests](web-acl-testing-view-sample.md). 

**Amazon CloudWatch metrics**  
In the dashboard graph panes, you can access the CloudWatch metrics for the graphed data. Choose the option at the top of the graph pane or from the **⋮** (vertical ellipsis) dropdown menu inside the pane. 

**Refreshing the dashboards**  
The dashboards don't refresh automatically. To update the display, choose the refresh ![\[Icon to refresh the dashboard graph\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/cloudwatch-refresh-icon.png) icon.

# Examples of the traffic overview dashboards for protection packs (web ACLs)
<a name="web-acl-dashboards-screenshots"></a>

This section shows example screens of the traffic overview dashboards for protection packs (web ACLs). 

**Note**  
If you're already using AWS WAF to protect your application resources, you can see the dashboards for any of your protection packs (web ACLs) at its page in the AWS WAF console. For information, see [Viewing the dashboards for a protection pack (web ACL)](web-acl-dashboards-accessing.md).

**Example screen: Data filters and **All traffic** dashboard action counts**  
The following screenshot depicts the traffic overview for a protection pack (web ACL) with the **All traffic** tab selected. The data filters are set to the defaults: all terminating actions for the last three hours. 

Inside the all traffic dashboard are the action totals for the various terminating actions. Each pane lists the request count and shows an up/down arrow indicating the change since the prior three hours time range. 

![\[The AWS WAF console shows the protection pack (web ACL) page Traffic overview tab with the default data filters selected. The terminating rule action options are Block, Allow, CAPTCHA, and Challenge. Below the data filters section are tabs for all traffic, Bot Control, and Account takeover prevention.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/web-acl-dashboard-data-filters-default-top-actions.png)


**Example screen: **Bot Control** dashboard action counts**  
The following screenshot depicts action counts for the Bot Control dashboard. This shows the same totals panes for the time range, but the counts are only for requests that the Bot Control rule group evaluated. Farther down, in the **Action totals** pane, you can see the action counts throughout the specified three-hour time range. For this time range, the CAPTCHA action wasn't applied to any of the requests that the rule group evaluated.

![\[The AWS WAF console shows the top portion of the Bot Control dashboard, with action totals for the time range and action totals throughout the time range.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/web-acl-dashboard-bot-action-totals.png)


**Example screen: **AI Traffic Analysis dashboard** dashboard action counts**  
The following screenshot depicts the AI Traffic Analysis dashboard for a protection pack (web ACL). The dashboard shows AI bot activity over the selected time range with filters for bot organization, intent type, and verification status.

![\[The AWS WAF console shows the top portion of the AI Traffic Analysis dashboard, with top crawlers and top paths for the time range and action totals throughout the time range.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/waf-phantom-edge-dashboard.png)


The dashboard includes:
+ **Bot Identity panel** – Lists detected AI bots with names and organizations
+ **Intent Classification** – Categorizes bot purposes (crawling, indexing, research, etc.)
+ **Access Patterns** – Top URLs accessed by AI agents with request counts
+ **Temporal Analysis** – Hourly and daily activity trends with 14-day historical view
+ **Organization Breakdown** – Traffic volume by bot owner organization

**Example screen: **Bot Control** dashboard token status summary graphs**  
The following screenshot depicts two of the summary graphics available in the Bot Control dashboard. The **Token status** pane shows counts for the various token status labels, paired with the rule action that was applied to the request. The **IP token absent thresholds** pane shows data for requests from IPs that were sending too many requests without a token. 

Hovering over any area in the graph brings up the available information details. In the **Token status** pane in this screenshot, the mouse is hovering over a point in time, without being on any graph line, so the console displays the data for all lines at that point in time. 

![\[The AWS WAF console shows two panes for Token status and IP token absent thresholds, with similar graph lines for blocked and challenged requests in each pane. The Token status pane also has a graph for allowed requests.\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/web-acl-dashboard-bot-token-panes.png)


This section shows just a few of the traffic summaries that are provided in the protection pack (web ACL) traffic overview dashboards. To see the dashboards for any of your protection packs (web ACLs), open the protection pack (web ACL)'s page in the console. For information about how to do this, see the guidance at [Viewing the dashboards for a protection pack (web ACL)](web-acl-dashboards-accessing.md).

# Viewing a sample of web requests
<a name="web-acl-testing-view-sample"></a>

This section describes the protection pack (web ACL) **Sampled requests** tab in the AWS WAF console. In this tab, you can view a graph of all of the rule matches for web requests that AWS WAF has inspected. Additionally, if you have request sampling enabled for the protection pack (web ACL), you can see a table view of a sample of the web requests that AWS WAF has inspected. You can also retrieve sampled request information through the API call `GetSampledRequests`.

The sample of requests contains up to 100 requests that matched the criteria for a rule in the protection pack (web ACL) and another 100 requests for requests that didn't match any rules and had the protection pack (web ACL) default action applied. The requests in the sample come from all the protected resources that have received requests for your content in the previous three hours. 

When a web request matches the criteria in a rule and the action for that rule doesn't terminate the request evaluation, AWS WAF continues inspecting the web request using the subsequent rules in the protection pack (web ACL). Because of this, a web request could appear multiple times. For information about rule action behaviors, see [Using rule actions in AWS WAF](waf-rule-action.md).

**To view the all rules graph and sampled requests**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. In the navigation pane, choose **protection packs (web ACLs)**.

1. Choose the name of the protection pack (web ACL) for which you want to view requests. The console takes you to the protection pack (web ACL)'s description, where you can edit it.

1. In the **Sampled requests** tab, you can see the following: 
   + **All rules graph** – This graph shows the matching rules and rule actions for all web request evaluations that were performed during the indicated time range. 
**Note**  
The time range for this graph is set in the protection pack (web ACL)'s **Traffic overview** tab, in the **Data filters** section. For information, see [Viewing the dashboards for a protection pack (web ACL)](web-acl-dashboards-accessing.md). 
   + **Sampled requests table** – This table displays sampled request data for the last 3 hours. 
**Note**  
If you aren't seeing the samples that you expect for a managed rule group, see the section below this procedure. 

     For each entry, the table displays the following data:  
**Metric name**  
The CloudWatch metric name for the rule in the protection pack (web ACL) that matched the request. If a web request doesn't match any rule in the protection pack (web ACL), this value is **Default**.  
If you change the name of a rule and you want the rule's metric name to reflect the change, you must update the metric name as well. AWS WAF doesn't automatically update the metric name for a rule when you change the rule name. You can change the metric name when you edit the rule in the console, by using the rule JSON editor. You can also change both names through the APIs and in any JSON listing that you use to define your protection pack (web ACL) or rule group.  
**Source IP**  
Either the IP address that the request originated from or, if the viewer used an HTTP proxy or an Application Load Balancer to send the request, the IP address of the proxy or Application Load Balancer.   
**URI**  
The part of a URL that identifies a resource, for example, `/images/daily-ad.jpg`.  
**Rule inside rule group**  
If the metric name identifies a rule group reference statement, this identifies the rule inside the rule group that matched the request.   
**Action**  
Indicates the action for the corresponding rule. For information about the possible rule actions, see [Using rule actions in AWS WAF](waf-rule-action.md).  
Sampled requests for rules with Count action in rule groups are not available in the Web ACL view. Count metrics and sampled requests for rule group rules are only visible to the rule group owner.  
**Time**  
The time that AWS WAF received the request from the protected resource. 

     To display additional information about the components of a web request, choose the name of the URI in the row of the request.

**Sampled requests for rules in managed rule groups**  
The console shows metrics for rule groups with "rule inside rule group" specifying the rule that was triggered. You can view metrics for default action rulesets and rules using the most recent `RuleActionOverrides` setting. For rules using the older `ExcludedRules` setting, select the specific rule from within the ruleset from the **Sampled Requests** metrics rule dropdown.

If you see the older settings, replace them with the new settings to start making the sampled requests available through the console. You can do this through the console by editing the managed rule group in the protection pack (web ACL) and saving it. AWS WAF automatically replaces any older settings with the `RuleActionOverrides` settings and sets the rule action override to Count. For more information about these two settings, see [JSON listing: `RuleActionOverrides` replaces `ExcludedRules`](web-acl-rule-group-override-options.md#web-acl-rule-group-override-replaces-exclude).

You can access sampled requests for a rule that has the old override in place through the AWS WAF REST API, SDKs, or command line. For information, see [GetSampledRequests](https://docs.aws.amazon.com/waf/latest/APIReference/API_GetSampledRequests.html) in the *AWS WAF API Reference*.

The following shows the syntax for the command line request: 

```
aws wafv2 get-sampled-requests \
  --web-acl-arn webACL ARN \
  --rule-metric-name Metric name of the rule in the managed rule group \
  --scope=REGIONAL or CLOUDFRONT \
  --time-window StartTime=UTC timestamp,EndTime=UTC timestamp \
  --max-items 100
```

# Enabling your protections in production
<a name="web-acl-testing-enable-production"></a>

This section provides instructions for enabling your tuned protections in production.

When you've finished the final stage of testing and tuning in your production environment, enable your protections in production mode.

**Production traffic risk**  
Before you deploy your protection pack (web ACL) implementation for production traffic, test and tune it in a test environment until you are comfortable with the potential impact to your traffic. Also test and tune it in count mode with your production traffic before enabling your protections for production traffic. 

**Note**  
To follow the guidance in this section, you need to understand generally how to create and manage AWS WAF protections like protection packs (web ACLs), rules, and rule groups. That information is covered in earlier sections of this guide.

Perform these steps first in your test environment, then in production.

**Enable your AWS WAF protections in production**

1. 

**Switch to your production protections**

   Update your protection pack (web ACL) and switch your settings for production. 

   1. 

**Remove any test rules that you don't need**

      If you added test rules that you don't need in production, remove them. If you're using any label matching rules to filter the results of managed rule group rules, be sure to leave those in place. 

   1. 

**Switch to production actions**

      Change the action settings for your new rules to their intended production settings. 
      + **Rule defined in the protection pack (web ACL)** – Edit the rules in the protection pack (web ACL) and change their actions from Count to their production actions. 
      + **Rule group** – In your protection pack (web ACL) configuration of the rule group, switch rules to use their own actions or leave them with the Count action override, according to the results of your testing and tuning activities. If you're using a label matching rule to filter the results of a rule group rule, be sure to leave the override for that rule in place. 

        To switch to using a rule's action, in your protection pack (web ACL) configuration, edit the rule statement for the rule group and remove the Count override for the rule. If you manage the protection pack (web ACL) in JSON, in the rule group reference statement, remove the entry for the rule from the `RuleActionOverrides` list. 
      + **protection pack (web ACL)** – If you changed the protection pack (web ACL) default action for your tests, switch it to its production setting. 

      With these settings, your new protections will be managing web traffic as you intend. 

   When you save your protection pack (web ACL), the resources that it's associated with will be using your production settings. 

1. 

**Monitor and tune**

   To be sure that web requests are being handled as you want, closely monitor your traffic after you enable the new functionality. You'll be monitoring metrics and logs for your production rule actions, instead of the count actions that you were monitoring for in your tuning work. Keep monitoring and adjust the behavior as needed to adapt to changes in your web traffic. 

# Using AWS WAF with Amazon CloudFront
<a name="cloudfront-features"></a>

Learn how to use AWS WAF with Amazon CloudFront features.

When you create a protection pack (web ACL), you can specify one or more CloudFront distributions that you want AWS WAF to inspect. CloudFront supports two types of distributions: standard distributions that protect individual tenants, and multi-tenant distributions that protect multiple tenants through a single, shared configuration template. AWS WAF inspects web requests for both distribution types based on the rules you define in your protection packs (web ACLs), with different implementation patterns for each type.

**Topics**
+ [

## How AWS WAF works with different distribution types
](#cloudfront-features-distribution-types)
+ [

## Using AWS WAF with CloudFront Flat-Rate Pricing Plans
](#waf-cf-pricing-plans)
+ [

# Common use cases for protecting CloudFront distributions with AWS WAF
](cloudfront-waf-use-cases.md)

## How AWS WAF works with different distribution types
<a name="cloudfront-features-distribution-types"></a>

### Distribution types
<a name="distribution-types-overview"></a>

AWS WAF provides web application firewall capabilities for both standard and multi-tenant distribution CloudFront distributions.

#### Standard distributions
<a name="standard-distribution-overview"></a>

For standard distributions, AWS WAF adds protection using a single protection pack (web ACL) for each distribution. You can enable this protection by associating an existing protection pack (web ACL) with a CloudFront distribution or by using one-click protection in the CloudFront console. This lets you manage the security controls for each of your distributions independently, since any changes to a protection pack (web ACL) will only affect the distribution associated with it.

This straightforward method of protecting CloudFront distributions is optimal for providing individual domains with specific protections from a single protection pack (web ACL).

##### Standard distribution considerations
<a name="standard-waf-considerations"></a>
+ Changes to a protection pack (web ACL) affect only its associated distribution
+ Each distribution requires independent protection pack (web ACL) configuration
+ Rules and rule groups are managed separately for each distribution

#### Multi-tenant distributions
<a name="tenant-distribution-overview"></a>

For multi-tenant distributions, AWS WAF adds protection across multiple domains using a single protection pack (web ACL). Domains that are managed by multi-tenant distributions are known as distribution tenants. You can only enable AWS WAF protection for multi-tenant distributions in the CloudFront console, either during or after the multi-tenant distribution creation process. However, changes to a protection pack (web ACL) are still managed through the AWS WAF console or API. 

Multi-tenant distributions offer the flexibility to enable AWS WAF protections at two levels:
+ **Multi-tenant distribution level** – Associated protection packs (web ACLs) provide baseline security controls that apply to all applications sharing that distribution
+ **Distribution tenant level** – Individual tenants within a multi-tenant distribution can have their own protection packs (web ACLs) to implement additional security controls or override multi-tenant distribution settings

These two tiers make multi-tenant distributions optimal for sharing AWS WAF protections across multiple domains without losing the ability to customize security for an individual distribution. 

#### Multi-tenant distribution considerations
<a name="tenant-waf-considerations"></a>
+ Individual distribution tenants inherit changes made to protection packs (web ACLs) that are associated with related multi-tenant distributions
+ The protection packs (web ACLs) associated with specific distribution tenants can override settings configured at the multi-tenant protection pack (web ACL) level
+ Managed rule groups can be implemented at both distribution and distribution tenant levels
+ Application identifiers can be located in logs to track security events by distribution

### AWS WAF features by distribution type
<a name="distribution-types-comparison"></a>


**Compare protection pack (web ACL) implementations**  

| AWS WAF Feature | Standard distributions | Multi-tenant distributions | 
| --- | --- | --- | 
| Associating protection packs (web ACLs) | One protection pack (web ACL) per distribution | You can share protection packs (web ACLs) across tenants, with optional tenant-specific protection packs (web ACLs) | 
| Rule management | Rules affect a single distribution | Multi-tenant distribution rules affect all associated tenants; distribution tenant-specific rules affect only that tenant | 
| Managed rule groups | Applied to individual distributions | Can be applied at multi-tenant distribution level for all tenants or at tenant level for specific applications | 
| Logging | Standard AWS WAF logs | Logs include tenant identifiers for security event attribution | 

## Using AWS WAF with CloudFront Flat-Rate Pricing Plans
<a name="waf-cf-pricing-plans"></a>

CloudFront flat-rate pricing plans combine the Amazon CloudFront global content delivery network (CDN) with multiple AWS services and features into a monthly price with no overage charges, regardless of traffic spikes or attacks.

Flat-rate pricing plans include the following AWS services and features for a simple monthly price:
+ CloudFront CDN
+ AWS WAF and DDoS protection
+ Bot management and analytics
+ Amazon Route 53 DNS
+ Amazon CloudWatch Logs ingestion
+ TLS certificate
+ Serverless edge compute
+ Amazon S3 storage credits each month

Plans are available in Free, Pro, Business, and Premium tiers to match your application's needs. Plans do not need an annual commitment to get the best available rates. Start with the Free plan and upgrade to access more capabilities and larger usage allowances.

For more information and a complete list of plans and features, see [CloudFront flat-rate pricing plans](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/flat-rate-pricing-plan.html) in the *Amazon CloudFront Developer Guide*.

**Important**  
A valid AWS WAF protection pack (web ACL) must remain associated with your CloudFront distribution when using any pricing plan. You cannot remove the protection pack (web ACL) association unless you switch back to pay-as-you-go pricing.  
While a AWS WAF web ACL must remain associated with your distribution, you maintain full control over your security configuration. You can customize your protection by adjusting which rules are enabled or disabled in your web ACL, and modify rule settings to match your security requirements. For information about managing web ACL rules, see [AWS WAF Rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rules.html).

# Common use cases for protecting CloudFront distributions with AWS WAF
<a name="cloudfront-waf-use-cases"></a>

The following AWS WAF features work the same way for all CloudFront distributions. Considerations for multi-tenant distributions are listed following each feature scenario.

## Using AWS WAF with CloudFront custom error pages
<a name="cloudfront-features-custom-error-pages"></a>

By default, when AWS WAF blocks a web request based on the criteria that you specify, it returns HTTP status code `403 (Forbidden)` to CloudFront, and CloudFront returns that status code to the viewer. The viewer then displays a brief and sparsely formatted default message similar to the following:

```
Forbidden: You don't have permission to access /myfilename.html on this server.
```

You can override this behavior in your AWS WAF protection pack (web ACL) rules by defining custom responses. For more information about customizing response behavior using AWS WAF rules, see [Sending custom responses for Block actions](customizing-the-response-for-blocked-requests.md).

**Note**  
Responses that you customize using AWS WAF rules take precedence over any response specifications that you define in CloudFront custom error pages.

If you'd rather display a custom error message through CloudFront, possibly using the same formatting as the rest of your website, you can configure CloudFront to return to the viewer an object (for example, an HTML file) that contains your custom error message.

**Note**  
CloudFront can't distinguish between an HTTP status code 403 that is returned by your origin and one that is returned by AWS WAF when a request is blocked. This means that you can't return different custom error pages based on the different causes of an HTTP status code 403.

For more information about CloudFront custom error pages, see [Generating custom error responses](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html) in the *Amazon CloudFront Developer Guide*.

### Custom error pages in multi-tenant distributions
<a name="custom-error-pages-template-distributions"></a>

For CloudFront multi-tenant distributions, you can configure custom error pages in the following ways:
+ At the multi-tenant level - These settings apply to all tenant distributions that use the multi-tenant distribution template
+ Through AWS WAF rules - Custom responses defined in protection packs (web ACLs) take precedence over both multi-tenant distribution and tenant-level custom error pages

## Using AWS WAF with CloudFront for applications running on your own HTTP server
<a name="cloudfront-features-your-own-http-server"></a>

When you use AWS WAF with CloudFront, you can protect your applications running on any HTTP webserver, whether it's a webserver that's running in Amazon Elastic Compute Cloud (Amazon EC2) or a webserver that you manage privately. You can also configure CloudFront to require HTTPS between CloudFront and your own webserver, as well as between viewers and CloudFront.

**Requiring HTTPS between CloudFront and your own webserver**  
To require HTTPS between CloudFront and your own webserver, you can use the CloudFront custom origin feature and configure the **Origin Protocol Policy** and the **Origin Domain Name** settings for specific origins. In your CloudFront configuration, you can specify the DNS name of the server along with the port and the protocol that you want CloudFront to use when fetching objects from your origin. You should also ensure that the SSL/TLS certificate on your custom origin server matches the origin domain name you've configured. When you use your own HTTP webserver outside of AWS, you must use a certificate that is signed by a trusted third-party certificate authority (CA), for example, Comodo, DigiCert, or Symantec. For more information about requiring HTTPS for communication between CloudFront and your own webserver, see the topic [Requiring HTTPS for Communication Between CloudFront and Your Custom Origin](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-cloudfront-to-custom-origin.html) in the *Amazon CloudFront Developer Guide*.

**Requiring HTTPS between a viewer and CloudFront**  
To require HTTPS between viewers and CloudFront, you can change the **Viewer Protocol Policy** for one or more cache behaviors in your CloudFront distribution. For more information about using HTTPS between viewers and CloudFront, see the topic [Requiring HTTPS for Communication Between Viewers and CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-viewers-to-cloudfront.html) in the *Amazon CloudFront Developer Guide*. You can also bring your own SSL certificate so viewers can connect to your CloudFront distribution over HTTPS using your own domain name, for example *https://www.mysite.com*. For more information, see the topic [Configuring Alternate Domain Names and HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-procedures.html) in the *Amazon CloudFront Developer Guide*.

For multi-tenant distributions, HTTP method configurations follow this hierarchy:
+ Template-level settings define the baseline HTTP methods allowed for all tenant distributions
+ Tenant distributions can override these settings to:
  + Allow fewer methods than the multi-tenant distribution (using AWS WAF rules to block additional methods)
  + Allow more methods if the multi-tenant distribution is configured to support them
+ AWS WAF rules at both multi-tenant distribution and tenant levels can further restrict HTTP methods regardless of the CloudFront configuration

## Choosing the HTTP methods that CloudFront responds to
<a name="cloudfront-features-allowed-http-methods"></a>

When you create an Amazon CloudFront web distribution, you choose the HTTP methods that you want CloudFront to process and forward to your origin. You can choose from the following options:
+ **`GET`, `HEAD`** – You can use CloudFront only to get objects from your origin or to get object headers.
+ **`GET`, `HEAD`, `OPTIONS`** – You can use CloudFront only to get objects from your origin, get object headers, or retrieve a list of the options that your origin server supports.
+ **`GET`, `HEAD`, `OPTIONS`, `PUT`, `POST`, `PATCH`, `DELETE`** – You can use CloudFront to get, add, update, and delete objects, and to get object headers. In addition, you can perform other `POST` operations such as submitting data from a web form.

You also can use AWS WAF byte match rule statements to allow or block requests based on the HTTP method, as described in [String match rule statement](waf-rule-statement-type-string-match.md). If you want to use a combination of methods that CloudFront supports, such as `GET` and `HEAD`, then you don't need to configure AWS WAF to block requests that use the other methods. If you want to allow a combination of methods that CloudFront doesn't support, such as `GET`, `HEAD`, and `POST`, you can configure CloudFront to respond to all methods, and then use AWS WAF to block requests that use other methods.

For more information about choosing the methods that CloudFront responds to, see [Allowed HTTP Methods](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesAllowedHTTPMethods) in the topic [Values that You Specify When You Create or Update a Web Distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html) in the *Amazon CloudFront Developer Guide*.

**Allowed HTTP method configurations in multi-tenant distributions**  
For multi-tenant distributions, HTTP method configurations set at the multi-tenant distribution level apply to all tenant distributions by default. Tenant distributions can override these settings if needed.
+ If you want to use a combination of methods that CloudFront supports, such as `GET` and `HEAD`, you don't need to configure AWS WAF to block requests that use other methods.
+ If you want to allow a combination of methods that CloudFront doesn't support by default, such as `GET`, `HEAD`, and `POST`, you can configure CloudFront to respond to all methods, and then use AWS WAF to block requests that use other methods.

When implementing security headers in multi-tenant distributions, consider the following:
+ Template-level security headers provide baseline protection across all tenant distributions
+ Tenant distributions can:
  + Add new security headers not defined in the multi-tenant distribution
  + Modify values for tenant-specific headers
  + Cannot remove or override security headers set at the multi-tenant distribution level
+ Consider using multi-tenant distribution-level headers for critical security controls that should apply to all tenants

## Logging considerations
<a name="cloudfront-features-logging"></a>

Both standard and multi-tenant distributions support AWS WAF logging, but there are important differences in how logs are structured and managed:


**Logging comparison**  

| Standard distributions | Multi-tenant distributions | 
| --- | --- | 
| One log configuration per distribution | Template and tenant-level logging options | 
| Standard log fields | Additional tenant identifier fields | 
| Single destination per distribution | Separate destinations possible for multi-tenant distribution and tenant logs | 

## Additional resources
<a name="cloudfront-saas-additional-resources"></a>
+ To learn more about multi-tenant distributions, see [Configure distributions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-working-with.html) in the *Amazon CloudFront Developer Guide*.
+ To learn more about using AWS WAF with CloudFront, see [Using AWS WAF protection](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-awswaf.html) in the *Amazon CloudFront Developer Guide*.
+ To learn more about AWS WAF logs, see [Log fields for protection pack (web ACL) traffic](logging-fields.md).

# Security in your use of the AWS WAF service
<a name="security"></a>

This section explains how the shared responsibility model applies to AWS WAF.

Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.

**Note**  
This section provides standard AWS security guidance for your use of the AWS WAF service and its AWS resources, such as AWS WAF protection packs (web ACLs) and rule groups.   
For information about protecting your AWS resources using AWS WAF, see the rest of the AWS WAF guide. 

Security is a shared responsibility between AWS and you. The [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security *of* the cloud and security *in* the cloud:
+ **Security of the cloud** – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. The effectiveness of our security is regularly tested and verified by third-party auditors as part of the [AWS compliance programs](https://aws.amazon.com/compliance/programs/). To learn about the compliance programs that apply to AWS WAF, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/).
+ **Security in the cloud** – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your organization’s requirements, and applicable laws and regulations. 

This documentation helps you understand how to apply the shared responsibility model when using AWS WAF. The following topics show you how to configure AWS WAF to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your AWS WAF resources. 

**Topics**
+ [

# Protecting your data in AWS WAF
](data-protection.md)
+ [

# Using IAM with AWS WAF
](security-iam.md)
+ [

# Logging and monitoring in AWS WAF
](waf-incident-response.md)
+ [

# Validating compliance in AWS WAF
](waf-compliance.md)
+ [

# Building for resilience in AWS WAF
](disaster-recovery-resiliency.md)
+ [

# Infrastructure security in AWS WAF
](infrastructure-security.md)

# Protecting your data in AWS WAF
<a name="data-protection"></a>

The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in AWS WAF. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/). For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*.

For data protection purposes, we recommend that you protect AWS account credentials and set up individual users with AWS IAM Identity Center or AWS Identity and Access Management (IAM). That way, each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
+ Use multi-factor authentication (MFA) with each account.
+ Use SSL/TLS to communicate with AWS resources. We require TLS 1.2 and recommend TLS 1.3.
+ Set up API and user activity logging with AWS CloudTrail. For information about using CloudTrail trails to capture AWS activities, see [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html) in the *AWS CloudTrail User Guide*.
+ Use AWS encryption solutions, along with all default security controls within AWS services.
+ Use advanced managed security services such as Amazon Macie, which assists in discovering and securing sensitive data that is stored in Amazon S3.
+ If you require FIPS 140-3 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/).

We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form text fields such as a **Name** field. This includes when you work with AWS WAF or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form text fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.

AWS WAF entities—such as protection packs (web ACLs), rule groups, and IP sets—are encrypted at rest, except in certain Regions where encryption is not available, including China (Beijing) and China (Ningxia). Unique encryption keys are used for each Region. 

## Deleting AWS WAF resources
<a name="deleting-resources"></a>

You can delete the resources that you create in AWS WAF. See the guidance for each resource type in following sections.
+ [Deleting a protection pack (web ACL)](web-acl-deleting.md)
+ [Deleting a rule group](waf-rule-group-deleting.md)
+ [Deleting an IP set](waf-ip-set-managing.md#waf-ip-set-deleting)
+ [Deleting a regex pattern set](waf-regex-pattern-set-managing.md#waf-regex-pattern-set-deleting)

# Using IAM with AWS WAF
<a name="security-iam"></a>

This section explains how to use IAM with AWS WAF.



AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use AWS WAF resources. IAM is an AWS service that you can use with no additional charge.

**Topics**
+ [

## Audience
](#security_iam_audience)
+ [

## Authenticating with identities
](#security_iam_authentication)
+ [

## Managing access using policies
](#security_iam_access-manage)
+ [

# How AWS WAF works with IAM
](security_iam_service-with-iam.md)
+ [

# Identity-based policy examples for AWS WAF
](security_iam_id-based-policy-examples.md)
+ [

# AWS managed policies for AWS WAF
](security-iam-awsmanpol.md)
+ [

# Troubleshooting AWS WAF identity and access
](security_iam_troubleshoot.md)
+ [

# Using service-linked roles for AWS WAF
](using-service-linked-roles.md)

## Audience
<a name="security_iam_audience"></a>

How you use AWS Identity and Access Management (IAM) differs based on your role:
+ **Service user** - request permissions from your administrator if you cannot access features (see [Troubleshooting AWS WAF identity and access](security_iam_troubleshoot.md))
+ **Service administrator** - determine user access and submit permission requests (see [How AWS WAF works with IAM](security_iam_service-with-iam.md))
+ **IAM administrator** - write policies to manage access (see [Identity-based policy examples for AWS WAF](security_iam_id-based-policy-examples.md))

## Authenticating with identities
<a name="security_iam_authentication"></a>

Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role.

You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*.

For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*.

### AWS account root user
<a name="security_iam_authentication-rootuser"></a>

 When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*. 

### Federated identity
<a name="security_iam_authentication-federated"></a>

As a best practice, require human users to use federation with an identity provider to access AWS services using temporary credentials.

A *federated identity* is a user from your enterprise directory, web identity provider, or Directory Service that accesses AWS services using credentials from an identity source. Federated identities assume roles that provide temporary credentials.

For centralized access management, we recommend AWS IAM Identity Center. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*.

### IAM users and groups
<a name="security_iam_authentication-iamuser"></a>

An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*.

An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*.

### IAM roles
<a name="security_iam_authentication-iamrole"></a>

An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*.

IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.

## Managing access using policies
<a name="security_iam_access-manage"></a>

You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*.

Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**.

By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation.

### Identity-based policies
<a name="security_iam_access-manage-id-based-policies"></a>

Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.

Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*.

### Resource-based policies
<a name="security_iam_access-manage-resource-based-policies"></a>

Resource-based policies are JSON policy documents that you attach to a resource. Examples include IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy.

Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy.

### Other policy types
<a name="security_iam_access-manage-other-policies"></a>

AWS supports additional policy types that can set the maximum permissions granted by more common policy types:
+ **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*.
+ **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
+ **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*.
+ **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*.

### Multiple policy types
<a name="security_iam_access-manage-multiple-policies"></a>

When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*.

# How AWS WAF works with IAM
<a name="security_iam_service-with-iam"></a>

This section explains how to use the features of IAM with AWS WAF.

Before you use IAM to manage access to AWS WAF, learn what IAM features are available to use with AWS WAF.






**IAM features you can use with AWS WAF**  

| IAM feature | AWS WAF support | 
| --- | --- | 
|  [Identity-based policies](#security_iam_service-with-iam-id-based-policies)  |   Yes  | 
|  [Resource-based policies](#security_iam_service-with-iam-resource-based-policies)  |   Yes  | 
|  [Policy actions](#security_iam_service-with-iam-id-based-policies-actions)  |   Yes  | 
|  [Policy resources](#security_iam_service-with-iam-id-based-policies-resources)  |   Yes  | 
|  [Policy condition keys (service-specific)](#security_iam_service-with-iam-id-based-policies-conditionkeys)  |   Yes  | 
|  [ACLs](#security_iam_service-with-iam-acls)  |   No   | 
|  [ABAC (tags in policies)](#security_iam_service-with-iam-tags)  |   Partial  | 
|  [Temporary credentials](#security_iam_service-with-iam-roles-tempcreds)  |   Yes  | 
|  [Forward access sessions (FAS)](#security_iam_service-with-iam-principal-permissions)  |   Yes  | 
|  [Service roles](#security_iam_service-with-iam-roles-service)  |   Yes  | 
|  [Service-linked roles](#security_iam_service-with-iam-roles-service-linked)  |   Yes  | 

To get a high-level view of how AWS WAF and other AWS services work with most IAM features, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*.

## Identity-based policies for AWS WAF
<a name="security_iam_service-with-iam-id-based-policies"></a>

**Supports identity-based policies:** Yes

Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.

With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. To learn about all of the elements that you can use in a JSON policy, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.

To view examples of AWS WAF identity-based policies, see [Identity-based policy examples for AWS WAF](security_iam_id-based-policy-examples.md).

## Resource-based policies within AWS WAF
<a name="security_iam_service-with-iam-resource-based-policies"></a>

**Supports resource-based policies:** Yes

Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource-based policies are IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services.

To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.

AWS WAF uses resource based policies to support the sharing of rule groups across accounts. You share a rule group that you own with another AWS account by providing the resource-based policy settings to the AWS WAF API call `PutPermissionPolicy` or to an equivalent CLI or SDK call. For additional information, including examples and links to documentation for the other available languages, see [PutPermissionPolicy](https://docs.aws.amazon.com/waf/latest/APIReference/API_PutPermissionPolicy.html) in the AWS WAF API Reference. This functionality isn't available through other means, such as the console or CloudFormation. 

## Policy actions for AWS WAF
<a name="security_iam_service-with-iam-id-based-policies-actions"></a>

**Supports policy actions:** Yes

Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.

The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Include actions in a policy to grant permissions to perform the associated operation.



To see a list of AWS WAF actions and permissions for each, see [Actions defined by AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-actions-as-permissions) in the *Service Authorization Reference*.

Policy actions in AWS WAF use the following prefix before the action:

```
wafv2
```

To specify multiple actions in a single statement, separate them with commas.

```
"Action": [
      "wafv2:action1",
      "wafv2:action2"
         ]
```



You can specify multiple actions using wildcards (\$1). For example, to specify all actions in AWS WAF that begin with `List`, include the following action:

```
"Action": "wafv2:List*"
```

To view examples of AWS WAF identity-based policies, see [Identity-based policy examples for AWS WAF](security_iam_id-based-policy-examples.md).

### Actions that require additional permissions settings
<a name="security_iam_action-additions"></a>

Some actions require permissions that can't be completely described in [Actions defined by AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-actions-as-permissions) in the *Service Authorization Reference*. This section provides additional permissions information.

**Topics**
+ [

#### Permissions for `AssociateWebACL`
](#security_iam_action-AssociateWebACL)
+ [

#### Permissions for `DisassociateWebACL`
](#security_iam_action-DisassociateWebACL)
+ [

#### Permissions for `GetWebACLForResource`
](#security_iam_action-GetWebACLForResource)
+ [

#### Permissions for `ListResourcesForWebACL`
](#security_iam_action-ListResourcesForWebACL)

#### Permissions for `AssociateWebACL`
<a name="security_iam_action-AssociateWebACL"></a>

This section lists the permissions required to associate a protection pack (web ACL) to a resource using the AWS WAF action `AssociateWebACL`. 

For Amazon CloudFront distributions, instead of this action, use the CloudFront action `UpdateDistribution`. For information, see [UpdateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateDistribution.html) in the *Amazon CloudFront API Reference*. 

**Amazon API Gateway REST API**  
Requires permission to call API Gateway `SetWebACL` on the REST API resource type and to call AWS WAF `AssociateWebACL` on a protection pack (web ACL). 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "apigateway:SetWebACL"
    ],
    "Resource": [
        "arn:aws:apigateway:*::/restapis/*/stages/*"
    ]
}
```

**Application Load Balancer**  
Requires permission to call `elasticloadbalancing:SetWebACL` action on the Application Load Balancer resource type and to call AWS WAF `AssociateWebACL` on a protection pack (web ACL). 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "elasticloadbalancing:SetWebACL"
    ],
    "Resource": [
        "arn:aws:elasticloadbalancing:*:account-id:loadbalancer/app/*/*"
    ]
}
```

**AWS AppSync GraphQL API**  
Requires permission to call AWS AppSync `SetWebACL` on the GraphQL API resource type and to call AWS WAF `AssociateWebACL` on a protection pack (web ACL). 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "appsync:SetWebACL"
    ],
    "Resource": [
        "arn:aws:appsync:*:account-id:apis/*"
    ]
}
```

**Amazon Cognito user pool**  
Requires permission to call the Amazon Cognito `AssociateWebACL` action on the user pool resource type and to call AWS WAF `AssociateWebACL` on a protection pack (web ACL). 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "cognito-idp:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:cognito-idp:*:account-id:userpool/*"
    ]
}
```

**AWS App Runner service**  
Requires permission to call the App Runner `AssociateWebACL` action on the App Runner service resource type and to call AWS WAF `AssociateWebACL` on a web ACL. 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "apprunner:AssociateWebAcl"
    ],
    "Resource": [
        "arn:aws:apprunner:*:account-id:service/*/*"
    ]
}
```

**AWS Verified Access instance**  
Requires permission to call the `ec2:AssociateVerifiedAccessInstanceWebAcl` action on the Verified Access instance resource type and to call AWS WAF `AssociateWebACL` on a web ACL. 

```
{
    "Sid": "AssociateWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:AssociateWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "AssociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "ec2:AssociateVerifiedAccessInstanceWebAcl"
    ],
    "Resource": [
        "arn:aws:ec2:*:account-id:verified-access-instance/*"
    ]
}
```

#### Permissions for `DisassociateWebACL`
<a name="security_iam_action-DisassociateWebACL"></a>

This section lists the permissions required to disassociate a protection pack (web ACL) from a resource using the AWS WAF action `DisassociateWebACL`. 

For Amazon CloudFront distributions, instead of this action, use the CloudFront action `UpdateDistribution` with an empty protection pack (web ACL) ID. For information, see [UpdateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateDistribution.html) in the *Amazon CloudFront API Reference*. 

**Amazon API Gateway REST API**  
Requires permission to call API Gateway `SetWebACL` on the REST API resource type. Does not require permission to call AWS WAF `DisassociateWebACL`.

```
{
    "Sid": "DisassociateWebACL",
    "Effect": "Allow",
    "Action": [
        "apigateway:SetWebACL"
    ],
    "Resource": [
        "arn:aws:apigateway:*::/restapis/*/stages/*"
    ]
}
```

**Application Load Balancer**  
Requires permission to call the `elasticloadbalancing:SetWebACL` action on the Application Load Balancer resource type. Does not require permission to call AWS WAF `DisassociateWebACL`.

```
{
    "Sid": "DisassociateWebACL",
    "Effect": "Allow",
    "Action": [
        "elasticloadbalancing:SetWebACL"
    ],
    "Resource": [
        "arn:aws:elasticloadbalancing:*:account-id:loadbalancer/app/*/*"
    ]
}
```

**AWS AppSync GraphQL API**  
Requires permission to call AWS AppSync `SetWebACL` on the GraphQL API resource type. Does not require permission to call AWS WAF `DisassociateWebACL`.

```
{
    "Sid": "DisassociateWebACL",
    "Effect": "Allow",
    "Action": [
        "appsync:SetWebACL"
    ],
    "Resource": [
        "arn:aws:appsync:*:account-id:apis/*"
    ]
}
```

**Amazon Cognito user pool**  
Requires permission to call the Amazon Cognito `DisassociateWebACL` action on the user pool resource type and to call AWS WAF `DisassociateWebACL`. 

```
{
    "Sid": "DisassociateWebACL1",
    "Effect": "Allow",
    "Action": "wafv2:DisassociateWebACL",
    "Resource": "*"
},
{
    "Sid": "DisassociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "cognito-idp:DisassociateWebACL"
    ],
    "Resource": [
        "arn:aws:cognito-idp:*:account-id:userpool/*"
    ]
}
```

**AWS App Runner service**  
Requires permission to call the App Runner `DisassociateWebACL` action on the App Runner service resource type and to call AWS WAF `DisassociateWebACL`. 

```
{
    "Sid": "DisassociateWebACL1",
    "Effect": "Allow",
    "Action": "wafv2:DisassociateWebACL",
    "Resource": "*"
},
{
    "Sid": "DisassociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "apprunner:DisassociateWebAcl"
    ],
    "Resource": [
        "arn:aws:apprunner:*:account-id:service/*/*"
    ]
}
```

**AWS Verified Access instance**  
Requires permission to call the `ec2:DisassociateVerifiedAccessInstanceWebAcl` action on the Verified Access instance resource type and to call AWS WAF `DisassociateWebACL`. 

```
{
    "Sid": "DisassociateWebACL1",
    "Effect": "Allow",
    "Action": "wafv2:DisassociateWebACL",
    "Resource": "*"
},
{
    "Sid": "DisassociateWebACL2",
    "Effect": "Allow",
    "Action": [
        "ec2:DisassociateVerifiedAccessInstanceWebAcl"
    ],
    "Resource": [
        "arn:aws:ec2:*:account-id:verified-access-instance/*"
    ]
}
```

#### Permissions for `GetWebACLForResource`
<a name="security_iam_action-GetWebACLForResource"></a>

This section lists the permissions required to get the protection pack (web ACL) for a protected resource using the AWS WAF action `GetWebACLForResource`. 

For Amazon CloudFront distributions, instead of this action, use the CloudFront action `GetDistributionConfig`. For information, see [GetDistributionConfig](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_GetDistributionConfig.html) in the *Amazon CloudFront API Reference*. 

**Note**  
`GetWebACLForResource` requires the permission to call `GetWebACL`. In this context, AWS WAF uses `GetWebACL` only to verify that your account has the permission it needs to access the protection pack (web ACL) that `GetWebACLForResource` returns. When you call `GetWebACLForResource`, you might get an error indicating that your account is not authorized to perform `wafv2:GetWebACL` on the resource. AWS WAF doesn't add this type of error to the AWS CloudTrail event history. 

**Amazon API Gateway REST API, Application Load Balancer, and AWS AppSync GraphQL API**  
Require permission to call AWS WAF `GetWebACLForResource` and `GetWebACL` for a protection pack (web ACL). 

```
{
    "Sid": "GetWebACLForResource",
    "Effect": "Allow",
    "Action": [
        "wafv2:GetWebACLForResource",
        "wafv2:GetWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
}
```

**Amazon Cognito user pool**  
Requires permission to call the Amazon Cognito `GetWebACLForResource` action on the user pool resource type and to call AWS WAF `GetWebACLForResource` and `GetWebACL`. 

```
{
    "Sid": "GetWebACLForResource1",
    "Effect": "Allow",
    "Action": [
        "wafv2:GetWebACLForResource",
        "wafv2:GetWebACL"
    ],
    "Resource": [ 
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "GetWebACLForResource2",
    "Effect": "Allow",
    "Action": [
        "cognito-idp:GetWebACLForResource"
    ],
    "Resource": [
        "arn:aws:cognito-idp:*:account-id:userpool/*"
    ]
}
```

**AWS App Runner service**  
Requires permission to call the App Runner `DescribeWebAclForService` action on the App Runner service resource type and to call AWS WAF `GetWebACLForResource` and `GetWebACL`. 

```
{
    "Sid": "GetWebACLForResource1",
    "Effect": "Allow",
    "Action": [
        "wafv2:GetWebACLForResource",
        "wafv2:GetWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "GetWebACLForResource2",
    "Effect": "Allow",
    "Action": [
        "apprunner:DescribeWebAclForService"
    ],
    "Resource": [
        "arn:aws:apprunner:*:account-id:service/*/*"
    ]
}
```

**AWS Verified Access instance**  
Requires permission to call the `ec2:GetVerifiedAccessInstanceWebAcl` action on the Verified Access instance resource type and to call AWS WAF `GetWebACLForResource` and `GetWebACL`. 

```
{
    "Sid": "GetWebACLForResource1",
    "Effect": "Allow",
    "Action": [
        "wafv2:GetWebACLForResource",
        "wafv2:GetWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "GetWebACLForResource2",
    "Effect": "Allow",
    "Action": [
        "ec2:GetVerifiedAccessInstanceWebAcl"
    ],
    "Resource": [
        "arn:aws:ec2:*:account-id:verified-access-instance/*"
    ]
}
```

#### Permissions for `ListResourcesForWebACL`
<a name="security_iam_action-ListResourcesForWebACL"></a>

This section lists the permissions required to retrieve the list of protected resources for a protection pack (web ACL) using the AWS WAF action `ListResourcesForWebACL`. 

For Amazon CloudFront distributions, instead of this action, use the CloudFront action `ListDistributionsByWebACLId`. For information, see [ListDistributionsByWebACLId](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListDistributionsByWebACLId.html) in the *Amazon CloudFront API Reference*. 

**Amazon API Gateway REST API, Application Load Balancer, and AWS AppSync GraphQL API**  
Require permission to call AWS WAF `ListResourcesForWebACL` for a web ACL. 

```
{
    "Sid": "ListResourcesForWebACL",
    "Effect": "Allow",
    "Action": [
        "wafv2:ListResourcesForWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
}
```

**Amazon Cognito user pool**  
Requires permission to call the Amazon Cognito `ListResourcesForWebACL` action on the user pool resource type and to call AWS WAF `ListResourcesForWebACL`. 

```
{
    "Sid": "ListResourcesForWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:ListResourcesForWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "ListResourcesForWebACL2",
    "Effect": "Allow",
    "Action": [
        "cognito-idp:ListResourcesForWebACL"
    ],
    "Resource": [
        "arn:aws:cognito-idp:*:account-id:userpool/*"
    ]
}
```

**AWS App Runner service**  
Requires permission to call the App Runner `ListAssociatedServicesForWebAcl` action on the App Runner service resource type and to call AWS WAF `ListResourcesForWebACL`. 

```
{
    "Sid": "ListResourcesForWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:ListResourcesForWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "ListResourcesForWebACL2",
    "Effect": "Allow",
    "Action": [
        "apprunner:ListAssociatedServicesForWebAcl"
    ],
    "Resource": [
        "arn:aws:apprunner:*:account-id:service/*/*"
    ]
}
```

**AWS Verified Access instance**  
Requires permission to call the `ec2:DescribeVerifiedAccessInstanceWebAclAssociations` action on the Verified Access instance resource type and to call AWS WAF `ListResourcesForWebACL`. 

```
{
    "Sid": "ListResourcesForWebACL1",
    "Effect": "Allow",
    "Action": [
        "wafv2:ListResourcesForWebACL"
    ],
    "Resource": [
        "arn:aws:wafv2:region:account-id:regional/webacl/*/*"
    ]
},
{
    "Sid": "ListResourcesForWebACL2",
    "Effect": "Allow",
    "Action": [
        "ec2:DescribeVerifiedAccessInstanceWebAclAssociations"
    ],
    "Resource": [
        "arn:aws:ec2:*:account-id:verified-access-instance/*"
    ]
}
```

## Policy resources for AWS WAF
<a name="security_iam_service-with-iam-id-based-policies-resources"></a>

**Supports policy resources:** Yes

Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.

The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (\$1) to indicate that the statement applies to all resources.

```
"Resource": "*"
```

To see the list of AWS WAF resource types and their ARNs, see [Resources defined by AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-resources-for-iam-policies) in the *Service Authorization Reference*. To learn with which actions you can specify the ARN of each resource, see [Actions defined by AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-actions-as-permissions). To allow or deny access to a subset of AWS WAF resources, include the ARN of the resource in the `resource` element of your policy.

The ARNs of AWS WAF `wafv2` resources have the following format:

```
arn:partition:wafv2:region:account-id:scope/resource-type/resource-name/resource-id
```

For general information about ARN specifications, see [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the Amazon Web Services General Reference. 

The following lists requirements that are specific to the ARNs of `wafv2` resources: 
+ *region*: For AWS WAF resources that you use to protect Amazon CloudFront distributions, set this to `us-east-1`. Otherwise, set this to the Region you're using with your protected regional resources. 
+ *scope*: Set the scope to `global` for use with an Amazon CloudFront distribution or `regional` for use with any of the regional resources that AWS WAF supports. The regional resources are 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, and an AWS Verified Access instance. 
+ *resource-type*: Specify one of the following values: `webacl`, `rulegroup`, `ipset`, `regexpatternset`, or `managedruleset`.
+ *resource-name*: Specify the name that you gave the AWS WAF resource, or specify a wildcard (`*`) to indicate all resources that satisfy the other specifications in the ARN. You must either specify the resource name and resource ID or specify a wildcard for both. 
+ *resource-id*: Specify the ID of the AWS WAF resource, or specify a wildcard (`*`) to indicate all resources that satisfy the other specifications in the ARN. You must either specify the resource name and resource ID or specify a wildcard for both.

For example, the following ARN specifies all protection packs (web ACLs) with regional scope for the account `111122223333` in Region `us-west-1`:

```
arn:aws:wafv2:us-west-1:111122223333:regional/webacl/*/*
```

The following ARN specifies the rule group named `MyIPManagementRuleGroup` with global scope for the account `111122223333` in Region `us-east-1`:

```
arn:aws:wafv2:us-east-1:111122223333:global/rulegroup/MyIPManagementRuleGroup/1111aaaa-bbbb-cccc-dddd-example-id
```

To view examples of AWS WAF identity-based policies, see [Identity-based policy examples for AWS WAF](security_iam_id-based-policy-examples.md).

## Policy condition keys for AWS WAF
<a name="security_iam_service-with-iam-id-based-policies-conditionkeys"></a>

**Supports service-specific policy condition keys:** Yes

Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.

The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.

In addition, AWS WAF supports the following condition keys that you can use to provide fine-grained filtering for your IAM policies:
+ **wafv2:LogDestinationResource**

  This condition key takes an Amazon Resource Name (ARN) specification for the logging destination. This is the ARN that you provide for the logging destination when you use the REST API call `PutLoggingConfiguration`. 

  You can explicitly specify an ARN and you can specify filtering for the ARN. The following example specifies filtering for Amazon S3 bucket ARNs that have a specific location and prefix. 

  ```
  "Condition": { "ArnLike": { "wafv2:LogDestinationResource": "arn:aws:s3:::aws-waf-logs-suffix/custom-prefix/*" } }
  ```
+ **wafv2:LogScope**

  This condition key defines the source of the logging configuration in a string. Currently, this is always set to the default of `Customer`, which indicates that the logging destination is owned and managed by you. 

To see a list of AWS WAF condition keys, see [Condition keys for AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-policy-keys) in the *Service Authorization Reference*. To learn with which actions and resources you can use a condition key, see [Actions defined by AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html#awswafv2-actions-as-permissions).

To view examples of AWS WAF identity-based policies, see [Identity-based policy examples for AWS WAF](security_iam_id-based-policy-examples.md).

## ACLs in AWS WAF
<a name="security_iam_service-with-iam-acls"></a>

**Supports ACLs:** No 

Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.

## ABAC with AWS WAF
<a name="security_iam_service-with-iam-tags"></a>

**Supports ABAC (tags in policies):** Partial

Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes called tags. You can attach tags to IAM entities and AWS resources, then design ABAC policies to allow operations when the principal's tag matches the tag on the resource.

To control access based on tags, you provide tag information in the [condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy using the `aws:ResourceTag/key-name`, `aws:RequestTag/key-name`, or `aws:TagKeys` condition keys.

If a service supports all three condition keys for every resource type, then the value is **Yes** for the service. If a service supports all three condition keys for only some resource types, then the value is **Partial**.

For more information about ABAC, see [Define permissions with ABAC authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) in the *IAM User Guide*. To view a tutorial with steps for setting up ABAC, see [Use attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the *IAM User Guide*.

## Using temporary credentials with AWS WAF
<a name="security_iam_service-with-iam-roles-tempcreds"></a>

**Supports temporary credentials:** Yes

Temporary credentials provide short-term access to AWS resources and are automatically created when you use federation or switch roles. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) and [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*.

## Forward access sessions for service AWS WAF
<a name="security_iam_service-with-iam-principal-permissions"></a>

**Supports forward access sessions (FAS):** Yes

 Forward access sessions (FAS) use the permissions of the principal calling an AWS service, combined with the requesting AWS service to make requests to downstream services. For policy details when making FAS requests, see [Forward access sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html). 

## Service roles for AWS WAF
<a name="security_iam_service-with-iam-roles-service"></a>

**Supports service roles:** Yes

 A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*. 

**Warning**  
Changing the permissions for a service role might break AWS WAF functionality. Edit service roles only when AWS WAF provides guidance to do so.

## Service-linked roles for AWS WAF
<a name="security_iam_service-with-iam-roles-service-linked"></a>

**Supports service-linked roles:** Yes

 A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles. 

For details about creating or managing AWS WAF service-linked roles, see [Using service-linked roles for AWS WAF](using-service-linked-roles.md).

# Identity-based policy examples for AWS WAF
<a name="security_iam_id-based-policy-examples"></a>

This section provides identity-based policy examples for AWS WAF.

By default, users and roles don't have permission to create or modify AWS WAF resources. To grant users permission to perform actions on the resources that they need, an IAM administrator can create IAM policies.

To learn how to create an IAM identity-based policy by using these example JSON policy documents, see [Create IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in the *IAM User Guide*.

For details about actions and resource types defined by AWS WAF, including the format of the ARNs for each of the resource types, see [Actions, resources, and condition keys for AWS WAF V2](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awswafv2.html) in the *Service Authorization Reference*.

**Topics**
+ [

## Policy best practices
](#security_iam_service-with-iam-policy-best-practices)
+ [

## Using the AWS WAF console
](#security_iam_id-based-policy-examples-console)
+ [

## Allow users to view their own permissions
](#security_iam_id-based-policy-examples-view-own-permissions)
+ [

## Grant read-only access to AWS WAF, CloudFront, and CloudWatch
](#security_iam_id-based-policy-examples-read-only1)
+ [

## Grant full access to AWS WAF, CloudFront, and CloudWatch
](#security_iam_id-based-policy-examples-full-access1)
+ [

## Grant access to a single AWS account
](#security_iam_id-based-policy-examples-access-to-account)
+ [

## Grant access to a single protection pack (web ACL)
](#security_iam_id-based-policy-examples-access-to-web-acl)
+ [

## Grant CLI access to a protection pack (web ACL) and rule group
](#security_iam_id-based-policy-examples-cli-access-to-web-acl)

## Policy best practices
<a name="security_iam_service-with-iam-policy-best-practices"></a>

Identity-based policies determine whether someone can create, access, or delete AWS WAF resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
+ **Get started with AWS managed policies and move toward least-privilege permissions** – To get started granting permissions to your users and workloads, use the *AWS managed policies* that grant permissions for many common use cases. They are available in your AWS account. We recommend that you reduce permissions further by defining AWS customer managed policies that are specific to your use cases. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) or [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*.
+ **Apply least-privilege permissions** – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as *least-privilege permissions*. For more information about using IAM to apply permissions, see [ Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
+ **Use conditions in IAM policies to further restrict access** – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific AWS service, such as CloudFormation. For more information, see [ IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*.
+ **Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions** – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see [Validate policies with IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html) in the *IAM User Guide*.
+ **Require multi-factor authentication (MFA)** – If you have a scenario that requires IAM users or a root user in your AWS account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see [ Secure API access with MFA](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html) in the *IAM User Guide*.

For more information about best practices in IAM, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.

## Using the AWS WAF console
<a name="security_iam_id-based-policy-examples-console"></a>

To access the AWS WAF console, you must have a minimum set of permissions. These permissions must allow you to list and view details about the AWS WAF resources in your AWS account. If you create an identity-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities (users or roles) with that policy.

You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API. Instead, allow access to only the actions that match the API operation that they're trying to perform.

To ensure that users and roles can use the AWS WAF console, also attach at least the AWS WAF `AWSWAFConsoleReadOnlyAccess` AWS managed policy to the entities. For information about this managed policy, see [AWS managed policy: AWSWAFConsoleReadOnlyAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSWAFConsoleReadOnlyAccess). For more information about attaching a managed policy to a user, see [Adding permissions to a user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

## Allow users to view their own permissions
<a name="security_iam_id-based-policy-examples-view-own-permissions"></a>

This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API.

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "ViewOwnUserInfo",
            "Effect": "Allow",
            "Action": [
                "iam:GetUserPolicy",
                "iam:ListGroupsForUser",
                "iam:ListAttachedUserPolicies",
                "iam:ListUserPolicies",
                "iam:GetUser"
            ],
            "Resource": ["arn:aws:iam::*:user/${aws:username}"]
        },
        {
            "Sid": "NavigateInConsole",
            "Effect": "Allow",
            "Action": [
                "iam:GetGroupPolicy",
                "iam:GetPolicyVersion",
                "iam:GetPolicy",
                "iam:ListAttachedGroupPolicies",
                "iam:ListGroupPolicies",
                "iam:ListPolicyVersions",
                "iam:ListPolicies",
                "iam:ListUsers"
            ],
            "Resource": "*"
        }
    ]
}
```

## Grant read-only access to AWS WAF, CloudFront, and CloudWatch
<a name="security_iam_id-based-policy-examples-read-only1"></a>

The following policy grants users read-only access to AWS WAF resources, to Amazon CloudFront web distributions, and to Amazon CloudWatch metrics. It's useful for users who need permission to view the settings in AWS WAF conditions, rules, and protection packs (web ACLs) to see which distribution is associated with a protection pack (web ACL), and to monitor metrics and a sample of requests in CloudWatch. These users can't create, update, or delete AWS WAF resources.

```
 {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "wafv2:Get*",
                "wafv2:List*",
                "cloudfront:GetDistribution",
                "cloudfront:GetDistributionConfig",
                "cloudfront:ListDistributions",
                "cloudfront:ListDistributionsByWebACLId",
                "cloudfront:ListDistributionTenantsByCustomization",
                "cloudfront:ListDistributionTenants",
                "cloudfront:GetDistributionTenant",
                "cloudwatch:GetMetricData",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "ec2:DescribeRegions",
                "pricingplanmanager:GetSubscription",
                "pricingplanmanager:ListSubscriptions",
                "route53:ListHostedZones",
                "route53:GetHostedZone"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}
```

## Grant full access to AWS WAF, CloudFront, and CloudWatch
<a name="security_iam_id-based-policy-examples-full-access1"></a>

The following policy lets users perform any AWS WAF operation, perform any operation on CloudFront web distributions, and monitor metrics and a sample of requests in CloudWatch. It's useful for users who are AWS WAF administrators.

```
 {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "wafv2:*",
                "cloudfront:CreateDistribution",
                "cloudfront:ListDistributions",
                "cloudfront:ListDistributionsByWebACLId",
                "cloudfront:UpdateDistribution",
                "cloudfront:GetDistributionConfig",
                "cloudfront:GetDistribution",
                "cloudfront:DisassociateDistributionTenantWebACL",
                "cloudfront:DisassociateDistributionWebACL",
                "cloudfront:AssociateDistributionTenantWebACL",
                "cloudfront:AssociateDistributionWebACL",
                "cloudfront:ListDistributionTenantsByCustomization",
                "cloudfront:ListDistributionTenants",
                "cloudfront:DeleteDistribution",
                "cloudfront:GetDistributionTenant",
                "cloudfront:DeleteDistributionTenant",
                "cloudwatch:GetMetricData",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "ec2:DescribeRegions",
                "pricingplanmanager:GetSubscription",
                "pricingplanmanager:ListSubscriptions",
                "pricingplanmanager:UpdateSubscription",
                "pricingplanmanager:CancelSubscription",
                "pricingplanmanager:CancelSubscriptionChange",
                "pricingplanmanager:AssociateResourcesToSubscription",
                "pricingplanmanager:DisassociateResourcesFromSubscription",
                "route53:ListHostedZones",
                "route53:GetHostedZone"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}
```

We strongly recommend that you configure multi-factor authentication (MFA) for users who have administrative permissions. For more information, see [Using Multi-Factor Authentication (MFA) Devices with AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_ManagingMFA.html) in the *IAM User Guide*. 

## Grant access to a single AWS account
<a name="security_iam_id-based-policy-examples-access-to-account"></a>

This policy grants the following permissions to the account 444455556666:
+ Full access to all AWS WAF operations and resources.
+ Read and update access to all CloudFront distributions, which allows you to associate protection packs (web ACLs) and CloudFront distributions.
+ Read access to all CloudWatch metrics and metric statistics, so that you can view CloudWatch data and a sample of requests in the AWS WAF console. 

------
#### [ JSON ]

****  

```
{
   "Version":"2012-10-17",		 	 	 
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
            "wafv2:*"
         ],
         "Resource": [
            "arn:aws:wafv2:us-east-1:444455556666:*"
         ]
      },
      {
         "Effect": "Allow",
         "Action": [
            "cloudfront:GetDistribution",
            "cloudfront:GetDistributionConfig",
            "cloudfront:ListDistributions",
            "cloudfront:ListDistributionsByWebACLId",
            "cloudfront:UpdateDistribution",
            "cloudwatch:ListMetrics",
            "cloudwatch:GetMetricStatistics",
            "ec2:DescribeRegions"
         ],
         "Resource": [
            "*"
         ]
      }
   ]
}
```

------

## Grant access to a single protection pack (web ACL)
<a name="security_iam_id-based-policy-examples-access-to-web-acl"></a>

The following policy lets users perform any AWS WAF operation through the console on a specific protection pack (web ACL) in the account `444455556666`.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "wafv2:*"
            ],
            "Resource": [
                "arn:aws:wafv2:us-east-1:444455556666:regional/webacl/test123/112233d7c-86b2-458b-af83-51c51example"
            ]
        },
        {
            "Sid": "consoleAccess",
            "Effect": "Allow",
            "Action": [
                "wafv2:ListWebACLs",
                "ec2:DescribeRegions"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```

------

## Grant CLI access to a protection pack (web ACL) and rule group
<a name="security_iam_id-based-policy-examples-cli-access-to-web-acl"></a>

The following policy lets users perform any AWS WAF operation through the CLI on a specific protection pack (web ACL) and a specific rule group in the account `444455556666`.

------
#### [ JSON ]

****  

```
{
   "Version":"2012-10-17",		 	 	 
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
            "wafv2:*"
         ],
         "Resource": [
        "arn:aws:wafv2:us-east-1:444455556666:regional/webacl/test123/112233d7c-86b2-458b-af83-51c51example",
        "arn:aws:wafv2:us-east-1:444455556666:regional/rulegroup/test123rulegroup/555555555-6666-1234-abcd-00d11example"
         ]
      }
   ]
}
```

------

The following policy lets users perform any AWS WAF operation through the console on a specific protection pack (web ACL) in the account `444455556666`.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "wafv2:*"
            ],
            "Resource": [
                "arn:aws:wafv2:us-east-1:444455556666:regional/webacl/test123/112233d7c-86b2-458b-af83-51c51example"
            ]
        },
        {
            "Sid": "consoleAccess",
            "Effect": "Allow",
            "Action": [
                "wafv2:ListWebACLs",
                "ec2:DescribeRegions"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```

------

# AWS managed policies for AWS WAF
<a name="security-iam-awsmanpol"></a>

This section explains how to use AWS managed policies for AWS WAF.

An AWS managed policy is a standalone policy that is created and administered by AWS. AWS managed policies are designed to provide permissions for many common use cases so that you can start assigning permissions to users, groups, and roles.

Keep in mind that AWS managed policies might not grant least-privilege permissions for your specific use cases because they're available for all AWS customers to use. We recommend that you reduce permissions further by defining [ customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies) that are specific to your use cases.

You cannot change the permissions defined in AWS managed policies. If AWS updates the permissions defined in an AWS managed policy, the update affects all principal identities (users, groups, and roles) that the policy is attached to. AWS is most likely to update an AWS managed policy when a new AWS service is launched or new API operations become available for existing services.

For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*.

## AWS managed policy: AWSWAFReadOnlyAccess
<a name="security-iam-awsmanpol-AWSWAFReadOnlyAccess"></a>

This policy grants read-only permissions that allow users to access AWS WAF resources and resources for integrated services, such as Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, Amazon Cognito, AWS App Runner, AWS Amplify, Amazon CloudWatch, and AWS Verified Access. You can attach this policy to your IAM identities. AWS WAF also attaches this policy to a service role that allows AWS WAF to perform actions on your behalf.

For details about this policy, see [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary) in the IAM console.

## AWS managed policy: AWSWAFFullAccess
<a name="security-iam-awsmanpol-AWSWAFFullAccess"></a>

This policy grants full access to AWS WAF resources and resources for integrated services, such as Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, Amazon Cognito, AWS App Runner, AWS Amplify, Amazon CloudWatch, and AWS Verified Access. You can attach this policy to your IAM identities. AWS WAF also attaches this policy to a service role that allows AWS WAF to perform actions on your behalf.

For details about this policy, see [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary) in the IAM console.

## AWS managed policy: AWSWAFConsoleReadOnlyAccess
<a name="security-iam-awsmanpol-AWSWAFConsoleReadOnlyAccess"></a>

This policy grants read-only permissions to the AWS WAF console, which includes resources for AWS WAF and for integrated services, such as Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, Amazon Cognito, AWS App Runner, AWS Amplify, Amazon CloudWatch, and AWS Verified Access. You can attach this policy to your IAM identities.

For details about this policy, see [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary) in the IAM console.

## AWS managed policy: AWSWAFConsoleFullAccess
<a name="security-iam-awsmanpol-AWSWAFConsoleFullAccess"></a>

This policy grants full access to the AWS WAF console, which includes resources for AWS WAF and for integrated services, such as Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, Amazon Cognito, AWS App Runner, AWS Amplify, Amazon CloudWatch, and AWS Verified Access. You can attach this policy to your IAM identities. AWS WAF also attaches this policy to a service role that allows AWS WAF to perform actions on your behalf.

For details about this policy, see [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary) in the IAM console.

## AWS managed policy: WAFV2LoggingServiceRolePolicy
<a name="security-iam-awsmanpol-WAFV2LoggingServiceRolePolicy"></a>

This policy allows AWS WAF to write logs to Amazon Data Firehose. This policy is used only if you enable logging in AWS WAF. This policy is attached to the service-linked role `AWSServiceRoleForWAFV2Logging`. For more information about the service-linked role, see [Using service-linked roles for AWS WAF](using-service-linked-roles.md). 

For details about this policy, see [WAFV2LoggingServiceRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/WAFV2LoggingServiceRolePolicy$serviceLevelSummary) in the IAM console.

## AWS WAF updates to AWS managed policies
<a name="security-iam-awsmanpol-updates"></a>



View details about updates to AWS managed policies for AWS WAF since this service began tracking these changes. For automatic alerts about changes to this page, subscribe to the RSS feed on the AWS WAF document history page at [Document history](doc-history.md).




| Policy | Description of change | Date | 
| --- | --- | --- | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Added the following permissions for CloudFront pricing plans. For more detail, see [Using AWS WAF with CloudFront Flat-Rate Pricing Plans](cloudfront-features.md#waf-cf-pricing-plans) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-11-18  | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Added the following permissions for CloudFront pricing plans. For more detail, see [Using AWS WAF with CloudFront Flat-Rate Pricing Plans](cloudfront-features.md#waf-cf-pricing-plans) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-11-18 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Updated the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) Added the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-11-03 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Updated the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) Added the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-11-03 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary). |  Added permissions AssociateWebACL, DisassociateWebACL, GetWebACLForResource, and ListResourcesForWebACL required for AWS Amplify.  | 2025-05-05 | 
| `AWSWAFReadOnlyAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. For details about this policy, see [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary) in the IAM console. |  Added permissions GetWebACLForResource and ListResourcesForWebACL required for AWS Amplify.  | 2025-05-05 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Added the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-05-05 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Added the following permissions:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/waf/latest/developerguide/security-iam-awsmanpol.html)  | 2025-05-05 | 
| `WAFV2LoggingServiceRolePolicy` This policy allows AWS WAF to write logs to Amazon Data Firehose. It's used only if you enable logging.  Details in IAM console: [WAFV2LoggingServiceRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/aws-service-role/WAFV2LoggingServiceRolePolicy$serviceLevelSummary). |  Added Statement IDs (Sids) to the permissions settings in the service-linked role that this policy is attached to.   | 2024-06-03 | 
| `AWSServiceRoleForWAFV2Logging` This service-linked role provides permissions policies that allow AWS WAF to write logs to Amazon Data Firehose.  Details in IAM console: [AWSServiceRoleForWAFV2Logging](https://console.aws.amazon.com/iam/home#/roles/details/AWSServiceRoleForWAFV2Logging). |  Added Statement IDs (Sids) to the permissions settings.   | 2024-06-03 | 
|  AWS WAF additions to change tracking  |  AWS WAF started tracking changes for the managed policy `WAFV2LoggingServiceRolePolicy` and the service-linked role `AWSServiceRoleForWAFV2Logging`.   | 2024-06-03 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary). |  Expanded permissions to add AWS Verified Access instances to the resource types that you can protect with AWS WAF.  | 2023-06-17 | 
| `AWSWAFReadOnlyAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add AWS Verified Access instances to the resource types that you can protect with AWS WAF.  | 2023-06-17 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Expanded permissions to add AWS Verified Access instances to the resource types that you can protect with AWS WAF.  | 2023-06-17 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add AWS Verified Access instances to the resource types that you can protect with AWS WAF.  | 2023-06-17 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary). |  Expanded permissions to correct the access settings for AWS App Runner services.  | 2023-06-06 | 
| `AWSWAFReadOnlyAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to correct the access settings for AWS App Runner services.  | 2023-06-06 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Expanded permissions to correct the access settings for AWS App Runner services.  | 2023-06-06 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to correct the access settings for AWS App Runner services.  | 2023-06-06 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary). |  Expanded permissions to add AWS App Runner services to the resource types that you can protect with AWS WAF.  | 2023-03-30 | 
| `AWSWAFReadOnlyAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add AWS App Runner services to the resource types that you can protect with AWS WAF.  | 2023-03-30 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Expanded permissions to add AWS App Runner services to the resource types that you can protect with AWS WAF.  | 2023-03-30 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add AWS App Runner services to the resource types that you can protect with AWS WAF.  | 2023-03-30 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary). |  Expanded permissions to add Amazon Cognito user pools to the resource types that you can protect with AWS WAF.  | 2022-08-25 | 
| `AWSWAFReadOnlyAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add Amazon Cognito user pools to the resource types that you can protect with AWS WAF.  | 2022-08-25 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Expanded permissions to add Amazon Cognito user pools to the resource types that you can protect with AWS WAF.  | 2022-08-25 | 
|  `AWSWAFConsoleReadOnlyAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleReadOnlyAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleReadOnlyAccess$serviceLevelSummary).  |  Expanded permissions to add Amazon Cognito user pools to the resource types that you can protect with AWS WAF.  | 2022-08-25 | 
| `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary).  |  Corrected the permissions settings for log delivery for Amazon Simple Storage Service (Amazon S3) and Amazon CloudWatch Logs. This change resolves access denied errors that were occurring during logging configuration. For information about logging your protection pack (web ACL) traffic, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).  | 2022-01-11 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Corrected the permissions settings for log delivery for Amazon Simple Storage Service (Amazon S3) and Amazon CloudWatch Logs. This change resolves access errors that were occurring during logging configuration. For information about logging your protection pack (web ACL) traffic, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).  | 2022-01-11 | 
|  `AWSWAFFullAccess` This policy allows AWS WAF to manage AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFFullAccess$serviceLevelSummary).  |  Added new permissions for expanded logging options. This change gives AWS WAF access to the additional logging destinations Amazon Simple Storage Service (Amazon S3) and Amazon CloudWatch Logs. For information about logging your protection pack (web ACL) traffic, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).  | 2021-11-15 | 
|  `AWSWAFConsoleFullAccess` This policy allows AWS WAF to manage AWS console resources and other AWS resources on your behalf in AWS WAF and in integrated services. Details in IAM console: [AWSWAFConsoleFullAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSWAFConsoleFullAccess$serviceLevelSummary).  |  Added new permissions for expanded logging options. This change gives AWS WAF access to the additional logging destinations Amazon Simple Storage Service (Amazon S3) and Amazon CloudWatch Logs. For information about logging your protection pack (web ACL) traffic, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).  | 2021-11-15 | 
|  AWS WAF started tracking changes  |  AWS WAF started tracking changes for its AWS managed policies.  | 2021-3-01 | 

# Troubleshooting AWS WAF identity and access
<a name="security_iam_troubleshoot"></a>

Use the following information to help you diagnose and fix common issues that you might encounter when working with AWS WAF and IAM.

**Topics**
+ [

## I am not authorized to perform an action in AWS WAF
](#security_iam_troubleshoot-no-permissions)
+ [

## I am not authorized to perform iam:PassRole
](#security_iam_troubleshoot-passrole)
+ [

## I want to allow people outside of my AWS account to access my AWS WAF resources
](#security_iam_troubleshoot-cross-account-access)

## I am not authorized to perform an action in AWS WAF
<a name="security_iam_troubleshoot-no-permissions"></a>

If you receive an error that you're not authorized to perform an action, your policies must be updated to allow you to perform the action.

The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a fictional `my-example-widget` resource but doesn't have the fictional `wafv2:GetWidget` permissions.

```
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: wafv2:GetWidget on resource: my-example-widget
```

In this case, the policy for the `mateojackson` user must be updated to allow access to the `my-example-widget` resource by using the `wafv2:GetWidget` action.

If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.

## I am not authorized to perform iam:PassRole
<a name="security_iam_troubleshoot-passrole"></a>

If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to AWS WAF.

Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service.

The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in AWS WAF. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service.

```
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
```

In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action.

If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.

## I want to allow people outside of my AWS account to access my AWS WAF resources
<a name="security_iam_troubleshoot-cross-account-access"></a>

You can create a role that users in other accounts or people outside of your organization can use to access your resources. You can specify who is trusted to assume the role. For services that support resource-based policies or access control lists (ACLs), you can use those policies to grant people access to your resources.

To learn more, consult the following:
+ To learn whether AWS WAF supports these features, see [How AWS WAF works with IAM](security_iam_service-with-iam.md).
+ To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*.
+ To learn how to provide access to your resources to third-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*.
+ To learn how to provide access through identity federation, see [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*.
+ To learn the difference between using roles and resource-based policies for cross-account access, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.

# Using service-linked roles for AWS WAF
<a name="using-service-linked-roles"></a>

This section explains how to use service-linked roles to give AWS WAF access to resources in your AWS account.

AWS WAF uses AWS Identity and Access Management (IAM)[ service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to AWS WAF. Service-linked roles are predefined by AWS WAF and include all the permissions that the service requires to call other AWS services on your behalf. 

A service-linked role makes setting up AWS WAF easier because you don’t have to manually add the necessary permissions. AWS WAF defines the permissions of its service-linked roles, and unless defined otherwise, only AWS WAF can assume its roles. The defined permissions include the trust policy and the permissions policy. That permissions policy can't be attached to any other IAM entity.

You can delete a service-linked role only after first deleting the role's related resources. This protects your AWS WAF resources because you can't inadvertently remove permission to access the resources.

For information about other services that support service-linked roles, see [AWS Services That Work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) and look for the services that have **Yes **in the **Service-Linked Role** column. Choose a **Yes** with a link to view the service-linked role documentation for that service.

## Service-linked role permissions for AWS WAF
<a name="slr-permissions"></a>

AWS WAF uses the service-linked role `AWSServiceRoleForWAFV2Logging` to write logs to Amazon Data Firehose. This role is used only if you enable logging in AWS WAF. For information about logging, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

This service-linked role is attached to the AWS managed policy `WAFV2LoggingServiceRolePolicy`. For more information about the managed policy, see [AWS managed policy: WAFV2LoggingServiceRolePolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-WAFV2LoggingServiceRolePolicy).

The `AWSServiceRoleForWAFV2Logging` service-linked role trusts the service to assume the role `wafv2.amazonaws.com`. 

The permissions policies of the role allow AWS WAF to complete the following actions on the specified resources:
+ Amazon Data Firehose actions: `PutRecord` and `PutRecordBatch` on Firehose data stream resources with a name that starts with `aws-waf-logs-`. For example, `aws-waf-logs-us-east-2-analytics`.
+ AWS Organizations action: `DescribeOrganization` on Organizations organizations resources. 

See the full service-linked role in the IAM console: [AWSServiceRoleForWAFV2Logging](https://console.aws.amazon.com/iam/home#/roles/details/AWSServiceRoleForWAFV2Logging).

You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. For more information, see [Service-Linked Role Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*.

## Creating a service-linked role for AWS WAF
<a name="create-slr"></a>

You don't need to manually create a service-linked role. When you enable AWS WAF logging on the AWS Management Console, or you make a `PutLoggingConfiguration` request in the AWS WAF CLI or the AWS WAF API, AWS WAF creates the service-linked role for you. 

You must have the `iam:CreateServiceLinkedRole` permission to enable logging.

If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you enable AWS WAF logging, AWS WAF creates the service-linked role for you again. 

## Editing a service-linked role for AWS WAF
<a name="edit-slr"></a>

AWS WAF doesn't allow you to edit the `AWSServiceRoleForWAFV2Logging` service-linked role. After you create a service-linked role, you can't change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*.

## Deleting a service-linked role for AWS WAF
<a name="delete-slr"></a>

If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or maintained. However, you must clean up the resources for your service-linked role before you can manually delete it.

**Note**  
If the AWS WAF service is using the role when you try to delete the resources, then the deletion might fail. If that happens, wait for a few minutes and try the operation again.

**To delete AWS WAF resources used by the `AWSServiceRoleForWAFV2Logging`**

1. On the AWS WAF console, remove logging from every web ACL. For more information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md).

1. Using the API or CLI, submit a `DeleteLoggingConfiguration` request for each web ACL that has logging enabled. For more information, see [AWS WAF API Reference](https://docs.aws.amazon.com/waf/latest/APIReference/Welcome.html).

**To manually delete the service-linked role using IAM**

Use the IAM console, the IAM CLI, or the IAM API to delete the `AWSServiceRoleForWAFV2Logging` service-linked role. For more information, see [Deleting a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.

## Supported Regions for AWS WAF service-linked roles
<a name="slr-regions"></a>

AWS WAF supports using service-linked roles in all of the regions where the service is available. For more information, see [AWS WAF endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/waf.html).

# Logging and monitoring in AWS WAF
<a name="waf-incident-response"></a>

This section explains how to use AWS tools for monitoring and responding to events in AWS WAF.

Monitoring is an important part of maintaining the reliability, availability, and performance of AWS WAF and your AWS solutions. You should collect monitoring data from all parts of your AWS solution so that you can more easily debug a multi-point failure if one occurs. AWS provides several tools for monitoring your AWS WAF resources and responding to potential events:

**Amazon CloudWatch alarms**  
Using CloudWatch alarms, you watch a single metric over a time period that you specify. If the metric exceeds a given threshold, CloudWatch sends a notification to an Amazon SNS topic or AWS Auto Scaling policy. For more information, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md).

**AWS CloudTrail logs**  
CloudTrail provides a record of actions taken by a user, role, or an AWS service in AWS WAF. Using the information collected by CloudTrail, you can determine the request that was made to AWS WAF, the IP address from which the request was made, who made the request, when it was made, and additional details. For more information, see [Logging API calls with AWS CloudTrail](logging-using-cloudtrail.md). 

**AWS WAF protection pack (web ACL) traffic logging**  
AWS WAF offers logging for the traffic that your protection packs (web ACLs) analyze. The logs include information such as the time that AWS WAF received the request from your protected AWS resource, detailed information about the request, and the action setting for the rule that the request matched. For more information, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

# Validating compliance in AWS WAF
<a name="waf-compliance"></a>

This section explains your compliance responsibility when using AWS WAF.

To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/).

You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html).

Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. For more information about your compliance responsibility when using AWS services, see [AWS Security Documentation](https://docs.aws.amazon.com/security/).

# Building for resilience in AWS WAF
<a name="disaster-recovery-resiliency"></a>

This section explains how AWS architecture supports data redundancy for AWS WAF.

The AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures. 

For more information about AWS Regions and Availability Zones, see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/).

# Infrastructure security in AWS WAF
<a name="infrastructure-security"></a>

This section explains how AWS WAF isolates service traffic.

As a managed service, AWS WAF is protected by AWS global network security. For information about AWS security services and how AWS protects infrastructure, see [AWS Cloud Security](https://aws.amazon.com/security/). To design your AWS environment using the best practices for infrastructure security, see [Infrastructure Protection](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html) in *Security Pillar AWS Well‐Architected Framework*.

You use AWS published API calls to access AWS WAF through the network. Clients must support the following:
+ Transport Layer Security (TLS). We require TLS 1.2 and recommend TLS 1.3.
+ Cipher suites with perfect forward secrecy (PFS) such as DHE (Ephemeral Diffie-Hellman) or ECDHE (Elliptic Curve Ephemeral Diffie-Hellman). Most modern systems such as Java 7 and later support these modes.

# AWS WAF quotas
<a name="limits"></a>

**Note**  
This is the latest version of AWS WAF. For AWS WAF Classic, see [AWS WAF Classic](classic-waf-chapter.md).

AWS WAF is subject to the following quotas (formerly referred to as limits). These quotas are the same for all Regions in which AWS WAF is available. Each Region is subject to these quotas individually. The quotas are not cumulative across Regions.

AWS WAF has default quotas on the maximum number of entities you can have per account. You can [request an increase](https://console.aws.amazon.com/servicequotas/home/services/wafv2/quotas) in these quotas.


| Resource | Default quota per account per Region | 
| --- | --- | 
|  Maximum number of protection packs (web ACLs)  |  100  | 
|  Maximum number of rule groups   |  100  | 
| Maximum number of IP sets  |  100  | 
| Maximum number of requests per second per protection pack (web ACL)  |  100,000  | 
| Maximum number of custom request headers per protection pack (web ACL) or rule group | 100 | 
| Maximum number of custom response headers per protection pack (web ACL) or rule group | 100 | 
| Maximum number of custom response bodies per protection pack (web ACL) or rule group | 50 | 
| Maximum number of token domains in a protection pack (web ACL) token domain list | 10 | 
| Maximum number of regex pattern sets  |  10  | 
| Maximum number of Application Load Balancer associations per protection pack (web ACL) | 100  | 

The maximum requests per second (RPS) allowed for AWS WAF on CloudFront is set by CloudFront and described in the [CloudFront Developer Guide](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html).

AWS WAF has fixed quotas on the following entity settings per account per Region. These quotas can't be changed.


| Resource | Quota per account per Region | 
| --- | --- | 
|  Maximum protection pack (web ACL) capacity units (WCUs) per protection pack (web ACL)\$1  |  5,000  | 
| Maximum WCUs per rule group |  5,000  | 
| Maximum number of reference statements per rule group. In a rule group, a reference statement can reference an IP set or a regex pattern set. |  50  | 
| Maximum number of reference statements per protection pack (web ACL). In a protection pack (web ACL), a reference statement can reference a rule group, an IP set, or a regex pattern set. |  50  | 
| Maximum number of IP addresses in CIDR notation per IP set |  10,000  | 
| Maximum number of rate-based rules per protection pack (web ACL)  |  10  | 
| Maximum number of rate-based rules per rule group |  4  | 
| Minimum request rate that can be defined for a rate-based rule |  10  | 
| Maximum number of unique IP addresses that can be rate limited per rate-based rule |  10,000  | 
| Maximum number of characters in a string match statement |  200  | 
| Maximum number of characters in each regex pattern |  200  | 
| Maximum number of unique regex patterns per regex pattern set |  10  | 
| Maximum size of a web request body that can be inspected for Application Load Balancer and AWS AppSync protections |  8 KB  | 
| Maximum size of a web request body that can be inspected for CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access protections\$1\$1 |  64 KB  | 
| Maximum number of text transformations per rule statement |  10  | 
| Maximum size of the custom response body content for a single custom response definition |  4 KB  | 
| Maximum number of custom headers for a single custom response definition |  10  | 
| Maximum number of custom headers for a single custom request definition |  10  | 
| Maximum combined size of all response body content for a single rule group or a single protection pack (web ACL) |  50 KB  | 
| Maximum number of Geo match country codes inside a single rule  |  50  | 

\$1Using more than 1,500 WCUs in a protection pack (web ACL) incurs costs beyond the basic protection pack (web ACL) price. For more information, see [Web ACL capacity units (WCUs) in AWS WAF](aws-waf-capacity-units.md) and [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/).

\$1\$1By default, the body inspection limit is set to 16 KB for CloudFront, API Gateway, Amazon Cognito, App Runner, and Verified Access resources, but you can increase this for any of these resources in your protection pack (web ACL) configuration, up to the listed maximum. For more information, see [Considerations for managing body inspection in AWS WAF](web-acl-setting-body-inspection-limit.md).

AWS WAF has the following fixed quotas on calls per account per Region. These quotas apply to the total calls to the service through any available means, including the console, CLI, AWS CloudFormation, the REST API, and the SDKs. These quotas can't be changed.


| Call type | Quota per account per Region | 
| --- | --- | 
| Maximum number of calls to AssociateWebACL |  One request every 2 seconds   | 
| Maximum number of calls to DisassociateWebACL |  One request every 2 seconds   | 
| Maximum number of calls to GetWebACLForResource  |  One request per second  | 
| Maximum number of calls to ListResourcesForWebACL |  One request per second  | 
| Maximum number of calls to GetDecryptedAPIKey |  One request every 2 seconds  | 
| Maximum number of calls to any individual Get or List action, if no other quota is defined for it  |  Five requests per second  | 
| Maximum number of calls to any individual Create, Put, or Update action, if no other quota is defined for it  |  One request per second  | 

AWS WAF has the following fixed quotas on calls by all accounts in a single organization in AWS Organizations. These quotas apply to the total calls to the service through any available means, including the console, CLI, AWS CloudFormation, the REST API, and the SDKs. These quotas can't be changed.


| Call type | Quota per organization in a single Region | 
| --- | --- | 
| Maximum number of calls by all accounts in an organization to ListResourcesForWebACL, in any single Region for the Regions US East (N. Virginia) (us-east-1), US West (Oregon) (us-west-2), or Europe (Ireland) (eu-west-1).  |  12 requests per second  | 
| Maximum number of calls by all accounts in an organization to ListResourcesForWebACL, in any single Region that doesn't have a different quota listed in this table.  |  6 requests per second  | 

# Migrating your AWS WAF Classic resources to AWS WAF
<a name="waf-migrating-from-classic"></a>

**Warning**  
AWS WAF Classic is is going through a planned end-of-life process. Refer to your AWS Health dashboard for the milestones and dates specific to your Region.

**Note**  
This is **AWS WAF** documentation. You should only use this version if you created AWS WAF resources, like rules and web ACLs, in AWS WAF prior to November 2019, and you have not migrated them over to the latest version yet. To migrate your web ACLs, see [Migrating your AWS WAF Classic resources to AWS WAF](#waf-migrating-from-classic).  
**For the latest version of AWS WAF**, see [AWS WAF](waf-chapter.md). 

This section provides guidance for migrating your rules and protection packs (web ACLs) from AWS WAF Classic to AWS WAF. AWS WAF was released in November 2019. If you created resources like rules and protection packs (web ACLs) using AWS WAF Classic, you either need to work with them using AWS WAF Classic or migrate them to this latest version. 

**Warning**  
AWS WAF Classic support will end on September 30, 2025. 

Before you start your migration work, familiarize yourself with AWS WAF by reading through [AWS WAF](waf-chapter.md).

**Topics**
+ [

# Why migrate to AWS WAF?
](waf-migrating-why-migrate.md)
+ [

# Migration caveats and limitations
](waf-migrating-caveats.md)
+ [

# How the migration works
](waf-migrating-how-it-works.md)
+ [

# Migrating a protection pack (web ACL) from AWS WAF Classic to AWS WAF
](waf-migrating-procedure.md)

# Why migrate to AWS WAF?
<a name="waf-migrating-why-migrate"></a>

The latest version of AWS WAF provides many improvements over the prior version, while maintaining most of the concepts and terminology that you're accustomed to. 

The following list describes the major changes in the latest AWS WAF. Before you continue with your migration, please take some time to review this list and to familiarize yourself with the rest of the AWS WAF guide. 
+ **Support for AWS WAF Classic will end on September 30, 2025. ** 
+ **AWS Managed Rules for AWS WAF** – The rule groups now available through AWS Managed Rules provide protection against common web threats. Most of these rule groups are included free of charge with AWS WAF. For more information, see [AWS Managed Rules rule groups list](aws-managed-rule-groups-list.md) and the blog post [Announcing AWS Managed Rules for AWS WAF](https://aws.amazon.com/blogs/aws/announcing-aws-managed-rules-for-aws-waf/).
+ **New AWS WAF API** – The new API allows you to configure all of your AWS WAF resources using a single set of APIs. To distinguish between regional and global applications, the new API includes a `scope` setting. For more information about the API, see the [AWS WAFV2 Actions](https://docs.aws.amazon.com/waf/latest/APIReference/API_Operations_AWS_WAFV2.html) and [AWS WAFV2 Data Types](https://docs.aws.amazon.com/waf/latest/APIReference/API_Types_AWS_WAFV2.html).

  In the APIs, SDKs, CLIs, and AWS CloudFormation, AWS WAF Classic retains its naming schemes and this latest version of AWS WAF is referred to with an added `V2` or `v2`, depending on the context.
+ **Simplified service quotas (limits)** – AWS WAF now allows more rules per protection pack (web ACL) and allows you to express longer regex patterns. For more information, see [AWS WAF quotas](limits.md).
+ **Computing needs determine capacity limits ** – The limits for protection packs (web ACLs) are now based on protection pack (web ACL) capacity units (WCUs). AWS WAF calculates a rule's WCUs according to its required operating capacity. The total WCUs for a protection pack (web ACL) equals the sum of WCUs from all its rules and rule groups.

  For general information about WCU, see [How AWS WAF works](how-aws-waf-works.md). For information about each rule's WCU usage, see [Using rule statements in AWS WAF](waf-rule-statements.md).
+ **Document-based rule writing** – You can now write and express rules, rule groups, and protection packs (web ACLs) in JSON format. You no longer need to use individual API calls to create different conditions and then associate the conditions to a rule. This greatly simplifies how you write and maintain your code. You can access a JSON format of your protection packs (web ACLs) through the console when you're viewing the protection pack (web ACL), by choosing **Download protection pack (web ACL) as JSON**. When you are creating your own rule, you can access its JSON representation by choosing **Rule JSON editor**.
+ **Rule nesting and full logical operation support** – You can write complex combined rules by using logical rule statements and by using nesting. You can create statements such as `[A AND NOT(B OR C)]`. For more information, see [Using logical rule statements in AWS WAF](waf-rule-statements-logical.md).
+ **Improved rate-based rules** – In the latest version of AWS WAF, you can customize the time window that the rule evaluates and how the rule aggregates requests. You can customize aggregation using combinations of a number of web request characteristics. Additionally the latest rate-based rules react more quickly to changes in traffic. For more information, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md). 
+ **Variable CIDR range support for IP set** – IP set specifications now have more flexibility in the IP ranges. For IPv4, AWS WAF supports `/1` to `/32`. For IPv6, AWS WAF supports `/1` to `/128`. For more information about IP sets, see [IP set match rule statement](waf-rule-statement-type-ipset-match.md).
+ **Chainable text transformations** – AWS WAF can perform multiple text transformations against web request content before inspecting it. For more information, see [Using text transformations in AWS WAF](waf-rule-statement-transformation.md).
+ **Improved console experience** – The new AWS WAF console features visual rule builder and a more user intuitive console design. 
+ **Expanded options for Firewall Manager AWS WAF policies** – In the Firewall Manager management of AWS WAF protection packs (web ACLs), you can now create a set of rule groups that AWS WAF processes first and a set of rule groups that AWS WAF processes last. After you apply the AWS WAF policy, local account owners can add their own rule groups that AWS WAF processes in between these two sets. For more information about Firewall Manager AWS WAF policies, see [Using AWS WAF policies with Firewall Manager](waf-policies.md). 
+ **AWS CloudFormation support for all rule statement types** – AWS WAF in AWS CloudFormation supports all rule statement types that the AWS WAF console and API support. Additionally, you can easily convert the rules that you write in JSON format to YAML format. 



# Migration caveats and limitations
<a name="waf-migrating-caveats"></a>

The migration only handles protection pack (web ACL) configurations, and the protection pack (web ACL) migration doesn't bring over all settings exactly as you have them in AWS WAF Classic. Some configuration items require manual configuration in AWS WAF (v2). A few things don't map exactly between the two versions, and you'll need to decide how you want to configure the functionality in AWS WAF (v2). Some settings, like the protection pack (web ACL)'s associations with AWS resources, are disabled initially in the new version so you can add them when you're ready. 

The following list describes the caveats of the migration and describes any steps you might want to take in response. Use this overview to plan your migration. The detailed migration steps, later on, walk you through the recommended mitigation steps. 
+ **Single account migration** – You can only migrate AWS WAF Classic resources for any account to AWS WAF resources for the same account. 
+ **Only protection pack (web ACL) configurations ** – The migration only migrates protection packs (web ACLs) and resources that the protection packs (web ACLs) are using. To migrate a resource, such as a rule group or IP set, that's not used by any migrated web ACL, manually create the resource in AWS WAF (v2).
+ **No AWS Marketplace managed rules** – The migration doesn't bring over any managed rules from AWS Marketplace sellers. Some AWS Marketplace sellers have equivalent managed rules for AWS WAF that you can subscribe to again. Before you do this, review the AWS Managed Rules that are provided with the latest version of AWS WAF. Most of these are free of charge for AWS WAF users. For information about managed rules, see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md). 
+ **No protection pack (web ACL) associations** – The migration doesn't bring over any associations between the protection pack (web ACL) and protected resources. This is by design, to avoid affecting your production workload. After you verify that everything is migrated correctly, associate the new protection pack (web ACL) with your resources.
+ **Logging disabled** – Logging for the migrated protection pack (web ACL) is disabled by default. This is by design. Enable logging when you are ready to switch over from AWS WAF Classic to AWS WAF.
+ **No AWS Firewall Manager rule groups** – The migration doesn't handle rule groups that are managed by Firewall Manager. You can migrate a protection pack (web ACL) that's managed by Firewall Manager, but the migration doesn't bring over the rule group. Instead of using the migration tool for these protection packs (web ACLs), recreate the policy for the new AWS WAF in Firewall Manager. 
**Note**  
The rule groups that Firewall Manager managed for AWS WAF Classic were Firewall Manager rule groups. With the new version of AWS WAF, the rule groups are AWS WAF rule groups. Functionally, they are the same. 
+ **AWS WAF Security Automations caveat** – Don't try to migrate any AWS WAF Security Automations. The migration doesn't convert Lambda functions, which might be in use by the automations. Consider deploying the automations for the latest version instead. For information, see [AWS WAF Security Automations](https://aws.amazon.com/solutions/aws-waf-security-automations/).

# How the migration works
<a name="waf-migrating-how-it-works"></a>

You can migrate your web ACLs from AWS WAF Classic to AWS WAF v2 using several methods. Follow these steps to complete your migration.

**To migrate from AWS WAF Classic to AWS WAF v2**

1. Identify your AWS WAF Classic web ACLs:
   + View a list of your web ACLs in the AWS Health dashboard.
   + Use the [AWS WAF Classic web ACL cleanup script](         https://github.com/aws-samples/sample-for-waf-classic-to-wafv2-migrate-and-cleanup/tree/main/scripts/waf-classic-cleanup          ) to get a list of all your web ACLs and their associations. This helps you identify which web ACLs are actively protecting resources and allows you to delete unused web ACLs.

1. Migrate individual web ACLs:
   + Follow the migration process in the [AWS WAF Developer Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-migrating-procedure.html).
   + Use the migration wizard to parse your AWS WAF Classic web ACL and generate an AWS CloudFormation template.
   + Use the generated template to create an equivalent AWS WAF v2 web ACL and complete the migration.

1. For multiple eligible web ACLs:
   + Use the [AWS WAF bulk migration script](https://github.com/aws-samples/sample-for-waf-classic-to-wafv2-migrate-and-cleanup/tree/main/scripts/waf-classic-migration          ) to migrate multiple eligible AWS WAF Classic web ACLs simultaneously.

1. For web ACLs managed by AWS Firewall Manager:
   + Firewall Manager policies use AWS WAF Classic web ACLs with AWS WAF Classic policies. For Shield Advanced policies created before January 2022, Firewall Manager also uses AWS WAF Classic web ACLs. You must migrate these policies to use AWS WAF v2 web ACLs.

     Follow the instructions at [Migrating AWS WAF Classic Web ACLs in Firewall Manager](migrate-waf-classic-fms.md).

**Important**  
We recommend reviewing each migrated web ACLto ensure it meets your security requirements before associating it with your resources.

# Migrating a protection pack (web ACL) from AWS WAF Classic to AWS WAF
<a name="waf-migrating-procedure"></a>

The automated migration carries over most of your AWS WAF Classic protection pack (web ACL) configuration, leaving some things that you need to handle manually.

**Note**  
Some protection configurations cannot be automatically migrated, and require manual configuration in AWS WAF (v2). See the list at [Migration caveats and limitations](waf-migrating-caveats.md).

The following lists the high-level steps for migrating a protection pack (web ACL). 

1. The automated migration reads everything related to your existing protection pack (web ACL), without modifying or deleting anything in AWS WAF Classic. It creates a representation of the web ACL and its related resources, compatible with AWS WAF. It generates an CloudFormation template for the new protection pack (web ACL) and stores it in an Amazon S3 bucket. 

1. You deploy the template into CloudFormation, in order to recreate the protection pack (web ACL) and related resources in AWS WAF. 

1. You review the protection pack (web ACL), and manually complete the migration, making sure that your new protection pack (web ACL) takes full advantage of the capabilities of the latest AWS WAF. 

1. You manually switch your protected resources over to the new protection pack (web ACL). 

**Topics**
+ [

# Migrating a protection pack (web ACL): automated migration
](waf-migrating-procedure-automatic.md)
+ [

# Migrating a protection pack (web ACL): manual follow-up
](waf-migrating-procedure-manual-finish.md)
+ [

# Migrating a protection pack (web ACL): additional considerations
](waf-migrating-procedure-additional.md)
+ [

# Migrating a protection pack (web ACL): switchover
](waf-migrating-procedure-switchover.md)

# Migrating a protection pack (web ACL): automated migration
<a name="waf-migrating-procedure-automatic"></a>

**To automatically migrate a protection pack (web ACL) configuration from AWS WAF Classic to AWS WAF**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choose **Switch to AWS WAF Classic** and review your configuration settings for the protection pack (web ACL). Make note of the settings, considering the caveats and limitations described in the preceding section, [Migration caveats and limitations](waf-migrating-caveats.md).

1. In the informational dialogue at the top, locate the sentence that starts with **Migrate protection packs (web ACLs)** and choose the link to the **migration wizard**. This launches the migration wizard.

   If you don't see the informational dialogue, you might have closed it since you launched the AWS WAF Classic console. In the navigation bar, choose **Switch to new AWS WAF** then choose **Switch to AWS WAF Classic**, and the informational dialogue should reappear.

1. Select the protection pack (web ACL) that you want to migrate. 

1. For **Migration configuration**, provide an Amazon S3 bucket to use for the template. You need an Amazon S3 bucket that's configured properly for the migration API, to store the AWS CloudFormation template that it generates. 
   + If the bucket is encrypted, the encryption must use Amazon S3 (SSE-S3) keys. The migration doesn't support encryption with AWS Key Management Service (SSE-KMS) keys.
   + The bucket name must start with `aws-waf-migration-`. For example, `aws-waf-migration-my-web-acl`.
   + The bucket must be in the Region where you are deploying the template. For example, for a protection pack (web ACL) in `us-west-2`, you must use an Amazon S3 bucket in `us-west-2` and you must deploy the template stack to `us-west-2`. 

1. For **S3 bucket policy**, we recommend choosing **Auto apply the bucket policy required for migration**. Alternatively, if you want to manage the bucket on your own, you must manually apply the following bucket policy: 
   + For global Amazon CloudFront applications (`waf`):

------
#### [ JSON ]

****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Effect": "Allow",
                 "Principal": {
                     "Service": "apiv2migration.waf.amazonaws.com"
                 },
                 "Action": "s3:PutObject",
                 "Resource": "arn:aws:s3:::<BUCKET_NAME>/AWSWAF/<CUSTOMER_ACCOUNT_ID>/*"
             }
         ]
     }
     ```

------
   + For regional Amazon API Gateway or Application Load Balancer applications (`waf-regional`):

------
#### [ JSON ]

****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Effect": "Allow",
                 "Principal": {
                     "Service": "apiv2migration.waf-regional.amazonaws.com"
                 },
                 "Action": "s3:PutObject",
                 "Resource": "arn:aws:s3:::<BUCKET_NAME>/AWSWAF/<CUSTOMER_ACCOUNT_ID>/*"
             }
         ]
     }
     ```

------

1. For **Choose how to handle rules that cannot be migrated**, choose either to exclude rules that can't be migrated, or to stop the migration. For information about rules that can't be migrated, see [Migration caveats and limitations](waf-migrating-caveats.md). 

1. Choose **Next**. 

1. For **Create CloudFormation template**, verify your settings, then choose **Start creating CloudFormation template** to begin the migration process. This can take a few minutes, depending on the complexity of your protection pack (web ACL).

1. In **Create and run CloudFormation stack to complete migration**, you can choose to go to the AWS CloudFormation console to create a stack from the template, to create the new protection pack (web ACL) and its resources. To do this, choose **Create CloudFormation stack**. 

After the automatic migration process completes, you're ready to proceed to the manual follow-up steps. See [Migrating a protection pack (web ACL): manual follow-up](waf-migrating-procedure-manual-finish.md).

# Migrating a protection pack (web ACL): manual follow-up
<a name="waf-migrating-procedure-manual-finish"></a>

After the automated migration is complete, review the newly created protection pack (web ACL) and fill in the components that the migration doesn't bring over for you. The following procedure covers the aspects of protection pack (web ACL) management that the migration doesn't handle. For the list, see [Migration caveats and limitations](waf-migrating-caveats.md).

**To finish the basic migration - manual steps**

1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. The console should automatically use the latest version of AWS WAF. To verify this, in the navigation pane, check that you can see the option **Switch to AWS WAF Classic**. If you see **Switch to new AWS WAF**, choose that to switch to the latest version. 

1. In the navigation pane, choose **protection packs (web ACLs)**. 

1. In the **protection packs (web ACLs)** page, locate your new protection pack (web ACL) in the list for the Region where you created it. Choose the protection pack (web ACL)'s name to bring up the settings for the protection pack (web ACL). 

1. Review all of the settings for the new protection pack (web ACL) against your prior AWS WAF Classic web ACL. By default, logging and protected resource associations are disabled. You enable those when you're ready to switch over. 

1. If your AWS WAF Classic protection pack (web ACL) had a managed rule group, the rule group inclusion wasn't brought over in the migration. You can add managed rule groups to the new protection pack (web ACL). Review the information about managed rule groups, including the list of AWS Managed Rules that are available with the new version of AWS WAF, at [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md). To add a managed rule group, do the following:

   1. In your protection pack (web ACL) settings page, choose the protection pack (web ACL) **Rules** tab. 

   1. Choose **Add rules**, then choose **Add managed rule groups**.

   1. Expand the listing for the vendor of your choice and select the rule groups that you want to add. For AWS Marketplace sellers, you might need to subscribe to the rule groups. For more information about using managed rule groups in your protection pack (web ACL), see [Using managed rule groups in AWS WAF](waf-managed-rule-groups.md) and [Using protection packs (web ACLs) with rules and rule groups in AWS WAF](web-acl-processing.md).

After you finish the basic migration process, we recommend that you review your needs and consider additional options, to be sure that the new configuration is as efficient as possible and that it's using the latest available security options. See [Migrating a protection pack (web ACL): additional considerations](waf-migrating-procedure-additional.md).

# Migrating a protection pack (web ACL): additional considerations
<a name="waf-migrating-procedure-additional"></a>

Review your new protection pack (web ACL) and consider the options available to you in the new AWS WAF to be sure that the configuration is as efficient as possible and that it's using the latest available security options. 

**Additional AWS Managed Rules**  
Consider implementing additional AWS Managed Rules in your protection pack (web ACL) to increase the security posture for your application. These are included with AWS WAF at no additional cost. AWS Managed Rules feature the following types of rule groups: 
+ Baseline rule groups provide general protection against a variety of common threats, such as stopping known bad inputs from making it into your application and preventing admin page access. 
+ Use-case specific rule groups provide incremental protection for many diverse use cases and environments.
+ IP reputation lists provide threat intelligence based on the client’s source IP.

For more information, see [AWS Managed Rules for AWS WAF](aws-managed-rule-groups.md).

**Rule optimization and cleanup**  
Revisit your old rules and consider optimizing them by rewriting them or removing outdated ones. For example, if in the past, you deployed an AWS CloudFormation template from the technical paper for OWASP Top 10 Web Application Vulnerabilities, [Prepare for the OWASP Top 10 Web Application Vulnerabilities Using AWS WAF and Our New White Paper](https://aws.amazon.com/blogs/aws/prepare-for-the-owasp-top-10-web-application-vulnerabilities-using-aws-waf-and-our-new-white-paper/), you should consider replacing that with AWS Managed Rules. While the concept found within the document is still applicable and may assist you in writing your own rules, the rules created by the template have been largely superseded by AWS Managed Rules.

**Amazon CloudWatch metrics and alarms**  
Revisit your Amazon CloudWatch metrics and set up alarms as needed. The migration doesn't carry over CloudWatch alarms and it's possible that your metric names aren't what you want. 

**Review with your application team**  
Work with your application team and check your security posture. Find out what fields are parsed frequently by the application and add rules to sanitize the input accordingly. Check for any edge cases and add rules to catch these cases if the application’s business logic fails to process them. 

**Plan the switchover**  
Plan the timing of the switch with your application team. The switch from the old protection pack (web ACL) association to the new one can take a small amount of time to propagate to all areas where your resources are stored. The propagation time can be from a few seconds to a number of minutes. During this time, some requests will be processed by the old protection pack (web ACL) and others will be processed by the new protection pack (web ACL). Your resources will be protected throughout the switch, but you might notice inconsistencies in request handling while the switch is underway. 

When you are ready to switch over, follow the procedure at [Migrating a protection pack (web ACL): switchover](waf-migrating-procedure-switchover.md).

# Migrating a protection pack (web ACL): switchover
<a name="waf-migrating-procedure-switchover"></a>

After you've verified your new protection pack (web ACL) settings, you can start to use it in place of your AWS WAF Classic protection pack (web ACL). 

**To begin using your new AWS WAF protection pack (web ACL)**

1. Associate the AWS WAF protection pack (web ACL) with the resources that you want to protect, following the guidance at [Associating or disassociating protection with an AWS resource](web-acl-associating-aws-resource.md). This automatically disassociates the resources from the old protection pack (web ACL). 

   The switch can take from a few seconds to a number of minutes to propagate. During this time, some requests might be processed by the old protection pack (web ACL) and others by the new protection pack (web ACL). Your resources will be protected throughout the switch, but you might notice inconsistencies in request handling until it's complete. 

1. Configure logging for the new protection pack (web ACL), following the guidance at [Logging AWS WAF protection pack (web ACL) traffic](logging.md). 

1. (Optional) If your AWS WAF Classic protection pack (web ACL) is no longer associated with any resources, consider removing it entirely from AWS WAF Classic. For information, see [Deleting a Web ACL](classic-web-acl-deleting.md).