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

# Amazon S3 and Security Lake

> Set up the AWS side of Wordsmith audit streaming to Amazon S3 or Amazon Security Lake.

> [!NOTE]
>
> **Preview.** To discuss access to audit streaming for your organisation, contact your Wordsmith account manager.

Wordsmith writes audit events into your AWS account by assuming an IAM role that you create. The role trusts the Wordsmith delivery role only with the external ID Wordsmith shows you, and it can write only under one prefix. Download the templates and scripts below from **Settings** > **Audit log** > **Streaming**.

## Amazon S3

1. In Wordsmith, start adding an **Amazon S3** destination. Copy the **Wordsmith role ARN** and the **external ID**.
2. Deploy `s3-destination.yaml` with CloudFormation. Enter those two values, your bucket name, an optional prefix, and the KMS key ARN if the bucket uses SSE-KMS.
3. Copy the stack's `RoleArn` output into Wordsmith, then verify and activate the destination.

Wordsmith writes data objects to `<prefix>/wordsmith/v1/dt=YYYY-MM-DD/` and one manifest per batch to `<prefix>/wordsmith/v1/_manifests/dt=YYYY-MM-DD/`. The manifest records the object's event count and SHA-256. The role allows `s3:PutObject` under `<prefix>/wordsmith/v1/` only. Wordsmith never reads objects back: each write is conditional, so a retry never overwrites data.

If the bucket is in a different account from the role, add a bucket policy statement that allows the role `s3:PutObject` on `arn:aws:s3:::<bucket>/<prefix>/wordsmith/v1/*`.

### Query with Athena

`athena/s3-jsonl-table.sql` creates a table over JSONL objects with partition projection, and a `wordsmith_audit_events` view that removes duplicate deliveries. The table reads only the `dt=` folders, so it never reads the manifests. `athena/s3-example-queries.sql` has queries for failed sign-ins, role changes, API key changes, export bursts and MCP tool failures.

## Amazon Security Lake

Security Lake takes one OCSF event class per custom source, so Wordsmith uses one custom source for each class it sends.

1. Deploy `security-lake-provider.yaml` in your Security Lake account and Region. It creates the role the AWS Glue crawler uses.
2. In Wordsmith, start adding an **Amazon Security Lake** destination and copy the **Wordsmith role ARN** and **external ID**.
3. With AWS CLI v2 and `jq`, run:

   ```bash theme={null}
   ./security-lake-setup.sh --region eu-west-1 \
     --wordsmith-role-arn <Wordsmith role ARN> \
     --external-id <external ID> \
     --crawler-role-arn <CrawlerRoleArn from step 1> \
     --output wordsmith-security-lake.json
   ```

   The script creates a custom source for each class Wordsmith sends: Account Change (3001), Authentication (3002), Entity Management (3004) and API Activity (6003). It limits each source's provider role to the Wordsmith role and external ID, and prints the settings under `wordsmith_config`.
4. In Wordsmith, enter the Region and account ID, then add each class with its source location and provider role from `wordsmith_config`. Each provider role can write only to its own source, so every class needs its own role. API Activity (6003) is required, because Wordsmith verifies the destination with it.
5. Verify and activate the destination.

`athena/security-lake-example-queries.sql` has example queries for the Wordsmith tables. Each source has its own Glue table; the script prints the table ARNs. If a table has no columns after the first delivery, run that source's Glue crawler: `aws glue start-crawler --name <source name>`.

## Related pages

* [List Audit Events](https://wordsmithai.mintlify.site/api-reference/audit/list-audit-events.md): the event fields each JSON line carries.
* [Microsoft Sentinel](https://wordsmithai.mintlify.site/siem/sentinel.md), [Splunk](https://wordsmithai.mintlify.site/siem/splunk.md) and [HTTPS receiver](https://wordsmithai.mintlify.site/siem/https.md): the other ways to collect the audit log.


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