Newshot

PyPI 加强对上传分发包的检查

Translation(model translation, not the source's own text)

PyPI 对上传分发的更严格检查

题图
题图

过去几个月里,PyPI 增加了一些额外的检查,可以拒绝上传的源码分发(“sdists”)和构建分发(“bdists”或“wheels”)。

这些检查是一项更大计划的一部分,该计划旨在让 Python 打包生态系统更能抵御解析器差异,后续还会增加更多检查,目标是让 PyPI 对分发的处理不那么宽松,并且更严格地符合各自的规范。

对于下游用户(包的使用者)来说,这些变化没有破坏性影响。遇到失败的包维护者应确保自己使用的是非 EOL 版本的 Python,以及能够生成符合打包标准的分发的构建后端。

背景¶

Python 打包有两种主要的分发格式:

  • 源码分发,即 sdists。它们以压缩 tar 归档(“tarballs”)的形式分发,后缀为 .tar.gz。
  • 构建分发,即 bdists(或 wheels)。它们以 ZIP 归档的形式分发,后缀为 .whl。

tar 和 ZIP 在设计时都不是为了承担它们在 Python 打包中的角色1:两者都包含与 Python 包分发无关的元数据,并且周围环绕着一个对输入解释十分宽松的解析器生态系统。

这种宽松在本地用户环境中通常是正确的,因为用户常常希望从损坏或轻微不正确的归档中恢复重要数据。

然而,在网络环境中,尤其是在打包环境中,这种宽松是不正确的:即使是彼此独立的宽松实现之间在解析上的微小差异,也可能导致解析器差异,从而使相同的输入在不同平台和不同工具下解压出不同的结果。

原则上,攻击者可以利用这些差异来破坏 Python 打包(以及最终用户)所假定的许多性质,包括:

  • PyPI 自身对每个上传分发的解析(包括依赖等重要元数据)与每个安装器看到的内容一致;
  • 第三方(如镜像和安全扫描器)所“看到”的分发内容与 PyPI 看到的一致;
  • 像 pip install ... 和 uv add ... 这样的调用会产生相同的安装状态。

违反这些性质可能导致用户安装看起来合法但实际恶意的分发,即使该分发自身的完整性(例如通过哈希)已经得到确认。

变更¶

在过去几周里,PyPI 已开始拒绝:

  • 使用“V7”风格 tar 归档的源码分发。V7 是一种遗留的、基本未被规范化的 tar 格式,源自 UNIX V7,从未由 Python 自带的 tarfile 模块生成过。
  • 包含可能在归档层面被误解为 ZIP 控制结构的 ZIP 注释的构建分发。

这些变更建立在 Seth Larson 去年八月专门为减少 ZIP 差异所做工作的基础之上。

这对我来说意味着什么?¶

如果你是 Python 打包的下游用户:没什么!这些变更不会直接影响你,你已经依赖的任何分发(通过 pip install 或 uv add 安装)都会继续正常工作。

如果你是包维护者:大概也没什么。PyPI 上绝大多数源码分发不受这些变更影响,因为它们已经符合 pax 要求。

如果你是维护者,并且确实因归档格式原因遇到上传被拒绝,请查阅 PyPI 的归档文档。随着我们逐步收紧对格式错误或不符合规范的上传的限制,PyPI 将努力保持该页面为最新状态。

对许多维护者来说,修复方法会很直接:

像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都要原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。

  • 确保你的分发包(包括 sdists 和 bdists)是用 Python 构建后端构建的,而不是通过手动用 tar、zip 或类似工具打包归档。流行的构建后端通常既符合分发包格式规范,也符合 PyPI 的附加归档限制。
  • 如果你无法从手动打包步骤迁移出去,请确保你手动符合归档要求,即:源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。构建分发包必须是有效的 ZIP 归档。两种格式都要求其成员使用 UTF-8 编码的文件名。

如果你无法从手动打包步骤迁移出去,请确保你手动符合归档要求,即:

  • 源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。

源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。

  • 此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。
  • 构建分发包必须是有效的 ZIP 归档。
  • 两种格式都要求其成员使用 UTF-8 编码的文件名。

下一步是什么?¶

这是一项持续进行的倡议,涉及 Python 生态系统的多个方面。我们的目标是将这项工作与 Python 本身(通过减少 Python 自有的 zipfile 和 tarfile 中的差异数量)以及 Python 打包标准(通过进一步约束和提高分发包规范的精确性)保持一致。

未来,PyPI 将继续识别可应用于上传的分发包的新限制。我们的目标是识别最小干扰的限制,即那些可以在不破坏(几乎)任何用户的情况下实施的限制。归档差异绝大多数利用了归档格式中晦涩或未使用的方面,因此这通常是可行的。

短期内,PyPI 将评估以下附加限制:

  • 完全拒绝 GNU 风格的 tar 归档。源码分发包规范已经禁止这些,但由于维护者的非平凡使用,目前是允许的。关于此事的初步计划见 #21012。
  • 完全拒绝 ZIP 注释。PyPI 已经拒绝了许多形式的这些,但允许一小部分,以兼容那些在归档注释中放入无害消息(如版本号)的 ZIP 编码器。关于此事的初步计划见 #20934。
  • 在众多其他打包生态系统中。↩

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗