readtheplan/readtheplan

# readtheplan `readtheplan` 是一个 Terraform plan 风险解释工具。它读取 `terraform plan` 的输出，根据操作 × 资源类型 × 所触及的合规上下文，将每项变更分类为 **safe（安全） / review（需审查） / dangerous（危险） / irreversible（不可逆）**，并发布一个 Markdown 格式的摘要，您的发布经理（或审计员，或 AI agent）可以在 30 秒内阅读完毕。 ## 状态 🧪 **Alpha — v0.0.2。** 在 PyPI 上的首个可用版本。MVP-1 CLI 发布了基于操作的风险分类器（参见 [ADR 0003](docs/adr/0003-risk-classification-taxonomy.md)），并且 MVP-4 复合 GitHub Action 对其进行了封装。接下来将推出感知资源的规则库（MVP-2）。 ## 为什么会有这个项目 Terraform 的 plan/apply 分离机制本意是让变更在进入生产环境之前能经过人工审查。但在实际操作中： - 代码层面的 diff ≠ plan 层面的 diff（重命名显示为销毁+创建，provider 版本升级会改动未触及的资源，`apply_immediately` 的切换具有隐藏的时机影响） - 如今 AI agent 会编写 Terraform PR —— 但大多数并不会批判性地阅读 plan，它们执行应用仅仅是因为“测试通过了” - 合规审查人员（金融、医疗、政府机构）需要的是结构化的风险分类，而不是一个 4000 行的文本块 - 现有的工具要么只是让 plan 显示得更美观（如 Spacelift、env0），要么只是扫描代码以排查策略违规（如 tflint、tfsec、checkov）。没有工具会结合影响范围上下文来对 **plan diff** 给出明确的定性。 ## 理念 基于这篇实地观察记录：**[terraform-apply-is-roulette](https://github.com/texasich/sre-field-notes/blob/main/notes/terraform-apply-is-roulette.md)**。如果您曾因轻信 `terraform validate` 而引发过紧急修复的恐慌，或者眼睁睁看着一次前向修复演变成更长时间的停机，那么这个工具就是为您量身打造的。 ## 计划中的 MVP 范围 1. CLI：`readtheplan analyze plan.json` → 输出带有风险等级的 Markdown 变更表格 2. 针对每种资源类型的纯英文解释（开箱即用即覆盖约 30 种高风险模式：KMS、IAM、RDS 替换、S3 存储桶销毁、EKS 节点组替换、route53 区域删除、网络 ACL 剥离） 3. AI agent 认证标头 —— 标记某个 agent 是否声明已阅读过该 plan 4. GitHub Action 封装：以 `uses: readtheplan/action@v1` 的方式安装，并发布一条 Markdown 格式的 PR 评论 5. YAML 规则自定义：定义组织特定的规则（例如“账号 1234 中的任何内容均标记为 `review`”） ## *不*在范围内（且不会纳入）的内容 - 超越 AWS 的多云支持（初期专注点） - SaaS 仪表板（推迟至收益能证明其合理性时再做） - 策略即代码引擎（OPA / Sentinel 已经存在） - 在重叠功能上与 Spacelift / env0 / Snyk IaC 竞争 ## 许可证 MIT — 详见 [LICENSE](./LICENSE)。 ## CLI JSON 输出 MVP-1 为自动化暴露了一个稳定的机器可读契约： ``` readtheplan analyze --format json plan.json ``` 该 JSON 对象包括： - `resource_change_count`：Terraform `resource_changes` 条目的总数。 - `actions`：以 Terraform 操作集（例如 `create` 或 `delete/create`）为键的计数。 - `risks`：以 readtheplan 风险等级为键的计数。 - `changes`：每个资源变更对应一个对象，包含 `address`、`type`、`actions` 和 `risk`。 无效输入将在标准错误（stderr）中报告并以非零状态退出。 ## GitHub Action 本仓库在根目录下包含一个复合 GitHub Action。默认情况下，它会安装通过 action 检出的本地 Python 包，运行 JSON CLI 契约，并将解析后的值作为输出公开。 ``` - name: Analyze Terraform plan id: readtheplan uses: readtheplan/readtheplan@v1 with: plan-file: plan.json fail-on-changes: "false" - name: Use readtheplan output run: | echo "${{ steps.readtheplan.outputs['summary-json'] }}" echo "${{ steps.readtheplan.outputs['resource-change-count'] }}" ``` Action 输出： - `summary-json`：由 `readtheplan analyze --format json` 输出的完整 JSON。 - `resource-change-count`：资源变更总数。 - `action-counts`：操作计数的紧凑 JSON 对象。 - `risk-counts`：风险计数的紧凑 JSON 对象。 ## 联系方式 欢迎开源贡献。作者：[@texasich](https://github.com/texasich)。

标签：AI代理, DevSecOps, EC2, ECS, GitHub Action, IaC, PyPI, Python, SRE, Terraform, terraform-plan, 上游代理, 云安全监控, 云计算, 偏差过滤, 发布管理, 变更审查, 基础设施变更, 安全合规, 审计, 平台工程, 开源框架, 持续集成, 提示词模板, 文档结构分析, 无后门, 漏洞利用检测, 网络代理, 规则引擎, 逆向工具, 静态分析