TF Approval Gate

AI 코딩 에이전트(Claude Code, Cursor 등)가 Terraform 변경 사항을 계획하고, 정책을 검사하고, 비용을 추정할 수 있게 해주는 MCP 서버입니다 -- 그러나 실제 사람이 Slack에서 Approve를 클릭하기 전에는 에이전트가 terraform apply를 실행하는 것을 구조적으로 불가능하게 만듭니다.

왜 필요한가

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을 호출합니다 -- Approve/Reject 버튼과 함께 diff + 정책 검사 결과 + 비용을 Slack에 게시합니다(APPROVAL_MODE=cli에서는 서버 터미널에 프롬프트를 표시). 정책 검사 결과가 blocking이면 게시 자체를 거부합니다.

3. 에이전트가 tf_check_approval_status를 폴링합니다.

4. 사람이 Approve를 클릭 → 서버는 클릭이 허용 목록(allow-list)에 등록된 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

PATH에 Terraform과 Checkov가 필요합니다. OPA/Conftest와 Infracost는 선택 사항입니다(없으면 해당 기능이 자동으로 건너뜁니다). 또는 아무것도 설치하지 않고 아래의 Docker 이미지를 사용해도 됩니다. 세 가지가 모두 포함되어 있습니다.

개발 모드로 실행합니다(APPROVAL_MODE=cli는 Slack에 게시하는 대신 diff를 서버 터미널에 출력하고 y/n을 기다립니다 -- 첫 로컬 테스트에 적합하지만 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 프로바이더 사용)로 지정하고 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 참조).

VS Code / GitHub Codespaces용 .devcontainer/devcontainer.json도 포함되어 있습니다 -- 컨테이너에서 저장소를 열면 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) 모두에서 실제 엔드투엔드 실행이 수행되었습니다. 전체 로드맵과 공개 출시 전에 남은 작업은 docs/architecture.md를 참조하세요(데모 GIF 및 외부 콜드 테스트 -- CONTRIBUTING.md 참조).

라이선스

MIT -- LICENSE 참조.