view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

internally facing microservice or an externally facing web
application.

Creating an alias in Route 53 for your domain pointing to the ALB
ensures you don't need to update application configurations with the
service's dynamic IP address. Additionally, using a load balancer
allows you to create custom routing rules to your service. If you want
to run multiple tasks for your service to support handling more
traffice a load balancer is required.

With those things in mind the framework automatically uses an ALB for
HTTP services and creates an alias record (A) for your domain for both
internal and external facing services.

## AWS WAF Support

For external-facing HTTPS services, `App::FargateStack` can automate
the creation and association of an AWS Web Application Firewall (WAF)
to provide an essential layer of security. This protects your
application from common web exploits and bots that could affect
availability or compromise security.

The framework follows a "Hybrid Management Model" for WAF, designed to
provide a secure, sensible baseline out-of-the-box while giving you
full control over fine-grained rule customization.

### Enabling WAF Protection

To enable WAF, simply add a `waf` block with `enabled: true` to your
`alb` configuration:

    alb:
      # ... existing alb configuration ...
      waf:
        enabled: true

### Configuring Managed Rules

To simplify configuration, `App::FargateStack` uses a keyword-based
system for enabling AWS Managed Rule Groups. You can specify a list of
keywords under the `managed_rules` key in your `waf` configuration.

If the `managed_rules` key is omitted, the framework will apply the
`default` bundle, which provides a strong and cost-effective security
baseline.

    waf:
      enabled: true
      managed_rules: [linux-app, admin, -php]

The framework supports both individual rule sets and pre-configured
"bundles" for common application types. It also supports a subtractive
syntax (prefixing a keyword with a `-`) to remove rule sets from a
bundle.

#### Rule Set Keywords

- **base**: A strong baseline including `AWSManagedRulesCommonRuleSet`, `AWSManagedRulesAmazonIpReputationList`, and `AWSManagedRulesKnownBadInputsRuleSet`.
- **admin**: Protects exposed administrative pages (`AWSManagedRulesAdminProtectionRuleSet`).
- **sql**: Protects against SQL injection attacks (`AWSManagedRulesSQLiRuleSet`).
- **linux**: Includes rules for Linux and Unix-like environments.
- **php**: Includes rules for applications running on PHP.
- **wordpress**: Includes rules specific to WordPress sites.
- **windows**: Includes rules for Windows Server environments.
- **anonymous**: **Use with caution.** Blocks traffic from anonymous sources like VPNs and proxies, which may block legitimate users.
- **ddos**: Mitigates application-layer (Layer 7) DDoS attacks like HTTP floods.
- **premium**: **Warning: Extra Cost.** Enables advanced, paid protections for bot control and account takeover prevention.

#### Rule Bundles

- **default**: Includes `base` and `sql`. This is the recommended starting point for most applications.
- **linux-app**: Includes `default` and `linux`.
- **wordpress-app**: Includes `default`, `linux`, and `wordpress`.
- **windows-app**: Includes `default` and `windows`.
- **all**: Includes all standard, non-premium rule sets. **Warning:** This will likely exceed the default WCU quota and may incur additional costs.

### The Bootstrap Process (First Run)

On the first `apply` run with WAF enabled, the framework will perform
a one-time bootstrap:

1. It generates a default `web-acl.json` file in your project
directory. This file contains the complete definition of your Web ACL,
including the rules generated from your `managed_rules` keywords.
2. It calls `aws wafv2 create-web-acl` to create a new Web ACL.
3. It calls `aws wafv2 associate-web-acl` to link the new Web ACL to
your Application Load Balancer.
4. It updates your configuration file with the state of the new
WAF resources, including its Name, ID, ARN, LockToken, and a checksum
of the `web-acl.json` file.
5. The `waf` block in your `fargate-stack.yml` is updated to reflect
the bootstrapped state. If the `managed_rules` key was not present,
it will be added with the default value of `[default]`.

### Ongoing Management (Subsequent Runs)

After the initial creation, you take full control of the rules. To
add, remove, or modify rules, you simply edit the `web-acl.json` file
directly.

On subsequent runs of `apply`, `App::FargateStack` will:

- Calculate a checksum of your `web-acl.json` file.
- If the checksum has changed, it will safely update the remote Web ACL
with your new rule set.
- If the checksum has not changed, it will skip the update to avoid
unnecessary API calls.

This model gives you the best of both worlds: the "minimal
configuration, maximum results" of a secure default, and the full
"transparent box" control to customize your security posture as your
application's needs evolve.

### Conflict and Drift Management

The framework includes robust safety checks to prevent accidental data
loss. If it detects that the Web ACL has been modified in the AWS
Console _and_ you have also modified your local `web-acl.json` file,
it will detect the state conflict, refuse to make any changes, and
provide a clear error message with instructions on how to resolve it.