5步把任意GitHub Action变成SLSA3 Builder:slsa-github-generator BYOB框架保姆级教程

原创2026-11-15 09:10:341,883 阅读

5步把任意GitHub Action变成SLSA3 Builder:slsa-github-generator BYOB框架保姆级教程

slsa-github-generator 是一款为 GitHub Actions 生成 SLSA 构建溯源(provenance)的开源工具,它自带的 BYOB(Build Your Own Builder)框架,让你无需手写签名、Intoto、Sigstore 等复杂逻辑,就能在 5 个步骤内把任意现有 GitHub Action 包装成符合 SLSA Build Level 3 的 Builder,为构建产物签发不可篡改的溯源证明。这篇保姆级教程带你从零跑通整个集成流程。

🎯 适用人群:已经在用某个 GitHub Action 构建/发布产物,想给它加上"防篡改"溯源能力的开发者。不需要你精通供应链安全。

一、先搞懂 BYOB:4 个角色各司其职

BYOB 框架的核心思路是委托(delegate):你只负责"包住"自己的 Action,剩下的隔离、签名、溯源生成都交给框架。理解下面 4 个角色,5 步集成就通了:

缩写 全称 职责 由谁维护
PW Project Workflow 项目工作流,调用 Builder 构建产物 你的仓库
TRW Tool Reusable Workflow SLSA 合规 Builder,"包裹"你的 Action 你的仓库
TCA Tool Callback Action 在隔离环境里跑你的原 Action 你的仓库
SRW / SSA SLSA Reusable Workflow / Setup Action 编排构建、生成并返回溯源 slsa-github-generator

下面是框架的组件关系图,箭头之间传递的是 SLSA Token(包含回调 Action 的位置和调用方输入):

slsa-github-generator BYOB框架 SLSA3 Builder 组件关系架构图

完整设计说明见 BYOB.md。

二、开始前的唯一门槛:触发事件

SLSA 规范要求构建必须由可信事件触发,BYOB 只支持以下 4 种(pull_request 暂不支持):

触发事件 说明
push 创建或更新 tag / 分支
create 创建 git tag 或分支
release 创建或更新 GitHub release
workflow_dispatch 手动触发

如果你的构建脚本依赖 PR 触发,需要先调整流程设计。

三、5 步集成实战

Step 1 · 定义 TRW 的输入输出

第一步是创建 TRW 文件(.github/workflows/xxx_slsa3.yml),让它的 inputs / secrets / outputs 与你的原 Action 一一对应。

  • inputs:低熵参数(如版本号、构建目标),会被记录进溯源;可为 boolean / number / string。
  • secrets:只放高熵值(如 token、密码);不要把用户名这类低熵 PII 当 secret。
  • outputs:把构建产物名、状态等回传给 PW。
  • 建议额外声明一个 rekor-log-public 布尔项,提示私有仓库名会进入公共透明日志。

⚠️ 关键差异:SRW 与 TRW、TRW 与 PW 各自运行在不同虚拟机上,TCA 构建出的产物 TRW 无法直接拿到,需通过"安全上传/下载"共享。这正是 Step 5 和加固部分要解决的。

Step 2 · 初始化 SRW 框架(setup-generic)

在 TRW 里调用 SLSA Setup Action(SSA) 拿到后续步骤要用的 slsa-token:

- uses: slsa-framework/slsa-github-generator/actions/delegator/setup-generic@v2.1.0
  id: slsa-setup
  with:
    slsa-workflow-recipient: "delegator_generic_slsa3.yml"
    slsa-build-action-path: "./internal/callback_action"   # TCA 路径
    slsa-runner-label: "ubuntu-latest"
    slsa-workflow-inputs: ${{ toJson(inputs) }}            # 会进入溯源
    slsa-workflow-masked-inputs: username                   # 在溯源中打码

参数含义:slsa-workflow-recipient 指定要初始化的 SRW;slsa-build-action-path 指向你的 TCA;slsa-workflow-masked-inputs 里逗号分隔的字段会在溯源中被替换为 ***(适合 username 等隐私项)。该 Action 的完整入参定义见 actions/delegator/setup-generic/action.yml。

Step 3 · 调用 SRW 跑构建

用 Token 调用 SRW,它会在隔离环境里唤起 TCA 并生成溯源。记得按需授权 id-token: write(签名)等权限,并把 secret 透传(最多 15 个):

slsa-run:
  needs: [slsa-setup]
  permissions:
    id-token: write    # 签名
    contents: write    # 上传产物
    actions: read
  uses: slsa-framework/slsa-github-generator/.github/workflows/delegator_generic_slsa3.yml@v2.1.0
  with:
    slsa-token: ${{ needs.slsa-setup.outputs.slsa-token }}
  secrets:
    secret1: ${{ inputs.password }}

SRW 本体见 .github/workflows/delegator_generic_slsa3.yml。

Step 4 · 创建 TCA 回调 Action

TCA 是框架在隔离 job 里真正调用的 Action,它要干三件事:

  1. 准备环境(如装好对应语言的编译器);
  2. 调用你的原 Action,从 slsa-workflow-inputs 里解出参数,secret 从 slsa-workflow-secret1~secret15 取:
- uses: ./../__TOOL_CHECKOUT_DIR__/path/to/your-action
  id: build
  with:
    content: ${{ fromJson(inputs.slsa-workflow-inputs).content }}
    token: ${{ inputs.slsa-workflow-secret2 || github.token }}
  1. 生成元数据布局文件(写进 slsa-layout-file),告诉框架"要溯源哪些产物",框架会自动追加 .build.slsa 后缀:
{
  "version": 1,
  "attestations": [
    { "name": "my-artifact",
      "subjects": [
        { "name": "my-artifact",
          "digest": { "sha256": "c71d239d...0ab4" } }
      ] }
  ]
}

💡 __TOOL_CHECKOUT_DIR__ 是框架把 TRW 仓库 checkout 后的本地路径,拼上你 action.yml 相对仓库根的路径即可调用原 Action。

Step 5 · 下载并上传 Attestations(溯源)

在 TRW 最后的 "publish" job 里下载 SRW 产出的溯源文件,上传到 release、制品库,或回传给 PW。框架提供了现成的安全下载 Action,会自动校验 SHA256:

建议为你的用户再包一个 secure-download-attestation Action,让他们无需了解 SLSA 仓库细节就能安全取回溯源。

四、安全加固:给 TCA 最小权限

默认 SRW 会给 TCA 赋予 contents: write、packages: write 等较高权限。为降低恶意依赖被攻破后的爆炸半径,推荐改用低权限 SRW:

  1. 把 SSA 的 slsa-workflow-recipient 与 Step 3 的调用都改为 .github/workflows/delegator_lowperms-generic_slsa3.yml,它只给 TCA contents: read;
  2. TCA 里不要直接发 release,而是:用 actions/delegator/random/action.yml 生成随机串做产物唯一名(防并发重名),把产物放进一个文件夹,再用 actions/delegator/secure-upload-folder/action.yml 安全上传并拿到 sha256;
  3. TRW 里下载产物后,由 TRW 负责发布。

依赖尽量按 hash 锁定(delegator 工作流除外,它需按 tag 固定版本以便 slsa-verifier 校验)。

五、最佳实践清单

  • 顶层 workflow 权限默认设为 read-only,最小化授权;
  • 下载的二进制先验证其 SLSA 溯源再执行;
  • 引入 OSSF Scorecard 等工具做整体 SDLC 体检;
  • 用户侧可用 slsa-verifier 工具验证溯源真伪。

六、延伸阅读

跑通以上 5 步,你的 GitHub Action 就拥有了 SLSA3 级 Builder,构建产物将附带一份可被验证、不可伪造的"出生证明"。🎉

登录后查看全文
slsa-github-generator