【Bug已解决】Backport workflow-hardening fix (excessive-permissions) to 3 release branches 解决方案

【Bug已解决】Backport workflow-hardening fix (excessive-permissions) to 3 release branches 解决方案一、现象长什么样项目如 diffusers 这类 GitHub 托管的库的 CI 工作流GitHub Actions被安全扫描指出「权限过大excessive-permissions」工作流在顶层或 job 级没显式限制permissions默认拿到了contents: write等高危权限。修复了这个 hardening 问题后需要把它回退backport到 3 个已发布的 release 分支——但手动改 3 个分支的.github/workflows/*.yml容易漏、容易不一致。现象/风险安全审计报Workflow does not restrict permissions; defaults grant write to contentsrelease 分支如branch-0.30/branch-0.29/branch-0.28仍带旧的高权限工作流新修复只在main上手动复制粘贴补丁到 3 个分支结果某分支漏了pull-requests: read或id-token: write权限仍不完整或者某分支的工作流语法因版本差异旧版 actions 不支持新字段应用失败。最迷惑的是这是「仓库维护 / CI 安全」类问题不是运行时崩但漏掉回退会让已发布分支长期暴露在不必要的写权限下是真实的安全债。二、背景GitHub Actions 工作流的permissions默认是「仓库安装时授予 GITHUB_TOKEN 的全部权限」通常包括contents: write。对于只做「读代码 跑测试」的 CI 工作流这过大。安全最佳实践OpenSSF / GitHub 推荐是顶层声明最小权限contents: read仅「需要发布的 job」如 publish才局部开contents: writeid-token: writeOIDC显式列出用到的pull-requests: read/issues: read等。当这个 hardening 在main修好后release 分支因「仍被用户 pip 安装、且 CI 仍在跑」也需要同样加固。但 release 分支是受保护分支不能直接 push要开 PR / 用git cherry-pick或backport工具。3 个分支逐个手动改极易出现「某分支权限块格式错 / 漏字段」。核心难点把同一个 hardening 补丁一致地应用到多个语法略有不同的 release 分支且可校验每个分支都完整。三、根因根因一句话main上的工作流权限加固excessive-permissions 修复需要回退到 3 个 release 分支但手动回退易漏字段/格式不一致导致 release 分支仍未完全加固留下安全债。三点展开未系统化回退靠手动复制补丁到 3 分支无统一机制保证一致。字段遗漏某分支漏pull-requests: read或id-token: write权限块不完整。分支语法差release 分支 actions 版本旧新权限语法/字段位置可能不适用应用失败。不是代码逻辑错是「跨分支安全补丁的一致性回退」缺失。四、最小可运行复现不依赖真实 git模拟「回退到 3 分支某分支漏字段」from dataclasses import dataclass, field from typing import Dict # 理想的 hardened 权限块 HARDENED { contents: read, pull-requests: read, id-token: write, } # 3 个 release 分支当前未加固的权限 branches { branch-0.30: {}, branch-0.29: {}, branch-0.28: {}, } def backport_manual(target, partialFalse): # 手动回退partialTrue 模拟漏了 id-token patch dict(HARDENED) if partial: patch.pop(id-token, None) branches[target] patch backport_manual(branch-0.30) backport_manual(branch-0.29, partialTrue) # 漏了 id-token backport_manual(branch-0.28) # 校验完整性 for b, perm in branches.items(): missing set(HARDENED) - set(perm) print(b, 缺:, missing)跑出来branch-0.29因手动回退漏了id-token权限块不完整——正是「回退不一致」的精确复现。五、解决方案第一层最小直接修复最小修复用一个脚本化补丁对 3 个 release 分支统一注入完整的最小权限块并在应用后断言每个分支都含全部必需字段。import yaml REQUIRED_PERMISSIONS { contents: read, pull-requests: read, id-token: write, } def harden_workflow(workflow_yaml: str) - str: 给单个 workflow 文件注入最小权限块顶层。 doc yaml.safe_load(workflow_yaml) # 顶层权限若已有则合并发布 job 局部可覆盖 existing doc.get(permissions, {}) or {} merged {**REQUIRED_PERMISSIONS, **existing} doc[permissions] merged return yaml.safe_dump(doc, sort_keysFalse) def backport_to_branches(branches_files: dict): branches_files: {分支名: workflow 文本} - {分支名: 加固后文本} results {} for name, text in branches_files.items(): results[name] harden_workflow(text) return results def verify(branches_files_hardened: dict): for name, text in branches_files_hardened.items(): doc yaml.safe_load(text) perm doc.get(permissions, {}) missing set(REQUIRED_PERMISSIONS) - set(perm) assert not missing, f{name} 权限块缺: {missing} return True要点统一注入REQUIRED_PERMISSIONS3 分支一致。已有字段合并发布 job 局部contents: write不被覆盖。verify断言每个分支权限块完整杜绝「漏字段」。这一步单独就让 3 个 release 分支都得到一致加固。六、解决方案第二层结构性改进第一层是「脚本注入 校验」。但项目有多个 workflow 文件、多个分支容易漏文件。更稳的做法把「权限加固 多分支多文件回退 校验」收敛成单一工具。from dataclasses import dataclass, field from typing import Dict, List dataclass class WorkflowPermissionHardener: CI 工作流权限加固与回退的单一工具。 required: Dict[str, str] field(default_factorylambda: { contents: read, pull-requests: read, id-token: write, }) # 允许局部覆盖的发布 job 权限 publish_override: Dict[str, str] field(default_factorylambda: { contents: write, id-token: write, }) def harden_text(self, text: str) - str: import yaml doc yaml.safe_load(text) doc[permissions] {**self.required, **(doc.get(permissions) or {})} # 给名字含 publish/release 的 job 局部覆盖 jobs doc.get(jobs, {}) for jname, j in jobs.items(): if publish in jname or release in jname: j[permissions] {**self.publish_override, **(j.get(permissions) or {})} return yaml.safe_dump(doc, sort_keysFalse) def backport(self, branch_files: Dict[str, Dict[str, str]]): branch_files: {分支: {文件名: 文本}} - 加固后同结构 out {} for branch, files in branch_files.items(): out[branch] {f: self.harden_text(t) for f, t in files.items()} return out def verify(self, hardened: Dict[str, Dict[str, str]]) - List[str]: import yaml errors [] for branch, files in hardened.items(): for f, t in files.items(): perm yaml.safe_load(t).get(permissions, {}) missing set(self.required) - set(perm) if missing: errors.append(f{branch}/{f} 缺 {missing}) return errors # 用法 hardener WorkflowPermissionHardener() hardened hardener.backport({ branch-0.30: {ci.yml: old_ci}, branch-0.29: {ci.yml: old_ci}, branch-0.28: {ci.yml: old_ci}, }) assert hardener.verify(hardened) [], 回退不完整结构收益单一工具加固逻辑、发布 job 局部覆盖、多分支多文件回退都集中。可校验verify返回不完整清单CI 可断言全绿。可扩展新必需权限加进required所有分支同步。七、解决方案第三层断言 / CI 守护写 pytest 守三条(1) 加固后含全部必需权限(2) 发布 job 局部覆盖生效(3) 多分支回退一致无遗漏。import yaml import pytest from your_lib import WorkflowPermissionHardener BASE name: ci\non: [push]\njobs:\n test:\n runs-on: ubuntu\n def test_hardened_has_all_required(): h WorkflowPermissionHardener() out h.harden_text(BASE) perm yaml.safe_load(out)[permissions] assert set(h.required).issubset(set(perm)) def test_publish_job_override(): h WorkflowPermissionHardener() doc name: c\njobs:\n publish:\n runs-on: ubuntu\n out h.harden_text(doc) jobs yaml.safe_load(out)[jobs] assert jobs[publish][permissions][contents] write def test_verify_catches_missing(): h WorkflowPermissionHardener() # 模拟某分支漏了 id-token bad {branch-x: {ci.yml: permissions:\n contents: read\n pull-requests: read\n}} errs h.verify(bad) assert any(id-token in e for e in errs) def test_backport_consistent(): h WorkflowPermissionHardener() hardened h.backport({ b1: {ci.yml: BASE}, b2: {ci.yml: BASE}, b3: {ci.yml: BASE}, }) assert h.verify(hardened) [] # 3 分支都完整 assert len(hardened) 3CI 常驻跑这四条后任何「回退漏字段」「发布 job 没覆盖」的回归都会立刻爆红。八、排查清单回退工作流权限加固到 release 分支时按顺序查先确认安全扫描报的是permissions未限制 / 默认 write——定位 excessive-permissions。顶层声明contents: read 其它只读权限仅发布 job 局部开contents: writeid-token: write。用脚本统一回退 3 分支别手动复制避免漏字段。回退后断言每个分支权限块含全部必需字段verify。注意 release 分支是受保护分支回退走 PR / backport 工具不直接 push。确认旧版 actions 语法兼容新权限字段避免应用失败。每次新增必需权限重跑verify确保历史分支同步。九、小结「回退 excessive-permissions 修复到 3 个 release 分支」根子是手动回退易漏字段/格式不一致release 分支长期未完全加固。修复三层次第一层脚本化注入完整最小权限块并断言完整第二层用WorkflowPermissionHardenerdataclass 把加固、发布 job 局部覆盖、多分支多文件回退与校验收敛为单一工具第三层用 pytest 守「含全部必需」「发布 job 覆盖」「多分支一致」。工程启示CI 工作流权限必须「最小权限 显式声明」且安全修复要系统性回退到所有受支持的 release 分支不能只在 main 上修。用脚本 校验保证跨分支一致比手动复制可靠得多——安全债最怕「main 修了、分支还裸着」。