TF Approval Gate

Ein MCP-Server, der es KI-Codierungsagenten (Claude Code, Cursor usw.) ermöglicht, Terraform-Änderungen zu planen, auf Richtlinienkonformität zu prüfen und Kosten zu schätzen – es aber strukturell unmöglich macht, dass der Agent terraform apply ausführt, ohne dass zuvor ein echter Mensch in Slack auf „Genehmigen" klickt.

Warum

KI-Agenten können heute Terraform direkt gegen echte Cloud-Konten schreiben und ausführen. Ein Agent, der eigenständig terraform apply ausführen kann, kann Produktionsinfrastruktur stillschweigend zerstören oder falsch konfigurieren – ohne dass ein Mensch im Loop ist. TF Approval Gate schließt diese Lücke: Jedes apply erfordert ein signiertes, einmalig verwendbares Token, das nur ein echter Mensch per Slack-Klick (oder im Dev-Modus ein echter Mensch am Terminal) ausstellen kann. Die Behauptung des Agenten, „der Mensch habe genehmigt", wird niemals vertraut – der Server verifiziert alles selbst erneut.

Related MCP server: Hivelore

So funktioniert es

1. Der Agent bearbeitet .tf-Dateien und ruft dann tf_propose_change auf – führt terraform plan, Checkov (+ OPA, falls konfiguriert) und Infracost (falls konfiguriert) aus und liefert einen gebündelten Vorschlag mit einer Empfehlung safe/needs_review/blocked zurück.

2. Der Agent ruft tf_request_approval auf – postet den Diff + Richtlinienbefunde + Kosten mit Genehmigen/Ablehnen-Buttons nach Slack (oder zeigt im APPROVAL_MODE=cli eine Eingabeaufforderung im Terminal des Servers an). Weigert sich, überhaupt zu posten, wenn Richtlinienbefunde blockierend sind.

3. Der Agent pollt tf_check_approval_status.

4. Ein Mensch klickt auf Genehmigen → der Server verifiziert, dass der Klick von einem auf der Whitelist stehenden Slack-Benutzer stammt, und stellt ein signiertes, einmalig verwendbares Token aus, das an den exakten Prüfsummenwert dieses Plans gebunden ist.

5. Der Agent ruft tf_apply mit dem Token auf. Der Server überprüft erneut Signatur, Ablauf, Einmalverwendungsstatus, die binäre Prüfsumme des Plans und prüft auf Cloud-seitige Drift – erst dann führt er terraform apply aus.

Siehe docs/architecture.md und docs/security-model.md für das vollständige Design und das Bedrohungsmodell.

Schnellstart (lokal, keine Slack-Einrichtung erforderlich)

git clone https://github.com/SORABH13/tf-approval-gate.git
cd tf-approval-gate
npm install
npm run build
npm run check-binaries   # confirms terraform + checkov are on PATH

Erfordert Terraform und Checkov auf dem PATH. OPA/Conftest und Infracost sind optional (Funktionen werden übersprungen, wenn sie fehlen). Oder überspringen Sie die Installation komplett und verwenden Sie das Docker-Image unten, das alle drei bündelt.

Führen Sie es im Dev-Modus aus (APPROVAL_MODE=cli gibt den Diff im Terminal des Servers aus und wartet auf eine j/n-Eingabe, anstatt nach Slack zu posten – gut für einen ersten lokalen Test, aber eine schwächere Garantie als Slack, siehe docs/security-model.md):

APPROVAL_MODE=cli TF_APPROVAL_GATE_SECRET=$(openssl rand -hex 32) npm start

Fügen Sie es dann als MCP-Server in Claude Code (oder einen beliebigen MCP-Client) hinzu:

{
  "mcpServers": {
    "tf-approval-gate": {
      "command": "node",
      "args": ["/absolute/path/to/tf-approval-gate/dist/index.js"],
      "env": {
        "APPROVAL_MODE": "cli",
        "TF_APPROVAL_GATE_SECRET": "<same secret as above>"
      }
    }
  }
}

Weisen Sie Ihren Agenten auf examples/local-demo (verwendet die null/random-Provider, keine Cloud-Zugangsdaten erforderlich) und lassen Sie ihn tf_workspace_init → tf_propose_change → tf_request_approval → tf_apply ausführen.

Docker / Devcontainer

docker build erzeugt ein Image mit vorinstalliertem Node, Terraform, Checkov und Conftest (OPA) – kein Host-Setup außer Docker selbst erforderlich.

docker build -t tf-approval-gate .
docker run --rm -it \
  -e APPROVAL_MODE=cli \
  -e TF_APPROVAL_GATE_SECRET=$(openssl rand -hex 32) \
  -v "$(pwd)/examples/local-demo":/examples/local-demo:ro \
  -v tf-approval-gate-data:/data \
  tf-approval-gate

Für den Slack-Modus fügen Sie -e SLACK_BOT_TOKEN=... -e SLACK_APP_TOKEN=... -e SLACK_APPROVAL_CHANNEL=... -e SLACK_APPROVER_USER_IDS=... hinzu und entfernen Sie APPROVAL_MODE=cli. Der Genehmigungsstatus wird im /data-Volume persistiert (SQLite-gestützt, siehe docs/architecture.md).

Eine .devcontainer/devcontainer.json ist ebenfalls für VS Code / GitHub Codespaces enthalten – öffnen Sie das Repository in einem Container und terraform/checkov/conftest sind sofort einsatzbereit.

Slack-Einrichtung (Produktionsmodus)

1. Erstellen Sie eine Slack-App aus examples/slack-app-manifest.yml.

2. Aktivieren Sie den Socket-Modus und generieren Sie ein Token auf App-Ebene (xapp-...).

3. Installieren Sie die App in Ihrem Workspace und kopieren Sie den Bot-Token (xoxb-...).

4. Setzen Sie SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_APPROVAL_CHANNEL und SLACK_APPROVER_USER_IDS (durch Kommas getrennte Slack-Benutzer-IDs, die auf Genehmigen/Ablehnen klicken dürfen) – siehe .env.example.

5. Führen Sie mit APPROVAL_MODE=slack aus (der Standardwert).

Vollständige Anleitung: docs/slack-setup.md.

Tools

Vollständige Referenz: docs/tool-reference.md.

Status

v0.1 bis v0.4 sind implementiert und getestet: Happy Path (Checkov, Slack-Socket-Modus / CLI-Fallback), OPA/Conftest, Infracost-Kostenschätzung und ein SQLite-gestützter Genehmigungsspeicher mit atomarem Einmalverbrauch des Tokens. Ein Docker-Image und Devcontainer sind gebaut und verifiziert. Echte End-to-End-Läufe wurden sowohl gegen die lokale null/random-Demo als auch gegen ein Live-AWS-Konto (examples/aws-s3-demo) durchgeführt. Siehe docs/architecture.md für die vollständige Roadmap und was vor einem öffentlichen Launch-Post noch offen ist (ein Demo-GIF und externe Kalt-Tests – siehe CONTRIBUTING.md).

Lizenz

MIT – siehe LICENSE.