py-iam-expand

0.3.0 verified Fri May 01 auth: no python

A Python package to expand and deobfuscate AWS IAM policies. Resolves wildcards (*, ?) into the full set of matching IAM actions, can invert action sets, and handles obfuscated policies. Currently at v0.3.0, supporting Python 3.10 through 3.14. Release cadence is irregular.

pip install py-iam-expand

Common errors

error ModuleNotFoundError: No module named 'iam_expand' ↓

cause The package is installed as `py-iam-expand` but the import module is `iam_expand` (with underscore).

fix

Import as from iam_expand import expand_policy.

error AttributeError: module 'iam_expand' has no attribute 'expand_policy' ↓

cause Using old import path from version 0.1.0 or an outdated import (e.g., `iam_expand.expand_policies`).

fix

Use from iam_expand import expand_policy (singular).

error botocore.exceptions.DataNotFoundError: Unable to load data for: iam/2010-05-08/service-2 ↓

cause botocore data missing or cached version is incomplete; usually happens offline or in restricted environments.

fix

Install botocore with full data (usually comes with boto3) or ensure network access on first run.

Warnings

gotcha The library depends on botocore (via py-aws-actions). If you are offline or have a stale botocore cache, expansion may fail or return incomplete results. Ensure network access or a recent action cache. ↓

fix Run your script with internet access or pre-populate botocore's action data.

breaking In v0.1.0, the function `expand_policy` was named `expand_policies` (plural). The import path changed from `iam_expand_expand_policies` to `iam_expand.expand_policy`. ↓

fix Update imports to `from iam_expand import expand_policy`.

gotcha Non-valid actions (e.g., misspelled actions like `ec2:Describ`) can cause errors. By default, the library fails. You can change behaviour via `non_valid_action_behavior` parameter. ↓

fix Use `expand_policy(policy_str, non_valid_action_behavior='keep')` or `'remove'` to avoid failures.

Imports

expand_policy
```
from iam_expand import expand_policy
```
The main function to expand IAM policy JSON strings.
expand_actions
```
from iam_expand import expand_actions
```
Expands a list of action strings with wildcards.
invert_actions
```
from iam_expand import invert_actions
```
Returns the set of actions not matching given patterns.

Quickstart

Expand IAM policy JSON containing wildcards into the full set of actions.

from iam_expand import expand_policy

policy_json = '{"Effect":"Allow","Action":["ec2:*","s3:Get*"]}'
expanded = expand_policy(policy_json)
print(expanded)