TF Approval Gate

Un servidor MCP que permite a los agentes de codificación de IA (Claude Code, Cursor, etc.) planificar, verificar políticas y estimar costes de cambios de Terraform, pero hace estructuralmente imposible que el agente ejecute terraform apply sin que un humano real haga clic en Approve en Slack primero.

Por qué

Los agentes de IA ahora pueden escribir y ejecutar Terraform directamente contra cuentas reales en la nube. Un agente que pueda ejecutar terraform apply por su cuenta puede destruir silenciosamente o configurar mal la infraestructura de producción sin intervención humana. TF Approval Gate cierra esa brecha: cada apply requiere un token firmado de un solo uso que solo un humano real puede generar con un clic en Slack (o, en modo de desarrollo, un humano real en una terminal). La afirmación del propio agente de que "el humano aprobó" nunca se da por válida: el servidor lo vuelve a verificar todo por sí mismo.

Related MCP server: Hivelore

Cómo funciona

1. El agente edita los archivos .tf y luego llama a tf_propose_change: ejecuta terraform plan, Checkov (+ OPA si está configurado) e Infracost (si está configurado), y devuelve una propuesta empaquetada con una recomendación safe/needs_review/blocked.

2. El agente llama a tf_request_approval: publica el diff, los hallazgos de políticas y el coste en Slack con botones Approve/Reject (o muestra un aviso en la terminal del servidor en APPROVAL_MODE=cli). Se niega a publicar por completo si los hallazgos de políticas son bloqueantes.

3. El agente consulta tf_check_approval_status.

4. Un humano hace clic en Approve → el servidor verifica que el clic proviene de un usuario de Slack incluido en la lista de permitidos y genera un token firmado de un solo uso vinculado al checksum de ese plan exacto.

5. El agente llama a tf_apply con el token. El servidor vuelve a verificar la firma, la caducidad, el estado de un solo uso, el checksum binario del plan y comprueba si hay deriva en la nube; solo entonces ejecuta terraform apply.

Consulta docs/architecture.md y docs/security-model.md para ver el diseño completo y el modelo de amenazas.

Inicio rápido (local, sin necesidad de configurar Slack)

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

Requiere Terraform y Checkov en PATH. OPA/Conftest e Infracost son opcionales (las funciones se omiten automáticamente si faltan). O evita instalar nada y usa la imagen de Docker a continuación, que incluye los tres.

Ejecútalo en modo desarrollo (APPROVAL_MODE=cli imprime el diff en la terminal del servidor y espera una respuesta y/n en lugar de publicar en Slack; es bueno para una primera prueba local, aunque ofrece una garantía más débil que Slack; consulta docs/security-model.md):

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

Luego añádelo como servidor MCP en Claude Code (o en cualquier cliente MCP):

{
  "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>"
      }
    }
  }
}

Apunta tu agente a examples/local-demo (utiliza los proveedores null/random, no requiere credenciales de nube) y pídele que ejecute tf_workspace_init → tf_propose_change → tf_request_approval → tf_apply.

Docker / devcontainer

docker build produce una imagen con Node, Terraform, Checkov y Conftest (OPA) preinstalados; no se requiere configuración adicional en el host aparte del propio Docker.

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

Para el modo Slack, añade -e SLACK_BOT_TOKEN=... -e SLACK_APP_TOKEN=... -e SLACK_APPROVAL_CHANNEL=... -e SLACK_APPROVER_USER_IDS=... y elimina APPROVAL_MODE=cli. El estado de las aprobaciones persiste en el volumen /data (respaldado por SQLite; consulta docs/architecture.md).

También se incluye un .devcontainer/devcontainer.json para VS Code / GitHub Codespaces: abre el repositorio en un contenedor y terraform/checkov/conftest estarán listos de inmediato.

Configuración de Slack (modo producción)

1. Crea una app de Slack a partir de examples/slack-app-manifest.yml.

2. Habilita el modo Socket y genera un token a nivel de app (xapp-...).

3. Instala la app en tu espacio de trabajo y copia el token del bot (xoxb-...).

4. Configura SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_APPROVAL_CHANNEL y SLACK_APPROVER_USER_IDS (IDs de usuario de Slack separados por comas autorizados para hacer clic en Approve/Reject); consulta .env.example.

5. Ejecuta con APPROVAL_MODE=slack (el valor predeterminado).

Guía completa: docs/slack-setup.md.

Herramientas

Referencia completa: docs/tool-reference.md.

Estado

Las versiones v0.1 a v0.4 están implementadas y probadas: el flujo normal (Checkov, Slack Socket Mode / respaldo por CLI), OPA/Conftest, estimación de costes con Infracost y un almacén de aprobaciones respaldado por SQLite con consumo atómico de tokens de un solo uso. La imagen de Docker y el devcontainer están creados y verificados. Se han realizado ejecuciones reales de extremo a extremo tanto con la demo local null/random como con una cuenta real de AWS (examples/aws-s3-demo). Consulta docs/architecture.md para ver la hoja de ruta completa y lo que aún queda abierto antes de una publicación de lanzamiento (un GIF de demostración y pruebas externas en frío; consulta CONTRIBUTING.md).

Licencia

MIT -- consulta LICENSE.