AWS WAF Integration

Connect WebDecoy to your AWS WAF Web ACL and let Response Actions enforce there automatically — a managed fingerprint rule for confirmed rotating actors, and time-boxed IP blocks for individual detections. Enforcement runs at your edge, in infrastructure you own; WebDecoy never sits in your traffic path.

What WebDecoy manages in your Web ACL

Mechanism	What it is	When it’s used
Managed fingerprint rule	A rule in your Web ACL matching confirmed actors’ JA4 TLS fingerprints	The Block actor at WAF action, for confirmed rotating actors only
Managed IP set	An IP set WebDecoy creates and maintains, with automatic expiry	The Block IP action

Both are created and updated by WebDecoy through the AWS API — you don’t hand-maintain rules. The fingerprint rule follows the actor across every IP it rotates through; IP blocks handle one-off offenders and expire automatically.

Prerequisites

• AWS account with AWS WAF v2 and an existing Web ACL attached to your resource (ALB, API Gateway, or CloudFront)
• IAM credentials with the permissions below

Required IAM Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "wafv2:GetWebACL",
        "wafv2:UpdateWebACL",
        "wafv2:CreateIPSet",
        "wafv2:GetIPSet",
        "wafv2:UpdateIPSet",
        "wafv2:ListIPSets"
      ],
      "Resource": "*"
    }
  ]
}

For production, scope Resource to your specific Web ACL and WebDecoy’s IP set ARNs, and use a dedicated IAM user for WebDecoy. Never use root credentials.

Setting Up the Integration

1. Go to Integrations → AWS WAF

2. Click Add AWS WAF Integration

3. Configure:

   Field	Description
   Name	A label for this connection (e.g., Production WAF)
   Access Key ID	AWS IAM access key
   Secret Access Key	AWS IAM secret key
   Region	AWS region of your Web ACL (e.g., us-east-1)
   Web ACL ARN	The ARN of the Web ACL WebDecoy should manage rules in
   Web ACL Name	The Web ACL’s name
   Scope	REGIONAL (ALB, API Gateway) or CLOUDFRONT
   Action	What pushed rules do: Block, Count (Monitor Only), or Allow
   IP Block Duration	How long pushed IP blocks stay in the IP set (1–8760 hours, default 24)

4. Click Connect — WebDecoy verifies it can reach the Web ACL

Start in Count mode

Set Action to Count (Monitor Only) first. Pushed rules will log what they would have blocked without blocking anything, so you can review the impact in AWS WAF metrics before switching to Block.

Scope Options

Scope	Use case
REGIONAL	ALB, API Gateway, AppSync
CLOUDFRONT	CloudFront distributions (use the Global WAF console)

Triggering enforcement

Rule pushes come from Response Actions — the integration itself just holds the connection. Typical setup:

1. Connect AWS WAF (this page)
2. Create a Response Action with the confirmed rotating actor trigger and the Block actor at WAF action
3. Optionally add a second Response Action with the high-risk detection trigger and the Block IP action

How It Works

Confirmed rotating actor (JA4 seen across many IPs, high threat)
        │
        ▼
Response Action fires (trigger: rotating actor)
        │
        ▼
WebDecoy updates the managed fingerprint rule in your Web ACL
        │
        ▼
AWS WAF matches the actor's JA4 on every request
        │
        ▼
Actor is blocked / counted on ALL its IPs — current and future

IP blocks follow the same path via the managed IP set, and expire after the configured duration.

Why fingerprint rules are limited to rotating actors

A JA4 fingerprint is shared by every client running the same software stack — blocking one from a single detection could block legitimate users who share it. WebDecoy only pushes fingerprint rules for confirmed rotating actors (a fingerprint seen across multiple IPs with high aggregate threat — behavior no legitimate user population produces), and per-detection triggers use scoped, expiring IP blocks instead.

Note that fingerprint rules are strongest against datacenter and scripted bots, whose TLS stacks stand out. They are intentionally conservative against browser-shaped traffic.

Managing blocked IPs

Blocked IPs live in the managed IP set on your Web ACL and expire automatically based on the integration’s block duration. To inspect or remove entries manually, use the AWS console (WAF → IP sets).

AWS WAF limits to know

Limit	Value
IPs per IP set	10,000
Web ACL capacity (WCU)	Rules consume capacity from your Web ACL’s budget

WebDecoy manages IP set size automatically — expired and oldest entries are removed as needed.

Troubleshooting

”Access Denied” Error

1. Verify the IAM policy includes all actions listed above (the fingerprint rule needs GetWebACL/UpdateWebACL)
2. Check credentials and region match the Web ACL
3. For CloudFront, use the CLOUDFRONT scope

Rules not appearing in the Web ACL

1. Verify the integration shows connected (green status)
2. Confirm a Response Action exists with a block action enabled
3. Fingerprint rules require the confirmed rotating actor trigger — check the actor’s status on the Actors screen

Nothing is being blocked

1. Check the integration’s Action setting — Count (Monitor Only) logs but doesn’t block
2. Verify the Web ACL is associated with your ALB/API Gateway/CloudFront resource
3. Review rule priority in the Web ACL

Cost Considerations

AWS WAF pricing: Web ACL $5/month, rules $1/month each, $0.60 per million requests. The WebDecoy-managed rule and IP set add little beyond your existing WAF usage.

---

Next Steps

• Response Actions — configure what triggers enforcement
• Actors — the identity model behind fingerprint rules
• Overview — all integrations