Skip to main content

INVENTORY IAM ROLES AND TRUST ACROSS AWS ACCOUNTS

This guide shows you how to record IAM roles, users, customer-managed policies and cross-account trust relationships for several AWS accounts with @webframp/aws/iam. The behavior only reads IAM. Nothing in the accounts changes.

Prerequisites

  • One AWS CLI profile per account, each with read access to IAM. This guide uses prod-readonly and staging-readonly (see Authenticate to AWS with SSO)
  • A Swamp repository

Pull the extension

swamp extension pull @webframp/aws/iam

The output looks like:

INF extension·pull: Pulling "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Extracted 30 files:

Define the inventory behavior

Create a behavior named iam-inventory of type @webframp/aws/iam (see Create and Run a Behavior). profiles is required and takes a list of profile names:

globalArguments:
  profiles:
    - prod-readonly
    - staging-readonly
  pathPrefix: /

To leave out AWS service-linked roles, set excludeServiceLinked to true. To skip AWS managed policies and record only customer-managed ones, set excludeAwsManagedPolicies to true. To limit discovery to one part of the IAM path tree, set pathPrefix to that path.

Run full discovery

swamp behavior run iam-inventory discover_all

This command runs discover_roles, discover_users and discover_policies against each profile, then discover_trust_map. It writes one roles, one users and one policies resource per account, and a trustMap resource built from the discovered roles.

Refresh one account

To re-scan a single account without changing the behavior, override profiles for one run:

swamp behavior run iam-inventory discover_roles --input 'profiles:json=["prod-readonly"]'

This command reads the roles in the prod-readonly account and writes a new roles resource for it. The trust map is built from the stored roles resources, so run the discover_trust_map method afterwards if you need it to include the refreshed roles.

Query the inventory

The roles, users, policies and trustMap resources are Swamp data. Search them with CEL expressions as shown in Query and Manage Data. For example, you can find roles trusted by outside accounts, or users whose access keys have not been used recently. The CEL Expressions reference lists the available fields and operators.

To check a fixed set of integration roles against expected policies, trust principals and external IDs, use @jentz/aws-iam-role-audit instead.