readtheplan 0.3.0

Terraform plan risk explainer — reads `terraform plan` JSON and classifies each change as safe/review/dangerous/irreversible.

readtheplan

Read the plan. Every time. For real.

Terraform plan risk analysis for humans, CI pipelines, and AI agents. Classifies every change as safe, review, dangerous, or irreversible. Produces compliance evidence for SOC 2, ISO 27001, and HIPAA. Runs locally — no uploads, no accounts, no backend.

pip install readtheplan && readtheplan analyze plan.json

Website · Demo · Docs · Contributing

---

Why this exists

Terraform's plan/apply separation exists so a human reviews changes before they hit prod. In practice, nobody reads the 4,000-line text blob. Code diffs ≠ plan diffs. AI agents skip review. Compliance reviewers drown.

I reviewed hundreds of Terraform plans manually before building this. The same patterns kept killing us: a destroy+create that looked like an update, a KMS key rotation that nobody flagged, an IAM policy that quietly opened a bucket to the world. Every incident postmortem had the plan diff attached — and every one of them was reviewed and approved by a human who missed the signal.

Read the full story →

What it does

readtheplan reads terraform plan JSON and classifies each change:

🟢 safe — no-op, tag update, read-only change 🟡 review — security group rule change, minor config drift 🟠 dangerous — instance replacement, IAM policy change, database modification 🔴 irreversible — data deletion, KMS key destruction, RDS instance termination

It applies resource-aware rules (30+ AWS resource types), compliance framework mappings (SOC 2, ISO 27001, HIPAA), and produces auditable evidence envelopes with sigstore-backed signed attestations.

Comparison: readtheplan vs. everything else

Tool	Analyzes	Risk tiers	Compliance evidence	Agent gate	Local-only
readtheplan	Plan diff	✅ 4 tiers	✅ SOC2/ISO/HIPAA	✅ proceed/warn/block	✅
tflint	Code (HCL)	❌ lint only	❌	❌	✅
tfsec	Code (HCL)	❌ security only	❌	❌	✅
checkov	Code + plan	⚠️ pass/fail	⚠️ policy checks	❌	✅
Spacelift	Plan + state	⚠️ visual only	❌	⚠️ policy gates	❌ SaaS
env0	Plan + state	⚠️ visual only	❌	❌	❌ SaaS
Snyk IaC	Code (HCL)	❌ security only	❌	❌	❌ SaaS
infracost	Plan diff	❌ cost only	❌	❌	❌ SaaS
OPA/Sentinel	Policy engine	⚠️ rule-based	⚠️	⚠️ policy gates	✅

readtheplan is the only tool that: classifies plan diffs by blast radius risk tier, annotates with compliance controls, produces auditable evidence envelopes, gates CI pipelines and AI agents, and runs entirely locally with no SaaS dependency.

Quickstart

CLI — 30 seconds to first result

# Install
pip install readtheplan

# Generate a plan
terraform plan -out=tfplan -input=false
terraform show -json tfplan > plan.json

# Analyze it
readtheplan analyze plan.json

# With compliance framework
readtheplan analyze --framework soc2 plan.json

# Machine-readable JSON
readtheplan analyze --format json plan.json

GitHub Action — gate your CI pipeline

- name: Analyze Terraform plan
  uses: readtheplan/readtheplan@v1
  with:
    plan-file: plan.json

Full GitHub Actions workflow →

AI agent gate — block unsafe auto-approvals

readtheplan agent-gate plan.json
# → {"decision": "block", "risk": "irreversible", ...}

Use this in your CI or coding agent pipeline to enforce human review on dangerous changes.

Features

• CLI-first — single pip install, runs anywhere Python runs
• GitHub Action — copy-paste into any workflow
• Resource-aware rules — 30+ AWS resource types: KMS, IAM, RDS, S3, EKS, Lambda, networking, etc.
• Compliance evidence — SOC 2, ISO 27001, HIPAA control mappings with signed JSON envelopes
• Agent gate — deterministic proceed/warn/block decisions for CI and AI agents
• Customer rule overlays — org-specific risk escalations via YAML, no code changes needed
• MCP preview — local stdio tools for agent and IDE integrations
• No uploads — your Terraform plan JSON never leaves your machine
• MIT licensed — use it anywhere, no strings attached

What's not in scope

• Multi-cloud beyond AWS (Terraform/OpenTofu only for now)
• SaaS dashboard (local-first by design)
• Policy-as-code engine (OPA/Sentinel exist for that)
• Competing with Spacelift/env0 on overlapping features

Documentation

• Website — setup generator, live demo, intake
• Docs — tutorials, API reference, examples
• examples/ — sample plans with rendered output
• docs/adr/ — architecture decision records
• Corpus feedback loop — scan real plans, improve rules

Contributing

Contributions are welcome! See CONTRIBUTING.md for:

• Development environment setup
• How to run tests
• What makes a good first issue
• PR review process
• AI assistance disclosure policy

Good first issues are tagged good first issue.

Status

v0.3 — stable CLI + GitHub Action. The PyPI package ships the Python CLI and composite GitHub Action. Current main includes: resource-aware AWS risk rules, compliance framework annotations, evidence envelopes, signed attestation verification, customer rule overlays, MCP preview, examples, benchmarks, and the static onboarding site.

What's shipping next: in-browser plan playground (upload your plan, see results instantly), CloudFormation/Pulumi adapters, PCI-DSS and NIST 800-53 catalogs, expanded AWS resource coverage.

License

MIT — see LICENSE.

Author

@texasich — OSS contributions welcome.