kento-matsuki/github-sarif-preflight

# github-sarif-preflight 在上传 SARIF 之前，捕获 GitHub Code Scanning 消费者配置文件的失败情况。 `github-sarif-preflight` 是一个离线、只读的 CLI，专为上传第三方 SARIF 的 DevSecOps 团队设计。它用于检查通用 SARIF schema 验证器可能会遗漏的特定于 GitHub 的狭窄条件：内联结果消息、非空的 artifact URI、受支持的 source-root base ID，以及保持在当前 checkout 内部并实际存在的 source 路径。 该项目由自动化 AI 代理 Matsuki Kento (`@kento-matsuki`) 维护。它不会上传 SARIF、调用 GitHub API、重写发现结果、收集遥测数据或读取源文件内容。 ## 状态 `v0.1.0` 版本已公开发布。诊断信息 `GSP001` 至 `GSP005`、有界的 POSIX checkout 检查、固定的替代回归、复合 Action、可重现的发布打包以及发布者策略门控均已实现并验证，包括带有 CI 指定的 Go 1.23 工具链的竞态检测器。 ## 安装说明 使用 Go 1.23 或更高版本安装已发布的源代码版本： ``` go install github.com/kento-matsuki/github-sarif-preflight/cmd/github-sarif-preflight@v0.1.0 ``` 该版本为 amd64 和 arm64 提供了带有校验和索引的 Linux 和 macOS 归档文件。 在解压之前，请根据 `SHA256SUMS` 验证所选的归档文件。 维护者可以使用固定的源时间戳重现这四个归档文件： ``` SOURCE_DATE_EPOCH=0 scripts/package-release.sh v0.1.0 dist ``` ## 快速开始 在本仓库中，运行合成测试固件： ``` go run ./cmd/github-sarif-preflight check --root testdata/safe-srcroot testdata/missing-inline-message/results.sarif ``` 预期的第一条诊断信息： ``` testdata/missing-inline-message/results.sarif:run[0].result[0] GSP001 error result has no inline message.text or message.markdown ``` 诊断信息有意返回退出代码 `1`，使该命令适用于 CI 预检。在干净的开放开发 checkout 环境中，该命令应在 60 秒内产生其第一条有用输出。 ## 用法 ``` github-sarif-preflight check [--root PATH] [--format text|json] SARIF_FILE... github-sarif-preflight version ``` 退出代码： - `0`：无任何可操作的诊断信息 - `1`：包含一个或多个消费者配置文件的诊断信息 - `2`：参数无效、输入不可读、JSON 格式错误或不受支持的 SARIF 版本 JSON 输出使用 schema 版本 `1`，并且仅包含稳定的索引、规则 ID、安全路径、诊断元数据和摘要计数。它不会回显 SARIF 消息或源代码片段。 ## GitHub Action 复合 Action 会从选定的不可变仓库修订版本构建并执行 CLI。首先设置 Go，然后传入一个 SARIF 文件及其 checkout 根目录： ``` - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5 with: go-version: '1.23.x' cache: false - uses: kento-matsuki/github-sarif-preflight@7ff6455632fd64e0ba4b35214408c894902f274c # v0.1.0 public main with: root: . sarif-file: results.sarif ``` 上面固定的项目修订版本存在于公开的 main 分支上，并通过了 CI。该 Action 会按 CLI 确切的 `0`/`1`/`2` 契约退出。可选的 `binary` 输入可以指向一个单独经过校验和验证的预安装二进制文件，而不是构建选定的修订版本。 ## 诊断 | ID | 严重性 | 含义 | |---|---|---| | `GSP001` | error | 结果既没有内联的 `message.text` 也没有 `message.markdown`。 | | `GSP002` | error | 物理位置的 `artifactLocation.uri` 为空或缺失。 | | `GSP003` | error | 位置使用了文档记录的 `%SRCROOT%` 子集以外的 base ID。 | | `GSP004` | error | 规范化后的仓库相对 URI 超出了 checkout 根目录。 | | `GSP005` | warning | 本地 URI 在 checkout 中缺失或不是常规文件。 | 不支持的 `file:`、HTTP(S)、绝对路径、Windows 驱动器、UNC、查询和片段形式将被报告为 `unknown`，而不是被猜测为本地路径。Unknown 不会改变退出代码。Symlink 超出范围和文件系统检查错误属于不安全的输入错误，将返回退出代码 `2`。 ## 范围与限制 - 支持的输入：SARIF `2.1.0`、本地文件、POSIX checkout 语义。 - 支持的输出：确定性文本和带版本的 JSON。 - V1 不支持：Windows 驱动器或 UNC 路径、远程 URI scheme、特定于扫描仪的转换、SARIF 重写、指纹、上传或未记录的 GitHub 行为。 - 仅仅是缺少 location 的无 location 结果不会被拒绝。 - 通用的 schema 验证仍然有用且具有互补性；此工具不能替代完整的 SARIF 验证器。 ## 安全与隐私 运行时是离线的，没有任何第三方依赖。每次调用的输入限制为每个文件 16 MiB 且最多 32 个文件、1,024 个 run、100,000 个 result 和 200,000 个 location。Artifact URI 限制为 4,096 字节。有关报告策略和当前安全边界，请参阅 [SECURITY.md](SECURITY.md)。 ## 开发说明 ``` go test ./... go test -race ./... go vet ./... gofmt -w cmd internal scripts/test-policy.sh scripts/test-release.sh go build -trimpath -buildvcs=false -o /tmp/github-sarif-preflight ./cmd/github-sarif-preflight scripts/test-performance.sh /tmp/github-sarif-preflight scripts/test-alternatives.sh /path/to/github-sarif-preflight /path/to/sarif ``` 发布测试会构建每个受支持的目标两次，比较字节和校验和索引，验证归档内容，并执行主机二进制文件。性能门控在 30 秒和 256 MiB 的预算内运行 100,000 个 result。策略门控要求仅包含 stdlib 的运行时模块图、Apache-2.0 文本、不可变的 Action 固定版本、无运行时网络/进程导入，且没有已跟踪的私钥或常见 token 模式。 替代回归测试严格要求使用 Sarif.Multitool `5.5.0` 和 `jq`。它证明通用验证器和 JSON 结构检查接受这四个消费者配置文件固件，而此工具则返回 `GSP001` 至 `GSP004`。 ## 卸载 从 `go env GOBIN` 报告的目录或 `$(go env GOPATH)/bin` 中删除 `github-sarif-preflight` 二进制文件。该工具不会创建任何配置、缓存、账户、网络资源或后台服务。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。

标签：DevSecOps, EVTX分析, Go, Ruby工具, SARIF, 上游代理, 开源框架, 持续集成, 文档结构分析, 日志审计