AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide AWS WAF, AWS Firewall Manager, and AWS Shield Advanced: Developer Guide Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon. AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Table of Contents What are AWS WAF, AWS Shield, and AWS Firewall Manager? .................................................................. 1 AWS Shield ............................................................................................................................... 2 AWS Firewall Manager ................................................................................................................ 2 Which should I choose?.............................................................................................................. 2 ........................................................................................................................................ 2 Setting up......................................................................................................................................... 3 Step 1: Sign up for an AWS account ............................................................................................. 3 Step 2: Create an IAM user .......................................................................................................... 3 Step 3: Download tools .............................................................................................................. 5 AWS WAF.......................................................................................................................................... 6 How AWS WAF works ................................................................................................................. 6 AWS WAF components........................................................................................................ 7 AWS WAF Web ACL capacity units (WCU) .............................................................................. 7 Resources that you can protect with AWS WAF ...................................................................... 7 Getting started with AWS WAF .................................................................................................... 8 Step 1: Set up AWS WAF .................................................................................................... 9 Step 2: Create a Web ACL ................................................................................................... 9 Step 3: Add a string match rule ........................................................................................... 9 Step 4: Add an AWS Managed Rules rule group .................................................................... 11 Step 5: Finish your web ACL configuration ........................................................................... 11 Step 6: Clean up your resources ......................................................................................... 12 Web access control lists (web ACLs) ............................................................................................ 12 How AWS resources handle response delays from AWS WAF .................................................. 13 Web ACL rule and rule group evaluation ............................................................................. 13 Deciding on the default action for a web ACL ...................................................................... 16 CAPTCHA, challenge, and token domain configuration .......................................................... 17 Working with web ACLs .................................................................................................... 18 Rule groups............................................................................................................................. 25 Managed rule groups ........................................................................................................ 26 Managing your own rule groups ......................................................................................... 81 Rule groups from other services ......................................................................................... 83 Rules...................................................................................................................................... 83 Rule name....................................................................................................................... 84 Rule action...................................................................................................................... 84 Rule statements............................................................................................................... 85 Web request body, headers, and cookies ................................................................................... 120 IP sets and regex pattern sets .................................................................................................. 122 Creating and managing an IP set ...................................................................................... 122 Creating and managing a regex pattern set ....................................................................... 124 Customized web requests and responses ................................................................................... 126 Custom request header insertions ..................................................................................... 128 Custom responses........................................................................................................... 129 Supported status codes ................................................................................................... 131 Labels on web requests ........................................................................................................... 132 How labeling works ........................................................................................................ 133 Syntax and naming requirements ..................................................................................... 134 Adding a label ............................................................................................................... 136 Matching against a label................................................................................................. 136 Label match examples..................................................................................................... 137 Intelligent threat mitigation ..................................................................................................... 140 Comparison of the options.............................................................................................. 141 AWS WAF tokens ............................................................................................................ 145 Bot Control.................................................................................................................... 152 Account takeover prevention ............................................................................................ 166 iii AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Client application integration........................................................................................... 176 CAPTCHA and Challenge actions ....................................................................................... 187 Logging web ACL traffic .......................................................................................................... 193 Pricing for logging web ACL traffic information .................................................................. 193 AWS WAF logging destinations ......................................................................................... 193 Managing logging for a web ACL ...................................................................................... 200 Log Fields...................................................................................................................... 201 Log Examples................................................................................................................. 205 Listing IP addresses blocked by rate-based rules ......................................................................... 213 Testing and tuning your protections ......................................................................................... 213 Testing and tuning high-level steps .................................................................................. 214 Preparing for testing ....................................................................................................... 215 Monitoring and tuning.................................................................................................... 216 Enabling your protections in production ............................................................................ 221 How AWS WAF works with Amazon CloudFront features .............................................................. 222 Using AWS WAF with CloudFront custom error pages .......................................................... 222 Using AWS WAF with CloudFront for applications running on your own HTTP server ................ 223 Choosing the HTTP methods that CloudFront responds to ................................................... 223 Security in your use of the AWS WAF service ............................................................................. 224 Data protection.............................................................................................................. 224 Identity and access management ...................................................................................... 225 Logging and monitoring.................................................................................................. 242 Compliance validation..................................................................................................... 243 Resilience...................................................................................................................... 244 Infrastructure security..................................................................................................... 244 AWS WAF quotas .................................................................................................................... 244 Migrating your AWS WAF Classic resources to AWS WAF .............................................................. 246 Why migrate to AWS WAF? .............................................................................................. 246 How the migration works ................................................................................................ 247 Migration caveats........................................................................................................... 248 Migrating a web ACL ....................................................................................................... 248 AWS WAF Classic ............................................................................................................................ 253 Setting up AWS WAF Classic .................................................................................................... 253 Step 1: Sign up for an AWS account ................................................................................. 254 Step 2: Create an IAM user .............................................................................................. 254 Step 3: Download tools ................................................................................................... 256 How AWS WAF Classic works ................................................................................................... 256 AWS WAF Classic pricing ......................................................................................................... 259 .................................................................................................................................... 259 Getting started with AWS WAF Classic ...................................................................................... 259 Step 1: Set up AWS WAF Classic ....................................................................................... 260 Step 2: Create a Web ACL ................................................................................................ 260 Step 3: Create an IP match condition ................................................................................ 261 Step 4: Create a geo match condition ............................................................................... 261 Step 5: Create a string match condition ............................................................................. 261 Step 5A: Create a regex condition (optional) ...................................................................... 263 Step 6: Create a SQL injection match condition .................................................................. 264 Step 7: (Optional) create additional conditions ................................................................... 265 Step 8: Create a rule and add conditions ........................................................................... 265 Step 9: Add the rule to a Web ACL ................................................................................... 267 Step 10: Clean up your resources ..................................................................................... 267 Creating and configuring a Web Access Control List (Web ACL) ..................................................... 269 Working with conditions .................................................................................................. 270 Working with rules ......................................................................................................... 300 Working with web ACLs ................................................................................................... 307 Working with AWS WAF Classic rule groups for use with AWS Firewall Manager .............................. 316 Creating an AWS WAF Classic rule group ........................................................................... 317 iv AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Adding and deleting rules from an AWS WAF Classic rule group ............................................ 317 Getting started with AWS Firewall Manager to enable AWS WAF Classic rules ................................. 318 Step 1: Complete the prerequisites ................................................................................... 319 Step 2: Create rules ........................................................................................................ 319 Step 3: Create a rule group ............................................................................................. 319 Step 4: Create and apply an AWS Firewall ManagerAWS WAF Classic policy ............................ 320 Tutorial: Creating a AWS Firewall Managerpolicy with hierarchical rules ......................................... 321 Step 1: Designate a Firewall Manager administrator account ................................................ 322 Step 2: Create a rule group using the Firewall Manager administrator account ........................ 322 Step 3: Create a Firewall Manager policy and attach the common rule group .......................... 323 Step 4: Add account-specific rules .................................................................................... 323 Conclusion..................................................................................................................... 323 Logging Web ACL traffic information ........................................................................................ 323 Listing IP addresses blocked by rate-based rules ......................................................................... 328 How AWS WAF Classic works with Amazon CloudFront features .................................................... 328 Using AWS WAF Classic with CloudFront custom error pages ................................................ 329 Using AWS WAF Classic with CloudFront for applications running on your own HTTP server ...... 329 Choosing the HTTP methods that CloudFront responds to ................................................... 330 Security................................................................................................................................. 330 Data protection.............................................................................................................. 331 Identity and access management ...................................................................................... 332 Logging and monitoring.................................................................................................. 353 Compliance validation..................................................................................................... 354 Resilience...................................................................................................................... 355 Infrastructure security..................................................................................................... 355 AWS WAF Classic quotas ......................................................................................................... 355 AWS Firewall Manager.................................................................................................................... 359 AWS Firewall Manager pricing .................................................................................................. 359 .................................................................................................................................... 359 AWS Firewall Manager prerequisites .......................................................................................... 359 Step 1: Join and configure AWS Organizations ................................................................... 360 Step 2: Set the AWS Firewall Manager administrator account ............................................... 360 Step 3: Enable AWS Config .............................................................................................. 361 Step 4: For third-party policies, subscribe in the AWS Marketplace and configure third-party settings......................................................................................................................... 361 Step 5: For Network Firewall and DNS Firewall policies, enable resource sharing ...................... 362 Step 6: To use AWS Firewall Manager in Regions that are disabled by default .......................... 362 Managing the Firewall Manager administrator ............................................................................ 363 Changing the account ..................................................................................................... 363 Disqualifying changes to the account ................................................................................ 364 Getting started with AWS Firewall Manager policies .................................................................... 365 Getting started with AWS WAF policies ............................................................................. 365 Getting started with AWS Shield Advanced policies ............................................................. 367 Getting started with Amazon VPC security group policies .................................................... 370 Getting started with AWS Network Firewall policies ............................................................ 372 Getting started with DNS Firewall policies ......................................................................... 374 Getting started with Palo Alto Networks Cloud NGFW policies .............................................. 375 Getting started with Fortigate CNF policies ........................................................................ 378 Working with AWS Firewall Manager policies ............................................................................. 380 .................................................................................................................................... 380 General settings............................................................................................................. 381 Creating a policy ............................................................................................................ 381 Deleting a policy ............................................................................................................ 400 Policy scope................................................................................................................... 400 Managed lists................................................................................................................. 402 AWS WAF policies ........................................................................................................... 405 AWS Shield Advanced policies .......................................................................................... 408 v AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Security group policies .................................................................................................... 411 Network Firewall policies ................................................................................................. 417 DNS Firewall policies ....................................................................................................... 423 Palo Alto Networks Cloud NGFW policies ........................................................................... 425 Fortigate CNF policies ..................................................................................................... 425 Resource sharing for Network Firewall and DNS Firewall policies ........................................... 426 Working with resource sets ...................................................................................................... 427 Considerations when working with resource sets in Firewall Manager ..................................... 427 Creating resource sets ..................................................................................................... 428 .................................................................................................................................... 428 Viewing resource compliance ................................................................................................... 428 Firewall Manager findings ........................................................................................................ 431 AWS WAF policy findings ................................................................................................. 432 Shield policy findings ...................................................................................................... 432 Security group common policy findings ............................................................................. 433 Security group content audit policy findings ...................................................................... 433 Security group usage audit policy findings ......................................................................... 434 DNS Firewall policy findings ............................................................................................ 434 Security................................................................................................................................. 434 Data protection.............................................................................................................. 435 Identity and access management ...................................................................................... 436 Logging and monitoring.................................................................................................. 456 Compliance validation..................................................................................................... 457 Resilience...................................................................................................................... 457 Infrastructure security..................................................................................................... 457 AWS Firewall Manager quotas .................................................................................................. 458 Soft quotas.................................................................................................................... 458 Hard quotas................................................................................................................... 460 AWS Shield.................................................................................................................................... 461 How Shield works ................................................................................................................... 462 AWS Shield Standard overview ......................................................................................... 463 AWS Shield Advanced overview ........................................................................................ 463 Examples of DDoS attacks ............................................................................................... 466 How Shield detects events ............................................................................................... 467 How Shield mitigates events ............................................................................................ 470 Examples of DDoS resilient architectures ................................................................................... 474 DDoS resiliency example for web applications .................................................................... 474 DDoS resiliency example for TCP and UDP applications ....................................................... 476 Example Shield Advanced use cases .......................................................................................... 477 Getting started ....................................................................................................................... 478 Subscribe to Shield Advanced .......................................................................................... 478 Add resources to protect and configure protections ............................................................ 479 Configure SRT support .................................................................................................... 482 Create a DDoS dashboard in CloudWatch and set CloudWatch alarms .................................... 483 SRT support........................................................................................................................... 484 Configuring access for the Shield Response Team (SRT) ....................................................... 485 Configuring proactive engagement ................................................................................... 486 Contacting the SRT ......................................................................................................... 487 Configuring custom mitigations with the SRT..................................................................... 487 Resource protections............................................................................................................... 488 Protections by resource type ............................................................................................ 488 Application layer (layer 7) protections ............................................................................... 489 Configuring health-based detection using health checks ...................................................... 496 Managing resource protections ......................................................................................... 503 Protection groups........................................................................................................... 507 Tracking protection changes ............................................................................................ 508 Visibility into DDoS events ....................................................................................................... 509 vi AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Global and account activity .............................................................................................. 509 Events........................................................................................................................... 512 Metrics.......................................................................................................................... 518 Event visibility across accounts ......................................................................................... 518 Responding to DDoS events ..................................................................................................... 520 Contacting support for an application layer attack .............................................................. 520 Manually mitigating an application layer attack .................................................................. 521 Requesting a credit after an attack ........................................................................................... 522 Security in your use of the Shield service .................................................................................. 523 Data protection.............................................................................................................. 523 Identity and access management ...................................................................................... 524 Logging and monitoring.................................................................................................. 537 Compliance validation..................................................................................................... 538 Resilience...................................................................................................................... 538 Infrastructure security..................................................................................................... 538 AWS Shield Advanced quotas ................................................................................................... 539 Monitoring..................................................................................................................................... 540 Monitoring tools..................................................................................................................... 540 Automated tools............................................................................................................ 540 Manual tools.................................................................................................................. 541 Monitoring with CloudWatch ............................................................................................ 542 Logging API calls with AWS CloudTrail ...................................................................................... 549 AWS WAF information in AWS CloudTrail ........................................................................... 550 AWS Shield Advanced information in CloudTrail ................................................................. 557 AWS Firewall Manager information in CloudTrail ................................................................ 558 Using the AWS WAF and AWS Shield Advanced API ............................................................................ 561 Using the AWS SDKs ............................................................................................................... 561 Making HTTPS requests to AWS WAF or Shield Advanced ............................................................ 561 Request URI................................................................................................................... 561 HTTP headers................................................................................................................ 561 HTTP request body ......................................................................................................... 562 HTTP responses...................................................................................................................... 563 Error responses.............................................................................................................. 564 Authenticating requests........................................................................................................... 564 Related information........................................................................................................................ 566 Document history........................................................................................................................... 567 Updates before 2018 .............................................................................................................. 582 AWS glossary................................................................................................................................. 585 vii AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide What are AWS WAF, AWS Shield, and AWS Firewall Manager? AWS WAF is a web application firewall that lets you monitor the HTTP and HTTPS 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 WAF also lets you control access to your content. Based on conditions that you specify, such as the IP addresses that requests originate from or the values of query strings, your protected resource responds to requests either with the requested content, with an HTTP 403 status code (Forbidden), or with a custom response. At the simplest level, AWS WAF lets you choose one of the following behaviors: • Allow all requests except the ones that you specify – This is useful when you want Amazon CloudFront, Amazon API Gateway, Application Load Balancer, AWS AppSync, or Amazon Cognito to serve content for a public website, but you also want to block requests from attackers. • Block all requests except the ones that you specify – This is useful when you want to serve content for a restricted website whose users are readily identifiable by properties in web requests, such as the IP addresses that they use to browse to the website. • Count requests that match your criteria – You can use the Count action to track your web traffic without modifying how you handle it. You can use this for general monitoring and also to test your new web request handling rules. When you want to allow or block requests based on new properties in the web requests, you can first configure AWS WAF to count the requests that match those properties. This lets you confirm your new configuration settings before you switch your rules to allow or block matching requests. • Run CAPTCHA or challenge checks against requests that match your criteria – You can implement CAPTCHA and silent challenge controls against requests to help reduce bot traffic to your protected resources. Using AWS WAF has several benefits: • Additional protection against web attacks using criteria that you specify. You can define criteria using characteristics of web requests such as the following: • IP addresses that requests originate from. • Country that requests originate from. • Values in request headers. • Strings that appear in requests, either specific strings or strings that match regular expression (regex) patterns. • Length of requests. • Presence of SQL code that is likely to be malicious (known as SQL injection). • Presence of a script that is likely to be malicious (known as cross-site scripting). 1 AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide AWS Shield • Rules that can allow, block, or count web requests that meet the specified criteria. Alternatively, rules can block or count web requests that not only meet the specified criteria, but also exceed a specified number of requests in any 5-minute period. • Rules that you can reuse for multiple web applications. • Managed rule groups from AWS and AWS Marketplace sellers. • Real-time metrics and sampled web requests. • Automated administration using the AWS WAF API. AWS Shield You can use AWS WAF web access control lists (web ACLs) to help minimize the effects of a Distributed Denial of Service (DDoS) attack. For additional protection against DDoS attacks, AWS also provides AWS Shield Standard and AWS Shield Advanced. AWS Shield Standard is automatically included at no extra cost beyond what you already pay for AWS WAF and your other AWS services. AWS Shield Advanced provides expanded DDoS attack protection for your Amazon EC2 instances, Elastic Load Balancing load balancers, CloudFront distributions, Route 53 hosted zones, and AWS Global Accelerator standard accelerators. AWS Shield Advanced incurs additional charges. For more information about AWS Shield Standard and AWS Shield Advanced, see AWS Shield (p. 461). AWS Firewall Manager AWS Firewall Manager simplifies your administration and maintenance tasks across multiple accounts and resources for a variety of protections, including AWS WAF, AWS Shield Advanced, Amazon VPC security groups, AWS Network Firewall, and Amazon Route 53 Resolver DNS Firewall. With Firewall Manager, you set up your protections just once and the service automatically applies them across your accounts and resources, even as you add new accounts and resources. For more information about Firewall Manager, see AWS Firewall Manager (p. 359). Which should I choose? You can use AWS WAF (p. 6), AWS Firewall Manager (p. 359), and AWS Shield (p. 461) together to create a comprehensive security solution. It all starts with AWS WAF. You can automate and then simplify AWS WAF management using AWS Firewall Manager. Shield Advanced adds additional features on top of AWS WAF, such as dedicated support from the Shield Response Team (SRT) and advanced reporting. If you want granular control over the protection that is added to your resources, AWS WAF alone is the right choice. If you want to use AWS WAF across accounts, accelerate your AWS WAF configuration, or automate protection of new resources, use Firewall Manager with AWS WAF. Finally, if you own high visibility websites or are otherwise prone to frequent DDoS attacks, you should consider purchasing the additional features that Shield Advanced provides. Note To use the services of the SRT, you must be subscribed to the Business Support plan or the Enterprise Support plan. 2 AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide Step 1: Sign up for an AWS account Setting up This topic describes preliminary steps, such as creating an AWS account, to prepare you to use AWS WAF, AWS Firewall Manager, and AWS Shield Advanced. You are not charged to set up this account and other preliminary items. You are charged only for AWS services that you use. After you complete these steps, see Getting started with AWS WAF (p. 8) to continue getting started with AWS WAF. Note AWS Shield Standard is included with AWS WAF and does not require additional setup. For more information, see How AWS Shield works (p. 462). Before you use AWS WAF or AWS Shield Advanced for the first time, complete the following tasks: • Step 1: Sign up for an AWS account (p. 3) • Step 2: Create an IAM user (p. 3) • Step 3: Download tools (p. 5) Step 1: Sign up for an AWS account When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including AWS WAF. You are charged only for the services that you use. If you have an AWS account already, skip to the next task. If you don't have an AWS account, use the following procedure to create one. To sign up for AWS 1. Open https://portal.aws.amazon.com/billing/signup. 2. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad. When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to an administrative user, and use only the root user to perform tasks that require root user access. Note your AWS account number, because you'll need it for the next task. Step 2: Create an IAM user To use the AWS WAF console, you must sign in to confirm that you have permission to perform AWS WAF operations. You can use the root credentials for your AWS account, but we don't recommend it. For greater security and control of your account, we recommend that you use AWS Identity and Access Management (IAM) to do the following: • Create an IAM user account for yourself or your business. 3