第15章 安全模型与注意事项
第15章 Security Model and Considerations
安全模型与注意事项
Trusted Publishing 的设计初衷,是为传统上用于发布到 PyPI 的长期 API token 提供一种更安全的替代方案。
近年来,API token 等凭据的失窃在网络攻击中扮演了重要角色。原因在于一个令人遗憾的现实:凭据管理既复杂又有风险。Trusted Publishing 通过使用短时效 token 取代长期 token 来降低这种风险。短时效 token 无需存储,因此更不容易被放错地方、泄露到日志或被恶意软件窃取。此外,即使短时效 token 泄露,攻击者可利用的时间窗口也非常有限,从而将潜在损害降到最低。
不过,你仍需了解 Trusted Publishing 无法覆盖的风险。应当把它视为保障软件包安全的工具箱中的一件工具。
一般注意事项
- Trusted Publishing 使用的短时效 API token,会在完成授权的 OIDC 流程后不超过 15 分钟内过期。与普通的 API 认证一样,Trusted Publishing 并不保证代码的安全性,也不保证代码作者的可信度。
- Trusted Publishing 不涉及软件包在构建前后是否被篡改的问题。这类风险可以通过 Attestations(证明)来应对。
- 短时效 API token 是敏感信息,必须妥善保护,防止被盗或泄露。
- OIDC token 本身同样是敏感信息,必须防止被盗或泄露。虽然 OIDC token 很快过期,但成功截获它的攻击者在其过期前可以用来生成 API token。
- 配置 Trusted Publisher 意味着信任一个身份提供方(IdP),例如 GitHub Actions。Trusted Publishing 依赖于该 IdP 以及被授权使用它的主体的完整性。实际上,这意味着使用 Trusted Publishing 的用户必须保护好自己的 CI/CD 工作流——这些工作流一旦存在弱点,其危害等同于凭据泄露。
总而言之:把你的 Trusted Publisher 当作 API token 对待。如果你不愿意让某个用户或代码接触你的 API token,那么它们也不应该能调用你的 Trusted Publisher。
各提供方的注意事项
每个 Trusted Publishing 提供方都是独立的 OIDC 身份提供方,拥有各自的安全模型和注意事项。
GitHub Actions / Google Cloud / ActiveState / GitLab CI/CD
GitHub Actions
安全模型
GitHub Actions 自身的 OpenID Connect token 安全模型有些微妙:
- 仓库中定义的任何工作流,只要拥有 id-token: write 权限,就可以请求任意 audience 的 OIDC token。
- OIDC token 中的 claims 绑定到具体的工作流,也就是说 org/repo 中定义在 foo.yml 的工作流无法冒充同一仓库中的 bar.yml。但如果 foo.yml 被重命名为 bar.yml,那么新的 bar.yml 与旧的 bar.yml 将无法区分——除非某些 claims 反映了仓库状态(如 git ref、分支等)。
- 一般来说,"第三方"事件无法请求 OIDC token:即使它们能触发请求 token 的工作流,实际获取 token 的步骤也会失败。例如,来自仓库 fork 的 PR 无法访问"上游"仓库工作流中的 OIDC token。
- 例外是 pull_request_target 事件,这类事件在设计上就存在根本性危险,未经仔细考量不应使用。
注意事项
针对 GitHub Actions 的 Trusted Publishing,你必须:
- 信任正确的用户名和仓库:如果你信任的不是自己掌控且信任的仓库,那个仓库就能向你的 PyPI 项目上传内容。
- 信任正确的工作流:不应该信任所有工作流都能上传到 PyPI;相反,应把职责隔离到一个尽可能小(且权限最低)的独立工作流中。建议将此工作流命名为 release.yml。
- 合并第三方代码改动时要谨慎:如果你信任 release.yml,就必须确保针对该工作流(或该工作流中运行的代码)的第三方改动没有恶意。
- 添加仓库贡献者、成员和管理员时要谨慎:默认情况下,任何能无条件向仓库提交代码的人,都可以修改你的发布工作流,使其在你未预期的时机触发(例如手动的 workflow_dispatch 触发器)。
这个风险可以通过使用带人工审批者的专用 environment 来缓解,详见下文。
Trusted Publisher 注册在项目上,而不是用户上。这意味着把用户从 PyPI 项目移除时,不会删除其注册的 Trusted Publisher。因此在对项目维护者进行"离职处理"时,应当审查其注册的所有 Trusted Publisher。
PyPI 已内置一些防护措施来增加针对 OIDC 的攻击难度(例如账号复活攻击)。但与所有认证方式一样,最终正确使用这些机制的责任在终端用户。
除了上述要求,你还可以通过以下方式进一步收紧 Trusted Publishing 工作流的范围:
- 使用 job 级权限:permissions 键可以定义在工作流级别或 job 级别;job 级别始终更安全,因为它限制了获得提升 GITHUB_TOKEN 凭据的 job 数量。
- 使用专用 environment:GitHub Actions 支持"environments",可用于将 secrets 隔离到特定工作流。OIDC 发布虽然不使用任何预配置的 secrets,但设置专用的发布或部署 environment 是通用最佳实践。
专用 environment 还支持额外保护措施,例如 required reviewers,可用于要求使用该 environment 的工作流必须经过人工批准。
例如,下面是 pypa/pip-audit 的 release environment 如何将审批限制为维护团队和管理团队成员的示例:
- 使用 tag 保护规则:如果你使用基于 tag 的发布工作流(例如在推送 tag 时触发),可以将与发布模式匹配的 tag 的创建和修改权限限制为维护者及以上(或自定义角色)。例如 v* 可以阻止非维护者创建或修改 v1.2.3 这类版本字符串的 tag。
- 限制发布 job 的范围:发布 job 理想情况下只应包含两个步骤:
1. 从独立的构建 job 获取可发布的分发文件; 2. 使用 pypa/gh-action-pypi-publish@release/v1 发布这些分发文件。
通过使用独立的构建 job,能把能接触 OIDC token 的步骤数量降到最低,同时防范意外和恶意的泄露。
Google Cloud
安全模型
如果某个 PyPI 项目配置了 Trusted Publisher,任何使用所配置服务账号的服务,都可以代表该身份向 Google 的身份提供方请求 OpenID Connect token。这个 token 可以换取具有发布权限的 PyPI API token,用于向该 PyPI 项目发布。还可以通过指定 subject(表示请求发起主体的 ID)进一步约束用于发布的身份。
注意事项
在 Google Cloud 上使用 Trusted Publishing 时,你必须信任所配置的服务账号以及任何将其作为默认临时身份的服务。特别是不建议配置默认服务账号,因为每个服务在创建时都会默认获得这些账号。
ActiveState
安全模型
Trusted Publishing 在 ActiveState Platform 构建基础设施中的隔离构建容器内进行。当用户触发会发布到 PyPI 的构建时,系统会生成一个 OIDC token,连同待上传的发布产物一起,作为环境变量传入所需的构建容器。构建容器使用该 OIDC token 请求 PyPI API token,然后用它上传你的发布内容。
注意事项
- Trusted Publisher 中配置的用户必须是触发 ActiveState Platform 构建的用户。该用户需要在项目关联的 ActiveState 组织中拥有编辑权限。 - ActiveState Platform 项目必须为私有。
关于使用 ActiveState Platform 进行 Trusted Publishing 的更多信息,请参阅 PyPI 配置文档和 ActiveState Platform 文档。
GitLab CI/CD
安全模型
- OIDC token 由通过 id_tokens 关键字指定了所需 audience 的工作流请求。token 会在 job 运行时通过环境变量提供。
- OIDC token 中的 claims 绑定到组和项目,也就是说位于 orgA/repo 的仓库无法冒充位于 orgB/repo 的仓库。
- OIDC token 中的 claims 绑定到顶层流水线,也就是说被顶层流水线(通常是 .gitlab-ci.yml)包含的任何流水线,都能使用信任 .gitlab-ci.yml 流水线的 Trusted Publisher 进行上传。
- 任何有权在仓库 CI/CD 中运行特定流水线的人,都可以生成该仓库和流水线对应的 OIDC token。
注意事项
针对 GitLab CI/CD 的 Trusted Publishing,你必须:
- 信任正确的命名空间和仓库:如果你信任的不是自己掌控且信任的仓库,那个仓库就能向你的 PyPI 项目上传内容。
- 警惕账号复活攻击:PyPI 会校验 OIDC token 中的命名空间 claim(用户名或组)。但如果该用户名或组被删除后,又创建了同名的新用户名或组,PyPI 仍会认可新生成 OIDC token 的有效性。
- 合并第三方代码改动时要谨慎:如果你信任顶层流水线 .gitlab-ci.yml,就必须确保对该文件的第三方改动没有恶意。这一点尤其重要,因为 GitLab 不会提供关于是哪个 job 请求了 token 的细粒度信息——claims 中只包含顶层流水线,这意味着顶层流水线运行的任何 job 都可以请求有效的 OIDC token。
- 添加仓库贡献者、成员和管理员时要谨慎:默认情况下,任何能无条件向仓库提交代码的人,都可以修改你的发布工作流,使其在你未预期的时机触发(例如手动的 when: manual 规则)。
这个风险可以通过使用带人工审批者的专用 environment 来缓解,详见下文。
Trusted Publisher 注册在项目上,而不是用户上。这意味着把用户从 PyPI 项目移除时,不会删除其注册的 Trusted Publisher。因此在对项目维护者进行"离职处理"时,应当审查其注册的所有 Trusted Publisher。
除了上述要求,你还可以通过以下方式进一步收紧 Trusted Publishing 工作流的范围:
- 使用专用 environment:GitLab CI/CD 支持"environments",可用于将 secrets 隔离到特定工作流。OIDC 发布虽然不使用任何预配置的 secrets,但设置专用的发布或部署 environment 是通用最佳实践。
专用 environment 还支持额外保护措施,例如 protected environments,可用于要求使用该 environment 的工作流必须经过人工批准。
- 使用受保护 tag:如果你使用基于 tag 的发布工作流(例如在推送 tag 时触发),可以将与发布模式匹配的 tag 的创建和修改权限限制为维护者及以上(或自定义角色)。例如 v* 可以阻止非维护者创建或修改 v1.2.3 这类版本字符串的 tag。
- 限制发布 job 的范围:发布 job 理想情况下只应包含两个步骤:
1. 从独立的构建 job 获取可发布的分发文件; 2. 使用 twine 发布分发文件,由它处理 OIDC 交换。
通过使用独立的构建 job,能把能接触 OIDC token 的步骤数量降到最低,同时防范意外和恶意的泄露。