Web ACLs, Rules & Rule Groups

A single Web ACL rarely relies on just one rule. Real configurations combine an AWS Managed Rule Group for broad coverage with a handful of custom rules for app-specific logic - a blocked country, a suspicious header, a known bad query string pattern. This page shows how those pieces fit together in one Rules array, and how to package custom rules into a reusable Rule Group.

Recipe

Build a Web ACL with two rules: a managed group for generic protection, and a custom ByteMatchStatement blocking a specific header value. Priority decides evaluation order.

# --- Python (boto3) ---
import boto3
 
wafv2 = boto3.client("wafv2", region_name="us-east-1")
 
wafv2.create_web_acl(
    Name="app-web-acl",
    Scope="REGIONAL",
    DefaultAction={"Allow": {}},
    VisibilityConfig={
        "SampledRequestsEnabled": True,
        "CloudWatchMetricsEnabled": True,
        "MetricName": "appWebAcl",
    },
    Rules=[
        {
            "Name": "AWS-CommonRuleSet",
            "Priority": 0,
            "OverrideAction": {"None": {}},
            "Statement": {"ManagedRuleGroupStatement": {
                "VendorName": "AWS", "Name": "AWSManagedRulesCommonRuleSet",
            }},
            "VisibilityConfig": {"SampledRequestsEnabled": True,
                                 "CloudWatchMetricsEnabled": True,
                                 "MetricName": "commonRuleSet"},
        },
        {
            "Name": "block-bad-header",
            "Priority": 1,
            "Action": {"Block": {}},
            "Statement": {"ByteMatchStatement": {
                "SearchString": "malicious-agent",
                "FieldToMatch": {"SingleHeader": {"Name": "user-agent"}},
                "TextTransformations": [{"Priority": 0, "Type": "LOWERCASE"}],
                "PositionalConstraint": "CONTAINS",
            }},
            "VisibilityConfig": {"SampledRequestsEnabled": True,
                                 "CloudWatchMetricsEnabled": True,
                                 "MetricName": "blockBadHeader"},
        },
    ],
)

// --- TypeScript (AWS SDK v3) ---
import { WAFV2Client, CreateWebACLCommand } from "@aws-sdk/client-wafv2";
 
const wafv2 = new WAFV2Client({ region: "us-east-1" });
 
await wafv2.send(new CreateWebACLCommand({
  Name: "app-web-acl",
  Scope: "REGIONAL",
  DefaultAction: { Allow: {} },
  VisibilityConfig: {
    SampledRequestsEnabled: true,
    CloudWatchMetricsEnabled: true,
    MetricName: "appWebAcl",
  },
  Rules: [
    {
      Name: "AWS-CommonRuleSet",
      Priority: 0,
      OverrideAction: { None: {} },
      Statement: { ManagedRuleGroupStatement: {
        VendorName: "AWS", Name: "AWSManagedRulesCommonRuleSet",
      } },
      VisibilityConfig: { SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true, MetricName: "commonRuleSet" },
    },
    {
      Name: "block-bad-header",
      Priority: 1,
      Action: { Block: {} },
      Statement: { ByteMatchStatement: {
        SearchString: "malicious-agent",
        FieldToMatch: { SingleHeader: { Name: "user-agent" } },
        TextTransformations: [{ Priority: 0, Type: "LOWERCASE" }],
        PositionalConstraint: "CONTAINS",
      } },
      VisibilityConfig: { SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true, MetricName: "blockBadHeader" },
    },
  ],
}));

Managed-group rules use OverrideAction, not Action - the group's own internal rules decide allow/block, and OverrideAction only lets you demote all of them to Count. Custom rules use Action directly. TextTransformations normalizes the input (here, lowercasing) before the match runs, which avoids simple case-based evasion.

Working Example

Package custom rules into a RuleGroup so multiple Web ACLs can reference the same logic without copy-pasting it. This adds a SqliMatchStatement for basic SQL injection detection on a query parameter.

# --- Python (boto3) ---
import boto3
 
wafv2 = boto3.client("wafv2", region_name="us-east-1")
 
group = wafv2.create_rule_group(
    Name="shared-app-rules",
    Scope="REGIONAL",
    Capacity=50,
    VisibilityConfig={
        "SampledRequestsEnabled": True,
        "CloudWatchMetricsEnabled": True,
        "MetricName": "sharedAppRules",
    },
    Rules=[{
        "Name": "block-sqli-in-search",
        "Priority": 0,
        "Action": {"Block": {}},
        "Statement": {"SqliMatchStatement": {
            "FieldToMatch": {"SingleQueryArgument": {"Name": "q"}},
            "TextTransformations": [{"Priority": 0, "Type": "URL_DECODE"}],
        }},
        "VisibilityConfig": {"SampledRequestsEnabled": True,
                             "CloudWatchMetricsEnabled": True,
                             "MetricName": "blockSqliInSearch"},
    }],
)
rule_group_arn = group["Summary"]["ARN"]

// --- TypeScript (AWS SDK v3) ---
import { CreateRuleGroupCommand } from "@aws-sdk/client-wafv2";
 
const group = await wafv2.send(new CreateRuleGroupCommand({
  Name: "shared-app-rules",
  Scope: "REGIONAL",
  Capacity: 50,
  VisibilityConfig: {
    SampledRequestsEnabled: true,
    CloudWatchMetricsEnabled: true,
    MetricName: "sharedAppRules",
  },
  Rules: [{
    Name: "block-sqli-in-search",
    Priority: 0,
    Action: { Block: {} },
    Statement: { SqliMatchStatement: {
      FieldToMatch: { SingleQueryArgument: { Name: "q" } },
      TextTransformations: [{ Priority: 0, Type: "URL_DECODE" }],
    } },
    VisibilityConfig: { SampledRequestsEnabled: true,
      CloudWatchMetricsEnabled: true, MetricName: "blockSqliInSearch" },
  }],
}));
const ruleGroupArn = group.Summary?.ARN;

Capacity is a WAF-computed cost unit budget, not a request count - each statement type consumes a fixed number of capacity units, and you must estimate (or use CheckCapacity) a value high enough to hold your rules. A Web ACL references this group with a RuleGroupReferenceStatement { ARN: ruleGroupArn } instead of repeating the rules inline.

Deep Dive

Statement Types Are Composable

A rule's Statement can be a single match type, or a logical combinator (AndStatement, OrStatement, NotStatement) wrapping several. For example, "block SQLi-looking input, but only from outside North America" combines a SqliMatchStatement and a NotStatement around a GeoMatchStatement inside an AndStatement. This lets a handful of primitive statement types express fairly specific policies without a full custom rule language.

Managed Rule Group Statements Can Be Scoped Down

ManagedRuleGroupStatement accepts an optional ScopeDownStatement - a nested statement that limits which requests the managed group even evaluates. This is how you apply AWSManagedRulesCommonRuleSet only to /api/* paths, for instance, leaving static asset requests un-evaluated by that group to save capacity and avoid false positives.

Priority and Evaluation Order

Rules run in ascending Priority order, and the first rule with a terminating action (Block or explicit Allow) stops evaluation. Count is non-terminating - a counted rule logs a match but lets evaluation continue to the next rule. This is why teams stage new rules with Count before flipping them to Block: it exposes what a rule would have blocked without actually blocking it.

RuleGroup vs Inline Rules

Inline rules (defined directly in a Web ACL's Rules array) are simplest when a rule is specific to one ACL. A RuleGroup is worth the extra object when the same logic (say, a company-wide blocklist of bad IPs or header patterns) needs to apply identically across several Web ACLs - update the group once, and every referencing ACL picks up the change.

Gotchas

• Forgetting LockToken on update. UpdateWebACL and UpdateRuleGroup both require the current LockToken from a fresh GetWebACL/GetRuleGroup call; a stale token is rejected to prevent lost updates.
• Confusing Action and OverrideAction. Custom rules use Action; rules that reference a managed group or rule group use OverrideAction. Using the wrong one is a validation error.
• Underestimating Capacity. Adding rules to a RuleGroup after the fact can exceed the capacity you provisioned at creation; capacity is fixed at creation and cannot be raised later, only lowered implicitly by removing rules.
• Skipping TextTransformations. A ByteMatchStatement without a transformation misses trivially obfuscated input (mixed case, URL encoding); most production rules include at least LOWERCASE or URL_DECODE.
• Priority collisions. Two rules sharing the same Priority value are rejected outright - each must be unique within the ACL or RuleGroup.
• Going straight to Block on new rules. Deploying an untested custom rule as Block risks blocking legitimate traffic; stage as Count first (see the logging page for how to read the results).

Alternatives

• AWS Managed Rule Groups alone, with no custom rules, cover a large share of generic threats and are the lowest-maintenance option for teams without dedicated security engineering time.
• Custom rules only, skipping managed groups, gives full control but means you own detecting every known attack pattern yourself - rarely worth it compared to layering on AWS's maintained groups.
• AWS Firewall Manager centrally pushes a common Web ACL policy across many accounts and resources in an AWS Organization, useful once you have more than a handful of ACLs to keep consistent.
• A third-party managed rule group from AWS Marketplace can supplement AWS's own groups for specialized coverage (a specific CMS, a specific compliance regime) referenced the same way via ManagedRuleGroupStatement with a different VendorName.

Most production Web ACLs land on a mix: one or two AWS Managed Rule Groups for baseline coverage, plus a small number of custom or shared-RuleGroup rules for anything specific to the application.

FAQs

Related

• WAF & Shield Basics - the minimal Web ACL and managed-group setup this page builds on.
• Rate-Based Rules & Bot Control - a specialized statement type and managed group for traffic-volume abuse.
• WAF Logging & Sampled Requests - reviewing what a Count-staged rule would have blocked.
• WAF & Shield via SDK Best Practices - the rule-tuning workflow tying this together.

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