TF Approval Gate

一个 MCP 服务器，让 AI 编程代理（Claude Code、Cursor 等）能够对 Terraform 变更进行规划、策略检查和成本估算——但在结构上使得代理无法运行 terraform apply，除非先有真人点击 Slack 中的 Approve。

为什么

AI 代理现在可以直接针对真实云账户编写并运行 Terraform。一个能够自行执行 terraform apply 的代理，可以在没有人工参与的情况下悄无声息地破坏或错误配置生产基础设施。TF Approval Gate 弥补了这一缺口：每次 apply 都需要一个已签名、一次性使用的令牌，且该令牌只能由真人的 Slack 点击（或在开发模式下，由真人操作终端）生成。代理自己声称的“人工已批准”永远不会被信任——服务器会自行重新验证一切。

Related MCP server: Hivelore

工作原理

1. 代理编辑 .tf 文件，然后调用 tf_propose_change——运行 terraform plan、Checkov（+ OPA，如已配置）和 Infracost（如已配置），并返回一个整合后的提案，附上 safe/needs_review/blocked 建议。

2. 代理调用 tf_request_approval——将 diff、策略发现和成本发布到 Slack，并附上 Approve/Reject 按钮（或在 APPROVAL_MODE=cli 模式下在服务器终端提示）。如果策略发现处于阻塞状态，则完全拒绝发布。

3. 代理轮询 tf_check_approval_status。

4. 真人点击 Approve → 服务器验证点击来自允许列表中的 Slack 用户，并生成一个已签名、一次性使用的令牌，绑定到该确切计划的校验和。

5. 代理携带该令牌调用 tf_apply。服务器重新验证签名、过期时间、一次性使用状态、计划的二进制校验和，并检查云端漂移——只有全部验证通过后才会运行 terraform apply。

完整设计与威胁模型参见 docs/architecture.md 和 docs/security-model.md。

快速开始（本地，无需配置 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

需要 Terraform 和 Checkov 位于 PATH 中。OPA/Conftest 和 Infracost 是可选的（缺失时相应功能会软跳过）。或者什么都不安装，直接使用下方的 Docker 镜像，它已包含全部三者。

以开发模式运行（APPROVAL_MODE=cli 会将 diff 打印到服务器终端并等待 y/n，而不是发布到 Slack——适合首次本地测试，但保证强度弱于 Slack，参见 docs/security-model.md）：

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

然后在 Claude Code（或任何 MCP 客户端）中将其添加为 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>"
      }
    }
  }
}

将你的代理指向 examples/local-demo（使用 null/random provider，无需云凭据），并让它依次运行 tf_workspace_init → tf_propose_change → tf_request_approval → tf_apply。

Docker / devcontainer

docker build 会生成一个预装 Node、Terraform、Checkov 和 Conftest（OPA）的镜像——除了 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

对于 Slack 模式，添加 -e SLACK_BOT_TOKEN=... -e SLACK_APP_TOKEN=... -e SLACK_APPROVAL_CHANNEL=... -e SLACK_APPROVER_USER_IDS=... 并移除 APPROVAL_MODE=cli。审批状态持久化在 /data 卷中（基于 SQLite，参见 docs/architecture.md）。

仓库还附带了一个 .devcontainer/devcontainer.json，用于 VS Code / GitHub Codespaces——在容器中打开仓库后，terraform/checkov/conftest 立即可用。

Slack 配置（生产模式）

1. 从 examples/slack-app-manifest.yml 创建 Slack 应用。

2. 启用 Socket Mode，生成应用级令牌（xapp-...）。

3. 将应用安装到你的工作区，复制机器人令牌（xoxb-...）。

4. 设置 SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_APPROVAL_CHANNEL 和 SLACK_APPROVER_USER_IDS（以逗号分隔、允许点击 Approve/Reject 的 Slack 用户 ID）——参见 .env.example。

5. 使用 APPROVAL_MODE=slack 运行（默认值）。

完整指南：docs/slack-setup.md。

工具

完整参考：docs/tool-reference.md。

状态

v0.1 到 v0.4 已实现并通过测试：正常路径（Checkov、Slack Socket Mode / CLI 回退）、OPA/Conftest、Infracost 成本估算，以及基于 SQLite、支持原子性一次性令牌消费的审批存储。Docker 镜像和 devcontainer 已构建并验证。已针对本地 null/random 演示和一个真实 AWS 账户（examples/aws-s3-demo）完成真实端到端运行。完整路线图以及公开发布帖之前仍需完成的事项（演示 GIF 和外部冷测试——参见 CONTRIBUTING.md）参见 docs/architecture.md。

许可证

MIT——参见 LICENSE。