AWS Security Hub ExecModule

Overview

AwsSecurityHubModule brings AWS Security Hub's consolidated findings and security-posture context into ValkyrAI workflows. It retrieves bounded finding queues and change history, shows enabled standards and their controls, exposes insight results, inventories member accounts and product integrations, and lists automation rules. A reviewed workflow can also update the severity, workflow status, or analyst note for as many as 100 exact findings after explicit confirmation.

Security Hub normalizes findings from AWS services and supported products into the AWS Security Finding Format (ASFF). That makes the connector a practical coordination layer across the AWS CloudTrail, CloudWatch, WAFv2, Shield Advanced, Firewall Manager, IAM, and other ValkyrAI ExecModules: Security Hub identifies and prioritizes the issue, while the appropriate service connector supplies reviewed investigation or remediation steps.

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, arbitrary ASFF documents, automation-rule mutations, standard enablement changes, or member-account administration.

Usage

Enable Security Hub in every AWS region the workflow must inspect.
Create a least-privilege AWS identity for only the operations the workflow needs.
Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and leave it in READY status.
Add AwsSecurityHubModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Set the exact AWS region, choose one operation, and provide only that operation's documented fields.
Use exact filters plus returnAll and limit to keep finding and posture reads bounded.
Place batch_update_findings behind a human or policy approval and set confirmUpdate: true only for a reviewed target set.

Security Hub is regional. Aggregation configuration can make findings from linked regions visible in a home region, but the module does not create or alter that configuration. Use the region that owns the intended Security Hub view.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported Security Hub 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.
`findingId`	string	Operation-specific	—	Exact ASFF finding identifier.
`productArn`	string	Operation-specific	—	Exact Security Hub product ARN for a finding.
`awsAccountId`	string	No	—	Exact 12-digit finding account filter.
`generatorId`	string	No	—	Exact finding generator filter.
`resourceId`	string	No	—	Exact affected-resource filter.
`resourceType`	string	No	—	Exact ASFF resource-type filter.
`severityLabel`	string	No	—	`INFORMATIONAL`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`workflowStatus`	string	No	—	`NEW`, `NOTIFIED`, `RESOLVED`, or `SUPPRESSED`.
`recordState`	string	No	—	`ACTIVE` or `ARCHIVED`.
`complianceStatus`	string	No	—	`PASSED`, `WARNING`, `FAILED`, or `NOT_AVAILABLE`.
`updatedAfter` / `updatedBefore`	ISO-8601 string	No	—	Inclusive finding or history time window.
`standardsSubscriptionArn`	string	Operation-specific	—	Exact enabled-standard subscription ARN.
`insightArn`	string	Operation-specific	—	Exact Security Hub insight ARN.
`onlyAssociated`	boolean	No	`true`	Limit member inventory to associated accounts.
`findingIdentifiers`	array	Update only	—	One to 100 unique objects containing `id` and `productArn`.
`updateSeverityLabel`	string	Update field	—	New bounded severity label.
`updateWorkflowStatus`	string	Update field	—	New bounded workflow status.
`noteText`	string	Conditional	—	Analyst note up to 512 characters.
`noteUpdatedBy`	string	Conditional	—	Analyst/workflow identifier up to 64 characters; required with `noteText`.
`confirmUpdate`	boolean	Update only	`false`	Confirms one exact finding-update batch.

Unknown or operation-inappropriate fields are rejected before any provider call. Finding filters use exact EQUALS comparisons. Raw 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 `findings`, `standards_controls`, or `finding_update`.
`items` / `count`	Bounded list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	Normalized insight result or update receipt.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Finding output contains bounded identity, title, description, timestamps, severity, workflow/compliance status, finding types, and up to 20 resource summaries. It intentionally omits resource detail documents, tags, product fields, user-defined fields, process/network evidence, malware details, raw provider payloads, analyst-note text, and other unrestricted nested ASFF data. History output records which fields changed without returning prior or new values.

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 creates a 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 selected operations. A read-oriented deployment may need a subset of:

securityhub:GetFindings
securityhub:GetFindingHistory
securityhub:GetEnabledStandards
securityhub:DescribeStandards
securityhub:DescribeStandardsControls
securityhub:GetInsights
securityhub:GetInsightResults
securityhub:ListMembers
securityhub:ListEnabledProductsForImport
securityhub:ListAutomationRules

Only workflows that update findings need securityhub:BatchUpdateFindings. Do not grant Security Hub enable/disable, member invitation, standards mutation, automation-rule mutation, product subscription mutation, finding import, 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, internal errors, and network failures up to the configured maximum, bounded from one to five attempts. The default is three attempts.

Each batch_update_findings call is sent once. If AWS returns an ambiguous network or service response, inspect the exact findings before retrying. ValkyrAI never replays a write automatically.

Operations

Finding triage

get_findings — retrieve a newest-updated-first, bounded finding queue. Optional exact filters cover finding/product identity, account, generator, resource, severity, workflow, record state, compliance, and update time.
get_finding_history — retrieve bounded change records for one exact findingId plus productArn, optionally within a time range. Returned history names changed fields but omits the old and new values.

get_findings is suitable for routing work, not exporting unrestricted finding payloads. Use findingId and productArn together when a workflow must reconcile one exact finding.

Standards and controls

get_enabled_standards — list enabled standard subscriptions or inspect one exact subscription ARN.
describe_standards — list standards available in the selected region.
describe_standards_controls — list bounded control status, severity, requirements, and remediation links for one enabled standard subscription.

These operations do not enable or disable standards or controls. They are designed for posture dashboards, exception review, audit preparation, and human-approved remediation routing.

Insights

get_insights — list Security Hub insights or select one exact insight ARN. The module reports insight identity and grouping without dumping the full stored filter document.
get_insight_results — return the grouped values and counts for one exact insight, bounded to the provider's result set.

Insights are useful for concise workflow branching such as “accounts with the most critical findings” or “resource types with recurring control failures.”

Administration visibility

list_members — list bounded member account IDs, administrator IDs, association state, and timestamps. Member email addresses are intentionally omitted.
list_enabled_products_for_import — list enabled Security Hub product-subscription ARNs.
list_automation_rules — list bounded automation-rule identity, order, state, terminal behavior, description, and timestamps. Rule criteria and actions are not returned.

The module does not invite/disassociate members, enable product integrations, create/update/delete automation rules, or alter aggregation configuration.

Finding updates

batch_update_findings — apply at least one reviewed severity, workflow-status, or analyst-note update to one to 100 unique exact findings.

The operation requires confirmUpdate: true. Notes require both noteText and noteUpdatedBy. AWS returns processed and unprocessed finding identities; unprocessed provider messages are omitted while stable error codes are retained. The request is sent once and must be reconciled before any replay.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required field, ARN, enum, limit, time range, identifier set, 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_SECURITY_HUB_HTTP_400`	AWS rejected an input, state, filter, or regional prerequisite.	Correct the target or request; inspect the request ID.
`AWS_SECURITY_HUB_HTTP_403`	IAM or Security Hub administration denied access.	Add only the missing least-privilege permission or prerequisite.
`AWS_SECURITY_HUB_HTTP_404`	A finding, standard subscription, or insight was not found.	Confirm region and exact ARN/identifier.
`AWS_SECURITY_HUB_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Reads retry; update state must be reconciled first.
`NETWORK_ERROR`	ValkyrAI could not reach AWS.	Reads may retry; inspect finding state before replaying a write.
`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 retrieves active high-severity findings that failed a compliance check:

{
  "operation": "get_findings",
  "region": "us-west-2",
  "severityLabel": "HIGH",
  "recordState": "ACTIVE",
  "complianceStatus": "FAILED",
  "updatedAfter": "2026-10-20T00:00:00Z",
  "returnAll": true,
  "limit": 250
}

Expected result shape:

{
  "status": "success",
  "operation": "get_findings",
  "attempts": 1,
  "resultType": "findings",
  "items": [
    {
      "id": "arn:aws:securityhub:us-west-2:123456789012:subscription/example/finding/abc",
      "productArn": "arn:aws:securityhub:us-west-2::product/aws/securityhub",
      "awsAccountId": "123456789012",
      "title": "S3 bucket public access should be blocked",
      "severity": {"label": "HIGH", "normalized": 70},
      "workflowStatus": "NEW",
      "recordState": "ACTIVE",
      "complianceStatus": "FAILED",
      "resources": [{"type": "AwsS3Bucket", "id": "arn:aws:s3:::example"}]
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

A practical follow-up workflow can deduplicate by finding identity, enrich the target with CloudTrail or CloudWatch evidence, open a ticket for a human owner, and then use batch_update_findings to mark the finding NOTIFIED. Remediation belongs to the reviewed connector for the affected AWS service; Security Hub finding status is not itself proof that the underlying resource was fixed.

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: One finding-update call accepts at most 100 unique identities. Finding resources are summarized to 20 entries and insight values to 100 entries.
Idempotency: Reads are repeatable. Finding updates are single-attempt; reconcile exact finding state after an ambiguous response.
Destructive behavior: No operation deletes findings or Security Hub configuration. Updates can still change triage and reporting state and therefore require confirmation.
Regional scope: Security Hub state, product subscriptions, standards, and controls are region-scoped. The module does not accept endpoint overrides.
Data minimization: Raw ASFF subdocuments, resource details/tags, analyst-note bodies, automation-rule actions, member emails, and history values are not returned.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed Security Hub findings are supplied.
Deferred capabilities: Security Hub enable/disable, aggregation configuration, organization configuration, member mutation, invitations, standards/control mutation, insight mutation, automation-rule mutation, product enable/disable, custom action mutation, finding import, batch delete, and unrestricted ASFF export are intentionally deferred.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsSecurityHubModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Finding triage​

Standards and controls​

Insights​

Administration visibility​

Finding updates​

Errors and Failure Modes​

Example​

Notes​

Related resources​