How it works
Aletheia builds its picture in four layers. Each one is useful on its own, and each one makes the next more precise.
1. Discovery
Section titled “1. Discovery”You connect an AWS account by creating a read-only IAM role. Aletheia assumes that role and runs a scan: it walks the supported resource types across the regions you care about and records what it finds.
Every scan produces a revision for each resource, so the inventory is a history rather than a snapshot. A resource that disappears is not deleted from Aletheia — it is marked as no longer present, which is what makes the change timeline meaningful.
2. Mapping
Section titled “2. Mapping”Discovery alone tells you what exists. Mapping tells you where it came from.
You connect a source control provider and point Aletheia at your Terraform state sources. It reads the state, parses the infrastructure-as-code in your repositories, and joins the two against the live inventory. Each resource then carries a management state:
| State | Meaning |
|---|---|
managed_synchronized |
Exactly one deployment unit’s state manages the resource |
unmanaged |
State coverage exists for the resource’s scope, but nothing claims this resource |
conflicting |
More than one deployment unit’s state claims the same resource |
managed_missing |
State claims a resource that discovery did not find |
unknown |
No state covers this resource’s scope, so management cannot be determined. The default |
The distinction between unmanaged and unknown matters. unmanaged is a
finding: Aletheia can see the state for that scope and this resource is not in it.
unknown is an absence of evidence: no state source covers that scope yet, so
nothing can be concluded. Adding the missing state source turns unknown into a
real answer.
Matches carry a confidence level and the evidence behind them, so a low-confidence match is visibly a guess rather than a fact. When Aletheia gets one wrong, you can correct it, and the correction is recorded as its own audit trail.
3. Ownership
Section titled “3. Ownership”Resources on their own are a flat list. Aletheia groups them into the structures your team actually uses:
- Applications — the deployable units you think in terms of.
- Environments — production, staging, and whatever else you run.
- Teams — the people accountable for them.
Membership can be declared explicitly or inferred from tags using inference rules. Inferred memberships stay marked as inferred until someone confirms them, so the difference between “we know” and “we guessed” survives.
4. Change
Section titled “4. Change”Two independent streams feed the change picture:
- AWS-side change is ingested from your account’s own change records, so a console edit made outside any pipeline still shows up.
- Pipeline-side change arrives from your CI. Your pipeline sends the plan it generated and the apply it ran, using an ingest token. Aletheia records what the plan intended and what the apply actually did.
Together these answer “what changed, where did it come from, and did anyone run it outside the pipeline”.
Where the AI fits
Section titled “Where the AI fits”The assistant reads the same data you can see and nothing else. It answers questions by calling the same read-only queries the product uses, and every answer carries citations back to the records it used. It cannot mutate anything, and it has no AWS access of its own. See Ask Aletheia.
Where to go next
Section titled “Where to go next”- Quickstart walks the first three layers end to end.
- Concepts and glossary defines each term precisely.