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

# AWS CloudTrail

> Connect your AWS account so Sazabi can subscribe to your trail's CloudWatch Logs group and stream CloudTrail events in real time.

[All AWS integration capabilities](https://docs.sazabi.com/catalogs/integrations/aws)

## About

AWS CloudTrail records every API call made in your AWS accounts: who made it, from which IP address, against which service, and whether it succeeded. Sazabi reads CloudTrail through the trail's CloudWatch Logs delivery. Connect your AWS account, pick the trail's log group, and Sazabi sets up a CloudWatch subscription filter on it, using the same cross-account IAM role as the [CloudWatch log source](https://docs.sazabi.com/catalogs/log-sources/connect-your-account/cloudwatch.md).

Each event keeps CloudTrail's own JSON, so the fields detections key on stay searchable: `eventName`, `eventSource`, `userIdentity`, `sourceIPAddress`, `errorCode`, `recipientAccountId`, `awsRegion`, `eventTime`, `eventCategory`, and `readOnly`.

Reading trails straight from their S3 bucket is not available yet; use CloudWatch Logs delivery.

To keep every AWS credential on your side, run your own OpenTelemetry Collector against the log group instead; see [AWS CloudTrail (send to an endpoint)](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/cloudtrail.md).

## Prerequisites

* A CloudTrail trail with CloudWatch Logs delivery turned on. An organization trail delivers every member account's events to one log group in the management (or delegated administrator) account.
* The trail's log group is in the same AWS region as your Sazabi project.
* Permission to create an IAM role in the account that owns the log group (`iam:CreateRole`, `iam:PutRolePolicy`).

### Turn on CloudWatch Logs delivery

Check whether your trail already delivers to CloudWatch Logs:

```bash theme={"system"}
aws cloudtrail describe-trails --query 'trailList[].{name:Name,org:IsOrganizationTrail,logGroup:CloudWatchLogsLogGroupArn}' --output table
```

If `logGroup` is empty, open the trail in the CloudTrail console, choose **CloudWatch Logs > Edit**, turn it on, and let the console create the log group and its delivery role. New events reach the log group within about five minutes.

## Set up in the dashboard

**Step 1**

### Create the IAM role

Go to [**Settings > Log streams**](https://app.sazabi.com/settings/log-source-providers), click **Add source**, and select **AWS CloudTrail**. Create the IAM role with CloudFormation, Terraform, or the AWS CLI; all three produce the same role, and the snippets embed the Sazabi account ID and the external ID for your project.

**Step 2**

### Enter the role ARN

Paste the role ARN into the dashboard and click **Connect**. Sazabi validates that it can assume the role using your project's external ID.

**Step 3**

### Pick the trail's log group

Click **Add log stream** and select the log group your trail delivers to (often named `aws-cloudtrail-logs-*` or `/aws/cloudtrail/*`). Sazabi installs a subscription filter on it.

## Set up with the CLI

Create the native connection in the dashboard, since the IAM role's trust policy must reference the external ID the setup form generates. Then manage the source with the [Sazabi CLI](https://docs.sazabi.com/reference/cli/log-sources.md):

```bash theme={"system"}
sazabi log-sources list --provider cloudtrail    # Find the CloudTrail log source ID
sazabi log-sources get <log-source-id>            # Log source details and its log streams
sazabi log-sources disable <log-source-id>        # Pause ingestion for its log streams
sazabi log-sources enable <log-source-id>         # Resume ingestion
```

## Verify

Make an AWS API call, for example `aws sts get-caller-identity`. Open the [Intake page](https://docs.sazabi.com/guides/instrument/intake.md) and confirm records attributed to the **AWS CloudTrail** source appear. CloudTrail delivers to CloudWatch Logs within about five minutes, and the subscription filter forwards each event within a minute or two after that.

## Troubleshooting

**No log groups listed** — Sazabi only lists log groups in your project's region. Check the trail's log group region, or create a Sazabi project in that region.

**"Access denied" on `sts:AssumeRole`** — The role's trust policy must allow the Sazabi AWS account ID shown in the setup form, with the matching `sts:ExternalId` condition.

**"Subscription filter quota exceeded"** — CloudWatch allows at most two subscription filters per log group. Remove one before adding the log stream in Sazabi.

**Events stop arriving** — Confirm the trail is still logging (`aws cloudtrail get-trail-status --name <trail>`), its CloudWatch Logs delivery is still set, and the subscription filter still exists on the log group.

## Further reading

> [card] [AWS CloudWatch](https://docs.sazabi.com/catalogs/log-sources/connect-your-account/cloudwatch.md)
>
> Forward any CloudWatch log group with the same IAM role.

> [card] [Log sources](https://docs.sazabi.com/catalogs/log-sources.md)
>
> Browse the full log source catalog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.