Skip to content
AletheiaAletheiaAletheia docs

What Aletheia reads

The CloudFormation template creates one IAM role. This page describes exactly what that role can and cannot do, so you can take it through a security review.

The shape of the access

Section titled “The shape of the access”

The role has three parts:

  1. A read-only managed policy covering the resource types Aletheia discovers.
  2. A narrowly scoped state-read policy — s3:GetObject and s3:GetObjectVersion, limited to the state locations you designate.
  3. An explicit deny that removes data-plane access the read-only policy would otherwise grant.

That third part is the one worth reading closely.

The explicit deny

Section titled “The explicit deny”

A broad AWS read-only policy grants more than infrastructure metadata: it can read the contents of your buckets, your secrets, and your parameter store. Aletheia does not need any of that, so the template denies it outright:

Denied Why
s3:GetObject, s3:GetObjectVersion Aletheia reads bucket configuration, never bucket contents. The narrow state-read policy re-grants this for the specific state objects you designate, and nothing else
secretsmanager:GetSecretValue Aletheia never reads secret values
ssm:GetParameter, ssm:GetParameters, ssm:GetParametersByPath Aletheia never reads parameter values
dynamodb:GetItem Aletheia reads table configuration, never table rows

An explicit Deny in IAM cannot be overridden by any Allow. So even if the read-only managed policy widens in a future AWS release, these stay closed.

Why there is no mutating access at all

Section titled “Why there is no mutating access at all”

The role grants no Create*, Update*, Delete*, Put*, or Run* action on any service. This is not a promise about how Aletheia behaves — it is a property of the role you created. A bug in Aletheia, or a compromise of Aletheia, still cannot modify your infrastructure, because the credentials it can obtain do not carry the permission.

How the role is assumed

Section titled “How the role is assumed”

The trust policy names Aletheia’s AWS account as principal and requires an external ID unique to your organization. Both conditions must hold.

The external ID is what prevents the confused deputy problem: knowing your role’s ARN is not enough to assume it, because the caller must also present a secret only you and Aletheia hold.

Aletheia holds no long-lived AWS credentials. It assumes the role for the duration of a scan and lets the temporary credentials expire.

CloudTrail

Section titled “CloudTrail”

The role also grants CloudTrail lookup, which is what populates the change timeline with changes made outside any pipeline. This reads event metadata — who called what, when — not the contents of any resource.

Where to go next

Section titled “Where to go next”