danilotrix86/ArchiteX

# ArchiteX ### 你的 Pull Request 架构防火墙 **在合并前捕获有风险的 Terraform 拓扑。确定性。本地。免费。** [](https://github.com/danilotrix86/ArchiteX/releases) [](https://github.com/danilotrix86/ArchiteX/actions/workflows/architex.yml) [](https://go.dev) [](LICENSE) [](CONTRIBUTING.md) [**快速开始**](#-30-second-quickstart) · [**实时演示**](#-what-the-pr-comment-actually-looks-like) · [**为何选择 ArchiteX?**](#-why-architex) · [**覆盖范围**](#-coverage) · [**路线图**](#-roadmap) ## 这是什么？ ArchiteX 是一个 **即插即用的 GitHub Action**，它读取 Pull Request 中的 Terraform 差异（diff），并以确定性的方式回帖架构审查评论作为置顶 PR 评论。每个 PR 都会得到： - 一个可解释的 **风险评分**（0–10） - 一份 **通俗英语摘要**，说明发生了什么变化以及为何重要 - 一个 **聚焦的差异图**（Mermaid），仅显示变化的节点及其一层上下文 - 一个可选的 **CI 网关**，可在出现关键违规时失败构建 - 一个 **带时间戳的审计包**，包含自包含的 HTML 报告和 SHA-256 清单 所有操作都在你自己的 GitHub Actions 运行器上执行。**原始 Terraform 从未离开运行器。** 无 SaaS、无遥测、无付费层级、无账户。 ## ⚡ 30 秒快速开始 将以下文件添加到你的 Terraform 仓库的 `.github/workflows/architex.yml`： ``` name: ArchiteX on: pull_request permissions: contents: read pull-requests: write jobs: architex: runs-on: ubuntu-latest steps: - uses: danilotrix86/ArchiteX@v1.3.1 with: terraform-dir: infra ``` **仅此而已。** 打开一个涉及 `infra/*.tf` 的 PR，ArchiteX 就会发布一个包含评分、图表和原因的置顶评论。默认情况下不会失败任何操作。 如果需要一个在高分风险变更时阻止合并的 CI 网关，只需修改一行： ``` with: terraform-dir: infra mode: blocking # advisory (default) | blocking ``` [完整的 GitHub Action 参考 →](docs/github-action.md) ## 🎬 PR 评论实际长什么样？ 一个开发者打开了一个 PR，其中添加了一个公网负载均衡器（ALB）并将安全组从私有（`10.0.0.0/16`）改为公网（`0.0.0.0/0`）。ArchiteX 发布如下内容： > 每一字节都是 **确定性的**。相同的差异会产生字节一致的输出来自不同运行、不同机器和不同贡献者。 ## 🤔 为何选择 ArchiteX？ 静态分析工具告诉你 _哪一行_ 有问题。ArchiteX 告诉你 _架构发生了什么变化_ 以及 _为什么审阅者应该在意_。 | | **ArchiteX** | tfsec / Trivy | Checkov | Terraform Cloud | |---|---|---|---|---| | **确定性输出**（字节一致的重跑） | ✅ | ⚠️ 部分 | ⚠️ 部分 | ❌ | | **架构差异**（新增/移除/变更） | ✅ | ❌ | ❌ | ⚠️ 仅计划 | | **PR 评论中的 Mermaid 图表** | ✅ | ❌ | ❌ | ❌ | | **面向非专家的英文摘要** | ✅ | ❌ | ❌ | ❌ | | **库模式解析**（`count = var.x ? 1 : 0`） | ✅ | ❌ | ⚠️ | ⚠️ | | **基线异常检测** | ✅ | ❌ | ❌ | ❌ | | **自包含 HTML 审计报告** | ✅ | ❌ | ❌ | ❌ | | **无网络环境友好**（无 SaaS、无遥测） | ✅ | ✅ | ✅ | ❌ | | **免费且开源** | ✅ | ✅ | ✅ | ❌ | | **单一二进制、单一 Action、零配置** | ✅ | ✅ | ⚠️ | ❌ | ArchiteX **补充** 基于规则的扫描器。一起运行它们：tfsec 捕获配置错误行的问题；ArchiteX 捕获 *架构* 漂移（新的入口点、新型资源、条件门等审阅者可能忽略的问题）。 ## 🏗 它是如何工作的？ ``` flowchart LR classDef stage stroke:#0366d6,stroke-width:2px,fill:#f6f8fa classDef output stroke:#28a745,stroke-width:2px,fill:#f6f8fa A([base/*.tf]):::stage --> P1 B([head/*.tf]):::stage --> P1 P1["1. Fact-Finder
HCL parse · graph build"]:::stage --> P2 P2["2. Delta Engine
added · removed · changed"]:::stage --> P3 P3["3. Risk & Policy Engine
18 rules · weighted score"]:::stage --> P4 P4["4. Interpreter
Mermaid · Markdown · HTML"]:::stage --> O1([Sticky PR comment]):::output P4 --> O2([Audit bundle
summary.md · score.json
egress.json · report.html
manifest.json with SHA-256]):::output ``` 每个阶段都是 **完全确定性** 的。解释器基于模板——无推理、无模型调用、无网络。相同的输入在所有运行中产生字节一致的输出。完整的架构规范请参见 [master.md](master.md)。 ## 🆕 v1.3 新功能 - **支持 EKS、自动伸缩组、RDS 组** — `aws_eks_cluster`、`aws_eks_node_group`、`aws_eks_addon`、`aws_eks_fargate_profile`、`aws_eks_identity_provider_config`、`aws_db_subnet_group`、`aws_db_parameter_group`、`aws_db_option_group`、`aws_launch_template`、`aws_autoscaling_group`、`aws_autoscaling_policy`。总计 **45 个 AWS 资源**。 - **3 条新的风险规则** — `eks_public_endpoint`、`eks_no_logging`、`asg_unrestricted_scaling`。总计 **18 条确定性规则**。 - **库模式** — 可选的解析器模式，适用于模块作者仓库。资源受 `count = var.create ? 1 : 0`（以及 `length(var.x) > 0 ? 1 : 0`）保护时，会被实例化为 **条件幻影**，在图中以 `?` 标记。风险规则拒绝对其评分，因此幻影不会产生误报。在 `.architex.yml` 中启用： ```yaml parser: mode: library # consumer（默认）| library ``` - **强化自测** — 每个固件（Tranche-1、Tranche-2、Tranche-3、库模式）都是 CI 中的回归测试。任何静默改变渲染输出的情况都会导致构建失败。 [完整的 v1.3 更新日志 →](CHANGELOG.md) ## 📦 覆盖范围 **45 种 AWS 资源类型**，组织为一组抽象架构角色： | 类别 | 资源 | 引入版本 | |---|---|---| | **网络** | `aws_vpc`、`aws_subnet`、`aws_internet_gateway`、`aws_nat_gateway`、`aws_route53_zone`、`aws_route53_record` | v1.0 – v1.2 | | **访问控制** | `aws_security_group`、`aws_security_group_rule`、`aws_network_acl`、`aws_network_acl_rule`、`aws_s3_bucket_public_access_block`、`aws_s3_bucket_policy`、`aws_sns_topic_policy`、`aws_sqs_queue_policy`、`aws_db_parameter_group`、`aws_db_option_group` | v1.0 – v1.3 | | **计算** | `aws_instance`、`aws_lambda_function`、`aws_ecs_cluster`、`aws_ecs_service`、`aws_ecs_task_definition`、`aws_eks_cluster`、`aws_eks_node_group`、`aws_eks_addon`、`aws_eks_fargate_profile`、`aws_launch_template`、`aws_autoscaling_group`、`aws_autoscaling_policy` | v1.0 – v1.3 | | **入口点** | `aws_lb`、`aws_lambda_function_url`、`aws_apigatewayv2_api`、`aws_cloudfront_distribution` | v1.0 – v1.2 | | **数据** | `aws_db_instance`、`aws_sns_topic`、`aws_sqs_queue`、`aws_secretsmanager_secret` | v1.0 – v1.2 | | **存储** | `aws_s3_bucket`、`aws_ebs_volume` | v1.1 – v1.2 | | **身份** | `aws_iam_role`、`aws_iam_policy`、`aws_iam_role_policy_attachment`、`aws_kms`、`aws_kms_alias`、`aws_eks_identity_provider_config` | v1.1 – v1.3 | | **专用网络** | `aws_db_subnet_group` | v1.3 | 不支持的资源类型会发出警告并略微降低置信度，但绝不会导致失败。 解析器还会展开 **本地模块递归**、**字面 `count` / `for_each` / `dynamic` 块**、**`data.aws_iam_policy.x.arn` 解析** 以及 **`jsonencode({...})` 策略体**——完整支持范围请参见 [docs/github-action.md](docs/github-action.md)。 ### 18 条确定性风险规则 每条规则贡献一个固定权重（上限为 10.0）。面向审阅者的名称在版本间保持稳定。 | 规则 | 权重 | 触发条件 | 引入版本 | |---|---:|---|---| | `public_exposure_introduced` | 4.0 | 节点的 `public` 属性从 `false` 变为 `true` | v1.0 | | `s3_bucket_public_exposure` | 4.0 | 移除 `aws_s3_bucket_public_access_block` 或添加了宽松桶策略 | v1.1 | | `eks_public_endpoint` | 3.5 | 添加的 `aws_eks_cluster` 启用了 `vpc_config.endpoint_public_access = true` 且无 CIDR 允许列表 | v1.3 | | `iam_admin_policy_attached` | 3.5 | 角色策略绑定了 `AdministratorAccess` 或 `IAMFullAccess` | v1.1 | | `messaging_topic_public` | 3.5 | 新增的 SNS/SQS 策略包含 `Allow … Principal = "*"` | v1.2 | | `nacl_allow_all_ingress` | 3.5 | NACL 规则允许 `0.0.0.0/0` 入口且为显式 `allow` | v1.2 | | `new_entry_point` | 3.0 | 新增的节点抽象类型为 `entry_point` | v1.0 | | `lambda_public_url_introduced` | 3.0 | 新增 `lambda_function_url`（在 `new_entry_point` 之上） | v1.1 | | `ebs_volume_unencrypted` | 3.0 | EBS 卷显式设置 `encrypted = false` | v1.2 | | `new_data_resource` | 2.5 | 新增的节点抽象类型为 `data` | v1.0 | | `cloudfront_no_waf` | 2.5 | 新增的 CloudFront 分布无 `web_acl_id` | v1.2 | | `potential_data_exposure` | 2.0 | `public_exposure_introduced` 与数据/访问控制变更同时发生 | v1.0 | | `eks_no_logging` | 1.5 | 新增的 EKS 集群未启用 `enabled_cluster_log_types` | v1.3 | | `first_time_abstract_type` | 1.5 | 仓库中首次出现新的抽象类型 | v1.2 | | `first_time_resource_type` | 1.0 | 仓库中首次出现新的 Terraform 类型 | v1.2 | | `asg_unrestricted_scaling` | 1.0 | ASG 的 `max_size > 100` 且无 `min_size` 底线 | v1.3 | | `resource_removed` | 0.5 | 节点被移除（最多计入 2 条原因） | v1.0 | | `first_time_edge_pair` | 0.5 | 首次出现新的（提供者类型，提供者类型）边 | v1.2 | **库模式下的幻影永远不会被评分。** 受 `count = var.create ? 1 : 0` 保护的资源具有 `Attributes["conditional"] = true`；每条资源级规则在其上短路。图中仍会显示该幻影（带 `?` 前缀），以便审阅者看到条件意图而不会产生误报。 ## ⚙️ 配置（可选） 在 Terraform 根目录放置 `.architex.yml` 以微调引擎。每个字段均为可选；缺少该文件将逐字节复现 v1.2 行为。 ``` parser: mode: library # consumer (default) | library -- v1.3 rules: iam_admin_policy_attached: weight: 5.0 # bump default 3.5 -> 5.0 s3_bucket_public_exposure: enabled: false # silence the rule entirely thresholds: warn: 3.0 # >= warn -> medium / warn (default 3.0) fail: 7.0 # >= fail -> high / fail (default 7.0) ignore: paths: - "**/legacy/**" # parser skips matching .tf files suppressions: - rule: lambda_public_url_introduced resource: aws_lambda_function_url.maintenance reason: "Maintenance lambda; auth type is AWS_IAM" expires: "2026-12-31" # expired entries still drop the rule # but get an (EXPIRED) flag in the PR comment ``` 你也可以直接在资源块上方添加行内指令： ``` # architex:ignore=s3_bucket_public_exposure reason="Static docs site, intentional" resource "aws_s3_bucket_policy" "docs" { ... } ``` 被抑制的发现结果 **绝不会静默处理**：它们会以独立 **“已抑制发现”** 部分出现在 PR 评论中，并附带原因和来源。 ### 基线异常检测 三条 `first_time_*` 规则会读取可选的 `.architex/baseline.json` 快照，该快照记录了仓库历史上出现过的 *资源种类*、*抽象类型* 与 *边对*（不包含原始 HCL 或资源名称）。使用以下命令生成或扩展它： ``` architex baseline ./infra # writes ./infra/.architex/baseline.json architex baseline ./infra --merge # union with the existing snapshot ``` 将基线提交到你的 Terraform 代码中。此后，新出现的项会作为叠加在现有规则之上的低权重信号呈现——例如，一个从未有过入口点的仓库中新添加公网 CloudFront，会得到 `new_entry_point`（3.0）+ `first_time_abstract_type`（1.5）+ `first_time_resource_type`（1.0）= **5.5**，而非 3.0。 ## 💻 本地 CLI 使用 ``` # 一次构建 go build -o architex . # 为 Terraform 目录构建图谱 ./architex graph ./infra/ # 两个快照之间的语义差异 ./architex diff ./base ./head # 风险评估 ./architex score ./base ./head # 完整的 PR 就绪 Markdown 报告（附带 HTML 报告的审计包） ./architex report ./base ./head --out ./.architex/ # 净化的出口有效载荷（离开运行器的唯一字节） ./architex sanitize ./base ./head --salt my-salt # 将报告作为粘性 PR 评论发布（唯一的网络调用） GITHUB_TOKEN=ghp_xxx ./architex comment ./.architex// \ --repo my-org/my-repo --pr 42 --mode advisory ``` ## 🔒 信任模型 - **分析在运行器本地执行。** 解析、图构建、差异计算、风险评估与 Markdown 渲染均在 `architex` 二进制中完成。`.tf` 源码从未传输到任何外部位置。 - **唯一网络调用是 PR 评论。** `architex comment` 使用 `GITHUB_TOKEN` 将渲染后的 Markdown POST 到 GitHub REST API。该令牌与工作流中其他步骤使用的相同。 - **审计包始终会上传。** 每次运行都会生成带时间戳的包（`diagram.mmd`、`summary.md`、`score.json`、`egress.json`、`report.html`、`manifest.json`，含 SHA-256 校验和），并作为工作流产物上传。`report.html` 是一个无 JavaScript、无 CDN 脚本、无远程字体的自包含页面；在断网浏览器中打开即可查看完整报告。 详见 [master.md §6](master.md#6-trust-model-and-data-sanitization) 获取完整的信任模型、脱敏控制和出口规范。 ## 🗺 路线图 - **v1.0** — 可用的三层 AWS 范围（VPC、子网、安全组、EC2、ALB、RDS）。 - **v1.1** — AWS Top 10 扩展（S3、IAM、Lambda、API Gateway v2）。17 个资源，8 条规则。 - **v1.2** — 深度与可配置性：解析器深度（模块、count、for_each、dynamic）、`.architex.yml`、基线异常检测、自包含 HTML 报告。34 个资源，15 条规则。 - **v1.3** — （本版本）EKS + 自动伸缩组 + RDS 组，库模式解析，条件幻影渲染，强化自测。**45 个资源，18 条规则。** - **未来** — 多云支持（Azure/GCP 优先）、GitLab 与 Bitbucket 适配器、非 Terraform IaC。详见 [master.md §8](master.md#8-scope-and-roadmap)。 ## 🤝 贡献 请参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解设置、欢迎的 PR 类型以及指导项目的设计原则。 最能帮助项目的方式： 1. **提交 Issue**：描述你的使用场景、无法解析的 Terraform 模式、期望存在的规则，或导致信任受损的误报。 2. **发起 Discussion**：就更广泛的设计问题与提案展开讨论。 3. **提交 Pull Request**：附上测试的修复或新增功能。 ## 📄 许可证 [MIT](LICENSE) — 可自由使用、修改和分发，包括商业场景。

**为更愿看一张图表而非滚动 600 行计划的审阅者而构建。** ⭐ 如果 ArchiteX 为你节省了一次代码审阅，请给仓库一颗星。

标签：DevOps安全, ECS, EVTX分析, GitHub Action, HTML报告, Mermaid图, PR评论, SHA-256, Terraform, Terraform拓扑, 代码审查, 免费工具, 安全审查, 审计包, 无SaaS, 无付费层级, 无遥测, 日志审计, 本地运行, 架构防火墙, 确定性评分, 粘性评论, 风险评分