OpenSSF Scorecard 怎样把依赖安全信号放入审查流程

如果团队把第三方依赖当成黑盒，只看版本号和漏洞列表，审查往往会漏掉构建权限、发布签名、分支保护以及工作流写权限等问题。OpenSSF Scorecard 的价值，是把这些软件供应链实践拆成可解释的检查项，再交给工程团队判断风险和安排修复。

官方地址：https://scorecard.dev/

官方仓库：https://github.com/ossf/scorecard

Scorecard 的总分适合做筛选信号，不适合直接当作“安全”或“不安全”的裁决。真正可落地的做法是：先看高风险单项，再确认检测范围和例外原因，最后把结论写进审查记录与修复 PR。

一、先分清总分、单项分数和风险等级

Scorecard 的每个自动检查都会返回 0 到 10 的分数，并带有风险等级；这些结果再汇总成整体分数。高风险检查反映的是更容易被利用、或一旦被利用影响更大的工程环节。例如代码审查、分支保护、令牌权限、依赖固定和发布签名，通常比“是否声明许可证”更值得优先看。

因此，阅读结果时不要只问“总分是多少”，而要问三个问题：

• 哪个检查项失分，具体检测到了什么文件、工作流或仓库事实？
• 这个检查项的风险等级是什么，是否会直接影响构建、发布或依赖更新？
• Scorecard 是否支持当前项目的托管平台、发布方式和工具链？

二、依赖审查优先看哪些检查项

围绕“依赖是否值得进入构建和发布链路”这个问题，可以先筛出一组紧凑的检查项：

这张表不是“必须全部满分”的清单。例如库项目可能没有传统意义上的发布包，或某种发布方式暂时不在自动检测范围内。检查结果只负责提出可追问的线索，最终结论仍要结合项目的真实交付方式。

三、用 GitHub Action 把结果留在工程系统里

官方 Action 支持把结果保存为 JSON 或 SARIF。团队若要在代码扫描界面集中查看结果，通常选择 SARIF；若要在内部系统做二次聚合，可保留 JSON。下面是一个缩减后的工作流示例，版本号和 Action 提交引用应以官方仓库的当前发布说明为准。

name: OpenSSF Scorecard

on:
  push:
    branches: [main]
  schedule:
    - cron: "15 7 * * 1"

# 默认只读，避免整个工作流继承不必要的写权限。
permissions: read-all

jobs:
  scorecard:
    runs-on: ubuntu-latest
    permissions:
      # 上传 SARIF 与发布结果分别需要明确声明权限。
      security-events: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          # 不把仓库凭据留在后续步骤的工作区中。
          persist-credentials: false
      - uses: ossf/scorecard-action@v2.5.0
        with:
          # SARIF 便于接入代码扫描界面，文件名保持稳定方便归档。
          results_file: results.sarif
          results_format: sarif
          publish_results: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          # 只上传本次 Scorecard 生成的结果文件。
          sarif_file: results.sarif

生产环境不应只复制示例中的浮动版本。更稳妥的做法是按照官方工作流示例，把 Action 固定到完整提交哈希，并在升级时单独审查变更。与此同时，顶层权限应保持只读，确实需要写权限的任务再在 job 级别声明。

四、把“低分”翻译成可审查的问题

一个好的审查记录不会写“Scorecard 只有 6 分，所以拒绝”。它应该把结果拆成事实、影响和行动：

1. 事实：记录具体检查项、结果文件、扫描对象以及检测范围。
2. 影响：说明它可能影响依赖更新、构建隔离、发布完整性还是仓库维护。
3. 补证：查看项目是否通过另一种方式满足要求，只是自动检查没有识别。
4. 行动：决定升级依赖、收紧权限、补充签名、增加审查规则，或记录一个明确的例外。

例如，Pinned-Dependencies 低分不一定说明所有依赖都可被替换。官方文档指出，该检查主要观察 Dockerfile、shell 脚本和 GitHub 工作流；Go 模块的完整语义版本也有其特殊处理。审查时应继续确认构建入口是否还有其他动态下载路径。

五、用维护者注释处理自动检测的盲区

Scorecard 提供维护者注释机制，用来解释“测试数据中的二进制文件”“已经修复但检测仍能看到的历史配置”“当前场景不适用”或“使用了工具但无法被识别”等情况。注释不是给低分涂色，而是把上下文留在结果旁边，避免下一位审查者重复猜测。

annotations:
  - checks:
      - binary-artifacts
    reasons:
      - reason: test-data # 说明该二进制只用于测试数据，不是发布产物。
  - checks:
      - dangerous-workflow
    reasons:
      - reason: remediated # 说明风险已由人工门禁和审批流程补救。
  - checks:
      - pinned-dependencies
    reasons:
      - reason: not-supported # 说明当前工具链的固定方式暂未被识别。

注释的前提是团队能拿出对应证据。对于“已修复”，要能指向修复 PR 或策略变更；对于“不适用”，要写清业务边界；对于“未检测到”，要避免把“工具没识别”误写成“项目没有做”。

六、让复查成为发布前的固定节点

推荐把闭环落成一条简单规则：高风险检查出现新失败时必须有审查记录；中风险检查进入依赖升级或发布变更的 PR；低风险检查只做周期性跟踪。修复 PR 合并后重新运行 Scorecard，并保存前后差异，而不是只更新一个总分截图。

如果结果交给多个团队消费，至少保留检查名称、风险等级、扫描对象、检测限制、维护者注释和责任人。这样，依赖准入、构建发布和安全响应使用的是同一份信号，审查也不会被一次性告警打断后失去上下文。

常见问题

Scorecard 分数低就代表不能使用这个依赖吗？

不代表。低分表示某些实践未被满足或未被识别，应结合风险等级、项目用途、暴露面和替代方案决定是否接受。

为什么要选择 SARIF？

SARIF 适合把扫描结果交给代码扫描系统统一展示；如果团队只需要脚本化汇总，也可以选择 JSON。

维护者注释会不会掩盖真实风险？

会有这种可能，所以注释应绑定可追溯的工程事实。注释本身不是修复动作，也不能代替权限收紧、依赖升级或发布签名。

参考资料

• https://scorecard.dev/
• https://github.com/ossf/scorecard
• https://github.com/ossf/scorecard-action
• https://github.com/ossf/scorecard/blob/main/docs/checks.md
• https://github.com/ossf/scorecard/blob/main/config/README.md