AWS Firewall Manager ExecModule

Overview

AwsFirewallManagerModule brings bounded AWS Firewall Manager policy, compliance, administrator, member-account, violation, and resource-set visibility into ValkyrAI workflows. It can also delete one exact policy after explicit confirmation, with a second confirmation required before AWS-managed policy resources may be removed.

The module is designed for multi-account security operations where teams need to understand which AWS accounts and resources comply with organization-wide controls. It complements the AWS WAFv2 and AWS Shield Advanced ExecModules: those modules inspect or act on service resources, while Firewall Manager evaluates and governs security policies across AWS Organizations.

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, policy JSON, managed-service data, IAM policies, or organization administration mutations.

Usage

Enable the AWS Organizations and Firewall Manager prerequisites for the intended administrator account and regions.
Create a least-privilege AWS identity for only the operations the workflow needs.
Save its access-key pair in a ValkyrAI IntegrationAccount, then verify it and leave it in READY status.
Add AwsFirewallManagerModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Set the exact AWS region, select one operation, and provide only the fields that operation accepts.
Use returnAll and limit for bounded pagination. Keep policy deletion behind reviewed approval steps.

Firewall Manager is regional. A policy created in one region is not discovered by a call to another region, even when the policy evaluates organization-wide resources. Run separate reviewed workflow steps for each required region.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported Firewall Manager operation.
`region`	string	Yes	—	AWS region such as `us-west-2`.
`nextToken`	string	No	—	Opaque continuation token returned by AWS.
`limit`	integer	No	`100`	Total result bound from 1 to 1,000.
`returnAll`	boolean	No	`false`	Follow provider pages until `limit` or exhaustion.
`policyId`	string	Operation-specific	—	Exact 36-character Firewall Manager policy UUID.
`memberAccount`	string	Operation-specific	—	Exact 12-digit AWS member account ID.
`resourceId`	string	Operation-specific	—	Exact non-compliant resource identifier.
`resourceType`	string	Operation-specific	—	Exact AWS type such as `AWS::EC2::Instance`.
`resourceSetId`	string	Operation-specific	—	Exact 36-character resource-set UUID.
`deleteAllPolicyResources`	boolean	No	`false`	Ask AWS to remove resources created by a deleted policy.
`confirmDelete`	boolean	`delete_policy`	`false`	Confirms deletion of one exact policy.
`confirmDeleteResources`	boolean	Conditional	`false`	Separately confirms deletion of policy-created resources.

Unknown or operation-inappropriate fields are rejected before any provider call. Credentials and transport overrides are always rejected as workflow input.

Outputs

All operations return a stable envelope:

Output	Description
`status`	`success` or `error`.
`operation`	Normalized operation name.
`attempts`	Provider calls, including pages and safe read retries.
`resultType`	Result family such as `policies`, `compliance_statuses`, or `policy_mutation`.
`items` / `count`	Bounded list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	Normalized object or mutation result.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Policy output intentionally excludes raw ManagedServiceData, policy update tokens, IAM material, and full service-specific policy documents. Compliance details return bounded violator identifiers, types, reasons, and counts without dumping provider metadata. Violation detail reports the exact resource coordinates and bounded counts without serializing raw service-specific violation payloads.

IntegrationAccount Requirements

Use an AWS IntegrationAccount with:

status: READY
verified: true
access key ID in the account API-key field
secret access key in the protected password field

The connector never reads credentials from workflow input. It constructs the regional AWS SDK client only after account verification and disables SDK-level retries so ValkyrAI can report exact attempt counts.

Grant only the actions needed by the selected operations. A read-oriented deployment may need a subset of:

fms:ListPolicies
fms:GetPolicy
fms:ListComplianceStatus
fms:GetComplianceDetail
fms:GetViolationDetails
fms:GetAdminAccount
fms:ListAdminAccountsForOrganization
fms:ListMemberAccounts
fms:ListResourceSets
fms:GetResourceSet
fms:ListResourceSetResources

Only workflows that delete policies need fms:DeletePolicy. Firewall Manager may also require AWS Organizations access and service-linked roles depending on account and policy configuration. Do not grant organization administration, policy creation/update, or broad wildcard access merely to satisfy a read workflow.

Configuration

ExecModuleConfig supplies the IntegrationAccount and optional retry policy. Read operations may retry transient throttling and service failures up to the configured maximum, bounded from one to five attempts. The default is three attempts.

Each policy deletion is sent once. If AWS returns an ambiguous network or service response, inspect the exact policy state before retrying. ValkyrAI does not replay destructive operations automatically.

Operations

Policy inventory

list_policies — list bounded policy summaries in the selected region.
get_policy — inspect one exact policy's scope, resource types, service type, remediation flags, resource-set references, and status. Raw managed-service policy data is not emitted.

Compliance and violations

list_compliance_status — list per-member-account evaluations for one policy.
get_compliance_detail — retrieve bounded violator summaries for one policy and member account.
get_violation_details — inspect one exact resource violation coordinate and its service-specific violation count.

Organization administration visibility

get_admin_account — read the legacy regional administrator account and role status.
list_admin_accounts — list Firewall Manager administrators registered for the organization.
list_member_accounts — list member account IDs visible to the Firewall Manager administrator.

These are read-only operations. The module does not associate or disassociate administrator accounts, update admin scope, or change AWS Organizations membership.

Resource sets

list_resource_sets — list bounded resource-set summaries.
get_resource_set — inspect one exact resource set and its resource types.
list_resource_set_resources — list bounded resource URIs and account IDs in one exact resource set.

Resource-set creation, updates, batch association, batch disassociation, and deletion are intentionally deferred.

Policy deletion

delete_policy — delete one exact policy only when confirmDelete is true.

By default, deleteAllPolicyResources is false. Setting it to true also requires confirmDeleteResources: true because AWS can remove resources created during policy remediation. The request is made once and must be reconciled before any replay.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required field, region, identifier, limit, or confirmation is invalid.	Correct input; no provider call was made.
`INTEGRATION_ACCOUNT_ERROR`	The bound account is missing, unverified, not `READY`, or incomplete.	Repair and verify the account.
`UNSUPPORTED_OPERATION`	The operation is outside this release.	Select one documented operation.
`AWS_FMS_HTTP_400`	AWS rejected the request, region state, prerequisite, identifier, or operation.	Usually no; inspect the request ID and account prerequisites.
`AWS_FMS_HTTP_403`	IAM, AWS Organizations, or Firewall Manager administration denied access.	Add only the missing least-privilege permission or prerequisite.
`AWS_FMS_HTTP_404`	The policy, member account, resource, or resource set was not found.	Confirm region, account, and exact identifier.
`AWS_FMS_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Reads retry; deletion state must be reconciled first.
`NETWORK_ERROR`	ValkyrAI could not reach AWS.	Reads may retry; investigate deletion state before replay.
`EXECUTION_ERROR`	An unexpected local failure was safely contained.	Inspect server logs; secrets remain redacted.

Provider exception messages are not returned to workflow output. AWS request IDs are retained when safely available for CloudTrail and support correlation.

Example

The following workflow step finds organization members with findings under one Firewall Manager policy:

{
  "operation": "list_compliance_status",
  "region": "us-west-2",
  "policyId": "11111111-2222-3333-4444-555555555555",
  "returnAll": true,
  "limit": 250
}

Expected result shape:

{
  "status": "success",
  "operation": "list_compliance_status",
  "attempts": 1,
  "resultType": "compliance_statuses",
  "items": [
    {
      "policyId": "11111111-2222-3333-4444-555555555555",
      "policyName": "organization-web-controls",
      "memberAccount": "123456789012",
      "lastUpdated": "2026-10-24T10:00:00Z",
      "evaluationResults": [
        {
          "complianceStatus": "NON_COMPLIANT",
          "violatorCount": 2,
          "evaluationLimitExceeded": false
        }
      ],
      "evaluationResultCount": 1,
      "issueCount": 0
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

A practical follow-up workflow can select each non-compliant member account, call get_compliance_detail, route the bounded finding to a human approval step, and use the relevant service-specific connector for remediation. The Firewall Manager module itself does not change WAF rules, Shield protections, security groups, or Network Firewall policies.

Notes

Pagination: Opaque AWS tokens are preserved. returnAll follows no more than 100 pages and never returns more than 1,000 items.
Rate limits: Only reads retry transient failures, with bounded backoff and at most five configured attempts.
API limits: Compliance-detail violators are bounded to 1,000 normalized summaries. Provider metadata and raw service-specific violation payloads are not emitted.
Idempotency: Reads are repeatable. Policy deletion is single-attempt and requires state reconciliation after an ambiguous response.
Destructive behavior: delete_policy is destructive. Removing policy-created resources requires a separate confirmation.
Regional scope: Inventory and policy identifiers are region-specific. The module does not accept endpoint overrides.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed Firewall Manager resources are supplied.
Deferred capabilities: Policy creation/update, raw managed-service policy data, application/protocol lists, notification channels, tags, administrator association, admin-scope changes, third-party firewall association, resource-set mutation, batch resource changes, and bulk policy deletion are intentionally deferred.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsFirewallManagerModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Policy inventory​

Compliance and violations​

Organization administration visibility​

Resource sets​

Policy deletion​

Errors and Failure Modes​

Example​

Notes​

Related resources​