Reading an S3 bucket in another AWS account

Do you actually need this?

Probably not. Answer one question: Is the S3 bucket in the same AWS account as the credentials the agent uses?

Answer	What to do
Yes, same account	Stop here. Attach the read policy to that IAM user or EC2 instance role and you are done. No role, no `role_arn`.
No, the bucket is in a different account	Follow this page.

“The credentials the agent uses” means the account your access_key_id belongs to, or the account of the EC2 instance role if the agent runs on EC2 without keys.

These are two different settings.bucket_arn: which bucket to read. arn:aws:s3:::my-logs. Always required in bucket-polling mode.role_arn: an identity to assume. arn:aws:iam::123456789012:role/AtatusLogReader. Only on this page’s cross-account setup.

What Atatus configures in AWS: nothing

Worth stating plainly, because it differs from most SaaS integrations. The agent runs on your machine and reads your bucket. The role is assumed between two accounts you control, so there is no Atatus AWS account to trust and no Atatus-issued external ID, so you choose both sides. The only thing that reaches Atatus is the log data, authenticated with the license key already in atatus.yml.

Configured by	Where	What
You, in the bucket’s account	IAM	The role, its read policy, its trust policy
You, in the agent’s own account	IAM	`sts:AssumeRole` permission
You, on the agent machine	`conf.d/s3.d/s3.yml`	`role_arn`, `external_id`
Atatus	None	Nothing in AWS

How it works

The agent authenticates with whatever resolves first: the access keys in your config, or the EC2 instance role when there are none.
Those credentials are used for one call only: sts:AssumeRole.
AWS returns temporary credentials for the role.
Every S3 and SQS call is signed with those, and the agent refreshes them before they expire.

Nothing belonging to the bucket’s account is ever written to the agent machine. Access is revoked by editing the trust policy, not by rotating a key you hold.

Terminology used below

Two accounts, and it matters which is which:

Name here	Meaning
Bucket account	Owns the S3 bucket. The role is created here.
Agent account	Owns the credentials the agent authenticates with.

Get both IDs before you start:

# Run with the bucket account's credentials
aws sts get-caller-identity --query Account --output text

# Run on the agent machine, with the credentials it will use
aws sts get-caller-identity --query Account --output text

Pick an external ID too, which is any hard-to-guess string you invent, for example atatus-7f3c1b. It is not a secret AWS issues; it is a value you set on both sides.

Step 1: Read policy (bucket account)

What the role is allowed to do. Save as read-policy.json, replacing the bucket name:

{
  "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/*"
    }
  ]
}

Read-only: the agent never writes to your bucket and never deletes an object. Using SQS notifications instead of bucket polling? Add the queue actions:

{
  "Sid": "AtatusReadQueue",
  "Effect": "Allow",
  "Action": ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes"],
  "Resource": "arn:aws:sqs:us-east-1:123456789012:atatus-cloudtrail"
}

Step 2: Trust policy (bucket account)

Who is allowed to assume the role. This is the piece that is usually wrong when things fail. Save as trust-policy.json and put the agent account ID in Principal:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<agent_account_id>:root" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "atatus-7f3c1b" }
      }
    }
  ]
}

:root here does not mean the root user. It means “any principal in that account that has been granted sts:AssumeRole”, which is why Step 4 is also required. It is the normal way to write this.

Not using an external ID? Delete the whole Condition block and leave external_id out of the agent config too. Setting it on one side only makes the assume fail. To restrict further, condition on the session name the agent uses:

"Condition": {
  "StringEquals": {
    "sts:ExternalId": "atatus-7f3c1b",
    "sts:RoleSessionName": "atatus-infra-agent"
  }
}

Step 3: Create the role (bucket account)

aws iam create-role \
  --role-name AtatusLogReader \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy \
  --role-name AtatusLogReader \
  --policy-name AtatusReadLogs \
  --policy-document file://read-policy.json

The Arn in the output is your role_arn:

arn:aws:iam::999999999999:role/AtatusLogReader

Using the AWS console instead

IAM → Roles → Create role
Trusted entity type: AWS account → Another AWS account
Enter the agent account ID
Tick Require external ID and enter yours
Skip permissions for now → name it AtatusLogReader → Create role
Open the role → Add permissions → Create inline policy → JSON → paste the read policy from Step 1
Copy the ARN shown at the top of the role page

Step 4: Allow the assume (agent account)

The role trusts the account; now the identity inside it needs permission. Attach to the IAM user whose access key is in the config, or to the EC2 instance role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::999999999999:role/AtatusLogReader"
    }
  ]
}

aws iam put-user-policy \
  --user-name atatus-log-reader \
  --policy-name AtatusAssumeLogRole \
  --policy-document file://assume-policy.json

Step 5: Verify before touching the agent

Run this on the machine running the agent, with the credentials it will use. It should return a set of temporary credentials:

aws sts assume-role \
  --role-arn arn:aws:iam::999999999999:role/AtatusLogReader \
  --role-session-name atatus-test \
  --external-id atatus-7f3c1b

Then confirm the role can actually see the objects:

CREDS=$(aws sts assume-role \
  --role-arn arn:aws:iam::999999999999:role/AtatusLogReader \
  --role-session-name atatus-test \
  --external-id atatus-7f3c1b \
  --query Credentials --output json)

export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r .AccessKeyId)
export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r .SecretAccessKey)
export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r .SessionToken)

aws s3 ls s3://my-cloudtrail-logs/ --recursive | head -3

Open a new shell afterwards, or unset those three, so the rest of your session goes back to your own credentials. That last command also gives you the real key path for bucket_list_prefix, so copy it from the output rather than guessing.

Do not skip this step. If the assume fails, the agent reports it in its log and collects nothing, and that looks identical to “no logs have arrived yet”.

Step 6: Configure the agent

Add role_arn and external_id to the stanza in /etc/atatus-infra-agent/conf.d/s3.d/s3.yml:

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

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

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

The same two lines work for any family. VPC Flow Logs only differ in source: and the prefix:

s3:
  - source: vpc_flow
    region: "us-east-1"
    bucket_arn: "arn:aws:s3:::central-flow-logs"
    bucket_list_prefix: "AWSLogs/999999999999/vpcflowlogs/"

    role_arn: "arn:aws:iam::999999999999:role/AtatusLogReader"
    external_id: "atatus-7f3c1b"
    start_timestamp: "2026-08-20T00:00:00Z"

On EC2, leave the access keys out entirely. The instance role assumes the target role, and no long-lived key is ever written to disk. Just make sure Step 4 is attached to the instance role.

Note that bucket_list_prefix contains the bucket account ID, because that is whose logs are in the bucket.

sudo service atatus-infra-agent restart

Multiple accounts

One stanza per account, each with its own role. They collect in parallel:

s3:
  - source: cloudtrail
    region: "us-east-1"
    bucket_arn: "arn:aws:s3:::prod-cloudtrail-logs"
    role_arn: "arn:aws:iam::111111111111:role/AtatusLogReader"
    external_id: "atatus-7f3c1b"

  - source: cloudtrail
    region: "us-east-1"
    bucket_arn: "arn:aws:s3:::staging-cloudtrail-logs"
    role_arn: "arn:aws:iam::222222222222:role/AtatusLogReader"
    external_id: "atatus-9d2e4a"

An organisation trail writing every account into one bucket needs only a single stanza, and the account each event came from is preserved on the event itself.

Configuration reference

Setting	Required	Description
`role_arn`	No	Role to assume. Only for a bucket in another account
`external_id`	No	Shared secret, when the trust policy requires one
`access_key_id`	No	Identity that assumes the role. Omit on EC2
`secret_access_key`	No	Use with `access_key_id`

Setting external_id without role_arn is rejected at startup, because on its own it would be silently ignored.

Troubleshooting

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

Message	Cause	Fix
`AccessDenied` on `sts:AssumeRole`	The trust policy does not name the agent’s account	Check `Principal` in Step 2 is the agent account, not the bucket account
`AccessDenied` on `sts:AssumeRole`	External ID mismatch, or set on only one side	It must match exactly, or be absent from both
`AccessDenied` on `sts:AssumeRole`	Step 4 missing	Attach `sts:AssumeRole` in the agent’s account
`s3 listing failed` after a successful assume	The role’s own read policy is missing or names the wrong bucket	Check Step 1
`s3 listing matched no objects`	`bucket_list_prefix` does not match the real key path	Use the `aws s3 ls` output from Step 5

In the bucket owner’s CloudTrail, the agent’s assume appears with roleSessionName: atatus-infra-agent, which makes it easy to tell apart from anything else using the role.

​Do you actually need this?

​What Atatus configures in AWS: nothing

​How it works

​Terminology used below

​Step 1: Read policy (bucket account)

​Step 2: Trust policy (bucket account)

​Step 3: Create the role (bucket account)

​Step 4: Allow the assume (agent account)

​Step 5: Verify before touching the agent

​Step 6: Configure the agent

​Multiple accounts

​Configuration reference

​Troubleshooting

Do you actually need this?

What Atatus configures in AWS: nothing

How it works

Terminology used below

Step 1: Read policy (bucket account)

Step 2: Trust policy (bucket account)

Step 3: Create the role (bucket account)

Step 4: Allow the assume (agent account)

Step 5: Verify before touching the agent

Step 6: Configure the agent

Multiple accounts

Configuration reference

Troubleshooting