WAF & Shield via SDK Best Practices

A Web ACL that blocks the wrong thing is often worse than no Web ACL - it looks like an outage to your users and like nothing to your dashboards until someone thinks to check WAF. The habits below keep rule changes safe to ship and keep the signal-to-noise ratio in logs and metrics high enough to actually use them.

Walk this list once now, then use it as a review checklist before shipping any code that creates or modifies Web ACLs, rules, or Shield protections.

How to Use This List

• Each item is a rule stated positively, with a one-line rationale.
• Groups run roughly in the order a rule's life cycle hits them: staging and testing first, then logging, scoping, and finally DDoS-specific operations.
• Check the boxes against your own Web ACLs and Shield subscription as a quick audit.
• Revisit whenever you add a new managed rule group, a new custom rule, or protect a new resource with Shield Advanced.

A - Staging & Rollout

• Deploy new custom rules with Count before Block. A rule you have not battle-tested against real traffic risks blocking legitimate requests; Count logs the match without enforcing it.
• Review sampled requests or logs before flipping Count to Block. Confirm the rule only matches what you intend using GetSampledRequests or a logging destination, not just a mental model of the pattern.
• Roll out AWS Managed Rule Group updates the same way. AWS periodically updates managed groups' internal rules; treat a version bump as a change worth watching in metrics, not a silent no-op.
• Keep a fresh LockToken on every update. Call GetWebACL immediately before UpdateWebACL in automation, since a stale token is rejected and a retry loop without refetching will fail every time.

Stage a new custom rule as Count first.

# --- Python (boto3) ---
import boto3
 
wafv2 = boto3.client("wafv2", region_name="us-east-1")
 
staged_rule = {
    "Name": "new-geo-block",
    "Priority": 10,
    "Action": {"Count": {}},   # staged - review before switching to Block
    "Statement": {"GeoMatchStatement": {"CountryCodes": ["XX"]}},
    "VisibilityConfig": {
        "SampledRequestsEnabled": True,
        "CloudWatchMetricsEnabled": True,
        "MetricName": "newGeoBlock",
    },
}

// --- TypeScript (AWS SDK v3) ---
import type { Rule } from "@aws-sdk/client-wafv2";
 
const stagedRule: Rule = {
  Name: "new-geo-block",
  Priority: 10,
  Action: { Count: {} },   // staged - review before switching to Block
  Statement: { GeoMatchStatement: { CountryCodes: ["XX"] } },
  VisibilityConfig: {
    SampledRequestsEnabled: true,
    CloudWatchMetricsEnabled: true,
    MetricName: "newGeoBlock",
  },
};

B - Logging & Visibility

• Turn on PutLoggingConfiguration for any production Web ACL. GetSampledRequests alone only covers the last 3 hours; durable logs are what let you investigate an incident from last week.
• Filter logs to BLOCK/COUNT actions on high-traffic ACLs. Logging every ALLOW match from a busy managed rule group inflates log volume and cost with little diagnostic value.
• Redact sensitive fields before they are ever logged. List headers like authorization and sensitive cookies in RedactedFields; redaction cannot be applied retroactively to already-written logs.
• Alarm on the ACL-level and rule-level CloudWatch metrics. VisibilityConfig's MetricName on both the ACL and each rule is what feeds CloudWatch; a spike in a specific rule's block count is often the first signal of an attack or a bad rule.

C - Rule & Rule Group Design

• Lean on AWS Managed Rule Groups for broad coverage. AWSManagedRulesCommonRuleSet and similar are maintained by AWS and updated as new threats emerge; do not reinvent generic protections with custom ByteMatchStatement rules.
• Scope managed groups down when they are too broad for part of your app. A ScopeDownStatement limits evaluation to matching requests (a specific path prefix, for example), reducing false positives and capacity usage on parts of the app that do not need it.
• Package shared custom rules into a RuleGroup. Rules used across more than one Web ACL belong in a RuleGroup so an update to one place propagates everywhere, instead of maintaining duplicate copies.
• Budget Capacity with headroom. A RuleGroup's capacity is fixed at creation; underestimating it blocks future rule additions without recreating the group.

D - Rate Limiting & Bot Control

• Scope rate-based rules to the endpoints that need them. A single global rate limit is usually either too loose for a targeted login-path attack or too tight for legitimate bulk traffic elsewhere; scope with a ScopeDownStatement.
• Aggregate on FORWARDED_IP, not IP, behind a proxy or CDN. Aggregating on the raw connection IP behind CloudFront or an ALB can put many real users behind one shared counter.
• Pair Bot Control's TARGETED inspection level with a client-side integration. Its adaptive detection is materially weaker without the companion JavaScript/CAPTCHA challenge; COMMON alone may be the better fit without that integration.
• Combine rate limiting with AWSManagedRulesATPRuleSet for login-specific abuse. Volume limits and account-takeover-specific detection catch different attack shapes; use both on a login endpoint.

E - Shield & Incident Readiness

• Protect every public entry point, not just the primary one. CreateProtection is per resource ARN; an application with both a CloudFront distribution and a separate ALB needs a Protection on each to get Shield Advanced's benefits on both.
• Grant DRT access before you need it. Call AssociateDRTLogBucket and AssociateDRTRole as part of onboarding Shield Advanced, not while an attack is already underway.
• Attach health checks to Protections where available. AssociateHealthCheck gives Shield's automated mitigation a real application-health signal beyond traffic patterns alone.
• Track the subscription term. Shield Advanced carries a 1-year commitment; check DescribeSubscription's renewal status well before it lapses if you plan to continue or cancel.

F - Ongoing Hygiene

• Revisit rule and rate limits on a schedule, not just at launch. Traffic patterns and legitimate usage change; a limit set correctly at launch can become too tight (or too loose) months later.
• Keep Priority values sparse. Numbering rules 10, 20, 30 instead of 1, 2, 3 leaves room to insert a new rule between two existing ones without renumbering everything.
• Verify associations after any infrastructure change. A new ALB or a recreated CloudFront distribution does not inherit a Web ACL automatically; confirm AssociateWebACL (or the distribution's WebACLId) is set again after such changes.
• Never fall back to classic WAF. All new rules, rule groups, and automation should target wafv2; classic WAF is deprecated and receives no new capability.

FAQs

Related

• WAF & Shield's Layered Protection Model - the conceptual split this checklist assumes.
• Web ACLs, Rules & Rule Groups - the rule and RuleGroup mechanics referenced above.
• WAF Logging & Sampled Requests - the tools this checklist's staging and logging items rely on.
• Shield Advanced & DDoS Response Team Access - the DRT and Protection setup referenced in section E.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).