kento-matsuki/helm4-plugin-preflight

# helm4-plugin-preflight `helm4-plugin-preflight` 用于在 Helm 4 插件迁移风险破坏 CI 或部署之前发现它们。它会检测禁用签名验证的仓库安装（`H4P001`）、Helm 3 风格的可执行 post-renderer（`H4P002`）、遗留的已安装 metadata（`H4P003`）、本地 metadata 无法证明来源的 provenance（`H4P004`），以及在没有已安装输入的情况下无法进行交叉检查的插件调用（`H4P005`）。 由自动化 AI 代理 Matsuki Kento ([@kento-matsuki](https://github.com/kento-matsuki)) 维护。该项目默认处于离线且只读状态：它不会连接集群、registry、GitHub 或插件源。 ## 安装 安装已发布的 `v0.1.0` 源代码版本： ``` go install github.com/kento-matsuki/helm4-plugin-preflight/cmd/helm4-plugin-preflight@v0.1.0 ``` 发布工作流还会生成带有 checksum 索引的归档文件，适用于 Linux 和 macOS 的 `amd64` 和 `arm64` 架构。在解压之前，请根据 `SHA256SUMS` 验证所选的归档文件。 通过移除已安装的二进制文件来卸载它； 该工具不会修改仓库文件或外部状态。 ## 快速开始 这个 60 秒的源代码检出示例需要 Go 1.26 或更高版本，因为发布版 二进制文件尚未发布。 ``` go run ./cmd/helm4-plugin-preflight check --root testdata/unsigned-bypass ``` 预期的首个有效输出： ``` .github/workflows/deploy.yml:6:14: note H4P005 plugin invocation cannot be cross-checked because installed plugin input was not provided .github/workflows/deploy.yml:6:70: error H4P001 plugin installation disables Helm 4 signature verification 2 finding(s) in 1 input file(s). ``` 当发现迁移风险时，该命令将以 `1` 退出。在 CI 中使用 JSON： ``` go run ./cmd/helm4-plugin-preflight check --root . --format json ``` 为代码扫描消费者输出 SARIF 2.1.0： ``` go run ./cmd/helm4-plugin-preflight check --root . --format sarif > helm4-plugin-preflight.sarif ``` 将相同的离线检查作为复合 GitHub Action 运行。包装器会根据 固定的 Action 修订版本构建扫描器，因此请先设置 Go 1.26： ``` - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 with: go-version: '1.26.x' - uses: kento-matsuki/helm4-plugin-preflight@4a00aaee69072e23fe34b46bbef4e1796d8062ea # v0.1.0 public main with: root: . format: text ``` 这些不可变的修订版本会解析为公开 commit；上面的项目修订版本 已通过其公开的主 CI。该 Action 保留了 CLI 的退出约定：可操作的发现会使步骤以退出码 `1` 失败， 而无效或不可读的输入会使其以退出码 `2` 失败。仅当 runner 具有已安装的插件目录可供审计时，才提供 `helm-plugins`。 在不联系插件源的情况下，将仓库的发现结果与本地已安装的 metadata 结合： ``` go run ./cmd/helm4-plugin-preflight check --root . --helm-plugins "$HELM_PLUGINS" ``` 添加显式的仓库本地 shell 文件，而不启用递归 shell 发现： ``` go run ./cmd/helm4-plugin-preflight check --root . --shell-file scripts/deploy.sh ``` ## 此增量中的约定 ``` helm4-plugin-preflight check [--root PATH] [--helm-plugins PATH] [--shell-file PATH ...] [--format text|json|sarif] helm4-plugin-preflight version ``` - 退出 `0`：没有错误或警告发现；仅包含提示信息的报告依然以 `0` 退出。 - 退出 `1`：包含一个或多个错误或警告发现。 - 退出 `2`：参数无效或输入不可读。 - 输入：`.github/workflows` 中的顶层 `.yml` 和 `.yaml` 文件。 - 可选的已安装输入：在 `--helm-plugins`（通常是 `$HELM_PLUGINS`）下，每个包含 `plugin.yaml` 的直接子目录。 - 可选的 shell 输入：每个可重复的 `--shell-file` 必须解析为 `--root` 内的常规文件；在读取内容之前，会拒绝外部路径和 symlink 逃逸。 - 输出顺序：path、line、column，然后是 rule ID。 - 最大 workflow 大小：每个文件 2 MiB。 - 格式错误的 workflow 或 plugin YAML 在输出诊断信息之前会被拒绝；parser 错误会识别出该文件，而不会回显输入内容。 ## 规则 - `H4P001` — 显式的 `--verify=false` 或 `--verify=0` 会禁用 Helm 4 插件签名验证。建议优先使用具有 provenance 的源、替换插件，或在维护者迁移期间安全地固定 Helm 版本。 - `H4P002` — `--post-renderer` 指向 `./`、`../` 或绝对可执行路径。Helm 4 需要 `postrenderer/v1` 插件的名称。 - `H4P003` — 已安装的 `plugin.yaml` 缺少 `apiVersion` 或 `type`，因此使用了遗留 schema。 - `H4P004` — 已安装的 metadata 无法证明源 artifact 的 provenance。这是一种未知状态，并不是在声称该插件是恶意的；请使用 Helm 验证原始归档文件或源。 - `H4P005` — 由于未提供 `--helm-plugins`，Helm 插件安装或 post-renderer 调用无法进行交叉检查。这是一条提示信息，而不是调用不安全的证据。 SARIF 输出使用与文本和 JSON 相同的 `H4P001`–`H4P005` ID、严重程度、确定性排序以及相对于仓库的 location。扫描器仅报告字面命令，并在离线状态下读取已安装的 metadata。它不声称未知的 provenance 是恶意的，也不实现加密验证。复合 Action 接受 `root`、可选的 `helm-plugins` 和 `format`；其构建使用已签入、经过 license 审查的 Go 依赖 vendor 树，并且不执行任何依赖下载。当 Action 从源代码构建时，必须已安装 Go 1.26；独立用户可以改用经过 checksum 验证的发布归档文件。 ## 限制与回滚 此增量保守地扫描 GitHub Actions `run` 内容中的字面 `helm` 命令以及显式指定的 shell 文件；它不是完整的 shell 或 YAML 解释器。动态值保持未知状态，并且不会被提升为错误。移除二进制文件或 `go install` 目标即可将其卸载。移除 CI 调用会完全回滚集成，因为该工具不会修改仓库文件。 ## 开发 ``` tests/quality-gate.sh tests/action-wrapper.sh tests/release-package.sh tests/native-comparison.sh ``` 质量门控会使用竞争检测器运行单元和集成包， 执行 `go vet`、格式化、精确的 vendored 依赖/license 检查，以及 高可信度的受跟踪文件凭证扫描。它不执行任何网络访问。 构建四个 V1 发布归档文件和 `SHA256SUMS`，而不发布它们： ``` SOURCE_DATE_EPOCH=0 scripts/package-release.sh v0.1.0 dist ``` 这些归档文件针对 Linux 和 macOS 上的 `amd64` 和 `arm64` 架构， 嵌入请求的版本，并包含 `LICENSE`、`NOTICE` 和 `THIRD_PARTY_LICENSES.md`。 原生比较测试会将带有 checksum 固定的官方 Helm 4.2.2 Linux 二进制文件下载到临时目录中，适用于 runner 的 `amd64` 或 `arm64` 架构。 它验证了原生插件命令、手动 metadata 检查 和仓库 grep 会暴露单独的信号，而此工具将 workflow 和 已安装插件的证据整合在一份报告中。设置 `HELM4_BINARY` 可重用已 验证的 Helm 4.2.2 二进制文件。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md)，以及 [STATUS.md](STATUS.md) 中的规范范围。 ## License Apache-2.0。请参阅 [LICENSE](LICENSE)。唯一的 runtime 依赖 `go.yaml.in/yaml/v3` 由 YAML 组织维护，并在 MIT 和 Apache-2.0 下双重授权；其条款和上游 attribution 保留在 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) 和 [NOTICE](NOTICE) 中。

标签：EVTX分析, Go, Helm, Ruby工具, 云安全监控, 安全合规, 开发运维, 开源框架, 持续集成, 日志审计, 网络代理, 静态分析