Free AWS Security Whitepaper
    Toc Consulting Logo
    Back to all tools

    iam-to-english

    Read any AWS IAM policy in plain English, and catch privilege escalation before it ships.

    iam-to-english is a free, open-source CLI maintained by KloudSec. It reads an IAM policy (identity policy, role trust policy, S3 bucket policy) and tells you in plain English what it allows, who it allows, and what could go wrong: privilege escalation paths (including combinations across statements), public access, wildcard abuse and risky trust relationships. The analysis runs 100% offline and deterministically, works in CI as a quality gate, and can optionally ask an LLM for a deeper review (local Ollama, Amazon Bedrock, the Anthropic API or the OpenAI API).

    View on GitHub

    Features

    Readable

    • One plain-English sentence per statement
    • Actions, resources and conditions translated, with the raw value underneath
    • A single risk verdict: CRITICAL, HIGH, MEDIUM, LOW or CLEAN
    • Identity policies, role trust policies and S3 bucket policies

    Detection

    • 21 known privilege escalation paths, including combinations across statements
    • Honors NotAction, explicit Deny, iam:PassedToService and resource scoping
    • GitHub OIDC trust policies without a sub condition flagged as CRITICAL
    • Semantic --diff between two policy versions

    CI and Privacy

    • --fail-on gate with stable exit codes (0, 1, 2)
    • JSON and Markdown output, GitHub Action and pre-commit hook
    • No network calls unless you fetch from AWS or opt in to an AI review
    • MIT license, written in Python

    Installation & Usage

    Install (pipx, Python 3.10+)

    pipx install iam-to-english
iam-to-english --version

    Docker (amd64 and arm64)

    docker run --rm -v "$(pwd):/data:ro" kloudsecio/iam-to-english /data/policy.json

    Use It

    iam-to-english policy.json                                  # a local file (JSON or YAML)
iam-to-english arn:aws:iam::aws:policy/ReadOnlyAccess       # an AWS managed policy
iam-to-english s3://my-bucket                               # a bucket policy
iam-to-english old.json --diff new.json                     # what changed
iam-to-english policies/*.json --fail-on HIGH               # a CI gate

    GitHub Action

    - uses: kloudsec-io/iam-to-english@v1.0.0
  with:
    files: "policies/*.json"
    fail-on: HIGH

    CLI Options

    OptionDescription
    -f, --format [text|json|markdown]Output format (default: text)
    -d, --diff TEXTCompare the source against another policy (semantic diff)
    --fail-on [critical|high|medium|low]Exit 1 if findings meet or exceed this severity
    -v, --verboseShow step-by-step attack paths
    --aiAdd an AI review (default backend: Amazon Bedrock)
    --ollamaAI review with a local Ollama model
    --anthropicAI review with the Anthropic API, key in ANTHROPIC_API_KEY
    --openaiAI review with the OpenAI API, key in OPENAI_API_KEY

    Need Help Implementing?

    We can help you deploy and customize this tool for your specific needs, or build custom solutions.

    Contact Us