This guide walks you through connecting AWS CloudTrail to TruU TOTAL for persona generation and threat detection.

Overview

TOTAL ingests cloud infrastructure activity events from AWS CloudTrail via the CloudTrail Lookup Events API or by reading from an S3 bucket where CloudTrail logs are delivered. We poll for new events on a configurable interval to collect, normalize, and correlate API calls, console sign-ins, IAM changes, resource access, and security-relevant actions across your AWS environment. Connector Type: Polling

Prerequisites

AWS IAM access with permission to create IAM users or roles and manage policies
CloudTrail enabled with at least one trail logging management events (most AWS accounts have this by default)
For enhanced coverage: Data events enabled for S3, Lambda, or other services
S3 bucket where CloudTrail delivers logs (if using S3-based ingestion)
Approximately 15 minutes to complete setup

Step 1: Choose Your Ingestion Method

TOTAL supports two methods for ingesting CloudTrail events:

Method	Best For	Latency	Coverage
CloudTrail Lookup API	Quick setup, management events	~15 min	Management events (last 90 days)
S3 Bucket	Full coverage, data events	~5-15 min	Management + data events (unlimited retention)

We recommend the S3 Bucket method for production deployments, as it provides access to both management and data events with configurable retention.

Step 2: Create an IAM Role for TOTAL

TOTAL authenticates to your AWS account using an IAM role with cross-account assume-role trust (recommended) or an IAM user with access keys.

Option A: Cross-Account IAM Role (Recommended)

Sign in to the AWS Console
Navigate to IAM → Roles → Create role
Select Another AWS account as the trusted entity
Enter the TOTAL AWS Account ID (provided in the TruU Portal)
Check Require external ID and enter the External ID shown in the TruU Portal
Click Next: Permissions
Attach the following managed policy (or create a custom one — see below):
- CloudTrailReadOnlyAccess
If using S3 ingestion, also attach:
- A custom policy granting s3:GetObject and s3:ListBucket on your CloudTrail S3 bucket
Name the role: TruU-TOTAL-CloudTrail-Reader
Click Create role
Copy the Role ARN and paste it into the TruU Portal

Option B: IAM User with Access Keys

Navigate to IAM → Users → Create user
Enter:
- Username: truu-total-cloudtrail
Select Programmatic access
Attach the CloudTrailReadOnlyAccess policy (and S3 read policy if applicable)
Click Create user
Copy the Access Key ID and Secret Access Key
Paste them into the TruU Portal

Custom IAM Policy (Least Privilege)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudtrail:LookupEvents",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:DescribeTrails",
        "cloudtrail:ListTrails"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-cloudtrail-bucket",
        "arn:aws:s3:::your-cloudtrail-bucket/*"
      ]
    }
  ]
}

Step 3: Configure S3 Bucket Access (If Using S3 Method)

In the TruU Portal, enter:
- S3 Bucket Name: Your CloudTrail log bucket name
- S3 Prefix (optional): The path prefix if CloudTrail logs are organized by account/region
- AWS Region: The region where your S3 bucket resides
TOTAL will validate access by listing recent log files

Step 4: Verify Connectivity

Once credentials are entered in the TruU Portal:

Click Test Connection — TOTAL will attempt to read recent CloudTrail events
If successful, you’ll see a confirmation with the number of recent events and trails detected
If configured, TOTAL will run a historical data pull to seed user personas

Security & Privacy

What We Access

Read-only access to CloudTrail events via the Lookup API or S3 bucket
Management events (API calls, console sign-ins, IAM changes)
Data events (if enabled): S3 object access, Lambda invocations, DynamoDB operations
All queries use timestamp filtering — we only fetch new events since the last poll

What We Don’t Have Access To

Write access to any AWS resources
Ability to create, modify, or delete IAM users, roles, or policies
Access to resource contents (S3 objects, database records, etc.)
Access to billing, cost management, or account settings
CloudTrail configuration or trail management

Updating or Rotating Credentials

Rotate Access Keys (If Using IAM User)

In AWS Console, go to IAM → Users → truu-total-cloudtrail
Under Security credentials, click Create access key
Copy the new Access Key ID and Secret Access Key
Paste them in the TruU Portal
After TOTAL confirms the new keys are active, deactivate the old access key

Revoke Access

To immediately remove TOTAL’s access:

Option A — Disable in the TruU Portal
Option B — Delete or deactivate the IAM role/user in AWS
Option C — Remove the trust relationship from the IAM role (for cross-account)

Rate Limiting & Scalability

AWS CloudTrail Rate Limits

Lookup Events API

Parameter	Limit
LookupEvents API	2 req/s per account per region (hard limit)
Max results per request	50 events
Lookback window	Last 90 days

S3 Bucket Ingestion (Recommended for Production)

Parameter	Limit
Log delivery frequency	~5 minutes
S3 GetObject rate	5,500 req/s per prefix
Retention	Unlimited (customer-controlled S3 lifecycle)

Ingestion Capacity

The Lookup Events API is severely rate-limited at 2 req/s (~100 events/sec) and is only suitable for low-volume environments or initial testing. For production, TOTAL uses the S3 bucket ingestion method, where throughput is bounded by S3 read speed (5,500 req/s per prefix) — effectively unlimited for log ingestion. A large enterprise with 100K+ users across a multi-account AWS Organization generates 1M–100M+ raw CloudTrail events/day depending on data event configuration. After filtering to human identities only (excluding service roles, Lambda execution roles, machine identities), the TOTAL-relevant subset is 500K–5M events/day. The practical constraint is AWS’s ~5-minute log delivery lag, not TOTAL’s read speed. TOTAL can ingest from an organization-wide CloudTrail trail that aggregates logs from all member accounts into a single S3 bucket. AWS costs are minimal — S3 GET requests for a typical enterprise are < $10/month.

Event Freshness

AWS delivers CloudTrail logs to S3 approximately every 5 minutes. TOTAL polls on a configurable interval (default: 5 minutes). End-to-end latency is typically 5–15 minutes.

Resilience

TOTAL uses cursor-based ingestion with at-least-once delivery. The polling cursor only advances after events are successfully collected, normalized, and published. If any step fails, the cursor stays put and the next poll replays from the last known-good position. No events are lost. Transient failures (S3 errors, throttling, timeouts) are retried automatically with exponential backoff. STS-based role assumption means no long-lived credentials — tokens auto-refresh before expiry. After 5 consecutive failures, the connector self-pauses and can be re-enabled from the TruU Portal. S3 log retention is customer-controlled (typically 90+ days), so data loss requires an outage longer than your retention policy.

Connector Design

Each connector polls on an independent, configurable interval. Events are batched and published in per-user order to preserve sequence integrity for persona building. Connector workers are stateless and scale horizontally — S3 log file processing parallelizes naturally across workers for multi-account environments. All polling intervals, concurrency, and event filtering rules are tunable from the TruU Portal.

Part 2: Event Types & Data Schema

Signal Classification

Signal Class	TOTAL Category
Cloud & Infrastructure	Authentication, Admin, Data Access, Network

Event Types We Ingest

TOTAL extracts the following categories of events from AWS CloudTrail. While CloudTrail records every API call in your AWS account, TOTAL only ingests events attributable to human identities — IAM users, federated users, and SSO users. Events from service roles, Lambda execution roles, and other machine identities are filtered out. Every event below includes a userIdentity block that resolves to a specific person.

Console & Authentication Events

Event Name	Event Source	Description	TOTAL Classification
`ConsoleLogin`	`signin.amazonaws.com`	AWS Console sign-in	Authentication
`ConsoleLoginFailure`	`signin.amazonaws.com`	Failed console sign-in attempt	Authentication
`SwitchRole`	`signin.amazonaws.com`	User switched IAM role	Authentication
`AssumeRole`	`sts.amazonaws.com`	Role assumed via STS	Authentication
`AssumeRoleWithSAML`	`sts.amazonaws.com`	Role assumed via SAML federation	Authentication
`GetSessionToken`	`sts.amazonaws.com`	User requested temporary session token	Authentication
`GetFederationToken`	`sts.amazonaws.com`	User requested federation token	Authentication

IAM Events

Event Name	Event Source	Description	TOTAL Classification
`CreateUser`	`iam.amazonaws.com`	New IAM user created	Admin
`DeleteUser`	`iam.amazonaws.com`	IAM user deleted	Admin
`CreateRole`	`iam.amazonaws.com`	New IAM role created	Admin
`DeleteRole`	`iam.amazonaws.com`	IAM role deleted	Admin
`AttachUserPolicy`	`iam.amazonaws.com`	Policy attached to user	Admin
`DetachUserPolicy`	`iam.amazonaws.com`	Policy detached from user	Admin
`AttachRolePolicy`	`iam.amazonaws.com`	Policy attached to role	Admin
`PutUserPolicy`	`iam.amazonaws.com`	Inline policy added to user	Admin
`CreateAccessKey`	`iam.amazonaws.com`	Access key created for user	Admin
`DeleteAccessKey`	`iam.amazonaws.com`	Access key deleted	Admin
`UpdateAccessKey`	`iam.amazonaws.com`	Access key activated/deactivated	Admin
`CreateLoginProfile`	`iam.amazonaws.com`	Console password created for user	Admin
`UpdateLoginProfile`	`iam.amazonaws.com`	Console password updated	Admin
`AddUserToGroup`	`iam.amazonaws.com`	User added to IAM group	Admin
`RemoveUserFromGroup`	`iam.amazonaws.com`	User removed from IAM group	Admin
`EnableMFADevice`	`iam.amazonaws.com`	MFA device enabled for user	Admin
`DeactivateMFADevice`	`iam.amazonaws.com`	MFA device deactivated	Admin

S3 Data Events (If Enabled)

Event Name	Event Source	Description	TOTAL Classification
`GetObject`	`s3.amazonaws.com`	Object downloaded from S3	Data Access
`PutObject`	`s3.amazonaws.com`	Object uploaded to S3	Data Access
`DeleteObject`	`s3.amazonaws.com`	Object deleted from S3	Data Access
`CopyObject`	`s3.amazonaws.com`	Object copied within S3	Data Access
`CreateBucket`	`s3.amazonaws.com`	New S3 bucket created	Admin
`DeleteBucket`	`s3.amazonaws.com`	S3 bucket deleted	Admin
`PutBucketPolicy`	`s3.amazonaws.com`	Bucket policy modified	Admin
`PutBucketPublicAccessBlock`	`s3.amazonaws.com`	Public access block modified	Admin

EC2 & Network Events

Event Name	Event Source	Description	TOTAL Classification
`RunInstances`	`ec2.amazonaws.com`	User launched an EC2 instance	Admin
`TerminateInstances`	`ec2.amazonaws.com`	User terminated an EC2 instance	Admin
`StopInstances`	`ec2.amazonaws.com`	User stopped an EC2 instance	Admin
`StartInstances`	`ec2.amazonaws.com`	User started an EC2 instance	Admin
`AuthorizeSecurityGroupIngress`	`ec2.amazonaws.com`	User added security group inbound rule	Network
`AuthorizeSecurityGroupEgress`	`ec2.amazonaws.com`	User added security group outbound rule	Network
`RevokeSecurityGroupIngress`	`ec2.amazonaws.com`	User removed security group inbound rule	Network
`CreateSecurityGroup`	`ec2.amazonaws.com`	User created a new security group	Network

Lambda & Serverless Events

Event Name	Event Source	Description	TOTAL Classification
`CreateFunction`	`lambda.amazonaws.com`	User created a Lambda function	Admin
`UpdateFunctionCode`	`lambda.amazonaws.com`	User updated Lambda function code	Admin
`UpdateFunctionConfiguration`	`lambda.amazonaws.com`	User updated Lambda configuration	Admin
`AddPermission`	`lambda.amazonaws.com`	User added permission to Lambda	Admin

Secrets & Key Management Events

Event Name	Event Source	Description	TOTAL Classification
`GetSecretValue`	`secretsmanager.amazonaws.com`	User retrieved a secret from Secrets Manager	Data Access
`CreateSecret`	`secretsmanager.amazonaws.com`	User created a new secret	Admin
`CreateKey`	`kms.amazonaws.com`	User created a new KMS key	Admin
`DisableKey`	`kms.amazonaws.com`	User disabled a KMS key	Admin
`ScheduleKeyDeletion`	`kms.amazonaws.com`	User scheduled KMS key deletion	Admin

CloudTrail & Logging Events

Event Name	Event Source	Description	TOTAL Classification
`StopLogging`	`cloudtrail.amazonaws.com`	User stopped CloudTrail logging	Alert
`DeleteTrail`	`cloudtrail.amazonaws.com`	User deleted a CloudTrail trail	Alert
`UpdateTrail`	`cloudtrail.amazonaws.com`	User modified CloudTrail trail configuration	Admin
`PutEventSelectors`	`cloudtrail.amazonaws.com`	User modified event selectors	Admin

Sample Source Event (CloudTrail — AssumeRole)

{
  "eventVersion": "1.09",
  "userIdentity": {
    "type": "IAMUser",
    "principalId": "AIDAEXAMPLE123456",
    "arn": "arn:aws:iam::123456789012:user/jane.doe",
    "accountId": "123456789012",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "userName": "jane.doe",
    "sessionContext": {
      "attributes": {
        "mfaAuthenticated": "true",
        "creationDate": "2026-03-15T08:00:00Z"
      }
    }
  },
  "eventTime": "2026-03-15T08:15:30Z",
  "eventSource": "sts.amazonaws.com",
  "eventName": "AssumeRole",
  "awsRegion": "us-east-1",
  "sourceIPAddress": "198.51.100.42",
  "userAgent": "aws-cli/2.15.0 Python/3.11.6",
  "requestParameters": {
    "roleArn": "arn:aws:iam::123456789012:role/ProductionAdmin",
    "roleSessionName": "jane-doe-prod-session",
    "durationSeconds": 3600
  },
  "responseElements": {
    "credentials": {
      "accessKeyId": "ASIAEXAMPLE789",
      "expiration": "Mar 15, 2026 9:15:30 AM",
      "sessionToken": "FwoGZX..."
    },
    "assumedRoleUser": {
      "assumedRoleId": "AROAEXAMPLE:jane-doe-prod-session",
      "arn": "arn:aws:sts::123456789012:assumed-role/ProductionAdmin/jane-doe-prod-session"
    }
  },
  "requestID": "req-id-001",
  "eventID": "evt-id-001",
  "readOnly": false,
  "resources": [
    {
      "accountId": "123456789012",
      "type": "AWS::IAM::Role",
      "ARN": "arn:aws:iam::123456789012:role/ProductionAdmin"
    }
  ],
  "eventType": "AwsApiCall",
  "managementEvent": true,
  "recipientAccountId": "123456789012",
  "eventCategory": "Management"
}

TOTAL Normalized Event

{
  "event_id": "b8c9d0e1-f2a3-4567-hijk-890123456789",
  "event_type": "AUTH",
  "source": "AWS_CLOUDTRAIL",
  "signal_type": "CLOUD",
  "domain_id": "customer-domain-001",
  "tuid": "tuid-jane-doe-001",
  "timestamp": "2026-03-15T08:15:30.000Z",
  "payload": {
    "user": "jane.doe",
    "action": "AssumeRole",
    "event_source": "sts.amazonaws.com",
    "target_role": "ProductionAdmin",
    "role_arn": "arn:aws:iam::123456789012:role/ProductionAdmin",
    "session_name": "jane-doe-prod-session",
    "source_ip": "198.51.100.42",
    "region": "us-east-1",
    "mfa_authenticated": true,
    "read_only": false
  },
  "raw_metadata": {
    "platform_event_id": "evt-id-001",
    "event_version": "1.09",
    "user_identity_type": "IAMUser",
    "principal_id": "AIDAEXAMPLE123456",
    "user_arn": "arn:aws:iam::123456789012:user/jane.doe",
    "account_id": "123456789012",
    "user_name": "jane.doe",
    "mfa_authenticated": true,
    "event_source": "sts.amazonaws.com",
    "event_name": "AssumeRole",
    "aws_region": "us-east-1",
    "source_ip": "198.51.100.42",
    "user_agent": "aws-cli/2.15.0 Python/3.11.6",
    "role_arn": "arn:aws:iam::123456789012:role/ProductionAdmin",
    "role_session_name": "jane-doe-prod-session",
    "duration_seconds": 3600,
    "assumed_role_arn": "arn:aws:sts::123456789012:assumed-role/ProductionAdmin/jane-doe-prod-session",
    "event_type": "AwsApiCall",
    "management_event": true,
    "event_category": "Management",
    "read_only": false,
    "created_at": "2026-03-15T08:15:30.000Z",
    "source_platform": "aws_cloudtrail"
  },
  "platform_event_id": "evt-id-001",
  "platform_event_source": "AWS_CLOUDTRAIL_API"
}

How This Feeds TOTAL

Persona Building

CloudTrail events define a user’s cloud infrastructure behavior profile — which AWS services they interact with, what roles they assume, which regions they operate in, and what resources they access. This forms the cloud layer of each persona, establishing expected patterns for cloud operations tied to job function.

Anomaly Detection

TOTAL’s behavioral engine uses CloudTrail events to detect:

Role assumption anomalies — assuming production roles at unusual times, from unusual IPs, or without MFA when MFA is normally used
Privilege escalation — IAM policy attachments, role creations, or access key generations that expand a user’s cloud permissions
Data exfiltration indicators — unusual S3 GetObject patterns, bulk downloads, or access to buckets outside normal scope
Security control tampering — stopping CloudTrail logging, deleting trails, or modifying security group rules to open network access
Secrets access anomalies — retrieving secrets or KMS keys outside normal patterns, especially for production environments
Infrastructure manipulation — launching instances, modifying configurations, or creating resources in regions or accounts outside the user’s baseline

Breach Lifecycle Coverage

CloudTrail events provide primary coverage across Privilege Escalation and Siege stages. Similar to EDR, this is a high-fidelity signal that emerges later in the attack chain and validates earlier persona-based risk. When an attacker reaches the cloud infrastructure layer, CloudTrail captures the precise API calls that reveal their objectives — making it invaluable for confirming and attributing threats detected by upstream identity and behavioral signals.

INTEGRATIONS

​Overview

​Prerequisites

​Step 1: Choose Your Ingestion Method

​Step 2: Create an IAM Role for TOTAL

​Option A: Cross-Account IAM Role (Recommended)

​Option B: IAM User with Access Keys

​Custom IAM Policy (Least Privilege)

​Step 3: Configure S3 Bucket Access (If Using S3 Method)

​Step 4: Verify Connectivity

​Security & Privacy

​What We Access

​What We Don’t Have Access To

​Updating or Rotating Credentials

​Rotate Access Keys (If Using IAM User)

​Revoke Access

​Rate Limiting & Scalability

​AWS CloudTrail Rate Limits

​Lookup Events API

​S3 Bucket Ingestion (Recommended for Production)

​Ingestion Capacity

​Event Freshness

​Resilience

​Connector Design

​Part 2: Event Types & Data Schema

​Signal Classification

​Event Types We Ingest

​Console & Authentication Events

​IAM Events

​S3 Data Events (If Enabled)

​EC2 & Network Events

​Lambda & Serverless Events

​Secrets & Key Management Events

​CloudTrail & Logging Events

​Sample Source Event (CloudTrail — AssumeRole)

​TOTAL Normalized Event

​How This Feeds TOTAL

​Persona Building

​Anomaly Detection

​Breach Lifecycle Coverage