Metadata-Version: 2.4
Name: catrole
Version: 0.5.0
Summary: AWS IAM Role/Policy permission viewer — see what a role or policy can do
Author: Chowdhury Faizal Ahammed, Neal Dreher
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.28
Requires-Dist: rich>=13.0

# catrole

![](banner.svg)

**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

<img width="2016" height="1674" alt="image" src="https://github.com/user-attachments/assets/85121686-4a3f-484c-9eab-2d5f5c946738" />

---

## 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

```bash
pip3 install catrole
```

### From source

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

For development (editable install):

```bash
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

```bash
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

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

### 2. Scan a policy

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

```bash
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.

```bash
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.

```bash
# 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`.

```bash
# 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

```bash
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

```bash
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

```bash
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.
