> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS CloudTrail

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)

1. Sign in to the [AWS Console](https://console.aws.amazon.com)
2. Navigate to **IAM** → **Roles** → **Create role**
3. Select **Another AWS account** as the trusted entity
4. Enter the TOTAL AWS Account ID (provided in the TruU Portal)
5. Check **Require external ID** and enter the External ID shown in the TruU Portal
6. Click **Next: Permissions**
7. Attach the following managed policy (or create a custom one — see below):
   * `CloudTrailReadOnlyAccess`
8. If using S3 ingestion, also attach:
   * A custom policy granting `s3:GetObject` and `s3:ListBucket` on your CloudTrail S3 bucket
9. Name the role: `TruU-TOTAL-CloudTrail-Reader`
10. Click **Create role**
11. Copy the **Role ARN** and paste it into the TruU Portal

### Option B: IAM User with Access Keys

1. Navigate to **IAM** → **Users** → **Create user**
2. Enter:
   * **Username**: `truu-total-cloudtrail`
3. Select **Programmatic access**
4. Attach the `CloudTrailReadOnlyAccess` policy (and S3 read policy if applicable)
5. Click **Create user**
6. Copy the **Access Key ID** and **Secret Access Key**
7. Paste them into the TruU Portal

### Custom IAM Policy (Least Privilege)

```json theme={null}
{
  "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)

1. 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
2. TOTAL will validate access by listing recent log files

***

## Step 4: Verify Connectivity

Once credentials are entered in the TruU Portal:

1. Click **Test Connection** — TOTAL will attempt to read recent CloudTrail events
2. If successful, you'll see a confirmation with the number of recent events and trails detected
3. 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)

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

### Revoke Access

To immediately remove TOTAL's access:

1. **Option A** — Disable in the TruU Portal
2. **Option B** — Delete or deactivate the IAM role/user in AWS
3. **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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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.