catrole 0.5.0

AWS IAM Role/Policy permission viewer — see what a role or policy can do

catrole

AWS IAM visibility tool — inspect roles, policies, users, groups, and AWS Identity Center permission sets across your entire AWS Organization, from one command line.

catrole flattens IAM policy documents into readable, greppable rows, exposes role trust relationships, and searches every account in your org in parallel — so IAM engineers can answer "who can do what, and where?" without clicking through the console.

---

Features

• Role scan — trust policy (who can assume the role, under what conditions), metadata, tags, permissions boundary, and every attached managed + inline policy flattened into individual permission rows.
• Policy scan — all statements of a customer-managed or AWS-managed policy, flattened.
• ARN scan — pass a full role/policy ARN; the account ID is extracted automatically.
• User scan — access keys with last-used data, MFA devices, group memberships, direct permissions, and group-inherited permissions shown per group.
• Group scan — members plus all attached and inline permissions.
• Identity Center permission-set scan — managed/customer-managed/inline policies and every account/principal assignment, with principal IDs resolved to human-readable names.
• Org-wide name search — wildcard search for roles, policies, users, groups, and IDC permission sets across every active account, run in parallel.
• Org-wide action search — find every role that grants a given IAM action (e.g. s3:DeleteBucket), one fast GetAccountAuthorizationDetails sweep per account.
• Cross-account by design — every call runs through an STS-assumed role in the target account.
• Audit-ready output — colour-coded Rich tables in the terminal, plus a timestamped CSV written on every run.

Architectural Diagram

---

Requirements

• Python >= 3.11
• AWS credentials configured (via ~/.aws/credentials, environment variables, or SSO)
• A cross-account IAM role you can assume in the target account(s)

Installation

From PyPI

pip3 install catrole

From source

git clone https://github.com/RajChowdhury240/catrole.git
cd catrole
pip3 install .

For development (editable install):

pip3 install -e .

---

How it works

catrole uses -R to specify an IAM role to assume in the target account via STS. All API calls are made using the temporary credentials from that assumed role (1-hour session).

If -R is not provided, catrole reads the role name from ~/.catrole.

Setting a default assume role

echo "readonly-role" > ~/.catrole

Once set, you can omit -R from all commands. -R on the command line always takes precedence over ~/.catrole.

---

Required IAM permissions

The role you assume with -R only ever needs read-only access. The simplest setup is to attach the AWS managed ReadOnlyAccess policy (or SecurityAudit) to that role.

If you prefer a least-privilege policy, the assumed role needs:

Mode	Required actions
Role / policy / user / group scan	iam:Get*, iam:List* (incl. iam:ListRoleTags)
Action search (-f)	iam:GetAccountAuthorizationDetails
Org-wide modes (-s, -f without -a)	organizations:ListAccounts, organizations:DescribeAccount
Identity Center modes (-P, -s -idc)	sso:ListInstances, sso:ListPermissionSets, sso:DescribePermissionSet, sso:List* policy/assignment reads, identitystore:DescribeUser, identitystore:DescribeGroup

In addition, the trust policy of the -R role must allow your principal to assume it.

---

Modes

1. Scan a role

Shows a complete profile for an IAM role:

• Role metadata (ARN, Role ID, path, creation date, max session duration, permissions boundary, tags)
• Trust policy — every statement of the AssumeRolePolicyDocument, broken out by Effect, Principal, Action, and Condition, so you can see exactly who (and under what conditions) can assume the role
• All attached (managed + inline) policies, flattened into individual permission rows

catrole -R readonly-role -a 123456789012 -r AppRole

2. Scan a policy

Shows all statements in a customer-managed or AWS-managed policy.

catrole -R readonly-role -a 123456789012 -p MyPolicy

3. Scan by ARN

Directly specify the full ARN of a role or policy — account ID is extracted automatically.

catrole -R readonly-role -A arn:aws:iam::123456789012:role/AppRole
catrole -R readonly-role -A arn:aws:iam::123456789012:policy/MyPolicy

4. Search by name pattern across accounts

Wildcard search across all active accounts in the AWS Organization (or scope to one account with -a).

By default -s searches roles and policies. Add type-filter flags to restrict the search to specific entity types — each flag is used without a value in search mode:

Filter flag	Searches
-r	IAM roles
-p	IAM customer-managed policies
-u	IAM users
-g	IAM groups
-idc	AWS Identity Center permission sets (uses --region)

If any filter flag is supplied, the search is restricted to those type(s). If none are supplied, the default scope (roles + policies) applies.

# Default: roles + policies, org-wide
catrole -R readonly-role -s '*lambda*'

# Roles only
catrole -R readonly-role -s '*admin*' -r

# Users only
catrole -R readonly-role -s '*admin*' -u

# Groups only
catrole -R readonly-role -s '*dev*' -g

# IDC permission sets (specify the region of your IDC instance)
catrole -R readonly-role -s '*PowerUser*' -idc --region us-east-1

# Combine filters
catrole -R readonly-role -s '*admin*' -r -u -g

# Scope to a single account
catrole -R readonly-role -s '*admin*' -a 123456789012 -r -u

Wildcards: * matches any sequence of characters, ? matches a single character. Name matching is case-sensitive.

Role results include each matched role's tags (key=value), shown in the table and the CSV — useful for spotting ownership, environment, or cost-allocation metadata across the org.

Note: IDC permission-set search only returns results in accounts where an Identity Center instance is discoverable (typically your management or delegated-admin account). Other accounts are silently skipped.

5. Find roles by IAM action

Search for roles whose policies grant a specific IAM action. Supports wildcards. Searches all org accounts, or a single account with -a.

# Find all roles that can create S3 buckets
catrole -R readonly-role -f 's3:CreateBucket'

# Find all roles with any S3 permission
catrole -R readonly-role -f 's3:*'

# Scope to a single account
catrole -R readonly-role -f 's3:*' -a 123456789012

Matching is bidirectional: a policy with s3:* matches a search for s3:CreateBucket, and a search for s3:* matches a policy with a specific action like s3:PutObject. Matching is case-insensitive.

Each account is swept with a single iam:GetAccountAuthorizationDetails call instead of one API call per role and policy — fast and throttle-friendly even on large accounts. Both Allow and Deny rows that match are reported, so review the Effect column rather than assuming every hit is granted access.

6. Scan an IAM user

Shows a complete profile for an IAM user including:

• User metadata (ARN, User ID, path, creation date, password last used)
• Access keys — Key ID, status (Active/Inactive), creation date, last used date, region, and service
• MFA devices — serial number and enabled date (warns if no MFA is configured)
• Group memberships
• Direct permissions — all attached managed and inline policies directly on the user
• Group-inherited permissions — policies from every group the user belongs to, shown per group

catrole -R readonly-role -a 123456789012 -u john.doe

The CSV export includes a Source column indicating whether each permission row comes from Direct attachment or a specific Group:<name>.

7. Scan an IAM group

Shows a complete profile for an IAM group including:

• Group metadata (ARN, Group ID, path, creation date)
• All members (user name, ARN, creation date)
• All permissions — attached managed and inline policies, flattened into individual rows

catrole -R readonly-role -a 123456789012 -g MyDevGroup

8. Scan an AWS Identity Center permission set

Shows a complete profile for an IDC permission set including:

• Permission set metadata (ARN, instance ARN, identity store ID, description, session duration, relay state)
• AWS managed policies attached to the permission set
• Customer managed policy references
• Inline policy (pretty-printed JSON)
• All provisioned accounts and principal assignments — every user and group assigned to the permission set across all provisioned accounts, with names resolved via the Identity Store

catrole -R readonly-role -a 123456789012 -P MyPermissionSet --region us-east-1

--region is required when your Identity Center instance is not in your shell's default AWS region. The sso-admin and identitystore APIs are regional and must target the region where IDC was set up (commonly us-east-1).

---

Output

Every scan prints a colour-coded Rich table to the terminal and automatically saves results to a timestamped CSV file in the current directory.

Mode	CSV filename pattern
Role	iam-role_<account>_<name>_<ts>.csv
Policy	iam-policy_<account>_<name>_<ts>.csv
Search	iam-search_<pattern>_<ts>.csv
Action search	iam-action-search_<pattern>_<ts>.csv
User	iam-user_<account>_<name>_<ts>.csv
Group	iam-group_<account>_<name>_<ts>.csv
Permission Set	idc-permset_<account>_<name>_<ts>.csv

---

All flags

  -R, --assume-role ROLE      IAM role to assume in target account(s) (or set via ~/.catrole)
  -a, --account ACCOUNT       AWS account ID (12 digits)
  -r, --role ROLE             With a value: scan IAM role by name (requires -a).
                              With -s and no value: filter search to roles.
  -p, --policy POLICY         With a value: scan IAM policy by name (requires -a).
                              With -s and no value: filter search to policies.
  -u, --user USER             With a value: scan IAM user by name (requires -a).
                              With -s and no value: filter search to users.
  -g, --group GROUP           With a value: scan IAM group by name (requires -a).
                              With -s and no value: filter search to groups.
  -A, --arn ARN               Full ARN of an IAM role or policy
  -s, --search PATTERN        Wildcard pattern to search across the org. Default scope: roles+policies.
                              Add -r/-p/-u/-g/-idc (no value) to filter type(s). Combine with -a
                              to scope to a single account.
  -f, --find-action ACTION    IAM action pattern to find in role policies across the org
  -P, --permission-set NAME   IDC permission set name to scan (requires -a, uses --region)
  -idc, --idc                 With -s: filter search to AWS Identity Center permission sets
      --region REGION         AWS region for Identity Center (required with -P, or with -s -idc,
                              if your IDC instance is not in your default region)
  -v, --version               Show version and exit
  -h, --help                  Show help and exit

Run catrole -h for full help.