Amazon S3 and Security Lake

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

Preview. Audit streaming is available to organisations in the audit streaming pilot.

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:

   ./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: the event fields each JSON line carries.
• Microsoft Sentinel, Splunk and HTTPS receiver: the other ways to collect the audit log.