AWS.WAFv2 reference

CreateAPIKey

Source: src/AWS/WAFv2/APIKeys.ts

Runtime binding for wafv2:CreateAPIKey — mint an API key for the CAPTCHA JavaScript integration, scoped to up to 5 token domains (e.g. onboarding a new tenant domain in a SaaS). The returned key is embedded in client-side JavaScript by design (it is not a secret credential).

Provide WAFv2.CreateAPIKeyHttp on the hosting Lambda Function to satisfy the requirement.

CreateAPIKey: CAPTCHA API Keys

// init — grants wafv2:CreateAPIKey
const createAPIKey = yield* AWS.WAFv2.CreateAPIKey();

// runtime
const { APIKey } = yield* createAPIKey({
  Scope: "REGIONAL",
  TokenDomains: ["example.com"],
});

CheckCapacity

Source: src/AWS/WAFv2/CheckCapacity.ts

Runtime binding for wafv2:CheckCapacity — compute the web ACL capacity units (WCU) a set of rules would consume, e.g. before updating an IP set or constructing rules dynamically.

Provide WAFv2.CheckCapacityHttp on the hosting Lambda Function to satisfy the requirement.

CheckCapacity: Account Operations

// init — grants wafv2:CheckCapacity
const checkCapacity = yield* AWS.WAFv2.CheckCapacity();

// runtime
const { Capacity } = yield* checkCapacity({
  Scope: "REGIONAL",
  Rules: [rule],
});

DeletePermissionPolicy

Source: src/AWS/WAFv2/DeletePermissionPolicy.ts

Runtime binding for wafv2:DeletePermissionPolicy — remove the IAM policy that shares the bound RuleGroup with other accounts; the rule group ARN is injected automatically. Deleting a policy that does not exist succeeds.

Provide WAFv2.DeletePermissionPolicyHttp on the hosting Lambda Function to satisfy the requirement.

DeletePermissionPolicy: Sharing Rule Groups

// init — grants wafv2:DeletePermissionPolicy on the rule group
const deletePermissionPolicy = yield* AWS.WAFv2.DeletePermissionPolicy(group);

// runtime
yield* deletePermissionPolicy();

GetIPSet

Source: src/AWS/WAFv2/GetIPSet.ts

Runtime binding for wafv2:GetIPSet — read the bound IPSet’s current addresses; the name, scope, and id are injected automatically.

Provide WAFv2.GetIPSetHttp on the hosting Lambda Function to satisfy the requirement.

GetIPSet: Managing IP Sets at Runtime

// init — grants wafv2:GetIPSet on the IP set
const getIPSet = yield* AWS.WAFv2.GetIPSet(blockList);

// runtime
const { IPSet } = yield* getIPSet();
const addresses = IPSet?.Addresses ?? [];

GetPermissionPolicy

Source: src/AWS/WAFv2/GetPermissionPolicy.ts

Runtime binding for wafv2:GetPermissionPolicy — read the IAM policy that shares the bound RuleGroup with other accounts; the rule group ARN is injected automatically. A rule group with no policy attached fails with the typed WAFNonexistentItemException.

Provide WAFv2.GetPermissionPolicyHttp on the hosting Lambda Function to satisfy the requirement.

GetPermissionPolicy: Sharing Rule Groups

// init — grants wafv2:GetPermissionPolicy on the rule group
const getPermissionPolicy = yield* AWS.WAFv2.GetPermissionPolicy(group);

// runtime
const { Policy } = yield* getPermissionPolicy().pipe(
  Effect.catchTag("WAFNonexistentItemException", () =>
    Effect.succeed({ Policy: undefined }),
  ),
);

GetRateBasedStatementManagedKeys

Source: src/AWS/WAFv2/GetRateBasedStatementManagedKeys.ts

Runtime binding for wafv2:GetRateBasedStatementManagedKeys — read the IP addresses that a rate-based rule of the bound WebACL is currently blocking; the web ACL name, id, and scope are injected automatically.

Provide WAFv2.GetRateBasedStatementManagedKeysHttp on the hosting Lambda Function to satisfy the requirement.

GetRateBasedStatementManagedKeys: Inspecting Traffic

// init — grants wafv2:GetRateBasedStatementManagedKeys on the web ACL
const getManagedKeys = yield* AWS.WAFv2.GetRateBasedStatementManagedKeys(acl);

// runtime
const { ManagedKeysIPV4 } = yield* getManagedKeys({ RuleName: "rate-limit" });
const blocked = ManagedKeysIPV4?.Addresses ?? [];

GetSampledRequests

Source: src/AWS/WAFv2/GetSampledRequests.ts

Runtime binding for wafv2:GetSampledRequests — read a sample of the web requests that the bound WebACL evaluated for a given rule and time window; the web ACL ARN and scope are injected automatically.

Provide WAFv2.GetSampledRequestsHttp on the hosting Lambda Function to satisfy the requirement.

GetSampledRequests: Inspecting Traffic

// init — grants wafv2:GetSampledRequests on the web ACL
const getSampledRequests = yield* AWS.WAFv2.GetSampledRequests(acl);

// runtime
const now = yield* Effect.sync(() => new Date());
const { SampledRequests } = yield* getSampledRequests({
  RuleMetricName: "rate-limit",
  TimeWindow: {
    StartTime: new Date(now.getTime() - 60 * 60 * 1000),
    EndTime: now,
  },
  MaxItems: 100,
});

GetTopPathStatisticsByTraffic

Source: src/AWS/WAFv2/GetTopPathStatisticsByTraffic.ts

Runtime binding for wafv2:GetTopPathStatisticsByTraffic — read aggregated statistics about the URI paths receiving the most bot traffic on the bound WebACL; the web ACL ARN and scope are injected automatically.

Requires a pricing plan that includes bot statistics — accounts without it receive the typed WAFFeatureNotIncludedInPricingPlanException.

Provide WAFv2.GetTopPathStatisticsByTrafficHttp on the hosting Lambda Function to satisfy the requirement.

GetTopPathStatisticsByTraffic: Inspecting Traffic

// init — grants wafv2:GetTopPathStatisticsByTraffic on the web ACL
const getTopPaths = yield* AWS.WAFv2.GetTopPathStatisticsByTraffic(acl);

// runtime
const now = yield* Effect.sync(() => new Date());
const { PathStatistics } = yield* getTopPaths({
  TimeWindow: {
    StartTime: new Date(now.getTime() - 60 * 60 * 1000),
    EndTime: now,
  },
  Limit: 10,
  NumberOfTopTrafficBotsPerPath: 3,
});

GetWebACLForResource

Source: src/AWS/WAFv2/GetWebACLForResource.ts

Runtime binding for wafv2:GetWebACLForResource — look up which web ACL (if any) protects an arbitrary regional resource (ALB, API Gateway stage, AppSync API, Cognito user pool, …). A resource with no web ACL association fails with the typed WAFNonexistentItemException.

Provide WAFv2.GetWebACLForResourceHttp on the hosting Lambda Function to satisfy the requirement.

GetWebACLForResource: Inspecting Associations

// init — grants wafv2:GetWebACLForResource + wafv2:GetWebACL
const getWebACLForResource = yield* AWS.WAFv2.GetWebACLForResource();

// runtime
const { WebACL } = yield* getWebACLForResource({
  ResourceArn: loadBalancerArn,
});

IPSet

Source: src/AWS/WAFv2/IPSet.ts

An AWS WAFv2 IP set — a named collection of IP addresses and CIDR ranges referenced from web ACL and rule group rules via IPSetReferenceStatement.

IPSet: Creating IP Sets

Block List of IPv4 Addresses

const blockList = yield* AWS.WAFv2.IPSet("BlockList", {
  addresses: ["192.0.2.44/32", "203.0.113.0/24"],
});

Reference from a Web ACL Rule

const acl = yield* AWS.WAFv2.WebACL("Firewall", {
  rules: [
    {
      Name: "block-bad-ips",
      Priority: 0,
      Statement: {
        IPSetReferenceStatement: { ARN: blockList.ipSetArn },
      },
      Action: { Block: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "block-bad-ips",
      },
    },
  ],
});

ListResourcesForWebACL

Source: src/AWS/WAFv2/ListResourcesForWebACL.ts

Runtime binding for wafv2:ListResourcesForWebACL — list the regional resources (ALBs, API Gateway stages, AppSync APIs, …) associated with the bound WebACL; the web ACL ARN is injected automatically.

Provide WAFv2.ListResourcesForWebACLHttp on the hosting Lambda Function to satisfy the requirement.

ListResourcesForWebACL: Inspecting Associations

// init — grants wafv2:ListResourcesForWebACL on the web ACL
const listResources = yield* AWS.WAFv2.ListResourcesForWebACL(acl);

// runtime
const { ResourceArns } = yield* listResources();

LoggingConfiguration

Source: src/AWS/WAFv2/LoggingConfiguration.ts

The logging configuration of an AWS WAFv2 WebACL — streams full web request logs to a Kinesis Data Firehose delivery stream, a CloudWatch Logs log group, or an S3 bucket.

The destination must be named with the aws-waf-logs- prefix. A web ACL has at most one logging configuration; deleting this resource disables logging.

LoggingConfiguration: Configuring Logging

Log to CloudWatch Logs

const logGroup = yield* AWS.Logs.LogGroup("WafLogs", {
  logGroupName: "aws-waf-logs-my-firewall",
});

yield* AWS.WAFv2.LoggingConfiguration("Logging", {
  resourceArn: acl.webAclArn,
  logDestinationConfigs: [logGroup.logGroupArn],
});

Redact Headers and Filter to Blocked Requests

yield* AWS.WAFv2.LoggingConfiguration("Logging", {
  resourceArn: acl.webAclArn,
  logDestinationConfigs: [logGroup.logGroupArn],
  redactedFields: [{ SingleHeader: { Name: "authorization" } }],
  loggingFilter: {
    DefaultBehavior: "DROP",
    Filters: [
      {
        Behavior: "KEEP",
        Requirement: "MEETS_ANY",
        Conditions: [{ ActionCondition: { Action: "BLOCK" } }],
      },
    ],
  },
});

DescribeManagedRuleGroup

Source: src/AWS/WAFv2/ManagedRuleGroups.ts

Runtime binding for wafv2:DescribeManagedRuleGroup — read the rules, labels, and WCU capacity of a vendor managed rule group.

Provide WAFv2.DescribeManagedRuleGroupHttp on the hosting Lambda Function to satisfy the requirement.

DescribeManagedRuleGroup: Managed Rule Group Catalog

// init — grants wafv2:DescribeManagedRuleGroup
const describeManagedRuleGroup = yield* AWS.WAFv2.DescribeManagedRuleGroup();

// runtime
const { Capacity, Rules } = yield* describeManagedRuleGroup({
  VendorName: "AWS",
  Name: "AWSManagedRulesCommonRuleSet",
  Scope: "REGIONAL",
});

PutPermissionPolicy

Source: src/AWS/WAFv2/PutPermissionPolicy.ts

Runtime binding for wafv2:PutPermissionPolicy — attach an IAM policy that shares the bound RuleGroup with other accounts (e.g. a SaaS granting tenant accounts the right to reference the group from their web ACLs); the rule group ARN is injected automatically. A malformed policy fails with the typed WAFInvalidPermissionPolicyException.

Provide WAFv2.PutPermissionPolicyHttp on the hosting Lambda Function to satisfy the requirement.

PutPermissionPolicy: Sharing Rule Groups

// init — grants wafv2:PutPermissionPolicy on the rule group
const putPermissionPolicy = yield* AWS.WAFv2.PutPermissionPolicy(group);

// runtime
yield* putPermissionPolicy({
  Policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { AWS: "arn:aws:iam::123456789012:root" },
        Action: ["wafv2:CreateWebACL", "wafv2:UpdateWebACL"],
        Resource: group.ruleGroupArn,
      },
    ],
  }),
});

RegexPatternSet

Source: src/AWS/WAFv2/RegexPatternSet.ts

An AWS WAFv2 regex pattern set — a named collection of regular expressions referenced from web ACL and rule group rules via RegexPatternSetReferenceStatement.

RegexPatternSet: Creating Regex Pattern Sets

Block Requests Matching Bad Path Patterns

const badPaths = yield* AWS.WAFv2.RegexPatternSet("BadPaths", {
  regularExpressions: ["^/wp-admin", "\\.php$"],
});

Reference from a Web ACL Rule

const acl = yield* AWS.WAFv2.WebACL("Firewall", {
  rules: [
    {
      Name: "block-bad-paths",
      Priority: 0,
      Statement: {
        RegexPatternSetReferenceStatement: {
          ARN: badPaths.regexPatternSetArn,
          FieldToMatch: { UriPath: {} },
          TextTransformations: [{ Priority: 0, Type: "NONE" }],
        },
      },
      Action: { Block: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "block-bad-paths",
      },
    },
  ],
});

RuleGroup

Source: src/AWS/WAFv2/RuleGroup.ts

An AWS WAFv2 rule group — a reusable, capacity-bounded collection of rules referenced from web ACLs via RuleGroupReferenceStatement.

The capacity (web ACL capacity units, WCU) is fixed at creation; changing it replaces the rule group.

RuleGroup: Creating Rule Groups

Rule Group with a Byte-Match Rule

const group = yield* AWS.WAFv2.RuleGroup("BlockAdminPaths", {
  capacity: 50,
  rules: [
    {
      Name: "block-admin",
      Priority: 0,
      Statement: {
        ByteMatchStatement: {
          SearchString: new TextEncoder().encode("/admin"),
          FieldToMatch: { UriPath: {} },
          TextTransformations: [{ Priority: 0, Type: "LOWERCASE" }],
          PositionalConstraint: "STARTS_WITH",
        },
      },
      Action: { Block: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "block-admin",
      },
    },
  ],
});

Reference from a Web ACL

const acl = yield* AWS.WAFv2.WebACL("Firewall", {
  rules: [
    {
      Name: "custom-rules",
      Priority: 0,
      Statement: {
        RuleGroupReferenceStatement: { ARN: group.ruleGroupArn },
      },
      OverrideAction: { None: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "custom-rules",
      },
    },
  ],
});

UpdateIPSet

Source: src/AWS/WAFv2/UpdateIPSet.ts

Runtime binding for wafv2:UpdateIPSet — replace the bound IPSet’s address list at runtime (the classic dynamic block list: a Lambda appends offending IPs as it detects them). The binding reads the IP set for a fresh LockToken, applies the update, and retries optimistic-lock conflicts automatically.

Provide WAFv2.UpdateIPSetHttp on the hosting Lambda Function to satisfy the requirement.

UpdateIPSet: Managing IP Sets at Runtime

// init — grants wafv2:GetIPSet + wafv2:UpdateIPSet on the IP set
const getIPSet = yield* AWS.WAFv2.GetIPSet(blockList);
const updateIPSet = yield* AWS.WAFv2.UpdateIPSet(blockList);

// runtime
const current = (yield* getIPSet()).IPSet?.Addresses ?? [];
yield* updateIPSet({ addresses: [...current, "192.0.2.7/32"] });

WebACL

Source: src/AWS/WAFv2/WebACL.ts

An AWS WAFv2 Web ACL — a collection of rules that inspect and control web requests for the AWS resources it is associated with.

REGIONAL web ACLs protect regional resources (Application Load Balancer, API Gateway, AppSync, Cognito user pools, App Runner, Verified Access) via WebACLAssociation. CLOUDFRONT web ACLs protect CloudFront distributions (set Distribution.webAclId to the web ACL’s ARN) and are always provisioned in us-east-1 — the provider pins the region for you.

WebACL: Creating Web ACLs

Allow-by-Default Web ACL with a Managed Rule Group

const acl = yield* AWS.WAFv2.WebACL("ApiFirewall", {
  rules: [
    {
      Name: "common-rule-set",
      Priority: 0,
      Statement: {
        ManagedRuleGroupStatement: {
          VendorName: "AWS",
          Name: "AWSManagedRulesCommonRuleSet",
        },
      },
      OverrideAction: { None: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "common-rule-set",
      },
    },
  ],
});

Rate Limiting Requests per IP

const acl = yield* AWS.WAFv2.WebACL("RateLimited", {
  defaultAction: { Allow: {} },
  rules: [
    {
      Name: "rate-limit",
      Priority: 0,
      Statement: {
        RateBasedStatement: { Limit: 100, AggregateKeyType: "IP" },
      },
      Action: { Block: {} },
      VisibilityConfig: {
        SampledRequestsEnabled: true,
        CloudWatchMetricsEnabled: true,
        MetricName: "rate-limit",
      },
    },
  ],
});

WebACL: CloudFront Scope

const acl = yield* AWS.WAFv2.WebACL("EdgeFirewall", {
  scope: "CLOUDFRONT", // provisioned in us-east-1 automatically
  defaultAction: { Allow: {} },
});

const distribution = yield* AWS.CloudFront.Distribution("Site", {
  // ...
  webAclId: acl.webAclArn,
});

WebACL: Protecting Regional Resources

const association = yield* AWS.WAFv2.WebACLAssociation("PoolFirewall", {
  webAclArn: acl.webAclArn,
  resourceArn: userPool.userPoolArn,
});

WebACLAssociation

Source: src/AWS/WAFv2/WebACLAssociation.ts

Associates a REGIONAL AWS WAFv2 WebACL with a regional resource (ALB, API Gateway stage, AppSync API, Cognito user pool, App Runner service, Amplify app, Verified Access instance) to protect it.

A resource can have at most one web ACL association; associating a different web ACL overwrites the previous association in place. CloudFront distributions are protected by setting Distribution.webAclId instead — never through this resource.

WebACLAssociation: Associating Web ACLs

const pool = yield* AWS.Cognito.UserPool("Users", {});

const acl = yield* AWS.WAFv2.WebACL("PoolFirewall", {
  defaultAction: { Allow: {} },
});

const association = yield* AWS.WAFv2.WebACLAssociation("PoolAssociation", {
  webAclArn: acl.webAclArn,
  resourceArn: pool.userPoolArn,
});