Amazon GuardDuty ExecModule

Overview

The Amazon GuardDuty ExecModule brings AWS threat detections into ValkyrAI as bounded, governed workflow data. Teams can discover regional detectors, build filtered finding queues, retrieve selected finding details, measure severity distribution, inspect saved filters and member-account posture, review publishing destinations, and explicitly archive or unarchive reviewed findings without placing AWS credentials in workflow payloads.

The connector is designed for triage and orchestration rather than bulk security-data export. Finding lists return exact IDs. Detail reads normalize a focused set of identity, severity, resource, timing, and archive-state fields instead of returning raw SDK objects or deeply nested provider evidence. Every list is bounded, read retries are explicit, and reversible archive-state changes require confirmation and execute once.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. It rejects raw access keys, secret keys, session tokens, authorization headers, endpoint overrides, and operation-inappropriate fields before any provider call.

Usage

1. Enable GuardDuty in each AWS region the workflow must inspect.
2. Create a least-privilege AWS identity containing only the GuardDuty actions used by the workflow.
3. Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
4. Add AwsGuardDutyModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Set the exact AWS region, choose one supported operation, and provide the regional detectorId except when listing detectors.
6. Use narrow severity, type, resource, archive-state, member, and result bounds.
7. Put archive or unarchive actions behind human or policy approval and set confirmMutation: true only after reviewing the exact finding IDs.

GuardDuty is regional. Listing a detector in one region does not prove GuardDuty is enabled or configured consistently elsewhere. This release does not create, update, or delete detectors, filters, members, threat-intelligence sets, publishing destinations, organization settings, or malware-protection plans, and it never generates sample findings.

Inputs

Input	Type	Required	Default	Description
operation	string	Yes	—	One supported GuardDuty operation.
region	string	Yes	—	Exact AWS region such as us-west-2.
detectorId	string	Most operations	—	Exact regional detector ID; omit only for list_detectors.
nextToken	string	No	—	Opaque continuation token returned by GuardDuty.
limit	integer	No	100	Total list bound from 1 to 1,000.
returnAll	boolean	No	false	Follow provider pages until limit or exhaustion.
findingIds	array	Detail/triage	—	One to 50 unique finding IDs.
findingTypes	array	No	—	Up to 20 exact GuardDuty finding types.
resourceTypes	array	No	—	Up to 20 exact GuardDuty resource types.
minimumSeverity / maximumSeverity	integer	No	—	Inclusive severity bounds from 0 through 10.
archived	boolean	No	—	Filter finding IDs by archive state.
filterName	string	Filter detail	—	Exact saved-filter name.
accountIds	array	Member detail	—	One to 50 unique 12-digit AWS account IDs.
onlyAssociated	boolean	No	true	Limit list_members to associated accounts.
confirmMutation	boolean	Triage	false	Required for archive and unarchive operations.

Unknown or operation-inappropriate fields are rejected. Lists reject duplicates and values outside documented size and character bounds.

Outputs

Every operation returns 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 finding_ids, findings, members, or finding_archive.
items / count	Bounded normalized list results and returned count.
pages / hasMore / nextToken	Pagination evidence for list operations.
data	Detector detail, severity statistics, filter detail, member detail, or mutation receipt.
requestId	AWS request identifier when safely available.
error	Stable code, redacted message, HTTP status, and retryability.

Finding detail includes bounded identity, ARN, account, region, type, title, description, severity, confidence, timestamps, resource type, detector, feature, service timing, event count, and archive state. It excludes raw action trees, network evidence, runtime process trees, credentials, private infrastructure detail, complete SDK payloads, and raw provider errors.

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.

A read-oriented deployment may need a subset of:

guardduty:ListDetectors
guardduty:GetDetector
guardduty:ListFindings
guardduty:GetFindings
guardduty:GetFindingsStatistics
guardduty:ListFilters
guardduty:GetFilter
guardduty:ListMembers
guardduty:GetMembers
guardduty:ListPublishingDestinations

Only approved triage workflows need guardduty:ArchiveFindings or guardduty:UnarchiveFindings. Do not grant detector mutation, sample-finding generation, member administration, filter mutation, organization administration, malware-plan mutation, threat-set mutation, or wildcard GuardDuty access merely to satisfy a read workflow.

Configuration

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

Archive and unarchive are sent exactly once. An ambiguous timeout may mean AWS accepted the request even though ValkyrAI did not receive a response. Re-read the exact findings before any manual replay.

Operations

Detector posture

• list_detectors — list bounded detector IDs in one region.
• get_detector — inspect detector status, publishing frequency, timestamps, and bounded feature status.

These operations help a workflow prove which regional detector it is querying. They do not enable or reconfigure GuardDuty.

Finding discovery and evidence

• list_findings — list bounded finding IDs with optional type, resource-type, severity, and archive-state criteria.
• get_findings — retrieve normalized detail for one to 50 exact finding IDs.
• get_findings_statistics — retrieve GuardDuty's count-by-severity summary for one detector.

A practical workflow can list active high-severity IDs, fetch only that batch, deduplicate by finding ID and update time, enrich the affected resource through another reviewed connector, create or update an incident, and then wait for an approved triage decision. Finding presence is evidence to investigate; it is not proof of compromise, customer impact, or successful remediation.

Saved filters and account coverage

• list_filters — list bounded saved-filter names.
• get_filter — inspect filter identity, description, action, rank, and criterion field names without returning every criterion value.
• list_members — list bounded administrator/member relationship state while omitting member email addresses.
• get_members — retrieve selected member-account state plus bounded unprocessed-account results.
• list_publishing_destinations — inspect bounded destination identity, type, and publishing status.

These reads make it possible to route detections with context about account coverage and export posture without changing those configurations.

Reversible triage

• archive_findings — archive one to 50 exact findings after confirmMutation: true.
• unarchive_findings — restore one to 50 exact findings after confirmMutation: true.

Both actions are reversible, single-attempt operations. They change GuardDuty triage state but do not remediate a resource, delete evidence, suppress a detector, or alter future detection.

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	A required field, identifier, filter, bound, or confirmation is invalid.	Correct input; no provider call was made.
INTEGRATION_ACCOUNT_ERROR	The 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_GUARDDUTY_HTTP_400	GuardDuty rejected an input or regional state.	Correct the target; inspect the request ID.
AWS_GUARDDUTY_HTTP_403	IAM denied the operation.	Add only the missing least-privilege action.
AWS_GUARDDUTY_HTTP_404	The detector, finding, filter, member, or destination was not found.	Confirm region and exact identifier.
AWS_GUARDDUTY_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; reconcile archive state before replaying a write.
NETWORK_ERROR	ValkyrAI could not reach GuardDuty.	Reads may retry; reconcile mutation state first.
EXECUTION_ERROR	An unexpected local failure was safely contained.	Inspect server logs; secrets remain redacted.

Provider exception text is never returned to workflow output. AWS request IDs are preserved when safely available for CloudTrail and support correlation.

Example

First list active high-severity findings:

{
  "operation": "list_findings",
  "region": "us-west-2",
  "detectorId": "12abc34d567e8fa901bc2d34e56789f0",
  "minimumSeverity": 7,
  "archived": false,
  "returnAll": true,
  "limit": 250
}

Expected result shape:

{
  "status": "success",
  "operation": "list_findings",
  "attempts": 1,
  "resultType": "finding_ids",
  "items": [{"findingId": "example-finding-id"}],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Pass the exact returned ID to get_findings, route the normalized result to an incident or approval step, and archive only after the workflow has recorded a reviewed disposition.

Notes

• Pagination: Opaque GuardDuty 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: Finding and member detail batches accept at most 50 unique IDs. Finding type and resource type filters accept at most 20 values.
• Idempotency: Reads are repeatable. Archive and unarchive are single-attempt reversible writes; reconcile current state after ambiguity.
• Destructive behavior: No operation deletes findings or GuardDuty resources. Archive changes triage visibility and unarchive reverses it.
• Regional scope: Detectors, findings, filters, members, and publishing destinations are regional. Endpoint overrides are not accepted.
• Data minimization: Member email, raw criteria values, nested action/evidence/process trees, raw SDK payloads, and provider exception text are excluded.
• Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed GuardDuty resources are supplied.
• Deferred capabilities: Detector, filter, member, organization, publishing-destination, malware-protection, threat-set, IP-set, and sample-finding mutations are intentionally deferred.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsGuardDutyModule through /v1/modules/metadata.

Related resources

• Amazon GuardDuty API Reference
• Amazon GuardDuty service authorization
• AWS Security Hub ExecModule
• AWS Config ExecModule
• AWS CloudTrail ExecModule