Scorecard 检查项怎样辅助仓库治理

Scorecard 检查项怎样辅助仓库治理？关键不是把仓库追到一个漂亮的总分，而是把每个检查项当成一条可以解释、可以分派、可以复查的治理信号。比如分支保护回答“重要分支是否有变更门槛”，令牌权限回答“自动化任务是否拿到了超出需要的权限”，依赖更新和签名发布则分别回答“依赖是否有人维护”和“交付物能否追溯”。

官方地址：https://github.com/ossf/scorecard/

官方 Action：https://github.com/ossf/scorecard-action

实际落地时，先按风险和仓库场景筛出要治理的检查项，再为每项写清证据、负责人、动作和复查条件。低分是待调查信号，不是脱离上下文的安全结论。

先确定 Scorecard 能回答什么

Scorecard 的检查结果适合放进仓库治理台账，因为它们通常对应仓库里能观察到的开发、构建或发布实践。官方检查文档为每项检查说明了风险、评分依据和修复方向，维护者可以据此回答“当前缺了什么”“缺口对应哪类风险”“下一步能改哪个仓库对象”。

但它不是万能扫描器。某个检查项只观察自己能够识别的证据，其他工具或自定义流程可能无法被自动识别；官方入门文档也提醒，不是所有检查项都适合所有项目。例如单人维护的仓库不一定适合把多人代码评审作为硬门槛，某些语言生态也不适用特定的依赖检查。

所以，治理台账至少要把三个概念分开：

按风险把检查项分成治理分组

仓库治理比按检查名称逐条浏览更适合按风险分组。下面的分组不是 Scorecard 的官方等级，而是一种方便分派工作的内部视图：先保护变更入口，再收紧自动化边界，最后补齐发布与响应证据。

分组的价值在于避免“看到一个低分就马上加规则”。例如，先处理 Token-Permissions 和 Dangerous-Workflow，通常比先在 README 中增加一个徽章更接近变更入口；而 Signed-Releases 与 SBOM 更适合由发布负责人和构建负责人共同维护。

优先处理能改变变更入口的检查项

一份可执行的第一轮治理清单，可以优先放四项。它们的共同点是：能对应到具体仓库设置、工作流或依赖文件，整改后也比较容易留下证据。

1. Branch-Protection：检查重要分支是否禁止强制推送、禁止删除，是否要求 Pull Request、评审和状态检查。它保护的是代码进入默认分支的入口。
2. Code-Review：检查近期变更是否出现人工评审证据。自动化机器人自己的评论不能简单等同于第二位理解代码的人。
3. Token-Permissions：检查工作流是否在顶层默认只读，并把必要的写权限收窄到具体任务。不要把整个工作流设置成 write-all 来省事。
4. Dependency-Update-Tool：检查是否启用 Dependabot 或 Renovate 一类的依赖更新入口。它证明的是工具已配置，不代表每一个更新都已经被合并。

这四项可以组成一个最小治理单元：变更需要经过规则，规则需要评审，自动化只拿必要权限，依赖则有持续更新入口。遇到低分时，不要只记“分数低”，而要记录具体缺口，例如“默认分支未要求状态检查”或“工作流顶层权限未声明”。

把低分项映射成证据和负责人

检查结果只有进入责任分工后才会产生治理价值。建议给每个待处理项固定五个字段：check 表示检查名，evidence 表示缺口证据，owner 表示负责人，remediation 表示动作，review_cadence 表示复查周期。

下面是一个治理台账的最小形状。它是普通 JSON，必须保持严格有效，因此不在代码块里加入注释；字段解释放在代码块外。

{
  "check": "Token-Permissions",
  "evidence": "工作流顶层没有只读 permissions 声明",
  "owner": "CI 维护者",
  "remediation": "改为顶层只读，并在具体 job 申明必要写权限",
  "review_cadence": "每次新增工作流和每月复查"
}

evidence 要写成能被另一个人复查的事实，不要写“安全性不足”这种没有对象的判断；remediation 要指向仓库里的文件、设置或发布流程；review_cadence 则防止规则改完一次就无人维护。

如果一个检查项在当前仓库确实不适用，也要把理由写进台账，而不是静默忽略。例如，单人项目可以记录“当前没有第二位维护者，代码评审不作为硬门槛；保留 Pull Request 记录并在贡献者增加时复评”。这样做的重点不是把分数刷高，而是让例外有上下文、有责任人、有触发条件。

用 GitHub Action 固定检查入口

如果仓库托管在 GitHub，可以用官方 Scorecard Action 把结果写成 SARIF，并上传到代码扫描页面。工作流本身也是治理对象，因此示例需要同时表达最小权限、固定 Action 引用和结果文件去向。

下面的 YAML 展示的是结构示例：顶层权限保持只读，分析 job 只声明上传扫描结果和发布结果所需的权限，Action 使用完整提交 SHA 固定版本。示例中的 SHA 用于说明固定引用写法，落地时应从官方仓库当前工作流或发布信息中选定实际提交。

name: OpenSSF Scorecard

on:
  push:
    branches: [main]
  schedule:
    - cron: "30 1 * * 6" # 中文注释：定期重跑，避免治理结果只停留在某次提交

# 中文注释：工作流默认只读，避免新 job 意外继承写权限
permissions: read-all

jobs:
  analysis:
    runs-on: ubuntu-latest
    permissions:
      security-events: write # 中文注释：允许把 SARIF 送入代码扫描
      id-token: write         # 中文注释：发布结果时用于获取 OIDC 身份
    steps:
      - name: Checkout
        uses: actions/checkout@
        with:
          persist-credentials: false # 中文注释：不让 checkout 凭据继续留在工作区

      - name: Run Scorecard
        uses: ossf/scorecard-action@
        with:
          results_file: results.sarif
          results_format: sarif
          publish_results: true # 中文注释：需要公开发布结果时才打开该选项

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@
        with:
          sarif_file: results.sarif

这段工作流表达了四个治理关系：仓库代码被读取，Scorecard 产生结果，SARIF 进入代码扫描，发布结果则使用单独的身份权限。官方 Action 文档还对发布结果的工作流结构有额外限制，不能把任意脚本和容器步骤塞进同一个分析 job；实际部署前要按官方示例调整。

把 SARIF 和检查详情接入复查

运行入口建立后，治理工作不应只看徽章。建议把一次检查结果拆成三类状态：

• 可修复：证据明确、对象明确，例如工作流顶层权限过宽、没有 SECURITY.md 或发布物没有签名附件。
• 需解释：工具没有识别到证据，但团队确实通过另一种方式完成，例如自建依赖更新服务或非默认的发布系统。
• 不适用：检查的前提不符合仓库类型或团队规模，需要记录理由和未来重新评估的触发条件。

这样处理的好处是，SARIF 负责让技术结果进入统一入口，治理台账负责让结果变成工作。对于同一个低分项，前者告诉你“哪里可能有问题”，后者告诉你“谁在什么时候做什么”。

不要把总分当成唯一门禁

Scorecard 检查项的评分是有上下文的。官方文档明确指出，检查可能只覆盖特定托管平台、特定文件位置或有限的近期提交；某些检查对其他工具的识别也可能不完整。因此，不建议设置“总分低于某个数就一律拒绝”的单一门禁。

更稳妥的门禁方式是对高风险对象单独设规则：

这类门禁更接近风险控制：即使总分变化，关键入口的保护也不会因为某一项不适用而被误判；同时，维护者也不会为了维持一个数字而引入不适合项目规模的流程。

最后用一张清单收口

把 Scorecard 接入仓库治理后，可以用下面的顺序做一次人工复查：

1. 确认当前仓库类型、托管平台、维护者规模和发布方式，先排除天然不适用的检查。
2. 优先查看 Branch-Protection、Code-Review、Token-Permissions 和 Dangerous-Workflow 的具体证据。
3. 为每一个待处理项补齐证据、负责人、整改动作和复查周期，而不是只复制总分。
4. 让官方 Action 输出 SARIF，并把代码扫描、工作流运行记录和发布结果放到团队能看到的入口。
5. 对误报、未知和例外保留解释，仓库结构或维护者规模变化时重新评估。

归根结底，Scorecard 最有价值的地方是把“仓库治理做得好不好”拆成了若干可以讨论的检查项。把检查项连接到证据、责任人和复查条件后，它才会从一个分数页面变成持续改进的工作清单。

相关问题

• Scorecard 分数低就代表仓库不能使用吗？不代表。应先看具体检查项、适用范围、证据质量和项目自身的风险策略。
• 可以只启用总分门禁吗？不建议。对分支保护、工作流权限和发布证据分别设门禁，通常比一个总分阈值更容易解释。
• 没有识别到自建工具时怎么办？保留工具产生的证据、在治理台账写明替代方案，并把该项标为需解释而不是直接当作已通过。
• 为什么要固定 GitHub Action 的提交 SHA？固定引用可以降低依赖漂移，方便复查某次工作流实际使用的 Action 代码。