5步把任意GitHub Action变成SLSA3 Builder:slsa-github-generator BYOB框架保姆级教程
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 的位置和调用方输入):
完整设计说明见 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,它要干三件事:
- 准备环境(如装好对应语言的编译器);
- 调用你的原 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 }}
- 生成元数据布局文件(写进
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:
- 下载溯源:actions/delegator/secure-attestations-download/action.yml
- 通用安全下载:actions/delegator/secure-download-folder/action.yml
建议为你的用户再包一个 secure-download-attestation Action,让他们无需了解 SLSA 仓库细节就能安全取回溯源。
四、安全加固:给 TCA 最小权限
默认 SRW 会给 TCA 赋予 contents: write、packages: write 等较高权限。为降低恶意依赖被攻破后的爆炸半径,推荐改用低权限 SRW:
- 把 SSA 的
slsa-workflow-recipient与 Step 3 的调用都改为 .github/workflows/delegator_lowperms-generic_slsa3.yml,它只给 TCAcontents: read; - TCA 里不要直接发 release,而是:用 actions/delegator/random/action.yml 生成随机串做产物唯一名(防并发重名),把产物放进一个文件夹,再用 actions/delegator/secure-upload-folder/action.yml 安全上传并拿到 sha256;
- TRW 里下载产物后,由 TRW 负责发布。
依赖尽量按 hash 锁定(delegator 工作流除外,它需按 tag 固定版本以便 slsa-verifier 校验)。
五、最佳实践清单
- 顶层 workflow 权限默认设为
read-only,最小化授权; - 下载的二进制先验证其 SLSA 溯源再执行;
- 引入 OSSF Scorecard 等工具做整体 SDLC 体检;
- 用户侧可用 slsa-verifier 工具验证溯源真伪。
六、延伸阅读
- 框架设计全解:BYOB.md
- 技术规范:SPECIFICATIONS.md
- 溯源数据格式:PROVENANCE_FORMAT.md
- 项目总览与各 Builder/Generator 选型:README.md
跑通以上 5 步,你的 GitHub Action 就拥有了 SLSA3 级 Builder,构建产物将附带一份可被验证、不可伪造的"出生证明"。🎉
