Amazon Detective ExecModule

Overview

The Amazon Detective ExecModule turns behavior-graph posture and investigation results into bounded, governed workflow evidence. Security teams can discover regional behavior graphs, inspect member-account coverage and datasource ingestion, build prioritized investigation queues, retrieve exact investigation summaries, and enumerate indicator categories without placing AWS credentials in workflow payloads.

The connector is designed to move reviewed evidence into response work, not to export an entire Detective graph. Investigation results normalize identity, severity, state, status, scope, and timestamps. Member results expose account, administrator, membership, invitation, and update state while deliberately omitting member email addresses and raw datasource-volume maps. Indicator results expose the indicator type and whether provider detail is available; raw IP addresses, user agents, geolocation strings, and related-finding payloads remain in Detective for an authorized investigator to review.

Every operation in this release is read-only and repeatable. Lists are bounded, provider pagination is explicit, transient reads use controlled retries, and all operations bind a verified IntegrationAccount. Raw access keys, secret keys, session tokens, authorization headers, endpoint overrides, unknown fields, malformed ARNs, and duplicate account identifiers are rejected before any AWS request.

Usage

Enable Amazon Detective in every AWS region the workflow must inspect.
Create a least-privilege AWS identity containing only the Detective read actions needed by the workflow.
Store its access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
Add AwsDetectiveModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
Set the exact AWS region, choose one supported operation, and provide a behavior-graph ARN for graph-scoped operations.
Use limit for a deliberate total bound. Enable returnAll only when the downstream workflow can safely process every page up to that bound.
Preserve graph ARN, investigation ID, entity ARN, state, status, and creation time when deduplicating response work.

Amazon Detective is regional. A graph or investigation returned in one region does not prove Detective is enabled, ingesting data, or configured consistently elsewhere. This release does not create or delete graphs, start investigations, change investigation state, accept or reject invitations, alter members, enable datasource packages, change organization configuration, or manage tags.

Inputs

Input	Type	Required	Default	Description
`operation`	string	Yes	—	One supported Amazon Detective read operation.
`region`	string	Yes	—	Exact AWS region such as `us-west-2`.
`graphArn`	string	Graph-scoped operations	—	Exact Detective behavior-graph ARN.
`nextToken`	string	No	—	Opaque continuation token returned by Detective.
`limit`	integer	No	`100`	Total list bound from 1 to 1,000.
`returnAll`	boolean	No	`false`	Follow provider pages until `limit` or exhaustion.
`accountIds`	array	Member detail	—	One to 50 unique 12-digit AWS account IDs.
`investigationId`	string	Investigation detail/indicators	—	Exact 21-digit investigation ID.
`indicatorType`	string	No	—	One Detective indicator type such as `TTP_OBSERVED` or `RELATED_FINDING`.
`severity`	string	No	—	`INFORMATIONAL`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`investigationStatus`	string	No	—	`RUNNING`, `FAILED`, or `SUCCESSFUL`.
`investigationState`	string	No	—	`ACTIVE` or `ARCHIVED`.
`entityArn`	string	No	—	Exact IAM user or role ARN.
`sortField`	string	No	—	`SEVERITY`, `STATUS`, or `CREATED_TIME`.
`sortOrder`	string	No	`DESC` when a field is supplied	`ASC` or `DESC`; requires `sortField`.

Unknown or operation-inappropriate fields are rejected. Account lists reject duplicates, unsupported enum values, 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 `graphs`, `members`, `investigations`, or `indicators`.
`items` / `count`	Bounded normalized list results and returned count.
`pages` / `hasMore` / `nextToken`	Pagination evidence for list operations.
`data`	Investigation detail, organization configuration, or unprocessed-account context.
`requestId`	AWS request identifier when safely available.
`error`	Stable code, redacted message, HTTP status, and retryability.

Graph results include ARN and creation time. Member results include account, administrator, graph, membership status, disabled reason, invitation type, and safe timestamps; root email addresses and detailed ingestion-volume maps are omitted. Investigation summaries include ID, severity, status, state, entity ARN/type, and creation time. Exact investigation detail adds graph ARN and scope timestamps. Indicator lists expose type and detail availability, leaving raw investigative attributes inside Detective.

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 deployment may need only the actions its reviewed workflows call:

detective:ListGraphs
detective:ListMembers
detective:GetMembers
detective:ListInvitations
detective:ListDatasourcePackages
detective:ListInvestigations
detective:GetInvestigation
detective:ListIndicators
detective:DescribeOrganizationConfiguration
detective:ListOrganizationAdminAccounts

Do not grant graph lifecycle, investigation creation or mutation, member administration, invitation mutation, datasource mutation, organization administration, tagging, or wildcard Detective access merely to satisfy this connector.

Configuration

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

The AWS SDK retry policy is disabled inside the connector. This keeps ValkyrAI's attempts field authoritative and avoids hidden replay behavior.

Operations

Behavior graphs and datasource coverage

list_graphs — list bounded behavior graphs administered by the calling account in one region.
list_datasource_packages — inspect bounded core, EKS audit, and Security Hub finding package ingest state for one graph.

These operations establish which regional graph a workflow is reading and whether expected datasource packages are active. They do not enable Detective, add packages, prove continuous ingestion, or establish complete organizational coverage.

Member and invitation posture

list_members — list bounded member-account state for one behavior graph.
get_members — retrieve normalized state for one to 50 exact member account IDs, with safe unprocessed-account reasons.
list_invitations — list open or accepted graph invitations visible to the calling member account.
list_organization_admin_accounts — list the delegated Detective administrator visible to an organization management account.
describe_organization_configuration — inspect whether new organization accounts are automatically enabled for one organization graph.

A multi-account security team can compare expected accounts with enabled Detective members, identify verification or volume constraints, and route a coverage gap to the accountable cloud owner. Member email addresses are deliberately excluded from workflow output.

Investigation routing

list_investigations — list bounded investigation summaries with optional severity, completion status, archive state, entity ARN, and sorting controls.
get_investigation — retrieve one exact investigation's identity, entity, severity, state, status, and scope timestamps.
list_indicators — list bounded indicator categories for one exact investigation, optionally filtered by indicator type.

A response workflow can queue active high-severity investigations, fetch exact detail for the reviewed set, correlate each entity with approved asset and ownership sources, and open or update incident work without duplicating the same investigation. Detective severity and indicators are evidence to investigate; they do not by themselves prove compromise, business impact, or successful remediation.

Errors and Failure Modes

Code	Meaning	Retry guidance
`VALIDATION_ERROR`	A required field, region, ARN, identifier, enum, or bound 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_DETECTIVE_HTTP_400`	Detective rejected an input or regional state.	Correct the target; inspect the request ID.
`AWS_DETECTIVE_HTTP_403`	IAM denied the operation.	Add only the missing least-privilege action.
`AWS_DETECTIVE_HTTP_404`	The graph, member, investigation, or related resource was not found.	Confirm region and exact identifier.
`AWS_DETECTIVE_HTTP_429` / `500` / `502` / `503` / `504`	Throttling or transient provider pressure.	Bounded read retries are automatic.
`NETWORK_ERROR`	ValkyrAI could not reach Detective.	Verify connectivity and retry the read.
`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

Build a bounded queue of active high-severity investigations:

{
  "operation": "list_investigations",
  "region": "us-west-2",
  "graphArn": "arn:aws:detective:us-west-2:111122223333:graph:0123456789abcdef0123456789abcdef",
  "severity": "HIGH",
  "investigationState": "ACTIVE",
  "sortField": "CREATED_TIME",
  "sortOrder": "DESC",
  "returnAll": true,
  "limit": 100
}

Expected result shape:

{
  "status": "success",
  "operation": "list_investigations",
  "attempts": 1,
  "resultType": "investigations",
  "items": [
    {
      "investigationId": "123456789012345678901",
      "severity": "HIGH",
      "status": "SUCCESSFUL",
      "state": "ACTIVE",
      "entityType": "IAM_ROLE",
      "entityArn": "arn:aws:iam::111122223333:role/SecurityResponder"
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

Pass reviewed IDs to get_investigation when a response workflow needs scope timing and current disposition. Use list_indicators to route the indicator category to an authorized investigator; review detailed evidence in Detective rather than copying raw investigative payloads into every downstream system.

Notes

Pagination: Detective tokens are opaque and can expire. returnAll follows no more than 100 pages and never returns more than 1,000 items.
Rate limits: All operations are reads and retry transient failures with bounded backoff and at most five configured attempts.
API limits: Exact member detail accepts at most 50 unique account IDs. Investigation and indicator pages request at most 100 results.
Idempotency: Every supported operation is read-only and repeatable; no operation changes Detective or AWS Organizations state.
Regional scope: Graphs, members, datasource packages, investigations, and invitations are requested through one exact regional endpoint. Endpoint overrides are not accepted.
Data minimization: Member email addresses, raw datasource-volume maps, raw indicator details, IP addresses, user agents, provider payloads, and provider exception text are excluded.
Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed Detective graph are supplied.
Deferred capabilities: Graph lifecycle, investigation start/archive, invitation decisions, member changes, datasource changes, organization changes, tags, and raw graph search are intentionally deferred.
Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsDetectiveModule through /v1/modules/metadata.

Overview​

Usage​

Inputs​

Outputs​

IntegrationAccount Requirements​

Configuration​

Operations​

Behavior graphs and datasource coverage​

Member and invitation posture​

Investigation routing​

Errors and Failure Modes​

Example​

Notes​

Related resources​