terraform-guard

AI-agent-native Terraform plan safety gate.

terraform-guard checks the JSON output of a Terraform/OpenTofu plan before apply and returns a deterministic verdict:

• allow: no dangerous change detected
• warn: risky change needs human review
• block: likely data loss, exposure, outage, or privilege blast radius

It is designed for the new failure mode: coding agents can now edit infrastructure and may try to run terraform apply. This tool gives agents, CI systems, and humans a machine-readable pre-apply stop sign.

Quick Start

pip install -e ".[dev]"
terraform plan -out=tf.plan
terraform show -json tf.plan > plan.json
terraform-guard check plan.json --pro --format text

Write PR/CI artifacts:

terraform-guard check plan.json --pro \
  --markdown-file terraform-guard.md \
  --sarif-file terraform-guard.sarif \
  --json-file terraform-guard.json

CI-friendly exit codes:

• 0: allow
• 1: parse/input error
• 2: warn when --fail-on warn
• 3: block

MCP

Run the local MCP server:

$terraform-guard-mcp

MCP tool:

• terraform_guard_check_plan(plan_json, ruleset)
• terraform_guard_list_rules(ruleset)

Local Pro mode is gated by TFGUARD_LICENSE_KEY. The current offline demo accepts keys beginning with TFG-PRO-; production licensing must replace this with signed offline licenses or marketplace verification.

GitHub Action

This repository includes a root action.yml for GitHub Action distribution:

- run: terraform plan -input=false -out=tf.plan
- run: terraform show -json tf.plan > tfplan.json
- uses: your-org/terraform-guard@v0
  with:
    plan-path: tfplan.json
    pro: "true"
    fail-on: block
    upload-sarif: "true"

Examples:

• docs/examples/github-action-plan-gate.yml
• docs/examples/github-action-apply-gate.yml
• docs/examples/gitlab-ci.yml
• docs/examples/atlantis.yaml

The action writes JSON, Markdown, and SARIF reports under terraform-guard-output/.

Apify

This repo includes an Apify Actor scaffold:

.actor/actor.json
.actor/input_schema.json
.actor/output_schema.json
.actor/openapi.json
.actor/pay_per_event.json
Dockerfile

The Actor supports two modes:

• normal Actor run: paste planJson, get a dataset/KV result
• Standby mode: exposes a Streamable HTTP MCP endpoint at /mcp

Pay-per-event hooks are wired for:

• terraform-plan-check
• terraform-pro-ruleset

Configure the same events in Apify Console when publishing.

Rules

Free rules:

ID	Severity	Check
TFG001	block	Database delete
TFG002	block	Stateful resource replacement
TFG003	warn	Newly introduced public ingress
TFG004	block	Network delete or replacement

Pro rules:

ID	Severity	Check
TFG005	block	Deletion protection disabled
TFG006	block	Database replacement by broad type match
TFG007	warn	Backup retention reduced
TFG008	warn	Wildcard or broad administrative IAM
TFG009	block	Load balancer removed or replaced
TFG010	block	Force-destroy storage bucket
TFG011	warn	Object storage made public
TFG012	block	Encryption at rest disabled
TFG013	block	Cryptographic key deleted or replaced
TFG014	warn	Database made publicly reachable

Recommended Product Lane

Do not position this as another static Terraform scanner. Checkov and Trivy already own broad IaC scanning.

The wedge is narrower and sharper:

pre-apply approval gate for AI-generated infrastructure changes.

Best distribution targets:

• local CLI and MCP for Cursor, Claude, Codex, VS Code, and other agents
• GitHub/GitLab CI gates with PR comments
• Atlantis, Spacelift, env0, and Terraform Cloud run-task integrations
• Apify as an agent marketplace and pay-per-event experiment

The moat should be low-false-positive plan risk scoring, repo/workspace baselines, approval evidence, and integrations in the actual apply path.

More detail:

• docs/CI_APPLY_PATH_INTEGRATIONS.md
• docs/MONETIZATION_AND_REGISTRATION.md
• docs/PRODUCT_STRATEGY.md

Development

pip install -e ".[dev]"
pytest
ruff check .

Privacy

The core scanner runs locally and does not call cloud APIs. Terraform plans can contain sensitive infrastructure metadata, so local CLI/MCP and self-hosted CI should be the primary enterprise deployment path. Hosted Apify runs are best for demo, marketplace discovery, and teams comfortable uploading plan JSON.