Amazon CloudTrail

Amazon Web Services

Overview

Integrates with AWS CloudTrail to retrieve management-event history across the configured AWS accounts and regions. CloudTrail records API activity and account events; the connector reads those events via the CloudTrail LookupEvents API over a bounded time window and emits one Brinqa object per event.

Data retrieved from Amazon CloudTrail

Connector Object	Required	Maps to Data Model
CloudTrail Event	Yes	Cloud Resource

note

For detailed steps on how to view the data retrieved from Amazon CloudTrail in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select Amazon CloudTrail from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Access key ID	No	—	AWS user access key ID, if not specified, the connector consults the default credentials provider chain to try and determine the \
Secret access key	No	—	AWS user secret access key, if not specified, the connector consults the default credentials provider chain to try and determine the \
Default region	No	—	Default AWS region, if not specified, the connector consults the default region provider chain to try and determine the region to use.
Assume role	No	—	Amazon Resource Name for the role to assume.
External ID	No	—	Optional STS external ID, sent when assuming the role named in the Assume role \
Session duration	No	900	Assume role session duration in seconds.
Page size	No	100	The maximum number of results to retrieve per operation.
Parallel requests	No	—	Maximum number of parallel requests.

Authentication

Authentication is shared across the AWS connector bundle via the AwsConfiguration base class. The CloudTrail sub-connector uses the AWS SDK for Java v2 CloudTrailClient, which signs every request with AWS SigV4 using credentials resolved through the following chain (in order):

1. STS AssumeRole — if assumeRoleARN is configured, the connector assumes that role (using the credentials below as the principal) and uses the resulting temporary session credentials. Set externalId as well if the role's trust policy enforces an ExternalId condition; it is sent on the AssumeRole call and is required for cross-account confused-deputy protection.
2. Static access keys — if accessKey / secretKey are configured, they are used directly.
3. Default credentials provider chain — environment variables, ~/.aws/credentials, container role, or EC2 instance metadata.

Assumed-role sessions use the configurable sessionDuration (default 900 s) with a unique session name per sync. assumeRoleARN may be a comma-separated list to sync multiple accounts in one run. A CloudTrailClient is constructed per role per region and closed when its region has been fully synced.

Choosing an authentication path

The list above is the order the connector resolves credentials in. In terms of what to configure, three paths are supported:

Path	Configure	When to use
STS AssumeRole (recommended)	assumeRoleARN, plus externalId if the trust policy requires one	Cross-account access, and the only path that supports an ExternalId condition. Still needs a principal, from either of the paths below.
Default credentials provider chain (fully keyless)	nothing	The platform runs inside your AWS account on an EC2 instance profile or an EKS IRSA role. No long-lived keys exist anywhere.
Static access keys (optional)	accessKey, secretKey	The platform runs outside your AWS account and no role is available. Long-lived credentials — prefer either path above.

sts:AssumeRole is required only when assumeRoleARN is set.

Required AWS API permissions

Permission	Purpose
cloudtrail:LookupEvents	Look up and page through management events within the time window
sts:AssumeRole	Only when assumeRoleARN is set

Sync Behavior

The connector supports incremental sync. Every LookupEvents request is bounded by a time window whose end is the sync start time and whose start is the later of the default lookback start (now − lookbackDays, default 7 days) and the since (Instant) incremental sync token. When a prior sync timestamp is available and is later than the default lookback start, since is used as the window start so only events recorded since the last sync are returned; otherwise the full lookbackDays window is queried.

How to obtain Amazon CloudTrail credentials

Create an IAM user for AWS access

For detailed steps on creating an IAM user and obtaining access keys, see the Amazon EC2 connector documentation. Follow the same process, but attach the required CloudTrail permissions (cloudtrail:LookupEvents) instead of the EC2 permissions.

The connector authenticates using the AWS SDK's credential resolution chain. If an assume-role ARN is configured, the connector assumes that IAM role using the provided credentials. Otherwise, it uses the provided access keys directly, falling back to the AWS Default Credential Provider Chain (environment variables, ~/.aws/credentials, or EC2 instance metadata).

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

CloudTrail Event

Source Field Name	SDM Attribute
constant "AWS"	CLOUD_PROVIDER
Event.accessKeyId	ACCESS_KEY_ID
Event.eventId	EVENT_ID
Event.eventId (fallback region:eventName:eventTime:username)	UID
Event.eventName	EVENT_NAME
Event.eventName (fallback the composite UID)	NAME
Event.eventSource	EVENT_SOURCE
Event.eventTime	EVENT_TIME
Event.readOnly (parsed "true"/"false" string to Boolean)	READ_ONLY
Event.resources[] rendered as resourceType:resourceName	RESOURCES (multivalued)
Event.username	USERNAME
sync region	REGION
sync timestamp	LAST_CAPTURED

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

CloudTrail Event

Operation options

Option	Type	Default	Description
region / regions	Comma-separated list of regions to query (one client per region). regions takes precedence over region.	Resolved from configuration / region provider chain
pageSize	Requested page size; effective page size is min(pageSize, 50).	Shared pageSize configuration (100) → capped at 50
parallelismLevel	Number of parallel worker threads.	min(4, CPU cores)	No
lookbackDays	Number of days back from now for the default lookup window.	7

Delta sync

Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on startTime (LookupEvents event-time window, mapped to EVENT_TIME).

API

• Type: AWS SDK for Java v2 (CloudTrailClient) · Endpoint: cloudtrail:LookupEvents

Changelog

Changelog

The Amazon CloudTrail connector has undergone the following changes:

Version	Description	Migration Steps
3.2.3	New Features - Roles that require an External ID can now be used. A new optional External ID setting is sent when assuming the role named in the connector's Assume role setting, so roles whose trust policy enforces an ExternalId condition — the standard protection against cross-account confused-deputy access — can now be assumed. Existing configurations are unaffected: leave it blank and the role is assumed exactly as before. The connector's authentication documentation now also describes all three supported paths — assuming a role, running fully keyless from an EC2 instance profile or EKS IRSA role, and static access keys. Bug Fixes - The Parallel requests setting is now labeled on the configuration screen. The setting was shown without its proper name or help text. It now displays its label and description. The setting's behavior and default are unchanged.	N/A
3.2.2	No changes in this release.	N/A
3.2.1	No changes in this release.	N/A
3.2.0	No changes in this release.	N/A
3.1.0	New Features - New connector — syncs CloudTrail events via a windowed lookup (default 7-day window, configurable via the lookbackDays operation option). Improvements - Sync failures are now visible. Previously, certain AWS API errors (throttling, server errors, transient network failures, validation errors) could be silently swallowed during multi-region sync, producing empty results without indicating a problem. These now surface as sync failures with a clear log entry detailing the HTTP status, AWS error code, request id, and service name. Per-region permission gaps (HTTP 401 / 403) still allow the sync to continue across other regions, but are now visible in logs.	N/A