Menu
AWS WAF Security Automations
AWS WAF Security Automations

Automated Deployment

Before you launch the AWS CloudFormation template, please review the architectural and configuration considerations discussed in this guide. Follow the step-by-step instructions in this section to configure and deploy the AWS WAF Security Automations solution into your account.

Time to deploy: Approximately 15 minutes, or longer if you need to create and configure an Amazon CloudFront distribution or Application Load Balancer.

Prerequisites

This solution is designed to work with web applications deployed with Amazon CloudFront or an Application Load Balancer. If you don't already have one of these resources configured, complete the applicable task before you launch the solution.

Configure a CloudFront Distribution

Complete the following steps to configure a CloudFront distribution to distribute both static and dynamic content of your web application. See the Amazon CloudFront Developer Guide for detailed instructions.

Configure an Application Load Balancer

Complete the following steps to configure an Application Load Balancer to distribute incoming traffic to your web application. See the Application Load Balancer Guide for detailed instructions.

What We'll Cover

The procedure for deploying this architecture on AWS consists of the following steps. For detailed instructions, follow the links for each step.

Step 1. Launch the Stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Enter values for the required parameters: Stack Name and CloudFront/ALB Access Log Bucket Name

  • Review the other template parameters, and adjust if necessary.

Step 2. Modify the Whitelist and Blacklist Sets (Optional)

  • Manually add applicable IP addresses to the AWS WAF whitelist and blacklist.

Step 3. Embed the Honeypot Link in Your Web Application (Optional)

  • Embed the hidden trap endpoint in your application.

  • Explicitly disallow access to the endpoint using the robots exclusion standard (CloudFront only).

Step 4. Associate the Web ACL with Your Web Application

  • Associate your Amazon CloudFront web distribution(s) or Application Load Balancers with the web ACL that this solution generates. You can associate as many distributions or load balancers you want.

Step 5. Configure Web Access Logging

  • Enable web access logging for your Amazon CloudFront web distribution or Application Load Balancer, and send log files to the appropriate Amazon S3 bucket.

Step 1. Launch the Stack

This automated AWS CloudFormation template deploys the AWS WAF Security Automations solution on the AWS Cloud.

Note

You are responsible for the cost of the AWS services used while running this solution. See the Cost section for more details. For full details, see the pricing webpage for each AWS service you will be using in this solution.

  1. Log in to the AWS Management Console and click the applicable button to launch the AWS CloudFormation template.

    
                                AWS WAF Security Automations launch button for CloudFront
                            
                                AWS WAF Security Automations launch button for Application Load Balancer

    You can also download the template as a starting point for your own implementation.

  2. The template is launched in the US East (N. Virginia) Region by default. To launch the solution in a different AWS Region, use the region selector in the console navigation bar.

    Note

    This solution uses AWS Lambda and Amazon API Gateway, which are currently available in specific AWS Regions only. Therefore, you must launch this solution an AWS Region where both Lambda and API Gateway are available. For the most current service availability information, see the AWS service offerings by region.

  3. On the Select Template page, verify that you selected the correct template and choose Next.

  4. On the Specify Details page, assign a name to AWS WAF configuration in the Stack name field. This will also be the name of the web ACL that the template creates.

    Important

    The stack name must be less than 25 characters.

  5. Under Parameters, review the parameters for the template, and modify them as necessary. To opt out of a particular feature, choose none or no as applicable.

    This solution uses the following default values.

    Parameter Default Description
    Stack Name <Requires input>

    The stack name must be less than 25 characters, cannot contain spaces, and must be unique within your AWS account. This will also be the name of the web ACL that the template creates.

    Activate SQL Injection Protection yes

    Choose yes to enable the component designed to block common SQL injection attacks.

    Activate Cross-site Scripting Protection yes

    Choose yes to enable the component designed to block common XSS attacks.

    Activate HTTP Flood Protection yes

    Choose yes to enable the component designed to block HTTP flood attacks.

    Activate Scanner & Probe Protection yes

    Choose yes to enable the component designed to block scanners and probes.

    Activate Reputation List Protection yes

    Choose yes to block requests from IP addresses on third-party reputation lists (supported lists: spamhaus, torproject, and emergingthreats).

    Activate Bad Bot Protection yes

    Choose yes to enable the component designed to block bad bots and content scrapers.

    CloudFront Access Log Bucket Name or ALB Access Log Bucket Name <Requires input>

    Enter a name for the Amazon S3 bucket where you want to store access logs for your CloudFront distribution or Application Load Balancer. This can be the name of either an existing S3 bucket, or a new bucket that the template will create during stack launch (if it does not find a matching bucket name). The solution will modify the bucket’s notification configuration to trigger the Log Parser AWS Lambda function whenever a new log file is saved in this bucket.

    Note

    If you use an existing S3 bucket for this parameter, it must be located in the same AWS Region where you are deploying the AWS CloudFormation template.

    Send Anonymous Usage Data yes

    Send anonymous data to AWS to help us understand solution usage across our customer base as a whole. To opt out of this feature, choose no.

    For more information, see Appendix B.
    Request Threshold 400

    If you chose yes for the Activate HTTP Flood Protection parameter, enter the maximum acceptable requests per minute per IP address. If you chose to deactivate this protection, ignore this parameter.

    Error Threshold 50

    If you chose yes for the Activate Scanner & Probe Protection parameter, enter the maximum acceptable bad requests per minute per IP address. If you chose to deactivate this protection, ignore this parameter.

    WAF Block Period 240

    If you chose yes for the Activate HTTP Flood Protection or Activate Scanner & Probe Protection parameter, enter the period (in minutes) to block applicable IP addresses. If you chose to deactivate both types of protection, ignore this parameter.

  6. Choose Next.

  7. On the Options page, you can specify tags (key-value pairs) for resources in your stack and set additional options, and then choose Next.

  8. On the Review page, review and confirm the settings. Be sure to check the box acknowledging that the template will create AWS Identity and Access Management (IAM) resources.

  9. Choose Create to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation console in the Status column. You should see a status of CREATE_COMPLETE in roughly fifteen (15) minutes.

    Note

    In addition to the Log Parser, IP Lists Parser, Access Handler AWS Lambda functions, this solution includes the solution-helper and custom-resourceLambda functions, which run only during initial configuration or when resources are updated or deleted.

    When running this solution, you will see all functions in the AWS Lambda console, but only the three primary solution functions are regularly active. However, do not delete the other two functions, as they are necessary to manage associated resources.

  10. To see details for the stack resources, choose the Outputs tab. This will include the BadBotHoneypotEndpoint value, which is the API Gateway honeypot endpoint. Note this value because you will use it in Step 3.

Step 2. Modify the Whitelist and Blacklist Sets (Optional)

After deploying the solution’s AWS CloudFormation stack, you can manually modify the whitelist and blacklist sets to add or remove IP addresses as necessary.

  1. Open the AWS WAF console, and in the left navigation pane, choose IP addresses.

  2. Choose Whitelist Set and add IP addresses from trusted sources.

  3. Choose Manual Blacklist Set and add IP addresses you want to block.

Step 3. Embed the Honeypot Link in Your Web Application (Optional)

If you chose to activate scanner and probe protection in Step 1, the AWS CloudFormation template creates a trap endpoint to a low-interaction production honeypot, intended to detect and divert inbound requests from content scrapers and bad bots. Valid users will not attempt to access this endpoint. However, content scrapers and bots, such as malware that scans for security vulnerabilities and scrapes email addresses might attempt to access the trap endpoint. In this scenario, the Access Handler AWS Lambda function will inspect the request in order to extract its origin, and then update the associated AWS WAF rule to block subsequent requests from that IP address.

Use the applicable procedure to embed the honeypot link for requests from either a CloudFront distribution or an Application Load Balancer.

Create a CloudFront Origin for the Honeypot Endpoint

Use this procedure for web applications that are deployed with a CloudFront distribution. With CloudFront, you can include a robots.txt file to help identify content scrapers and bots that ignore the robots exclusion standard. Complete the following steps to embed the hidden link and then explicitly disallow it in your robots.txt file.

  1. Open the AWS CloudFormation console, choose the stack that you built in Step 1, and then choose the Outputs tab.

  2. From the BadBotHoneypotEndpoint key, copy the endpoint URL. It contains two components that you will need to complete this procedure: the endpoint host name (e.g., xxxxxxxxxx.execute-api.region.amazonaws.com) and the request URI (/ProdStage).

  3. Open the Amazon CloudFront console and choose the distribution that you want to use.

  4. Choose Distribution Settings, and on the Origins tab, choose Create Origin.

  5. In the Origin Domain Name field, paste the endpoint URL that you copied in Step 2. Accept the default values for the other fields and choose Create.

  6. On the Behaviors tab, choose Create Behavior.

  7. Create a new cache behavior and point it to the new origin. You can use a custom domain, such as a fake product name that is similar to other content in your web application.

  8. Embed this endpoint link in your content pointing to the honeypot. You should hide this link from your regular human users, as shown in the following code example:

    <a href="/behavior_path" rel="nofollow" style="display: none" aria-hidden="true">honeypot link</a>

  9. Modify the robots.txt file in the root of your website to explicitly disallow the honeypot link, as follows:

    Copy
    User-agent: * Disallow: /behavior_path

Embed the Honeypot Endpoint as an External Link

Use this procedure for web applications that are deployed with an Application Load Balancer.

  1. Open the AWS CloudFormation console, choose the stack that you built in Step 1, and then choose the Outputs tab.

  2. From the BadBotHoneypotEndpoint key, copy the endpoint URL.

  3. Embed this endpoint link in your web content. Use the full URL that you copied in Step 2. You should hide this link from your regular human users, as shown in the following code example:

    <a href="BadBotHoneypotEndpoint value/" rel="nofollow" style="display: none" aria-hidden="true">honeypot link</a>

    Note

    This procedure uses nofollow to instruct robots to not access the honeypot URL. However, because the link is embedded externally, you cannot include a robots.txt file to explicitly disallow the link. If you want to use a relative path and include the robots exclusion standard (similar to the previous procedure for web apps deployed with CloudFront), you must first Set up a Custom Domain Name for an API Host Name as explained in the Amazon API Gateway Developer Guide.

Step 4. Associate the Web ACL with Your Web Application

Update your Amazon CloudFront distribution(s) or Application Load Balancer(s) to activate AWS WAF and logging using the resources you generated in Step 1.

Note

You can associate only one web ACL with a CloudFront distribution or Application Load Balancer. Therefore, you cannot use this solution’s web ACL in addition to an existing association.

  1. Open the AWS WAF console and choose the web ACL that you want to use.

  2. On the Rules tab, choose Add association.

  3. For AWS resources using this web ACL, choose the CloudFront distribution or Application Load Balancer.

  4. Choose Add to save your changes.

Step 5. Configure Web Access Logging

Configure Amazon CloudFront or your Application Load Balancer to send web access logs to the appropriate Amazon S3 bucket so that this data is available for the Log Parser AWS Lambda function.

Store Web Access Logs from a CloudFront Distribution

  1. Open the Amazon CloudFront console at https://console.aws.amazon.com/cloudfront/.

  2. Select your web application’s distribution, and choose Distribution Settings.

  3. On the General tab, choose Edit.

  4. For AWS WAF Web ACL, choose the web ACL the solution created (the same name you assigned to the stack during initial configuration).

  5. For Logging, choose On.

  6. For Bucket for Logs, choose the Amazon S3 bucket that you want use to store web access logs (that you defined in Step 1). The drop-down list enumerates the buckets associated with the current AWS account.

  7. Choose Yes, edit to save your changes

Store Web Access Logs from an Application Load Balancer

  1. Open the Amazon Elastic Compute Cloud console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Load Balancers.

  3. Select your web application’s Application Load Balancer.

  4. On the Description tab, choose Edit attributes.

  5. Choose Enable access logs.

  6. For S3 location, type the name of the Amazon S3 bucket that you want use to store web access logs (that you defined in Step 1).

  7. Choose Save.