steadytao/planwright

Planwright 是一个本地优先的基础设施规划引擎。它将强类型计划和选定的基础设施即代码制品转换为可审查的架构图，然后生成证据：验证结果、安全说明、成本说明、丢失报告、图表和部署包。 Planwright 将基础设施转换视为迁移和证据问题，而不是语法转换问题。 - [安装说明](#installation) - [发布文件](#release-files) - [更新](#update) - [依赖项](#dependencies) - [编译](#compile) - [快速验证路径](#quick-proof-path) - [用法与选项](#usage-and-options) - [示例](#examples) - [Planwright 不适用的场景](#what-planwright-is-not) - [当前范围](#current-scope) - [兼容性](#compatibility) - [安全边界](#safety-boundaries) - [文档](#documentation) - [开发](#development) - [贡献](#contributing) - [治理](#governance) - [支持](#support) - [安全](#security) - [赞助](#sponsoring) - [许可证](#licence) - [更新日志](#changelog) # 安装说明 [](https://github.com/steadytao/planwright/releases/latest/download/planwright_windows_amd64.exe "Windows x64") [](https://github.com/steadytao/planwright/releases/latest/download/planwright_linux_amd64 "Linux x64") [](https://github.com/steadytao/planwright/releases/latest/download/planwright_darwin_arm64 "macOS Arm64") [](https://github.com/steadytao/planwright/tarball/main "源码 TAR 包") [](#alternatives "备用下载") [](https://github.com/steadytao/planwright/releases "所有版本") 您可以使用发布的二进制文件或通过从源码编译来安装 Planwright。 ## 发布文件 #### 推荐 文件 | 描述 :--- | :--- [planwright_windows_amd64.exe](https://github.com/steadytao/planwright/releases/latest/download/planwright_windows_amd64.exe) | Windows x64 独立可执行文件，推荐用于 Windows x64 [planwright_linux_amd64](https://github.com/steadytao/planwright/releases/latest/download/planwright_linux_amd64) | Linux x64 独立可执行文件，推荐用于 Linux x64 [planwright_darwin_arm64](https://github.com/steadytao/planwright/releases/latest/download/planwright_darwin_arm64) | macOS Apple Silicon 独立可执行文件，推荐用于 Apple Silicon Mac #### 备选 文件 | 描述 :--- | :--- [planwright_windows_arm64.exe](https://github.com/steadytao/planwright/releases/latest/download/planwright_windows_arm64.exe) | Windows Arm64 独立可执行文件 [planwright_linux_arm64](https://github.com/steadytao/planwright/releases/latest/download/planwright_linux_arm64) | Linux Arm64 独立可执行文件 [planwright_darwin_amd64](https://github.com/steadytao/planwright/releases/latest/download/planwright_darwin_amd64) | macOS Intel 独立可执行文件 [planwright_linux_amd64_desktop.zip](https://github.com/steadytao/planwright/releases/latest/download/planwright_linux_amd64_desktop.zip) | 包含 Planwright 图标的 Linux x64 桌面元数据包 [planwright_linux_arm64_desktop.zip](https://github.com/steadytao/planwright/releases/latest/download/planwright_linux_arm64_desktop.zip) | 包含 Planwright 图标的 Linux Arm64 桌面元数据包 [planwright_darwin_amd64_app.zip](https://github.com/steadytao/planwright/releases/latest/download/planwright_darwin_amd64_app.zip) | 包含 Planwright 图标的 macOS Intel `.app` 包 [planwright_darwin_arm64_app.zip](https://github.com/steadytao/planwright/releases/latest/download/planwright_darwin_arm64_app.zip) | 包含 Planwright 图标的 macOS Apple Silicon `.app` 包 #### 杂项 文件 | 描述 :--- | :--- [SHA2-256SUMS](https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS) | SHA-256 校验清单 [SHA2-256SUMS.sig](https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS.sig) | `SHA2-256SUMS` 的 OpenPGP 签名 [SHA2-512SUMS](https://github.com/steadytao/planwright/releases/latest/download/SHA2-512SUMS) | SHA-512 校验清单 [SHA2-512SUMS.sig](https://github.com/steadytao/planwright/releases/latest/download/SHA2-512SUMS.sig) | `SHA2-512SUMS` 的 OpenPGP 签名 [public.key](https://github.com/steadytao/planwright/releases/latest/download/public.key) | 发布公钥的便捷副本 [planwright_sbom.spdx.json](https://github.com/steadytao/planwright/releases/latest/download/planwright_sbom.spdx.json) | SPDX JSON SBOM [planwright_sbom.cdx.json](https://github.com/steadytao/planwright/releases/latest/download/planwright_sbom.cdx.json) | CycloneDX JSON SBOM Planwright 使用由维护者控制的 OpenPGP 发布密钥对校验清单进行签名。请将 [docs/releases/signing.md](docs/releases/signing.md) 中记录的指纹、维护者控制的公告或其他受信任的渠道作为信任根；`public.key` 仅为方便下载的发布资产。 在 Linux 上验证的示例： ``` curl -LO https://github.com/steadytao/planwright/releases/latest/download/public.key curl -LO https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS curl -LO https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS.sig gpg --import ./public.key gpg --verify ./SHA2-256SUMS.sig ./SHA2-256SUMS sha256sum -c ./SHA2-256SUMS --ignore-missing gh attestation verify ./planwright_linux_amd64 -R steadytao/planwright ``` 在 Windows 上验证的示例： ``` Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/public.key" -OutFile "public.key" Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS" -OutFile "SHA2-256SUMS" Invoke-WebRequest -Uri "https://github.com/steadytao/planwright/releases/latest/download/SHA2-256SUMS.sig" -OutFile "SHA2-256SUMS.sig" gpg --import .\public.key gpg --verify .\SHA2-256SUMS.sig .\SHA2-256SUMS (Get-FileHash .\planwright_windows_amd64.exe -Algorithm SHA256).Hash.ToLower() Select-String -Path .\SHA2-256SUMS -Pattern "planwright_windows_amd64.exe" gh attestation verify .\planwright_windows_amd64.exe -R steadytao/planwright ``` # 更新 Planwright 目前不包含自更新命令。请在验证校验清单后，下载新的发布二进制文件并替换旧的可执行文件。 # 依赖项 Planwright 发布的二进制文件旨在无需安装 Terraform、OpenTofu、AWS CLI、kubectl、Helm、Kustomize、OPA 或 Rego 的情况下运行。这些工具目前不会被 Planwright 调用；但在 Planwright 周围，它们在准备输入文件或审查生成的输出时可能仍然有用。 对于从源码构建，请安装： - [go.mod](go.mod) 中声明的 Go 版本 - Git - 如果您想验证发布清单，请安装 OpenPGP 工具，例如 GnuPG # 编译 从源码构建 CLI： ``` git clone https://github.com/steadytao/planwright.git cd planwright go build -o planwright ./cmd/planwright ./planwright version ``` 在 Windows 上： ``` git clone https://github.com/steadytao/planwright.git cd planwright go build -o planwright.exe ./cmd/planwright .\planwright.exe version ``` # 快速验证路径 Planwright 最快且实用的路径是 AWS Web 应用示例： ``` go run ./cmd/planwright validate examples/aws-webapp-basic/planwright.yaml go run ./cmd/planwright risks examples/aws-webapp-basic/planwright.yaml go run ./cmd/planwright cost-notes examples/aws-webapp-basic/planwright.yaml go run ./cmd/planwright generate terraform examples/aws-webapp-basic/planwright.yaml --out ./generated/terraform go run ./cmd/planwright generate mermaid examples/aws-webapp-basic/planwright.yaml --out ./generated/diagrams go run ./cmd/planwright pack examples/aws-webapp-basic/planwright.yaml --out ./planwright-pack ``` 该路径会产生： - 验证输出 - Markdown 安全和成本说明 - 面向 Terraform/OpenTofu 的审查文件 - Mermaid 架构图 - 一个基于目录的 Planwright 包，包含清单、图、报告、生成的文件和图表 请在 [examples/aws-webapp-basic/README.md](examples/aws-webapp-basic/README.md) 中阅读完整的演练。 # 用法与选项 Planwright 是 CLI 优先的。当前的命令接口包含： ``` planwright validate planwright validate-graph planwright explain planwright generate terraform --out planwright generate mermaid --out planwright risks planwright cost-notes planwright docs check [path ...] planwright import cloudformation --out --loss-report planwright import sam --out --loss-report planwright import k8s --out --loss-report planwright import awsscan --out --loss-report planwright diff --out planwright schema graph --out planwright policy profiles planwright policy graph --profile --out --sarif planwright pack --out planwright review terraform-plan --out --sarif planwright review terraform-state --out --loss-report planwright serve [project-dir] [--addr 127.0.0.1:5786] planwright version ``` 计划中的命令（例如 `tui`、`scan aws`、`generate kubernetes`、自定义策略包以及 OPA/Rego 策略执行）不属于当前实现的一部分。 # 示例 典型演练： - [examples/aws-webapp-basic/README.md](examples/aws-webapp-basic/README.md)，由兼容性测试夹具覆盖的典型验证路径 验证示例计划： ``` go run ./cmd/planwright validate examples/aws-webapp-basic/planwright.yaml ``` 生成面向 Terraform/OpenTofu 的审查文件： ``` go run ./cmd/planwright generate terraform examples/aws-webapp-basic/planwright.yaml --out ./generated/terraform ``` 生成 Mermaid 图表： ``` go run ./cmd/planwright generate mermaid examples/aws-webapp-basic/planwright.yaml --out ./generated/diagrams ``` 创建本地 Planwright 包目录： ``` go run ./cmd/planwright pack examples/aws-webapp-basic/planwright.yaml --out ./planwright-pack ``` 审查 Terraform plan JSON 测试夹具： ``` go run ./cmd/planwright review terraform-plan examples/terraform-plan-risk-review/tfplan.json --out ./generated/terraform-review.md --sarif ./generated/planwright.sarif ``` 审查 Terraform state JSON 测试夹具： ``` go run ./cmd/planwright review terraform-state examples/terraform-state-inventory/state.json --out ./generated/terraform-state.md --loss-report ./generated/terraform-state-loss.md ``` 启动当前的本地浏览器工作台： ``` go run ./cmd/planwright serve . --addr 127.0.0.1:5786 ``` # 当前范围 Planwright 处于 v0.14 Terraform/OpenTofu 状态清单阶段。当前的重点是安全地读取本地 state JSON、生成可审查的清单证据，并将图降维、provider schema 获取和 Terraform/OpenTofu 执行排除在范围之外，直到后续阶段。 当前已实现的接口： - Go CLI - `planwright.v1` 强类型计划解析器 - `planwright.graph.v1` 架构图模型 - JSON Schema 2020-12 导出和本地图验证 - 首个 AWS Web 应用模式的图降维 - 针对该首个 AWS 模式的面向 Terraform/OpenTofu 的审查输出 - Mermaid 架构图输出 - 用于安全、成本、可部署性、清理和假设的 Markdown 报告 - 基于目录的 Planwright 包输出 - 带有丢失报告的 CloudFormation 和 SAM 子集导入 - 带有 Gateway API 和 Cilium 清单支持的已渲染 Kubernetes 清单导入 - 从选定的 AWS CLI JSON 制品导入本地 AWS 扫描包 - 带有 Markdown 和 SARIF 输出的 Terraform plan JSON 审查 - 带有 Markdown 丢失报告的 Terraform/OpenTofu state JSON 清单 - 本地图 JSON 差异审查 - 内置的 `lab`、`small-business` 和 `production` 策略配置文件审查 - 通过 `planwright serve` 实现的文本和表格本地浏览器工作台 - 用于测试、Linting、静态分析、漏洞、文档、工作流验证和供应链卫生的 GitHub Actions CI 重要的延期接口： - Terraform 状态导入 - Terraform HCL 或模块评估 - Terraform provider schema 获取 - Pulumi 导入 - Kubernetes 生成 - Kubernetes 实时集群扫描 - 实时 AWS 账户扫描 - AWS SDK 集成 - AWS 凭据加载 - 完整的 CloudFormation 或 SAM 导入 - 无损转换或往返导入 - zip 归档包输出 - 托管演示 - 拖拽式可视化画布编辑 - 资源卡片图规划 - Terraform/OpenTofu 执行 - 实时漂移证明 - 自定义策略包 - OPA/Rego 集成 - 合规性认证 - 可复现构建保证 # 兼容性 级别 | 含义 :--- | :--- 0 | 仅作为原始源代码保留 1 | 已解析语法 2 | 已提取资源清单 3 | 已推断关系 4 | 已降维到 Planwright 图 5 | 已生成为其他格式 6 | 已使用测试夹具进行往返测试 7 | 已在沙箱中进行可部署性测试 8 | 已进行生产环境配置验证 当前的支持是故意不完整的。强类型计划路径在首个内置 AWS Web 应用模式上达到了级别 5。CloudFormation、SAM、已渲染的 Kubernetes 清单和本地 AWS 扫描包在其支持的子集上达到了级别 4。Terraform plan JSON 审查为级别 2 以及选定的审查发现，因为它目前尚未将 Terraform 计划降维到 Planwright 图中。 有关矩阵和当前限制，请参见 [docs/compatibility.md](docs/compatibility.md)。 # 安全边界 Planwright 默认执行本地分析。 在当前实现中，它： - 读取显式的本地计划、图、模板、清单和扫描包文件 - 输出本地验证、审查和解释结果 - 仅在被明确要求时写入本地生成的制品 - 仅在被明确启动时运行仅限环回的本地浏览器工作台 - 拒绝本地 Web 服务器中意外的 Host 标头 - 不读取云凭据 - 不联系云 API - 不联系 Kubernetes 集群 - 不部署或销毁基础设施 - 不执行导入的内容 - 不运行 AWS CLI、AWS SDK、`kubectl`、Helm、Kustomize、Terraform、OpenTofu、OPA 或 Rego - 不证明合规性 未来的实时扫描功能必须默认保持只读，并且需要显式的账户、区域和身份确认。 # 文档 请从 [docs/README.md](docs/README.md) 开始。 核心文档： - [docs/roadmap.md](docs/roadmap.md)，完整的版本控制路线图 - [docs/compatibility.md](docs/compatibility.md)，兼容性矩阵和导入边界 - [docs/architecture/design.md](docs/architecture/design.md)，引擎设计和产品边界 - [docs/architecture/threat-model.md](docs/architecture/threat-model.md)，当前的优先威胁模型 - [docs/architecture/decisions/](docs/architecture/decisions/)，ADR - [docs/releases/README.md](docs/releases/README.md)，发布流程 - [docs/releases/signing.md](docs/releases/signing.md)，发布签名模型 # 开发 实用的本地检查： ``` go test ./... go vet ./... go build ./cmd/planwright golangci-lint config verify --config .github/config/golangci.yml golangci-lint fmt --config .github/config/golangci.yml --diff golangci-lint run --config .github/config/golangci.yml go test -race ./... staticcheck ./... gosec ./... govulncheck ./... go mod verify go mod tidy -diff go run ./cmd/planwright docs check . npx --yes cspell@10.0.1 lint "**/*.md" ".github/**/*.yml" ".github/**/*.yaml" --config .github/config/cspell.json --no-progress --no-summary --no-must-find-files python3 .github/scripts/ci/check_action_pins.py python3 .github/scripts/ci/check_file_headers.py python3 .github/scripts/release/generate_contributors.py --check actionlint pre-commit run --all-files ``` 每个路线图版本在下一个版本开始之前，都必须完成针对安全性、正确性、兼容性、文档一致性和意外生成制品的全面代码库检查。 # 治理 治理记录在 [docs/project/GOVERNANCE.md](docs/project/GOVERNANCE.md)、[docs/project/MAINTAINERS.md](docs/project/MAINTAINERS.md) 和 [.github/CODEOWNERS](.github/CODEOWNERS) 中。 # 支持 支持期望记录在 [.github/SUPPORT.md](.github/SUPPORT.md) 中。 # 安全 请不要在公共问题中报告安全漏洞。 有关报告指南，请参见 [.github/SECURITY.md](.github/SECURITY.md)。 # 许可证 Planwright 在 Apache License 2.0 下发布。请参见 [LICENSE](LICENSE)。 [AUTHORS](AUTHORS) 是经过整理的用于版权目的的作者列表。 [CONTRIBUTORS](CONTRIBUTORS) 是贡献者表彰名单。 # 更新日志 请参见 [CHANGELOG.md](CHANGELOG.md)。

标签：EVTX分析, Go语言, 成本分析, 文档结构分析, 日志审计, 本地化, 架构图, 程序破解, 自动化验证