AWS Shield Advanced ExecModule

Overview

AwsShieldAdvancedModule brings bounded AWS Shield Advanced subscription, protection, attack, and protection-group visibility into ValkyrAI workflows. It can also create or delete one exact resource protection after explicit confirmation.

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, region or endpoint overrides, raw SDK requests, subscription activation, contact information, DDoS Response Team configuration, or arbitrary Shield payloads.

AWS exposes Shield Advanced through a global control plane at shield.us-east-1.amazonaws.com. The module fixes SDK routing and SigV4 signing to us-east-1; the protected resource ARN still identifies the real regional or global resource. Reads may retry transient failures with bounded backoff. Protection creation and deletion are sent once so an ambiguous provider response can be reconciled before replay.

Usage

1. Activate AWS Shield Advanced for the AWS account through an approved administrative process. This module never creates or deletes the account subscription.
2. Create a least-privilege AWS identity for the exact Shield operations the workflow needs.
3. Store its access-key pair in an AWS IntegrationAccount.
4. Verify the account and ensure its status is READY.
5. Add AwsShieldAdvancedModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
6. Start with get_subscription_state, list_protections, and list_attacks to understand the current posture.
7. Before creating or deleting a protection, review the exact resource or protection ID and set the matching confirmation field to true.

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

Inputs

Common and pagination inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported Shield Advanced operation.
nextToken	string	No	—	Opaque provider continuation token for list operations.
limit	integer	For list operations	100	Total result bound from 1 to 1,000.
returnAll	boolean	For list operations	false	Follow provider pages until limit or a provider boundary.

Each provider page is capped at 100 records. returnAll never removes the total limit or 100-page safety boundary.

Protection and attack inputs

Input	Operations	Rules
protectionId	describe_protection, delete_protection	Exact UUID returned by Shield Advanced.
resourceArn	describe_protection, list_attacks, create_protection	Exact ARN, at most 2,048 characters.
protectionName	create_protection	1–128 letters, numbers, dots, underscores, or hyphens.
attackId	describe_attack	Exact attack identifier, 1–128 letters, numbers, or hyphens.
protectionGroupId	Group description and membership listing	Exact protection-group ID, 1–36 letters, numbers, or hyphens.
startTime	list_attacks	Optional inclusive ISO-8601 instant such as 2026-10-20T00:00:00Z.
endTime	list_attacks	Optional exclusive ISO-8601 instant after startTime.

When both attack times are supplied, the interval must be positive and at most 366 days. describe_protection requires exactly one of protectionId or resourceArn.

Mutation confirmations

Input	Required for	Meaning
confirmCreate	create_protection	Must be true to create one protection for the named resource.
confirmDelete	delete_protection	Must be true to delete the exact protection ID.

Deleting a Shield protection removes Shield Advanced coverage from that resource. It does not delete the underlying CloudFront distribution, Route 53 hosted zone, accelerator, Elastic IP address, or load balancer.

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	Subscription, protection, attack, protection-group, group-resource, or mutation family.
items / count	Bounded normalized list results.
pages	Provider pages consumed.
hasMore / nextToken	Whether and where provider pagination may continue.
data	Bounded details for one exact subscription, protection, attack, group, or mutation.
requestId	Safe AWS request reference when available.
error	Safe code, message, HTTP status, and retryability.

Protection output includes IDs, names, protected-resource and protection ARNs, bounded health-check IDs, and application-layer automatic-response posture. Attack output includes time bounds, resource identity, vector names, bounded counters, summarized properties, mitigation names, and subresource counts. It intentionally excludes raw provider objects and unbounded contributor or packet-level material.

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:

shield:GetSubscriptionState
shield:DescribeSubscription
shield:ListProtections
shield:DescribeProtection
shield:ListAttacks
shield:DescribeAttack
shield:ListProtectionGroups
shield:DescribeProtectionGroup
shield:ListResourcesInProtectionGroup
shield:CreateProtection
shield:DeleteProtection

Separate read-only inventory identities from protection-mutation identities when practical. Scope shield:CreateProtection and shield:DeleteProtection to reviewed resources or protection ARNs where AWS supports resource-level permissions and conditions.

AWS Shield Advanced is a paid account-level service. A READY IntegrationAccount proves only that ValkyrAI may use the stored identity; it does not prove the account has an active Shield Advanced subscription or that a requested resource is eligible.

Configuration

The module uses the operation selector plus bounded execution and safety controls. All Shield calls use the AWS global control-plane endpoint in us-east-1; no user-controlled region or endpoint is accepted.

Recommended policy profiles:

• Inventory: subscription, protection, attack, group, and group-membership reads.
• Protection operator: inventory plus confirmed create or delete for pre-approved resources.
• Incident review: attack list and exact attack description, normally without mutation permissions.

ValkyrAI applies the module retry policy only to read operations. Keep the configured maxAttempts between 1 and 5.

Operations

get_subscription_state

Returns ACTIVE or INACTIVE for the account's Shield Advanced subscription. This is a read and does not activate a subscription.

describe_subscription

Returns bounded subscription dates, auto-renew posture, time commitment, proactive-engagement status, ARN, and account limits. It excludes emergency contacts and DDoS Response Team access configuration.

list_protections

Returns bounded protection identity, resource ARN, health-check IDs, and application-layer automatic-response posture. Supports opaque-token pagination.

describe_protection

Reads one protection by exact protectionId or exact protected resourceArn. Supplying neither or both fails before provider access.

list_attacks

Returns bounded DDoS attack summaries. Optionally filters by one exact resource ARN and an ISO-8601 time interval. Supports opaque-token pagination.

describe_attack

Returns one attack's bounded counters, summarized properties, mitigation names, time bounds, and subresource count. Top-contributor payloads and raw provider objects are not returned.

list_protection_groups

Returns bounded protection-group IDs, ARNs, aggregation and pattern posture, resource type, and bounded members. Supports opaque-token pagination.

describe_protection_group

Reads one exact protection group by ID.

list_group_resources

Lists the protected resource ARNs currently included in one exact protection group. Supports opaque-token pagination.

create_protection

Creates one named protection for one exact eligible resource ARN. confirmCreate=true is mandatory. The request is sent once and returns the created protection ID when AWS accepts it.

delete_protection

Deletes one exact protection by UUID. confirmDelete=true is mandatory. The request is sent once. This operation removes Shield Advanced protection from the resource but does not delete the resource itself.

Errors and Failure Modes

Code	Cause	Safe response
VALIDATION_ERROR	Missing, malformed, unaccepted, overlong, contradictory, or unconfirmed input.	Correct the named input; AWS was not called.
UNSUPPORTED_OPERATION	Operation is outside the published allowlist.	Choose a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or incomplete.	Repair and verify the account without moving credentials into input.
AWS_SHIELD_HTTP_<status>	AWS rejected or could not complete the request.	Inspect IAM, subscription, resource eligibility, account limits, target identity, and requestId.
NETWORK_ERROR	SDK transport failure before an HTTP response.	Restore connectivity; reconcile any mutation before replay.
EXECUTION_ERROR	Unexpected local execution failure.	Inspect sanitized logs and the workflow receipt.

Transient reads may retry with bounded exponential backoff. Protection creation and deletion never retry automatically, even when AWS reports a retryable status, because the provider might have completed the change before the response was lost.

For an ambiguous create response, run describe_protection with the exact resource ARN or list_protections before attempting another create. For an ambiguous delete response, reconcile the exact protection ID before replay.

Example

This workflow first reviews subscription and protection posture, then adds one approved CloudFront distribution:

{
  "operation": "create_protection",
  "protectionName": "customer-edge",
  "resourceArn": "arn:aws:cloudfront::123456789012:distribution/E123EXAMPLE",
  "confirmCreate": true
}

Expected result shape:

{
  "status": "success",
  "operation": "create_protection",
  "attempts": 1,
  "resultType": "protection_mutation",
  "data": {
    "created": true,
    "protectionId": "11111111-2222-3333-4444-555555555555",
    "name": "customer-edge",
    "resourceArn": "arn:aws:cloudfront::123456789012:distribution/E123EXAMPLE"
  },
  "requestId": "safe-provider-request-id"
}

The example ARN and IDs are placeholders. External AWS execution is not validated by the deterministic local test suite because no customer AWS credentials are used during repository validation.

Notes

• Global endpoint: every Shield Advanced API request is signed for us-east-1 and sent through AWS's global Shield endpoint. Protected resource ARNs may identify other supported regions.
• Pagination: list operations expose provider tokens and default to a bounded first page. returnAll=true still stops at limit or 100 pages.
• Rate limits: AWS can throttle reads and mutations. Reads retry within the workflow policy; mutations remain single-attempt.
• API limits: total returned items are capped at 1,000, page requests at 100, tokens at 4,096 characters, and attack windows at 366 days.
• Idempotency: reads are safe to retry. CreateProtection and DeleteProtection do not expose an idempotency token in this release, so reconcile exact state after an ambiguous result.
• Destructive behavior: only delete_protection is destructive, and it requires the exact protection UUID plus confirmDelete=true.
• Deferred capabilities: subscription creation/deletion, protection-group writes, DRT access, emergency contacts, proactive engagement, health-check associations, automatic application-layer response changes, tags, and bulk mutation are intentionally excluded.
• Credential limits: the native AWS IntegrationAccount contract currently supplies an access-key pair. Raw session tokens and provider-chain or endpoint overrides are not accepted through module input.