AWS WAFv2 ExecModule

Overview

AwsWafV2Module brings bounded AWS WAFv2 Web ACL discovery, rule-group inspection, protected-resource inventory, logging visibility, and explicitly confirmed regional association changes into ValkyrAI workflows.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. Workflow input never accepts AWS keys, session tokens, authorization headers, endpoint overrides, raw SDK requests, complete Web ACL replacement documents, rule statements, logging filters, custom response bodies, or lock tokens.

This first release is designed for security inventory, release-readiness checks, policy drift detection, logging verification, and controlled attachment or removal of an existing Web ACL from one regional resource. Reads may retry transient failures with bounded backoff. Association mutations require exact ARNs and explicit confirmation and are sent once so an ambiguous provider response can be reconciled before replay.

Usage

1. Create or select a least-privilege AWS identity for the exact WAFv2 actions the workflow needs.
2. Store its access-key pair in an AWS IntegrationAccount.
3. Verify the account and ensure its status is READY.
4. Add AwsWafV2Module and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose REGIONAL or CLOUDFRONT, provide the correct signing region, and select an operation.
6. Before changing a regional association, inspect the target resource and Web ACL, review the blast radius, then set the matching confirmation field to true.

AWS requires WAF calls with CLOUDFRONT scope to use the us-east-1 endpoint. The module enforces that rule. Regional resources use their actual AWS region.

Never place credentials in module input. Credential-shaped fields and endpoint overrides are rejected before any AWS request.

Inputs

Common and pagination inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported WAFv2 operation.
region	string	Yes	—	AWS signing region such as us-west-2; use us-east-1 for CLOUDFRONT.
scope	string	Yes	—	REGIONAL or CLOUDFRONT.
nextMarker	string	No	—	Opaque provider continuation marker for list operations.
limit	integer	For paginated list operations	100	Total result bound from 1 to 1,000.
returnAll	boolean	For paginated list operations	false	Follow provider pages until limit or a provider boundary.

Resource inputs

Input	Operations	Rules
webAclId	get_web_acl	Exact UUID returned by WAFv2.
webAclName	get_web_acl	Exact Web ACL name, 1–128 letters, numbers, underscores, or hyphens.
webAclArn	Resource inventory, logging lookup, and association	Exact Web ACL ARN, at most 2,048 characters.
ruleGroupId	get_rule_group	Exact UUID returned by WAFv2.
ruleGroupName	get_rule_group	Exact rule-group name.
resourceArn	Resource lookup and association mutation	Exact ARN of one regional protected resource.
resourceType	list_resources	One supported regional family: APPLICATION_LOAD_BALANCER, API_GATEWAY, APPSYNC, COGNITO_USER_POOL, APP_RUNNER_SERVICE, VERIFIED_ACCESS_INSTANCE, or AMPLIFY.

Mutation confirmations

Input	Required for	Meaning
confirmAssociation	associate_web_acl	Must be true to attach the selected Web ACL to the selected regional resource.
confirmDisassociation	disassociate_web_acl	Must be true to remove the current Web ACL from the selected regional resource.

The WAFv2 association APIs used here do not manage CloudFront distribution associations. Use CLOUDFRONT scope for Web ACL, rule-group, and logging inventory only. CloudFront association requires an explicit CloudFront distribution update and is deliberately deferred.

Outputs

Successful execution uses a stable envelope:

Output	Meaning
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and safe read retries.
resultType	Web ACL, rule group, logging, resource, or association family.
items / count	Bounded normalized list results.
pages	Provider pages consumed.
hasMore / nextMarker	Whether and where provider pagination may continue.
data	Bounded metadata for one exact Web ACL, rule group, logging configuration, or association result.
requestId	Safe AWS request reference when available.
error	Safe code, message, HTTP status, and retryability.

Web ACL and rule-group output includes bounded identity, description, capacity, visibility settings, rule names, priorities, configured actions, and metric settings. It intentionally excludes complete rule statements, raw provider objects, custom response bodies, lock tokens, and request-inspection content. Logging output includes destination ARNs plus counts and safe filter posture, but not redacted-field definitions.

IntegrationAccount Requirements

The bound account must be verified, have status READY, and supply its AWS access-key ID through apiKey plus its secret access key through password. The module never serializes those values into output or logs.

Grant only the operations used by the workflow:

wafv2:ListWebACLs
wafv2:GetWebACL
wafv2:ListRuleGroups
wafv2:GetRuleGroup
wafv2:ListResourcesForWebACL
wafv2:GetWebACLForResource
wafv2:ListLoggingConfigurations
wafv2:GetLoggingConfiguration
wafv2:AssociateWebACL
wafv2:DisassociateWebACL

Separate read-only inventory identities from association-capable identities when practical. Scope mutation permissions to reviewed Web ACLs and protected resources with IAM conditions and resource ARNs where AWS supports them. This release does not need permissions to create, update, or delete Web ACLs, rule groups, IP sets, regex pattern sets, logging configurations, or tags.

Configuration

The module uses ExecModuleConfig for IntegrationAccount binding, retry ceiling, and workflow policy. It does not accept endpoint overrides, custom signing hosts, inline IAM policies, role-session material, complete Web ACL documents, rule statement JSON, logging filters, or provider lock tokens.

Reads use at most five attempts, bounded by configured maxAttempts. AWS SDK retries are disabled so the module owns the visible attempt count. associate_web_acl and disassociate_web_acl always use one provider call, even when AWS returns a transient error.

Operations

Operation	Behavior	Side effect
list_web_acls	Lists bounded Web ACL summaries for the selected scope.	None; provider read quota applies.
get_web_acl	Reads safe configuration and rule posture for one exact Web ACL.	None.
list_rule_groups	Lists bounded customer rule-group summaries for the selected scope.	None.
get_rule_group	Reads safe configuration, capacity, visibility, and rule posture for one exact group.	None.
list_resources	Lists regional resources currently protected by one exact Web ACL and resource family.	None.
get_web_acl_for_resource	Reads the Web ACL currently associated with one regional resource.	None.
list_logging_configurations	Lists bounded logging destinations and safe filter posture for the selected scope.	None.
get_logging_configuration	Reads logging posture for one exact Web ACL ARN.	None.
associate_web_acl	Attaches one existing Web ACL to one regional resource after confirmation.	External security-control write.
disassociate_web_acl	Removes the current Web ACL from one regional resource after confirmation.	External security-control write that can reduce protection.

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	A region, scope, identifier, ARN, resource type, marker, bound, field, or confirmation failed locally.	Correct input; no AWS call occurred.
UNSUPPORTED_OPERATION	The requested WAFv2 capability is outside this release.	Select one documented operation.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair the account binding.
AWS_WAFV2_HTTP_400	AWS rejected a scope, ARN, association state, marker, or exact resource.	Usually no; inspect input and live association state.
AWS_WAFV2_HTTP_403	IAM denied the action or resource.	Add only the missing least-privilege permission.
AWS_WAFV2_HTTP_404	The selected Web ACL, rule group, logging configuration, or resource was not found.	Confirm account, region, scope, and identifier.
AWS_WAFV2_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; mutation state must be reconciled first.
NETWORK_ERROR	AWS could not be reached.	Reads may retry; inspect the current resource association before replaying a mutation.
EXECUTION_ERROR	An unexpected local failure was safely normalized.	Use logs and request references; secrets remain redacted.

AWS can accept an association change before the client observes a timeout. A retryable status is never permission to blindly send the mutation again. Use get_web_acl_for_resource to reconcile the current association first.

Example

This example attaches a reviewed regional Web ACL to an API Gateway stage:

{
  "operation": "associate_web_acl",
  "region": "us-west-2",
  "scope": "REGIONAL",
  "webAclArn": "arn:aws:wafv2:us-west-2:123456789012:regional/webacl/customer-api/11111111-2222-3333-4444-555555555555",
  "resourceArn": "arn:aws:apigateway:us-west-2::/restapis/a1b2c3/stages/prod",
  "confirmAssociation": true
}

Expected normalized result:

{
  "status": "success",
  "operation": "associate_web_acl",
  "attempts": 1,
  "resultType": "association",
  "data": {
    "associated": true
  },
  "requestId": "example-request-id"
}

A workflow should follow the mutation with get_web_acl_for_resource, then verify expected application behavior and WAF metrics independently. A successful control-plane response does not prove that every rule is correct, that logging delivery is healthy, or that legitimate traffic remains unaffected.

Notes

• Pagination: Web ACL, rule-group, and logging lists expose nextMarker; returnAll: true follows at most 100 provider pages and never returns more than limit items.
• Scope and region: CLOUDFRONT always signs through us-east-1. Regional reads and associations use the protected resource's region.
• CloudFront association boundary: The WAFv2 association APIs do not update CloudFront distributions. This module refuses CloudFront association mutations rather than implying support.
• Eventual consistency: WAF resources and associations can take time to become available. Re-read exact state before escalating or replaying a mutation.
• Rate limits: AWS WAF quotas apply to control-plane reads and writes. Use bounded pages and avoid tight inventory loops.
• Rules: Output exposes safe rule posture, not complete statements. Review source-controlled WAF definitions or the AWS console for condition-level policy analysis.
• Logging: Destination presence does not prove delivery, retention, encryption, parsing, or alert coverage. Verify the downstream log service separately.
• Idempotency: Reads are repeatable within provider freshness limits. Association mutations are single-attempt and require state reconciliation after ambiguous responses.
• Destructive behavior: disassociate_web_acl can remove application-layer protection from a resource. It requires explicit confirmation and should be followed by an independent exposure review.
• Deferred capabilities: Web ACL, rule-group, IP-set, regex-set, managed-rule, logging, tag, permission-policy, and mobile-SDK lifecycle operations; rule JSON mutation; sampled request bodies; rate-based managed keys; CloudFront association updates; Firewall Manager writes; bulk changes; and Web ACL deletion are intentionally deferred.
• Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed WAF resources are supplied.
• Functional reference: n8n's AWS integration patterns provide the familiar credential, resource, operation, and pagination model, with custom API calls for unsupported services. ValkyrAI applies that model through IntegrationAccount, strict per-operation inputs, bounded normalized output, explicit association confirmations, and mutation replay safety.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsWafV2Module through /v1/modules/metadata.

Related documentation

• AWS WAFv2 API Reference
• AWS WAF resource association guidance
• AWS WAF logging guidance
• AWS CloudFront ExecModule