# Architecture overview
<a name="architecture-overview"></a>

This section provides a reference implementation architecture diagram for the components deployed with this solution.

## Architecture diagram
<a name="architecture-diagram"></a>

Deploying this solution with the default parameters deploys the following components in your AWS account.

 **CloudFormation template deploys AWS WAF and other AWS resources to protect your web application from common attacks.** 

![\[aws waf architecture overview\]](http://docs.aws.amazon.com/solutions/latest/security-automations-for-aws-waf/images/aws-waf-architecture-overview.png)


At the core of the design is an [AWS WAF](https://aws.amazon.com/waf/) web ACL, which acts as the central inspection and decision point for all incoming requests to a web application. During initial configuration of the CloudFormation stack, the user defines which protective components to activate. Each component operates independently and adds different rules to the web ACL.

The components of this solution can be grouped into the following areas of protection.

**Note**  
The group labels don’t reflect the priority level of the WAF rules.
+  **AWS Managed Rules (A)** - This component contains AWS Managed Rules [IP reputation rule groups](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-ip-rep.html), [baseline rule groups](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html), and [use-case specific rule groups](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-use-case.html). These rule groups protect against exploitation of common application vulnerabilities or other unwanted traffic, including those described in [OWASP](https://owasp.org/) publications, without having to write your own rules.
+  **Manual IP lists (B and C)** - These components create two AWS WAF rules. With these rules, you can manually insert IP addresses that you want to allow or deny. You can configure IP retention and remove expired IP addresses on allowed or denied IP sets using [Amazon EventBridge](https://aws.amazon.com/eventbridge) [rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) and [Amazon DynamoDB](https://aws.amazon.com/dynamodb). For more information, refer to [Configure IP retention on Allowed and Denied AWS WAF IP sets](configure-ip-retention-on-allowed-and-denied-aws-waf-ip-sets.md).
+  **SQL Injection (D) and XSS (E)** - These components configure two AWS WAF rules that are designed to protect against common SQL injection or cross-site scripting (XSS) patterns in the URI, query string, or body of a request.
+  **HTTP Flood (F)** - This component protects against attacks that consist of a large number of requests from a particular IP address, such as a web-layer DDoS attack or a brute-force login attempt. With this rule, you set a quota that defines the maximum number of incoming requests allowed from a single IP address within a default five-minute period (configurable with the **Athena Query Run Time Schedule** parameter). After this threshold is breached, additional requests from the IP address are temporarily blocked. You can implement this rule by using an AWS WAF rate-based rule, or by processing AWS WAF logs using a Lambda function or Athena query. For more information about the tradeoffs related to HTTP flood mitigation options, refer to [Log parser options](log-parser-options.md).
+  **Scanner and Probe (G)** - This component parses application access logs searching for suspicious behavior, such as an abnormal amount of errors generated by an origin. Then it blocks those suspicious source IP addresses for a customer-defined period of time. You can implement this rule using a [Lambda](https://aws.amazon.com/lambda/) function or [Athena](https://aws.amazon.com/athena/) query. For more information about the tradeoffs related to scanner and probe mitigation options, refer to [Log parser options](log-parser-options.md).
+  **IP Reputation Lists (H)** - This component is the `IP Lists Parser` Lambda function that checks third-party IP reputation lists hourly for new ranges to block. These lists include the Spamhaus Don’t Route Or Peer (DROP) and Extended DROP (EDROP) lists, the Proofpoint Emerging Threats IP list, and the Tor exit node list.
+  **Bad Bot (I)** - This component enhances bad bot detection by monitoring direct connections to an Application Load Balancer (ALB) or Amazon CloudFront, in addition to the honeypot mechanism. If a bot bypasses the honeypot and attempts to interact with ALB or CloudFront, the system analyzes request patterns and logs to identify malicious activity. When a bad bot is detected, its IP address is extracted and added to an AWS WAF block list to prevent further access. Bad bot detection operates through a structured logic chain, ensuring comprehensive threat coverage:
  + HTTP Flood Protection Lambda Log Parser – Collects bad bot IPs from log entries during flood analysis.
  + Scanner & Probe Protection Lambda Log Parser – Identifies bad bot IPs from scanner-related log entries.
  + HTTP Flood Protection Athena Log Parser – Extracts bad bot IPs from Athena logs, using partitions across query run.
  + Scanner & Probe Protection Athena Log Parser – Retrieves bad bot IPs from scanner-related Athena logs, using the same partitioning strategy.
  + Fallback Detection – If both HTTP Flood Protection and Scanner & Probe Protection are disabled, the system relies on the Log Lambda parser, which logs bot activity based on [WAF label filters](https://docs.aws.amazon.com/waf/latest/developerguide/waf-labels.html).

Each of the three custom Lambda functions in this solution publish runtime metrics to CloudWatch. For more information on these Lambda functions, refer to [Component details](component-details.md).

# AWS Well-Architected design considerations
<a name="well-architected"></a>

This solution uses the best practices from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/), which helps customers design and operate reliable, secure, efficient, and cost-effective workloads in the cloud.

This section describes how the design principles and best practices of the Well-Architected Framework benefit this solution.

## Operational excellence
<a name="operational-excellence"></a>

This section describes how we architected this solution using the principles and best practices of the [operational excellence pillar](https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/welcome.html).
+ The solution pushes metrics to CloudWatch to provide observability into the infrastructure, Lambda functions, [Amazon Data Firehose](https://aws.amazon.com/kinesis/data-firehose/), Amazon S3 buckets, and the rest of the solution components.
+ We develop, test, and publish the solution through an AWS continuous integration and continuous delivery (CI/CD) pipeline. This helps developers achieve high quality results consistently.
+ You can install the solution with a CloudFormation template that provisions all the required resources in your account. To update or delete the solution, you only need to update or delete the template.

## Security
<a name="security-pillar"></a>

This section describes how we architected this solution using the principles and best practices of the [security pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html).
+ All inter-service communications use [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM) roles.
+ All roles used by the solution follow [least-privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) access. In other words, they only contain minimum permissions required so that the service can function properly.
+ All data storage, including Amazon S3 buckets and DynamoDB, have encryption at rest.

## Reliability
<a name="reliability"></a>

This section describes how we architected this solution using the principles and best practices of the [reliability pillar](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html).
+ The solution uses AWS serverless services wherever possible (for example, Lambda, Firehose, Amazon S3, and Athena) to ensure high availability and recovery from service failure.
+ We perform automated tests on the solution to detect and fix errors quickly.
+ The solution uses Lambda functions for data processing. The solution stores data in Amazon S3 and DynamoDB, and it persists in multiple Avaialbility Zones by default.

## Performance efficiency
<a name="performance-efficiency"></a>

This section describes how we architected this solution using the principles and best practices of the [performance efficiency pillar](https://docs.aws.amazon.com/wellarchitected/latest/performance-efficiency-pillar/welcome.html).
+ The solution uses a serverless architecture to ensure high scalability and availability at a reduced cost.
+ The solution enhances database performance by parititioning data and optimizing query to reduce the amount of data scanning and achieve faster results.
+ The solution is automatically tested and deployed every day. Our solution architects and subject matter experts review the solution for areas to experiment and improve.

## Cost optimization
<a name="cost-optimization"></a>

This section describes how we architected this solution using the principles and best practices of the [cost optimization pillar](https://docs.aws.amazon.com/wellarchitected/latest/cost-optimization-pillar/welcome.html).
+ The solution uses a serverless architecture, and customers pay only for what they use.
+ The solution’s compute layer defaults to Lambda, which uses a pay-per-use model.
+ The Athena database and queries are optimized to reduce the amount of data scanning, thereby reducing cost.

## Sustainability
<a name="sustainability"></a>

This section describes how we architected this solution using the principles and best practices of the [sustainability pillar](https://docs.aws.amazon.com/wellarchitected/latest/sustainability-pillar/sustainability-pillar.html).
+ The solution uses managed and serverless services to minimize the environmental impact of the backend services.
+ The solution’s serverless design is aimed at reducing carbon footprint compared to the footprint of continually operating on-premises servers.