Terraform Guardrail MCP

Source: Dev.to

Overview

• MCP server – exposes provider metadata and compliance checks.
• CLI – scans Terraform configs (.tf, .tfvars) and state files (.tfstate) for sensitive leaks and missing ephemeral = true flags.
• Web UI – quick uploads for scans and visual reports.
• Rules engine – focuses on ephemeral values, write‑only arguments, and secret hygiene.

Architecture

flowchart LR
    subgraph Interfaces
        CLI[CLI]
        MCP[MCP Server]
        WEB[Web UI]
    end

    subgraph Core
        SCAN[Compliance Engine]
        GEN[Snippet Generator]
    end

    REG[Terraform Registry]
    TF[Terraform CLI]

    CLI --> SCAN
    WEB --> SCAN
    MCP --> SCAN
    MCP --> GEN
    SCAN --> TF
    GEN --> REG
    MCP --> REG

flowchart TB
    INPUTS[Inputs: .tf, .tfvars, .tfstate] --> PARSE[Parse & Normalize]
    PARSE --> RULES[Apply Rules TG001‑TG005]
    RULES --> REPORT[Findings + Summary Report]
    REPORT --> OUTPUT[CLI JSON / UI Render / MCP Response]

Features

• Scan .tf and .tfvars for sensitive values and missing ephemeral = true.
• Scan .tfstate for leaked sensitive values.
• Retrieve provider metadata for AWS and Azure via the Terraform Registry.
• Generate Terraform snippets for common AWS/Azure resources.
• Schema‑aware validation (requires the Terraform CLI and an initialized workspace).
• Multi‑environment policies and OPA‑compatible output.
• Stack‑aware orchestration and drift detection.

Installation

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install the package (editable mode with dev extras)
pip install -e "[dev]"

Or install directly from PyPI:

pip install terraform-guardrail

• PyPI: (latest: 0.2.3)

Usage

CLI Scanning

# Scan a directory (default JSON output)
terraform-guardrail scan ./examples --format json

# Scan with a state file
terraform-guardrail scan ./examples --state ./examples/sample.tfstate

# Enable schema‑aware validation (requires Terraform CLI + initialized workspace)
terraform-guardrail scan ./examples --schema

Snippet Generation

terraform-guardrail generate aws aws_s3_bucket --name demo

MCP Server (STDIO)

terraform-guardrail mcp

Web UI

terraform-guardrail web

Visit and upload a Terraform file to view a compliance report.

Alternatively, run the Streamlit app:

streamlit run streamlit_app.py

Live demo:

Deployment Guide

1. Push the repository to GitHub.
2. Create a new Streamlit Cloud app.
3. Set the main file path to streamlit_app.py.
4. Deploy – Streamlit will install dependencies from requirements.txt.

For a detailed walkthrough, see docs/streamlit_cloud.md in the repository.

Release Checklist

• Update version in pyproject.toml.

• Update RELEASE_NOTES.md and CHANGELOG.md.

• Commit changes and push to main.

• Tag the release:

  git tag -a vX.Y.Z -m "vX.Y.Z"
  git push origin vX.Y.Z

• Verify that the GitHub Actions release workflow completes successfully.

The repository uses git‑cliff to generate CHANGELOG.md:

git cliff -o CHANGELOG.md
# or
make changelog

Additional make targets:

make release-dry VERSION=0.2.1   # dry‑run release
make version-bump VERSION=0.2.1 # bump version

Tools Overview

References

• GitHub repository:
• Architecture diagram (README):
• Wiki diagrams:
• GitHub releases:

---

MIT License