The IAM Permissions Agent: Tightly Scoped Investigations

IAM debugging is plumbing. The agent that walks a request through the permission graph and explains the decision in two paragraphs.

Walk the permission graph

The agent walks the permission graph deterministically. Input: an ARN, an action, a resource. Question: should this combination be allowed; if yes by what path; if no, what is missing. Walk identity policy, group policy, role policy, resource policy, SCP; output an explicit allow or deny path, never “unsure”.

• Three-input question. ARN, action, resource; the bounded query.
• Walk five policy layers. Identity, group, role, resource, SCP; deterministic order.
• Explicit allow or deny path. Never “unsure”; deterministic walk produces deterministic answer.
• Per-decision audit trail. The walk is reproducible; supports investigation and review.

Explain in two paragraphs

Output is two paragraphs. Paragraph one: the answer (allowed or denied) and the controlling policy. Paragraph two: how to change the answer (which policy to modify, which statement to add or remove); the change is always shown as a diff so the human can apply it directly.

• Paragraph one: the answer. Allowed or denied; controlling policy named.
• Paragraph two: the change. Which policy to modify; which statement to add or remove.
• Always as diff. The proposed change is reviewable text; humans apply it.
• Per-explanation reproducibility. Re-running the agent on the same inputs produces the same explanation.

What it catches that humans miss

The agent catches the cases humans confuse. SCPs that quietly deny what an identity policy would otherwise allow; resource policies that allow access not granted by identity policies; permission boundaries that limit max-permission below role; implicit deny vs explicit deny because the difference matters for IAM debugging and is often confused.

• SCP silent denies. Identity policy allows but SCP denies; the override is silent without the walk.
• Resource policy grants. Identity policy denies but resource policy grants; access exists where humans don’t expect.
• Permission boundaries. Limit max-permission below role; the boundary is the surprise.
• Implicit vs explicit deny. The difference matters for debugging; humans confuse the two.

Safety considerations

The agent is read-only by design. The agent never proposes changes; it explains the current state. The proposed-diff in the explanation is just text and humans implement it; the agent does not have IAM-write capability. The agent’s analysis is logged for audit so “why was this access granted” is reproducible from the audit trail.

• Read-only by design. Agent explains current state; never proposes changes directly.
• Diff is just text. Humans implement; agent has no IAM-write capability.
• Audit-logged analysis. “Why was this access granted?” reproducible from the trail.
• Per-query logged decision. Each agent decision captured; supports compliance review.

Eval cases

Four eval cases cover most permission patterns. Standard allow: identity policy allows; agent confirms. Standard deny: no policy grants; agent confirms. SCP override: identity policy allows but SCP denies; agent identifies the SCP. Resource-policy: identity policy denies but resource policy grants; agent identifies the resource policy.

• Standard allow. Identity policy allows; agent confirms.
• Standard deny. No policy grants; agent confirms; the negative case.
• SCP override. Identity allows, SCP denies; agent identifies the SCP.
• Resource-policy override. Identity denies, resource grants; agent identifies the resource policy.