kloudsecio/iam-to-english repository overview

$ iam-to-english examples/privilege-escalation.json
Policy: examples/privilege-escalation.json
2 statements | Services: IAM, Lambda
Risk: CRITICAL (1 privilege escalation path)

IN SHORT:
  #1 DeployLambdas: Can create Lambda functions, invoke Lambda functions and get Lambda function
      details, on all resources.
  #2 PassAnyRole: Can pass an IAM role to an AWS service, on all resources.

STATEMENT BY STATEMENT:

ALLOW #1 (DeployLambdas)
   Actions:
     - Create Lambda functions
       lambda:CreateFunction
     - Invoke Lambda functions
       lambda:InvokeFunction
     - Get Lambda function details
       lambda:GetFunction
   Resources:
     - All resources (no restriction)

ALLOW #2 (PassAnyRole)
   Actions:
     - Pass an IAM role to an AWS service
       iam:PassRole
   Resources:
     - All resources (no restriction)

PRIVILEGE ESCALATION PATHS (ways to gain more access than granted):

  [CRITICAL] PassRole + Lambda Code Execution
    Found in: Statement #1 (DeployLambdas), Statement #2 (PassAnyRole)
    Risk: Can pass a high-privilege IAM role to a new or modified Lambda function and invoke it to
      execute arbitrary commands.
    Permissions involved: iam:PassRole, lambda:CreateFunction, lambda:InvokeFunction
    How to fix: Restrict iam:PassRole using 'iam:PassedToService' condition to specific services and
      scope Resource to non-privileged roles.

  Run with --verbose to see the attack steps.

# pipx (recommended: isolated, puts iam-to-english on your PATH)
pipx install iam-to-english

# pip
pip install iam-to-english

# Upgrade
pipx upgrade iam-to-english            # or: pip install --upgrade iam-to-english

# Latest development version
pipx install git+https://github.com/kloudsec-io/iam-to-english

# From a clone (for contributors, see CONTRIBUTING.md)
git clone https://github.com/kloudsec-io/iam-to-english && cd iam-to-english
pip install -e ".[dev]"

iam-to-english policy.json              # JSON or YAML file
iam-to-english policy.yaml
iam-to-english policies/*.json          # several files at once (summary + combined exit code)
cat policy.json | iam-to-english -      # stdin
iam-to-english '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:GetObject","Resource":"*"}]}'

aws iam get-policy-version --policy-arn arn:aws:iam::123456789012:policy/MyPolicy --version-id v3 | iam-to-english -
aws iam get-role --role-name deploy | iam-to-english -          # the role's trust policy
aws s3api get-bucket-policy --bucket my-bucket | iam-to-english -

iam-to-english arn:aws:iam::aws:policy/ReadOnlyAccess -p myprofile   # managed policy (default version)
iam-to-english arn:aws:iam::123456789012:role/deploy                  # a role ARN = its trust policy
iam-to-english --role-name MyRole --trust-policy                      # same, by name
iam-to-english --role-name MyRole InlinePolicyName -p prod            # an inline role policy
iam-to-english s3://my-bucket                                         # a bucket policy

iam-to-english policy.json                 # colored text (plain when piped or NO_COLOR is set)
iam-to-english policy.json -v              # + step-by-step attack paths for escalation findings
iam-to-english policy.json -f json         # machine-readable, includes summary.risk_level
iam-to-english policy.json -f markdown     # for PR comments / GitHub job summaries

iam-to-english old-policy.json --diff new-policy.json

$ iam-to-english old.json --diff new.json
IAM Policy Diff: old.json -> new.json
=====================================

RISK INCREASED: MEDIUM -> CRITICAL

NEW PRIVILEGE ESCALATION PATHS:
  + [CRITICAL] PassRole + EC2 Instance Profile
    Risk: Can launch an EC2 instance with an existing privileged IAM instance profile and access credentials via IMDS.
    Permissions involved: iam:PassRole, ec2:RunInstances

Permissions Added (+):
  + Launch EC2 instances (ec2:RunInstances), on all resources
  + Pass an IAM role to an AWS service (iam:PassRole), on all resources

Permissions Removed (-):
  - Launch EC2 instances (ec2:RunInstances), on arn:aws:ec2:eu-west-1:123456789012:instance/*

Widened to All Resources (!):
  ! Launch EC2 instances (ec2:RunInstances) now applies to all resources

Deny Guardrails Removed (!):
  - Every IAM action (iam:*), on all resources

# Analyze a local file: mount the folder read-only at /data
docker run --rm -v "$(pwd):/data:ro" kloudsecio/iam-to-english /data/policy.json

# Options work as usual
docker run --rm -v "$(pwd):/data:ro" kloudsecio/iam-to-english /data/policy.json -f markdown --fail-on high

# Compare two versions
docker run --rm -v "$(pwd):/data:ro" kloudsecio/iam-to-english /data/old.json --diff /data/new.json

# From stdin (note -i)
cat policy.json | docker run --rm -i kloudsecio/iam-to-english -

# Inline JSON
docker run --rm kloudsecio/iam-to-english '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:GetObject","Resource":"*"}]}'

docker run --rm -v ~/.aws:/root/.aws:ro kloudsecio/iam-to-english \
  arn:aws:iam::aws:policy/ReadOnlyAccess -p myprofile

docker run --rm -v ~/.aws:/root/.aws:ro kloudsecio/iam-to-english \
  --role-name MyRole InlinePolicyName -p myprofile

docker run --rm -v ~/.aws:/root/.aws:ro kloudsecio/iam-to-english \
  s3://my-bucket -p myprofile

# Amazon Bedrock
docker run --rm -v "$(pwd):/data:ro" -v ~/.aws:/root/.aws:ro kloudsecio/iam-to-english \
  /data/policy.json --ai -p myprofile --ai-region eu-west-1

# Anthropic API (the key is passed by name, so it never appears in the command)
docker run --rm -v "$(pwd):/data:ro" -e ANTHROPIC_API_KEY kloudsecio/iam-to-english \
  /data/policy.json --anthropic

# Ollama running on your host: localhost inside the container is the container itself
docker run --rm -v "$(pwd):/data:ro" kloudsecio/iam-to-english \
  /data/policy.json --ollama --ollama-url http://host.docker.internal:11434

docker build -t iam-to-english .
docker run --rm iam-to-english --version

# .github/workflows/iam.yml
name: IAM policy review
on: pull_request
jobs:
  iam:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kloudsec-io/iam-to-english@main   # or pin a release tag / commit SHA
        with:
          files: "policies/*.json"
          fail-on: HIGH          # or CRITICAL / MEDIUM / LOW, or "" to never fail
          format: markdown       # rendered in the job summary

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/kloudsec-io/iam-to-english
    rev: main          # pre-commit recommends pinning a tag or commit SHA
    hooks:
      - id: iam-to-english
        # args: [--fail-on, CRITICAL]     # default is HIGH
        # files: ^infra/iam/.*\.json$     # default: files under iam/ or policies/, or named *policy*

pip install iam-to-english
iam-to-english policies/*.json --fail-on HIGH -f markdown > iam-report.md

export ANTHROPIC_API_KEY=...
iam-to-english policy.json --anthropic
iam-to-english policy.json --anthropic --ai-model claude-haiku-5-5     # faster, cheaper

export OPENAI_API_KEY=...
iam-to-english policy.json --openai
iam-to-english policy.json --openai --ai-model gpt-5-mini

iam-to-english policy.json --ai -p myprofile --ai-region eu-west-1
iam-to-english policy.json --ai --ai-model eu.anthropic.claude-sonnet-4-6 --ai-region eu-west-1

iam-to-english policy.json --ollama                       # picks an installed model automatically
iam-to-english policy.json --ollama --ai-model gemma3:4b

ollama serve
ollama pull gemma3:4b      # 3.3 GB -- best quality/size ratio for IAM analysis

Usage: iam-to-english [OPTIONS] [SOURCE]...

  -f, --format [text|json|markdown]  Output format (default: text)
  -d, --diff TEXT                    Compare SOURCE against another policy (semantic diff)
  --fail-on [critical|high|medium|low]
                                     Exit 1 if findings meet or exceed this severity
  -v, --verbose                      Show step-by-step attack paths
  -p, --profile TEXT                 AWS profile (for fetching policies from AWS)
  --role-name TEXT                   IAM role name (for inline or trust policies)
  --trust-policy                     Fetch the role's trust (assume role) policy
  --s3-bucket TEXT                   Fetch the bucket policy of this S3 bucket
  --ai                               Add an AI review (default backend: Amazon Bedrock)
  --ollama                           AI review with a local Ollama model (implies --ai)
  --anthropic                        AI review with the Anthropic API, key in ANTHROPIC_API_KEY
  --openai                           AI review with the OpenAI API, key in OPENAI_API_KEY
  --ollama-url TEXT                  Ollama API URL (default: http://localhost:11434)
  --ai-region TEXT                   AWS region for Bedrock (default: from your AWS profile)
  --ai-model TEXT                    Model for the chosen AI backend
  --ai-profile TEXT                  Separate AWS profile for Bedrock
  --no-color                         Disable colored output
  --no-warnings                      Hide warnings from the output (--fail-on still uses them)
  --version                          Show version
  -h, --help                         Show help

iam-to-english examples/s3-readonly.json               # clean, least-privilege
iam-to-english examples/dynamodb-policy.yaml           # YAML input
iam-to-english examples/complex-policy.json            # conditions, Deny, scoped PassRole (MEDIUM)
iam-to-english examples/privilege-escalation.json      # PassRole + Lambda (CRITICAL)
iam-to-english examples/overly-permissive.json         # full admin (CRITICAL)
iam-to-english examples/github-oidc-trust-policy.json  # any GitHub repo can assume the role
iam-to-english examples/public-bucket-policy.json      # public website bucket with TLS enforcement