AWS CloudTrail ExecModule

Overview

AwsCloudTrailModule brings bounded AWS CloudTrail inventory, audit lookup, delivery-status inspection, event-selector review, and exact logging-state controls into ValkyrAI workflows. It lets an incident, compliance, or platform workflow discover trails, confirm whether an exact trail is recording, retrieve recent management or Insights event metadata, inspect selector coverage, and explicitly start or stop logging.

The connector implements eight operations:

• list_trails, describe_trails, and get_trail discover trail identity and configuration.
• get_trail_status reads recording and delivery state.
• lookup_events retrieves bounded event metadata from CloudTrail's recent-event lookup window.
• get_event_selectors summarizes basic and advanced selector coverage.
• start_logging and stop_logging change one exact trail's recording state after explicit confirmation.

n8n's reusable AWS IAM credential model is the functional workflow reference: region, access key ID, secret access key, and temporary-credential awareness belong in a reusable credential rather than node input. ValkyrAI follows its native IntegrationAccount contract and adds exact field allowlists, trail/region identity checks, bounded pagination, confidential output, raw-event omission, read-only retries, single-attempt mutations, and deterministic receipts.

Usage

1. Identify the AWS account, region, and exact trails that a workflow may inspect or control.
2. Create a least-privilege principal with only the required CloudTrail actions and resource conditions.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsCloudTrailModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use list_trails or describe_trails before accepting a trail name or ARN from another workflow step.
6. Bound event lookup by time, attribute, and limit; retain the AWS request ID for audit evidence.
7. Read get_trail_status immediately before and after a requested logging-state change.
8. Require human review before setting confirmStartLogging or confirmStopLogging to true.

Never put access keys, secret keys, session tokens, passwords, or credential objects in module input. Raw credential-shaped fields are rejected before network access. Trail topology, audit-event metadata, usernames, access-key IDs, and delivery errors are classified as confidential workflow data.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eight documented operations.
region	string	Every execution	None	Valid AWS region such as us-west-2.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	List operations	100	Total bound from 1 through 1,000.
returnAll	boolean	List operations	false	Follow pages until limit, provider exhaustion, or 100 pages.
trailName	string	Exact-trail operations	None	AWS trail name or ARN; ARN region must match region.
includeShadowTrails	boolean	describe_trails	false	Include replicated shadow trails for multi-region trails.
lookupAttributeKey	string	Optional lookup filter	None	AccessKeyId, EventId, EventName, EventSource, ReadOnly, ResourceName, ResourceType, or Username.
lookupAttributeValue	string	With lookupAttributeKey	None	Non-empty provider lookup value, at most 2,000 characters.
eventCategory	string	lookup_events	MANAGEMENT	MANAGEMENT or INSIGHT.
startTime	string	Optional lookup bound	None	ISO-8601 UTC instant.
endTime	string	Optional lookup bound	None	ISO-8601 UTC instant, not before startTime.
confirmStartLogging	boolean	start_logging	false	Must be exactly true.
confirmStopLogging	boolean	stop_logging	false	Must be exactly true.

If both times are supplied, their span may not exceed CloudTrail's 90-day recent-event lookup window. Only one lookup attribute pair is accepted because the CloudTrail LookupEvents API accepts one attribute per request. Unexpected fields fail before provider access.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Trail, event, selector, status, or logging-state family.
items	array	List or describe success	Bounded normalized trails or events.
count	integer	Items present	Number of returned items.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Exact read/mutation success	Normalized configuration, status, selectors, or acceptance receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Event results contain event ID, name, source, time, read-only marker, bounded principal identifiers, and up to 50 resource references. The provider's raw CloudTrailEvent JSON is deliberately omitted because it can contain request parameters and response elements that need a separate disclosure review.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / CloudTrail
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only actions used by the reviewed workflow:

• Discovery: cloudtrail:ListTrails, cloudtrail:DescribeTrails, and cloudtrail:GetTrail.
• Status and audit reads: cloudtrail:GetTrailStatus, cloudtrail:LookupEvents, and cloudtrail:GetEventSelectors.
• Logging controls: cloudtrail:StartLogging and/or cloudtrail:StopLogging only for explicitly governed trails.

Use IAM resource scoping, organization service-control policies, separate read and mutation accounts, trail home-region restrictions, and human approval to reduce blast radius. Prefer a read-only account unless logging-state control is an explicit requirement.

Configuration

The awsAccount relationship is the only credential configuration. Operation, trail, filters, pagination, time bounds, and safety confirmations belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-cloudtrail-security"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"lookup_events\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_trails	Lists bounded trail names, ARNs, and home regions.	Read-only; each page retries transient failures.
describe_trails	Returns bounded trail configuration, optionally including shadow trails.	Read-only; bounded retry.
get_trail	Reads one exact trail by name or ARN.	Read-only; bounded retry.
get_trail_status	Reads recording state and recent delivery/error timestamps.	Read-only; bounded retry.
lookup_events	Looks up bounded recent management or Insights event metadata.	Read-only; each page retries transient failures.
get_event_selectors	Summarizes basic and advanced event-selector coverage.	Read-only; bounded retry.
start_logging	Requests recording for one exact trail.	Confirmed external mutation; exactly one attempt.
stop_logging	Suspends recording and delivery for one exact trail.	Confirmed destructive mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, trail, filter, time, bound, or confirmation.	No	Correct the named input; no AWS request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_CLOUDTRAIL_HTTP_400	Invalid trail identity, home-region mismatch, invalid lookup, or provider conflict.	Usually no	Inspect exact trail state and request ID.
AWS_CLOUDTRAIL_HTTP_403	IAM, SCP, organization, KMS, S3, or resource policy denied the request.	No	Grant only the missing action or revise the workflow.
AWS_CLOUDTRAIL_HTTP_404	Exact trail is absent.	No	Reconcile current region, home region, name, and ARN.
AWS_CLOUDTRAIL_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; writes remain single-attempt	Reconcile trail status before any mutation replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; writes report ambiguity	Treat provider acceptance as unknown until status is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, trail topology, account details, lookup values, and policy information from leaking through failures.

Example

Look up recent IAM management events:

{
  "operation": "lookup_events",
  "region": "us-west-2",
  "lookupAttributeKey": "EventSource",
  "lookupAttributeValue": "iam.amazonaws.com",
  "eventCategory": "MANAGEMENT",
  "startTime": "2026-09-01T00:00:00Z",
  "endTime": "2026-09-07T00:00:00Z",
  "limit": 50,
  "returnAll": true
}

Expected result shape:

{
  "status": "success",
  "operation": "lookup_events",
  "attempts": 1,
  "resultType": "events",
  "items": [
    {
      "eventId": "provider-event-reference",
      "eventName": "UpdateRole",
      "eventSource": "iam.amazonaws.com",
      "username": "security-automation",
      "eventTime": "2026-09-06T23:41:12Z",
      "readOnly": "false"
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "aws-request-reference"
}

The result supplies triage metadata, not the full event payload. Use the event ID and your approved evidence path when raw request or response fields are required.

Notes

• Pagination: list_trails and lookup_events accept an opaque nextToken; lookup pages request at most 50 events and all loops stop at limit, provider exhaustion, or 100 pages.
• Rate limits: AWS SDK internal retries are disabled. ValkyrAI applies bounded backoff only to read operations and honors ExecModule retry attempts from 1 through 5.
• API limits: LookupEvents covers events recorded in the selected region during the last 90 days and accepts one lookup attribute per request. This module caps a workflow at 1,000 returned items.
• Idempotency: reads are retry-safe. Logging start/stop calls are issued exactly once; after an ambiguous result, call get_trail_status and reconcile AWS evidence before replay.
• Destructive behavior: stop_logging suspends API-call recording and delivery for the exact trail and can disable Insights on that trail. It requires confirmStopLogging: true and review of the trail's home region and organizational role.
• Event privacy: raw CloudTrailEvent JSON is not returned. Treat usernames, access-key IDs, resource names, delivery errors, and trail configuration as confidential.
• Multi-region behavior: use the trail's home region for logging controls. includeShadowTrails is opt-in because shadow trail results can otherwise be mistaken for independent writable trails.
• Deferred scope: create/update/delete trail, tag lifecycle, event-selector mutation, Insights-selector mutation, channels, Lake event data stores, queries, dashboards, imports, and raw event disclosure are intentionally excluded.
• External verification: repository tests use a deterministic transport and make no AWS call. Provider behavior requires a separately authorized least-privilege AWS account and reviewed trail scope.