AWS CloudTrail - Atatus Docs

Overview

CloudTrail records every API call made in your AWS account. Atatus reads those records directly from the S3 bucket your trail already writes to, so there is nothing to change about how CloudTrail itself is configured. Once flowing, CloudTrail events are analysed by the built-in AWS detection rules, such as console logins without MFA, IAM policy changes, S3 bucket policy modifications, access-denied bursts, root account activity, and more.

Collection starts from the moment you set it up. Objects already in the bucket are not ingested, so a trail holding years of history costs you nothing.

Requirements

Component	Requirement
Agent	`atatus-infra-agent`
Version	4.3.0+
Runs on	One Linux machine that can reach AWS
AWS	A CloudTrail trail already delivering to an S3 bucket
Permissions	Read access to that bucket (see below)

Run the agent on one machine only. An EC2 instance is easiest, because it can use an instance role instead of long-lived access keys.

Collection modes

Choose one.

Mode	How it works	When to use
SQS notifications (recommended)	S3 tells an SQS queue whenever a new object lands; the agent consumes the queue	Preferred: the agent reacts immediately and never lists the bucket
Bucket polling	The agent lists the bucket on an interval	When you cannot create a queue

With SQS, a notification only exists for objects created after you set it up, so old logs are unreachable rather than filtered out.

Step 1: Create the SQS queue (Mode A only)

Skip this section if you are using bucket polling.

export REGION=us-east-1
export BUCKET=my-cloudtrail-logs
export ACCOUNT=123456789012

aws sqs create-queue --queue-name atatus-cloudtrail --region $REGION

Allow S3 to write to the queue. Save as queue-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "s3.amazonaws.com" },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:123456789012:atatus-cloudtrail",
      "Condition": {
        "ArnLike":      { "aws:SourceArn": "arn:aws:s3:::my-cloudtrail-logs" },
        "StringEquals": { "aws:SourceAccount": "123456789012" }
      }
    }
  ]
}

aws sqs set-queue-attributes \
  --queue-url https://sqs.$REGION.amazonaws.com/$ACCOUNT/atatus-cloudtrail \
  --attributes Policy="$(jq -c . queue-policy.json | jq -Rs .)" \
  --region $REGION

Then point the bucket at the queue. Save as notification.json:

{
  "QueueConfigurations": [
    {
      "QueueArn": "arn:aws:sqs:us-east-1:123456789012:atatus-cloudtrail",
      "Events": ["s3:ObjectCreated:*"]
    }
  ]
}

aws s3api put-bucket-notification-configuration \
  --bucket $BUCKET --notification-configuration file://notification.json

S3 sends a single s3:TestEvent message when the notification is created. The agent consumes and discards it, so no action is needed.

Step 2: Create the IAM policy

The agent needs read access to the bucket, plus queue access in Mode A.

Mode A: SQS notifications

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AtatusReadQueue",
      "Effect": "Allow",
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes"
      ],
      "Resource": "arn:aws:sqs:us-east-1:123456789012:atatus-cloudtrail"
    },
    {
      "Sid": "AtatusReadObjects",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-cloudtrail-logs/*"
    }
  ]
}

Mode B: bucket polling

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AtatusListBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-cloudtrail-logs"
    },
    {
      "Sid": "AtatusReadObjects",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-cloudtrail-logs/*"
    }
  ]
}

Replace the region, account ID and bucket name with your own. These policies are read-only, so the agent never writes to your bucket and never deletes an S3 object.

Attaching the policy

On EC2 (recommended): attach the policy to the instance role of the machine running the agent. Nothing else to configure; the agent picks the role up automatically. Anywhere else: create an IAM user, attach the policy, and generate an access key:

aws iam create-user --user-name atatus-cloudtrail-reader

aws iam put-user-policy \
  --user-name atatus-cloudtrail-reader \
  --policy-name AtatusCloudTrailRead \
  --policy-document file://policy.json

aws iam create-access-key --user-name atatus-cloudtrail-reader

Keep the AccessKeyId and SecretAccessKey from the output. You will need them in the next step.

Step 3: Configure the agent

Create /etc/atatus-infra-agent/conf.d/s3.d/s3.yml. One file covers every AWS log family delivered to S3, and source: picks the family. CloudTrail is shown here; VPC Flow Logs use the same file with source: vpc_flow.

The file must end in .yml. Files with any other extension are ignored without warning.

Mode A: SQS notifications

s3:
  - source: cloudtrail
    region: "<region>"
    queue_url: "<queue_url>"

    access_key_id: "<access_key_id>"
    secret_access_key: "<secret_access_key>"

Mode B: bucket polling

s3:
  - source: cloudtrail
    region: "<region>"
    bucket_arn: "<bucket_arn>"
    bucket_list_prefix: "<bucket_list_prefix>"
    bucket_list_interval: 5m
    number_of_workers: 5

    access_key_id: "<access_key_id>"
    secret_access_key: "<secret_access_key>"
    start_timestamp: "2026-08-01T00:00:00Z"

Filled in, that looks like:

s3:
  - source: cloudtrail
    region: "us-east-1"
    bucket_arn: "arn:aws:s3:::my-cloudtrail-logs"
    bucket_list_prefix: "AWSLogs/123456789012/CloudTrail/"
    bucket_list_interval: 5m
    number_of_workers: 5

    access_key_id: "AKIAIOSFODNN7EXAMPLE"
    secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    start_timestamp: "2026-08-01T00:00:00Z"

Check the real key path before setting bucket_list_prefix. If the trail was created with a custom S3 prefix, objects live under <prefix>/AWSLogs/<account>/CloudTrail/…, not AWSLogs/…. A prefix that matches nothing lists zero objects and reports no error, which looks exactly like “no logs yet”.Confirm with: aws s3 ls s3://my-cloudtrail-logs/ --recursive | head -3Leaving bucket_list_prefix out entirely reads the whole bucket, which always works but is slower on a large one.

Using access keys

If the machine has no instance role, add the credentials to the stanza:

s3:
  - source: cloudtrail
    region: "<region>"
    queue_url: "<queue_url>"

    access_key_id: "<access_key_id>"
    secret_access_key: "<secret_access_key>"

Omit both keys entirely to use the standard AWS credential chain: environment variables, shared config, then the EC2/ECS instance role. Where the agent runs inside AWS this is the better option, because it keeps long-lived keys off disk.

Reading a bucket in another AWS account

If the bucket belongs to a different AWS account than the credentials above, add a role instead of asking that account for a user key:

s3:
  - source: cloudtrail
    region: "us-east-1"
    bucket_arn: "arn:aws:s3:::central-security-logs"
    bucket_list_prefix: "AWSLogs/999999999999/CloudTrail/"

    role_arn: "arn:aws:iam::999999999999:role/AtatusLogReader"
    external_id: "atatus-7f3c1b"

The credentials above are then used for one call only (sts:AssumeRole), and everything else is read with the temporary credentials the role returns. See Reading an S3 bucket in another AWS account for the role, the two IAM policies, and how to verify it before restarting the agent.

Same account? You do not need a role. Attach the policy from Step 2 to your user or instance role and skip this.

Step 4: Restart and verify

sudo service atatus-infra-agent restart

Generate an event in AWS by signing in to the console or running any CLI command. CloudTrail delivers objects to S3 up to 15 minutes after the API call, so wait before concluding anything is wrong. Then open SIEM → Security Events in Atatus and filter on dataSource: cloudtrail.

Configuration reference

Setting	Required	Description
`source`	Yes	Log family: `cloudtrail` or `vpc_flow`
`region`	Yes	AWS region of the queue or bucket
`queue_url`	Mode A	SQS queue URL. Selects notification mode
`bucket_arn`	Mode B	Bucket ARN. Selects polling mode
`bucket_list_prefix`	No	Restrict polling to a key prefix
`bucket_list_interval`	No	How often to list the bucket. Default `120s`
`number_of_workers`	No	Parallel object readers. Default `5`
`visibility_timeout`	No	SQS visibility timeout. Default `300s`
`access_key_id`	No	Use with `secret_access_key`
`secret_access_key`	No	Use with `access_key_id`
`role_arn`	No	Assume this role and read with its temporary credentials
`external_id`	No	Shared secret when the role’s trust policy requires one
`start_timestamp`	No	Collect only objects newer than this (RFC3339)
`siem`	No	Set `false` to send to Logs instead of SIEM
`labels`	No	Extra key/value labels on every event

queue_url and bucket_arn are mutually exclusive, so set one, not both.

Send to Logs instead of SIEM

By default CloudTrail records become security events and run through the detection rules. To keep them as ordinary searchable logs instead:

s3:
  - source: cloudtrail
    region: "<region>"
    queue_url: "<queue_url>"
    siem: false

Same collection, different destination. You can run two stanzas (one per bucket or account) if some should go to SIEM and others to Logs.

How it behaves

Only new logs are collected. Collection begins when the agent first starts with this configuration. To deliberately backfill a known window, set start_timestamp: "2026-08-01T00:00:00Z".
Restarts are safe. The agent records which objects it has already sent, so restarting the agent or rebooting the machine never re-sends them.
Multiple accounts and regions in a single bucket are picked up automatically, so you do not list them.
Digest files (CloudTrail-Digest/) are skipped; they hold integrity metadata, not events.

Troubleshooting

Errors appear in the agent log at /var/log/atatus-infra-agent/.

Symptom	Likely cause	Fix
`s3 listing matched no objects`	`bucket_list_prefix` does not match the real key path, usually a missing custom trail prefix	Run `aws s3 ls s3://<bucket>/ --recursive \| head` and use the actual prefix
`s3 listing failed`	Missing `s3:ListBucket`, or wrong bucket ARN	Check the IAM policy and the ARN
`every listed object was filtered out`	`start_timestamp` is set later than the objects	Remove it, or move it earlier
`AccessDenied` from `sts:AssumeRole`	Trust policy does not name your account, or `external_id` does not match	Check both sides of the trust policy
Queue depth rising, no events	Missing `s3:GetObject`	Add it to the IAM policy
Queue depth rising, no messages consumed	Queue policy does not let S3 send	Re-check `SourceArn` and `SourceAccount`
Events arrive as logs, no detections	`siem: false` is set	Remove it

The agent logs first successful delivery once per endpoint when data first reaches Atatus. If you never see that line, the problem is upstream of the network, so check the listing and filter messages above.

​Overview

​Requirements

​Collection modes

​Step 1: Create the SQS queue (Mode A only)

​Step 2: Create the IAM policy

​Mode A: SQS notifications

​Mode B: bucket polling

​Attaching the policy

​Step 3: Configure the agent

​Mode A: SQS notifications

​Mode B: bucket polling

​Using access keys

​Reading a bucket in another AWS account

​Step 4: Restart and verify

​Configuration reference

​Send to Logs instead of SIEM

​How it behaves

​Troubleshooting

Overview

Requirements

Collection modes

Step 1: Create the SQS queue (Mode A only)

Step 2: Create the IAM policy

Mode A: SQS notifications

Mode B: bucket polling

Attaching the policy

Step 3: Configure the agent

Mode A: SQS notifications

Mode B: bucket polling

Using access keys

Reading a bucket in another AWS account

Step 4: Restart and verify

Configuration reference

Send to Logs instead of SIEM

How it behaves

Troubleshooting