manynames3/terragate

# TerraGate TerraGate 是一个生产级的 Terraform PR 风险门禁，用于在基础设施变更合并之前对其进行审查。它会解析 Terraform plan JSON，对敏感值进行脱敏，运行确定性的安全/成本/可靠性/治理检查，使用 LangGraph 工作流来丰富和排序发现的问题，持久化审查历史，起草 GitHub PR 评论，并在发布或提交建议的修复之前要求人工批准。 **定位：** AI 辅助的 Terraform 审查工具，将策略证据视为事实来源，将 LLM 输出视为解释、修复和工作流加速。 ## TL;DR - **它是什么：** 一款面向云/平台团队的 AI 辅助 Terraform PR 审查工具。 - **它做什么：** 将 Terraform plan JSON 或沙箱生成的计划转化为有证据支持的风险发现、修复指导、检查状态以及受批准门禁控制的 GitHub 评论。 - **它为何可信：** 它首先使用确定性策略检查，在 AI 审查前对制品进行脱敏，持久化运行记录/发现/证据，具备 Alembic 迁移、测试、CI、Docker Compose、GitHub 集成以及适配 Cognito 的身份验证。 - **在线演示：** [https://terragate.hangi87.workers.dev](https://terragate.hangi87.workers.dev) - **运行示例：** [严重安全风险审查](https://terragate.hangi87.workers.dev/runs/run_8182267f6ba84b629a) ## 问题 Terraform PR 审查速度很慢，因为审查者必须从分散的 plan 输出、代码差异、标签和部落知识中重建爆炸半径、安全暴露、成本影响和运营风险。通用的 AI 审查本身不够可信，因为 Terraform plan JSON 可能包含敏感值，并且幻觉产生的基础设施发现会造成审查噪音。 ## 解决方案 TerraGate 将 Terraform plan 转化为审查工作流：解析并对计划进行脱敏，运行确定性检查，将发现映射到证据和 PR 上下文，对风险进行排序，生成修复/操作手册指导，起草一条清晰的 PR 评论，并在人工批准之前阻止所有外部写入。 ## 运营价值 - 通过将 plan JSON 转化为带有证据的优先级发现，减少人工审查时间。 - 通过在合并前捕获公共入口、破坏性的有状态变更、缺少备份、弱标签和成本意外，降低云风险。 - 通过在评论或补丁提交前要求明确批准，保留审查者的控制权。 - 通过对原始制品进行脱敏并发送精简后的证据摘要，确保敏感数据不会包含在可选的 LLM 调用中。 ## 关于 本项目专为平台工程师、SRE、DevOps 团队和安全审查者构建，他们需要更快的基础设施变更审查速度，而不需要信任 LLM 去猜测原始文件。**审查 Terraform PR** 是主要工作流。操作手册和合规视图重用相同的持久化发现和证据；更广泛的事件和成本优化工作流不在范围之内。 核心产品理念是确定性优先，AI 次之： 1. 解析 Terraform plan JSON。 2. 对敏感值进行脱敏。 3. 提取规范化的资源变更。 4. 运行确定性策略检查。 5. 使用审查者节点根据结构化证据进行解释、优先级排序和生成修复建议。 6. 在 GitHub 写入之前要求人工批准。 ## 截图与图表 公开演示的架构图源自仓库自有的源代码，反映了本仓库中定义的 AWS/Cloudflare 部署形态。  除非是从运行的应用程序生成的，否则 UI 截图特意不进行签入。请使用上方的实时演示链接或下方的本地快速开始来查看当前的仪表板。 ## 技术栈 | 领域 | 技术 | | --- | --- | | 前端 | Next.js 16, React 19, TypeScript, Tailwind CSS, lucide-react | | 后端 API | FastAPI, Pydantic, SQLAlchemy | | Agent 工作流 | LangGraph, LangChain, 可选的 OpenAI 模型调用 | | 数据库 | Docker Compose 中的 PostgreSQL，本地/手动运行时的 SQLite 回退 | | 迁移 | Alembic | | 身份验证 | 开发角色请求头回退，Amazon Cognito JWT/Hosted UI 集成路径 | | 制品存储 | 用于开发的本地文件系统适配器，为未来的对象存储进行了结构化 | | GitHub | PR 元数据、webhook 端点、检查运行、评论、已批准的补丁提交、模拟回退 | | 成本 | 可选的 Infracost CLI，确定性启发式回退 | | 可观测性 | 可选的 LangSmith 追踪，数据库中的审计日志记录 | | 本地开发/部署 | Docker Compose, API/web Dockerfiles, GitHub Actions CI | | 公开演示托管 | Cloudflare Workers/OpenNext 前端，AWS API Gateway + Lambda/Mangum 后端路径 | ## 工程亮点 - **感知 Terraform 的解析器：** 验证 `terraform show -json` 输出，提取 `resource_changes`、操作、提供者、前/后状态以及计划摘要指标。 - **敏感数据防护栏：** 在 AI 审查或制品显示之前，对类似密钥的键和 PR 补丁片段进行脱敏。 - **确定性策略引擎：** 实现具有 JSON 路径证据的安全、成本、可靠性、治理和合规类检查。 - **LangGraph 工作流：** 运行具名的审查节点，用于摄取、脱敏、规范化、策略检查、成本估算、爆炸半径分析、审查者丰富、合并/去重、PR 映射、修复、合规映射、报告和批准门禁。 - **Human-in-the-loop GitHub 操作：** PR 评论和建议的补丁提交在批准前会被阻止。 - **生产级持久化：** 存储运行、制品、发现、证据、修复建议、批准、GitHub 检查/评论、修复补丁、审查作业和审计事件。 - **支持异步执行：** 支持内联执行、FastAPI 后台任务，以及一个从数据库认领排队审查作业的 worker 进程。 - **运营风险分析：** 检测破坏性的有状态变更，并生成操作手册级别的检查清单，用于备份、维护窗口、回滚、所有者签署和应用后验证。 - **托管演示防护栏：** 包括预加载的示例审查端点、上传大小限制、禁用沙箱、只读策略包，以及用于公开演示的模拟 GitHub 写入。 - **工程规范：** TypeScript 检查、ESLint、pytest、有针对性的前端回归测试、Docker Compose、Alembic 迁移、示例数据、API 合同文档、威胁模型和 ADR。 ## 证据矩阵 | 领域 | 证据 | | --- | --- | | IaC | `infra/terraform/aws-public-demo` 配置了 API Gateway、Lambda 容器、ECR、CodeBuild、私有 RDS、VPC/子网/安全组、日志组和输出。 | | CI/CD | `.github/workflows/ci.yml` 运行后端测试、Alembic 迁移验证、前端类型检查/lint/构建以及 Terraform fmt/validate。AWS 后端部署使用 Terraform + CodeBuild；Cloudflare 部署使用 OpenNext/Wrangler。 | | 安全 | Terraform plan 和 PR 补丁脱敏、Cognito JWT 支持、演示的开发认证隔离、私有 RDS、安全组范围的数据库访问、批准门禁控制的 GitHub 写入、公开演示防护栏。 | | 可靠性 | 持久化的运行/作业状态、节点级图进度、重试元数据、worker 认领流程、明确的公开演示回退行为、已记录的故障模式和恢复。 | | 可观测性 | CloudWatch 日志组、Cloudflare Workers 可观测性、持久化的审计事件、可选的 LangSmith 追踪、UI 中可见的图进度。 | | 成本 | Lambda/API Gateway 请求驱动的后端，演示堆栈中没有 NAT 网关，可停止的小型 RDS，14 天的日志保留期，可选的 Infracost，已记录的低空闲公开演示路径。 | | 运营 | 操作手册级别的修复输出、部署文档、卸载文档、威胁模型、公开演示指南、API 合同、审查者指南。 | | 测试 | 针对解析器/脱敏/策略/风险/API/身份验证/GitHub 行为的 Pytest 覆盖率、前端回归测试、TypeScript/lint/构建检查以及 CI Terraform 验证。 | | 文档 | 架构文档、ADR、权衡、安全、可观测性、成本模型、测试、部署、卸载和审查者指南。 | ## 架构 已实现的公开演示路径通过 Cloudflare Workers 提供 Next.js/OpenNext 前端服务。浏览器请求调用 AWS API Gateway HTTP API，后者在私有子网中调用由 Mangum 包装的 FastAPI Lambda。后端内联运行确定性优先的 LangGraph 审查，将临时制品存储在 Lambda `/tmp` 中，并将审查状态和审计事件持久化到私有、加密的 RDS PostgreSQL 中。 - **请求流：** 审查者从 Cloudflare Workers 加载 UI；浏览器将 API 调用直接发送到 API Gateway -> FastAPI/Lambda -> 审查引擎 -> RDS。可选的 GitHub、OpenAI、LangSmith 和 Infracost 适配器在公开演示路径中被禁用、模拟或依赖于凭证。 - **部署流：** Terraform 配置 AWS 后端并启动 CodeBuild，后者克隆选定的 Git ref，构建 `Dockerfile.lambda`，推送到 ECR，并通过镜像摘要提供给 Lambda。Cloudflare 前端部署是一个独立的手动 npm 脚本。GitHub Actions 仅运行测试和构建；它不进行部署。 - **安全性：** Lambda 和 RDS 在私有子网中运行，RDS 仅接受来自 Lambda 安全组的 5432 端口流量，原始计划在可选的 AI 审查之前进行脱敏，GitHub 写入需要人工批准。Cognito 支持是可选的，不由演示 Terraform 配置；公开演示使用开发身份验证。 - **成本控制：** 该堆栈使用请求驱动的 Lambda/API Gateway，无空闲 worker 的内联执行，没有 NAT 网关，默认使用小型 RDS，以及 14 天的日志保留。在演示之外停止 RDS 是记录在案的手动控制，而不是自动计划任务。 架构文档： - [AWS 图表源码](docs/architecture_aws.py) - [AWS 图表 SVG](docs/architecture_aws.svg) - [Mermaid 图表源码](docs/architecture.mmd) - [架构图说明与证据](docs/architecture-notes.md) - [架构概览和 C4 风格图表](docs/architecture.md) - [招聘经理审查指南](docs/reviewer-guide.md) - [部署指南](docs/deployment.md) - [操作手册](docs/runbook.md) - [安全模型](docs/security.md) - [可观测性模型](docs/observability.md) - [成本模型](docs/cost-model.md) - [卸载指南](docs/teardown.md) - [测试指南](docs/testing.md) - [权衡](docs/tradeoffs.md) - [GitHub App 接入计划](docs/github-app-onboarding.md) - [S3/KMS 制品存储计划](docs/s3-artifact-storage.md) - [持久化 worker 队列计划](docs/worker-queue.md) - [架构决策记录](docs/adrs/README.md) - [产品就绪计划](docs/product-readiness.md) - [低成本公开演示部署](docs/public-demo.md) - [API 合同](docs/api-contract.md) - [威胁模型](docs/threat-model.md) - [演示脚本](docs/demo-script.md) ## 目前可用的功能 - 上传 Terraform plan JSON。 - 可选地从已配置的沙箱目录运行 Terraform plan 生成。 - 配置凭证后获取 GitHub PR 元数据和已更改的文件。 - 接受 GitHub pull request webhook，用于原生 PR 审查触发。 - 解析并汇总 Terraform 资源变更。 - 对原始计划值和 GitHub 补丁上下文进行脱敏。 - 运行确定性的安全、成本、可靠性、治理和合规检查。 - 在配置后使用 Infracost 估算成本，或使用带标签的启发式回退。 - 分析破坏性有状态变更的爆炸半径。 - 生成结构化的发现、证据、修复建议、合规参考和操作手册检查清单项。 - 生成 markdown GitHub PR 评论草稿。 - 在发布评论或提交建议的修复之前要求批准。 - 持久化审查历史、审计日志事件和图进度。 - 将运行历史和运行操作限制在已认证用户的组织内。 - 使用确定性和模拟回退在本地运行，无需 OpenAI 或 GitHub 凭证。 - 启动内置的公开演示示例审查，无需访问者上传 Terraform plan。 ## 项目结构 ``` apps/ api/ FastAPI API, LangGraph workflow, persistence, integrations, tests web/ Next.js dashboard, review form, run detail, approvals, settings docs/ Architecture, ADRs, API contract, threat model, demo script infra/ Dockerfiles and Docker Compose sample-data/terraform-plans/ Safe, risky security, risky cost, and destructive prod plan fixtures ``` ## 本地设置 ### 选项 A：Docker Compose ``` cd terragate cp .env.example .env docker compose -f infra/docker-compose.yml up --build ``` 打开： - Web：`http://localhost:3000` - API 文档：`http://localhost8000/docs` Docker Compose 运行 PostgreSQL、API、worker 和 Web 应用。可选的 Redis 和 Qdrant 服务定义在 Compose profiles 之后，供未来扩展使用。 ### 公开演示模式 对于托管的公开工作样例演示，请启用安全的公开路径： ``` PUBLIC_DEMO_MODE=true PUBLIC_DEMO_ALLOW_UPLOADS=true PUBLIC_DEMO_MAX_UPLOAD_BYTES=1500000 PUBLIC_DEMO_DISABLE_SANDBOX=true PUBLIC_DEMO_MOCK_GITHUB_WRITES=true PUBLIC_DEMO_ALLOW_LIVE_GITHUB_READS=false REVIEW_EXECUTION_MODE=inline ``` 这使得完整的审查工作流对于内置的示例计划和可选的有上限的上传保持正常功能，同时阻止昂贵或有风险的操作，例如 Terraform 沙箱执行和实时的 GitHub 写入。有关 Cloudflare Workers + AWS API Gateway/Lambda 部署形态，请参见 [docs/public-demo.md](docs/public-demo.md)。 ### 选项 B：手动本地运行 后端： ``` cd terragate/apps/api python -m venv .venv source .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --reload --port 8000 ``` 前端： ``` cd terragate/apps/web npm install npm run dev ``` 手动模式下，如果 `DATABASE_URL` 为空，则默认使用 SQLite。Docker Compose 使用 PostgreSQL。API 在启动时运行 Alembic 迁移；也可以使用 `alembic upgrade head` 从 `apps/api` 手动运行迁移。 ## 演示流程 使用包含的示例计划： ``` sample-data/terraform-plans/safe-plan.json sample-data/terraform-plans/risky-security-plan.json sample-data/terraform-plans/risky-cost-plan.json sample-data/terraform-plans/destructive-prod-plan.json ``` 建议的演练步骤： 1. 启动应用程序。 2. 打开 New Review。 3. 上传 `sample-data/terraform-plans/risky-security-plan.json`。 4. 选择 `prod`、AWS 和 `default` 策略配置文件。 5. 显示图进度、计划摘要、严重性细分、发现、证据、修复建议和 PR 评论草稿。 6. 尝试在批准之前发布到 GitHub，以显示批准门禁。 7. 批准草稿。 8. 发布到 GitHub。如果没有凭证，API 将返回明确的模拟响应。 ## 环境 将 `.env.example` 复制到 `.env`。重要变量： | 变量 | 用途 | | --- | --- | | `DATABASE_URL` | PostgreSQL 连接字符串；手动模式下为空时的 SQLite 回退 | | `OPENAI_API_KEY` | 启用可选的 LLM 审查者丰富 | | `LANGSMITH_API_KEY` / `LANGSMITH_PROJECT` | 可选的 LangSmith 追踪 | | `GITHUB_TOKEN` 或 GitHub App 变量 | 启用实时的 PR 元数据、检查、评论和已批准的补丁提交 | | `INFRACOST_API_KEY` | 启用更强大的基于 Infracost 的成本估算 | | `AUTH_MODE` | `dev` 或 `cognito` | | `COGNITO_*` 和 `NEXT_PUBLIC_COGNITO_*` | Cognito JWT 验证和 Hosted UI 登录 | | `TERRAFORM_SANDBOX_*` | 可选的 Terraform plan 执行沙箱设置 | | `REVIEW_EXECUTION_MODE` | `inline`、`background` 或 worker 支持的执行 | | `PUBLIC_DEMO_*` | 启用托管演示防护栏、示例审查流程、上传限制和模拟外部写入 | 对于 Cognito，创建一个没有 client secret 的公共 app client，启用 authorization-code + PKCE，将 `http://localhost:3000/auth/callback` 添加为允许的回调 URL，并将 `http://localhost:3000` 添加为允许的登出 URL。默认情况下，组映射到应用角色：`terragate-admins`、`terragate-reviewers` 和 `terragate-viewers`。 ## 生成 Terraform Plan JSON ``` terraform plan -out=tfplan.binary terraform show -json tfplan.binary > tfplan.json ``` Terraform plan JSON 可能会暴露密钥和提供者生成的值。将其视为敏感信息。应用程序在审查节点之前以及在存储 GitHub 补丁上下文之前对敏感内容进行脱敏，但原始上传的制品仍应作为敏感数据处理。 ## 安全和隐私防护栏 - 原始 Terraform plan 绝不会发送给 LLM。 - LLM 审查者节点接收的是精简后的证据摘要，而不是完整的原始计划。 - 类似密钥的键和 PR 补丁片段会被脱敏。 - 确定性发现包含具体的证据和规则 ID。 - 低置信度或高风险发现可能需要人工审查。 - GitHub 评论和建议的补丁提交受批准门禁控制。 - 缺少外部凭证会返回模拟/开发响应，而不是导致演示失败。 - Cognito 模式验证已签名的 JWT，并将组/自定义声明映射到平台角色。 ## GitHub 集成 提供 `repo_owner`、`repo_name` 和 `pull_number` 后，后端可以获取 PR 标题、作者、状态、标签、审查者、引用、最新 head SHA、更改的文件和 Terraform 文件补丁。在有上下文可用时，发现会通过启发式方法映射回已更改的 Terraform 文件。 该应用可以创建 GitHub check-run 记录、起草单条 PR 评论、发布已批准的评论，并将已批准的建议补丁提交到同一仓库的 PR 分支。如果缺少凭证或安全的 PR 元数据，它会记录模拟事件并返回明确的消息。 ## 测试和 CI 后端： ``` cd apps/api source .venv/bin/activate python -m pytest ``` 前端： ``` cd apps/web npm test npm run typecheck npm run lint npm run build ``` GitHub Actions 运行后端 pytest 以及前端回归测试、类型检查、lint 和构建。 CI 还会验证 AWS 公开演示堆栈的 Alembic 迁移以及 Terraform 格式/验证。 ## 部署概览 - **本地：** Docker Compose 运行 API、Web、worker 和 PostgreSQL。手动模式可以使用 SQLite 进行快速的 API 运行。 - **公开演示前端：** 通过 OpenNext 和 Wrangler 的 Cloudflare Workers。当前仓库包含 `apps/web/wrangler.jsonc` 和用于预览/部署的 npm 脚本。 - **公开演示后端：** AWS API Gateway 调用 Mangum 包装的 FastAPI Lambda 容器。Terraform 配置私有 RDS PostgreSQL、ECR、CodeBuild、VPC 网络和日志组。 - **CI：** GitHub Actions 验证代码和 Terraform，但特意不进行自动部署。 参见 [docs/deployment.md](docs/deployment.md) 和 [docs/public-demo.md](docs/public-demo.md)。 ## 安全模型摘要 - 确定性检查是权威的；可选的 LLM 调用仅接收脱敏后的证据摘要。 - Terraform plan 值和 GitHub 补丁片段在 AI 审查之前或敏感上下文中显示之前进行脱敏。 - 公开演示模式默认阻止实时的 GitHub 写入、Terraform 沙箱执行和策略包编辑。 - Cognito JWT 验证存在于私有部署中，而公开演示使用开发身份验证并明确标示。 - GitHub 评论/检查/补丁提交受批准门禁控制和审计。 - 在 AWS 演示堆栈中，私有 RDS 仅接受来自 Lambda 安全组的 PostgreSQL 流量。 参见 [docs/security.md](docs/security.md) 和 [docs/threat-model.md](docs/threat-model.md)。 ## 可观测性模型摘要 - 运行会持久化图进度、节点状态、发现、批准、GitHub 操作尝试和审计事件。 - 公开演示基础设施将 Lambda 和 CodeBuild 日志写入 CloudWatch，保留期为 14 天。 - Cloudflare Workers 可观测性在 `apps/web/wrangler.jsonc` 中启用。 - LangSmith 追踪通过环境变量可选，默认情况下在低成本的公开演示 Terraform 中禁用。 参见 [docs/observability.md](docs/observability.md)。 ## 成本控制摘要 - Lambda/API Gateway 是请求驱动的。 - 公开演示堆栈避免了 NAT 网关和独立的常驻 worker。 - RDS 使用小型实例类，并且被记录为可在演示之外停止。 - 日志保留期限制为 14 天。 - Infracost 可以提供更准确的估算；当 Infracost 不可用时，启发式估算会进行标记。 参见 [docs/cost-model.md](docs/cost-model.md)。 ## 公开演示性能 公开演示针对极低的空闲成本进行了优化，因此不活动后的第一次 API 请求可能比付费的常驻服务慢。可能的原因包括 Lambda 容器冷启动、FastAPI/数据库连接启动和 RDS 连接预热。 UI 旨在向第一印象隐藏该成本： - Cloudflare 托管的应用外壳、导航、控件和静态信任信号会立即渲染。 - 仪表板指标和运行历史通过骨架状态渐进式加载，而不是显示临时的零值。 - 仪表板在应用程序外壳可见后获取持久化的审查历史。 - API 仅在执行审查作业时导入 LangGraph/LangChain 审查工作流，因此简单的健康检查和仪表板端点避免了不必要的繁重启动工作。 这是一个深思熟虑的作品集演示权衡：在保持可信的用户体验的同时保持低空闲消耗。付费的生产部署将添加持久化队列、更强的缓存，以及可选的 Lambda 预置并发或常驻服务，以满足更严格的延迟目标。 ## 卸载和清理 - 可以使用 Docker Compose 停止本地容器。 - AWS 公开演示资源使用 `terraform destroy` 移除。 - Cloudflare 前端资源通过 Wrangler/Cloudflare 进行管理。 - 演示堆栈在设计上是可消耗的：默认情况下禁用 RDS 删除保护和最终快照。 参见 [docs/teardown.md](docs/teardown.md)。 ## 已知的局限性 - worker 采用数据库轮询机制，而不是像 SQS、Celery 或 Temporal 那样的持久化队列系统。 - Terraform 沙箱对于演示和受信任的本地环境很有用，但它不是经过强化的多租户 SaaS 隔离边界。 - 公开演示模式默认情况下有意禁用沙箱执行；严重的多租户托管版本应在短生命周期的容器中隔离 Terraform 执行，并且不共享凭证。 - 在安装并配置了 Infracost 时，成本估算最为准确；回退估算被有意标记为启发式。 - 建议的补丁是可审查的草稿，在提交前可能需要人工编辑。 - 策略包是可编辑的 JSON 文件，尚未形成完整的批准/版本控制工作流。 - Cognito 身份验证已连接用于 JWT 验证和 Hosted UI，但持久化的组织成员资格和行级授权是未来的工作。 ## 路线图 - 持久化队列后端，如 SQS 或 Temporal，用于客户规模的审查执行。 - 租户隔离的 Terraform 执行，具有短暂的云凭证和更强大的沙箱边界。 - 策略包批准/版本控制工作流，每次运行带有策略快照。 - 带有保留和删除控制的 S3/KMS 制品存储适配器。 - 与 Python 检查并行的 OPA/Rego 策略执行。 - 用于事件调查和修复上下文的 Chroma/Qdrant 操作手册检索。 - UI 中的 LangSmith 追踪链接。 - 一流的 GitHub App 安装载入和仓库注册。

标签：ECS, GitHub Actions, LLM工作流, Terraform, 代码审查, 政策检查, 智能体, 测试用例, 自动笔记, 请求拦截, 逆向工具