开创先例

如果其他存档提取库（例如 zipfile）获得类似功能，它们应该尽可能模仿此 API。

为了简化用例，内置过滤器将具有字符串名称；例如，用户可以传递 filter='data' 而不是处理 TarInfo 对象的特定函数。

shutil.unpack_archive() 函数将获得一个 filter 参数，它将传递给 extractall。

添加适用于各种存档格式的基于函数的 API 超出了本 PEP 的范围。

完整披露与分销商信息

PEP 作者为 Red Hat 工作，Red Hat 是 Python 的一个分销商，与 CPython 通常具有不同的安全需求和支持周期。此类分销商可能希望进行供应商补丁以：

• 允许在系统范围内配置默认值，并且
• 尽快更改默认值，即使在较旧的 Python 版本中也是如此。

该提案使这变得容易，并允许用户查询设置。

修改和遗忘成员元数据

TarInfo 类将获得一个新的方法 replace()，它的工作方式与 dataclasses.replace 类似。它将返回 TarInfo 对象的副本，其中属性根据仅关键字参数指定进行替换：

• 名称
• mtime
• 众数
• linkname
• uid
• gid
• uname
• gname

除了 name 和 linkname 之外，任何这些参数都将被允许设置为 None。当 extract 或 extractall 遇到这样的 None 时，它将不会设置该元数据。（如果 uname 或 gname 为 None，它将回退到 uid 或 gid，就像未找到名称一样。）当 addfile 或 tobuf 遇到这样的 None 时，它将引发 ValueError。当 list 遇到这样的 None 时，它将打印一个占位符字符串。

文档将提及该方法存在的原因：从 TarFile.getmembers 检索的 TarInfo 对象是“活动”的；直接修改它们会影响后续不相关的操作。

过滤器

TarFile.extract 和 TarFile.extractall 方法将新增一个 filter 仅关键字参数，该参数接受一个可调用对象，可以按如下方式调用：

filter(/, member: TarInfo, path: str) -> TarInfo|None

其中 member 是要提取的成员，path 是存档提取到的路径（即，对每个成员都相同）。

使用时，它将在每个成员被提取时调用，并且提取将根据结果进行。如果它返回 None，则该成员将被跳过。

该函数也可以引发异常。这取决于 TarFile.errorlevel，可以中止提取或导致该成员被跳过。

我们还将为常见用例提供一组默认值。除了函数之外，filter 参数可以是以下字符串之一：

• 'fully_trusted'：当前行为：按原样尊重元数据。如果用户完全信任存档，或实现自己的复杂验证，则应使用此选项。
• 'tar'：大致遵循 GNU tar 命令的默认值（作为普通用户运行时）
  • 从文件名中删除前导 '/' 和 os.sep
  • 拒绝提取具有绝对路径的文件（在上述 / 剥离之后，例如 Windows 上的 C:/foo）。
  • 拒绝提取其绝对路径（在跟踪符号链接之后）将超出目标的文件。（请注意，GNU tar 而是延迟创建一些链接。）
  • 清除高模式位（setuid、setgid、sticky）和组/其他写入位（S_IWGRP|S_IWOTH）。（这是 GNU tar 默认值的一个近似值，该默认值通过当前的 umask 设置来限制模式。）
• 'data'：提取“数据”存档，禁止常见攻击向量但限制功能。特别是，许多特定于 UNIX 风格文件系统（或等效地，特定于 tar 存档格式）的功能被忽略，这使其成为跨平台存档的良好过滤器。除了 tar
• 拒绝提取链接（硬链接或软链接），这些链接链接到绝对路径。
• 拒绝提取最终链接到目标外部路径的链接（硬链接或软链接）。（在不支持链接的系统上，tarfile 在大多数情况下会回退到创建常规文件。此提案不更改该行为。）
• 拒绝提取设备文件（包括管道）。
• 对于常规文件和硬链接
  • 设置所有者读写权限（S_IRUSR|S_IWUSR）。
  • 如果所有者没有执行权限（S_IXUSR），则移除组和其他 可执行 权限（S_IXGRP|S_IXOTH）。
• 对于其他文件（目录），完全忽略模式（将其设置为 None）。
• 忽略用户和组信息（将 uid、gid、uname、gname 设置为 None）。

任何其他字符串都将导致 ValueError。

相应的过滤函数将作为 tarfile.fully_trusted_filter()、tarfile.tar_filter() 等可用，因此它们可以很容易地用于自定义策略。

请注意，这些过滤器从不返回 None。以这种方式跳过成员是用户定义过滤器的功能。

默认值及其配置

TarFile 将获得一个新的属性 extraction_filter，以允许配置默认过滤器。默认情况下，它将是 None，但如果 filter 参数缺失或为 None，用户可以将其设置为将被调用的可调用对象。

如果参数和属性都为 None

• 在 Python 3.12-3.13 中，将发出 DeprecationWarning，并且提取将使用 'fully_trusted' 过滤器。
• 在 Python 3.14+ 中，它将使用 'data' 过滤器。

应用程序和系统集成商可能希望更改 TarFile 类本身的 extraction_filter 以设置全局默认值。当使用函数时，他们通常会希望将其包装在 staticmethod() 中，以防止注入 self 参数。

TarFile 的子类也可以覆盖 extraction_filter。

FilterError

tarfile 模块中将添加一个新异常 FilterError。它将有几个新的子类，每个子类对应一个上述拒绝原因。FilterError 的 member 属性将包含相关的 TarInfo。

在上述列表中，“拒绝”提取文件意味着将引发 FilterError。与其他提取错误一样，如果 TarFile.errorlevel 大于或等于 1，这将中止提取；如果 errorlevel=0，错误将被记录并且成员将被忽略，但提取将继续。请注意，extractall() 可能会留下部分提取的存档；用户有责任进行清理。

错误级别，以及致命/非致命错误

目前，TarFile 有一个 errorlevel 参数/属性，它指定如何处理错误：

• 当 errorlevel=0 时，文档指出“使用 extract() 和 extractall() 时，所有错误都会被忽略”。代码只忽略 非致命 和 致命 错误（见下文），因此，例如，如果您将 None 作为目标路径传递，您仍然会收到 TypeError。
• 当 errorlevel=1（默认值）时，所有 非致命 错误都会被忽略。（通过设置 debug 参数/属性，它们可能会被记录到 sys.stderr。）文档中没有定义哪些错误是 非致命 的，但代码将 ExtractionError 视为此类。具体来说，是以下问题：
  • “无法解析存档内的链接”（在不支持符号链接的系统上引发）
  • “系统不支持 fifo/特殊设备”（如果系统支持这些设备，例如对于 PermissionError，则不用于故障）
  • “无法更改所有者/模式/修改时间”

  请注意，例如，文件名过长 或 磁盘空间不足 不符合条件。非致命 错误在类 Unix 系统上不太可能出现。

• 当 errorlevel=2 时，所有错误都会被引发，包括 致命 错误。哪些错误是 致命 的，再次没有定义；实际上是 OSError。

过滤器拒绝提取成员不完全符合 致命/非致命 类别。

• 本 PEP 不改变现有行为。（欢迎在 Discourse 主题 25970 中提出改进意见。）
• 当过滤器拒绝提取成员时，错误默认不应静默通过。

为了满足此要求，FilterError 将被视为 致命 错误，也就是说，它只会在 errorlevel=0 时被忽略。

希望忽略 FilterError 但不忽略其他 致命 错误的用户应创建自定义过滤器函数，并在 try 块中调用另一个过滤器。

进一步验证的提示

即使进行了拟议的更改，tarfile 仍不适合在未经事先检查的情况下提取不受信任的文件。除其他问题外，拟议的策略不能阻止拒绝服务攻击。用户应进行额外检查。

新文档将告诉用户考虑

• 提取到一个新的空目录，
• 对磁盘、内存和 CPU 使用施加外部（例如，操作系统级别）限制，
• 根据允许的字符列表检查文件名（以过滤掉控制字符、易混淆字符等），
• 检查文件名是否具有预期的扩展名（不鼓励在“点击”时执行的文件，或没有扩展名的文件，如 Windows 特殊设备名称），
• 限制提取文件的数量、提取数据的总大小以及单个文件的大小，
• 检查在不区分大小写的文件系统上将被遮蔽的文件。

此外，文档将指出：

• tar 文件通常包含同一文件的多个版本：提取时，后来的版本预计会覆盖较早的版本，
• tarfile 不会防范“实时”数据的问题，例如，攻击者在提取（或添加）过程中篡改目标目录（有关更多信息，请参阅 GNU tar 手册）。

此列表并非详尽无遗，但文档是收集此类一般技巧的好地方。如果它变得太长或需要与 zipfile 或 shutil 合并（超出本提案范围），则可以将其移至单独的文档。

TarInfo 身份和 offset

使用 replace() 的过滤器，提取机制处理的 TarInfo 对象不一定与 members 中存在的对象相同。这可能会影响覆盖 makelink 等方法并依赖对象身份的 TarInfo 子类。

此类代码可以切换到比较 offset，即成员头在文件中的位置。

请注意，可重写方法和 offset 都仅在源代码注释中有所记载。

tarfile CLI

CLI (python -m tarfile) 将获得一个 --filter 选项，该选项将接受所提供默认过滤器之一的名称。无法指定自定义过滤器函数。

如果未提供 --filter，CLI 将使用默认过滤器（目前为 'fully_trusted'，并附带弃用警告；从 Python 3.14 开始为 'data'）。

不会有短选项。（-f 会与 GNU tar 的文件名选项令人困惑地相似。）

其他存档库

如果其他归档库（例如 zipfile）获得类似功能，其解压函数应使用 filter 参数，该参数至少接受字符串 'fully_trusted'（应禁用任何安全预防措施）和 'data'（应避免可能让用户感到惊讶的功能）。

标准化基于函数的过滤器 API 超出了本 PEP 的范围。

Shutil

shutil.unpack_archive() 将获得一个 filter 参数。如果给定，它将传递给底层提取函数。目前，将其传递给 zip 存档将失败（直到 zipfile 获得 filter 参数，如果它真的获得的话）。

如果未指定 filter（或将其保留为 None），则它不会被传递，因此解压 tarball 将使用默认过滤器（现在是 'fully_trusted' 附带弃用警告，从 Python 3.14 开始是 'data'）。

复杂过滤器

请注意，一些用户定义的过滤器需要，例如，计算提取的成员或进行后处理。这需要比 filter 可调用对象更复杂的 API。但是，这种复杂的 API 不需要暴露给 tarfile。例如，使用假设的 StatefulFilter，用户将编写：

with StatefulFilter() as filter_func:
    my_tar.extract(path, filter=filter_func)

一个简单的 StatefulFilter 示例将添加到文档中。

SafeTarFile

Lars Gustäbel 最初的想法是提供一个单独的类来实现安全检查（参见 gh-65308）。这种方法存在两个主要问题：

• 这个名字具有误导性。一般的存档操作永远不可能完全“安全”，免受所有不必要的行为，而不影响合法用例。
• 它没有解决不安全默认值的问题。

然而，SafeTarFile 背后的许多想法在本 PEP 中得到了重用。

向 tarfile 添加 absolute_path 选项

Issue gh-73974 要求在解压方法中添加 absolute_path 选项。这将是正式解决 CVE-2007-4559 的最小更改。它不足以保护不知情的人，也无法赋能勤奋和好奇的人。

'tar' 过滤器的其他名称

'tar' 过滤器暴露了类 UNIX 文件系统特有的功能，因此它可以命名为 'unix'。或者 'unix-like'、'nix'、'*nix'、'posix'？

从功能上讲，tar 格式 和 类 UNIX 文件系统 本质上是等效的，因此 tar 是一个好名字。

向 zipfile 和 shutil.unpack_archive 添加过滤器

为了一致性，zipfile 和 shutil.unpack_archive() 可以获得对 filter 参数的支持。然而，这需要本 PEP 作者无法承诺在 Python 3.12 中进行的研究。

zipfile 的过滤器可能对安全没有帮助。Zip 主要用于跨平台数据包，因此，ZipFile.extract 的默认值已经类似于 'data' 过滤器所做的事情。'fully_trusted' 过滤器会 新允许 绝对路径和 .. 路径组件，除了统一的 unpack_archive API 之外，可能没有太多用处。

过滤器应该对安全以外的用例有用，但这些通常需要自定义过滤器函数，并且需要适用于 TarInfo 和 ZipInfo 的 API。这 绝对 超出了本 PEP 的范围。

如果只实现了本 PEP 而 zipfile 没有变化，那么 unpack_archive 调用者的影响是 tar 文件的默认值从 'fully_trusted' 更改为更合适的 'data'。在此过渡期内，Python 3.12-3.13 将发出 DeprecationWarning。这很烦人，但有几种处理方法：例如，有条件地添加 filter 参数，全局设置 TarFile.extraction_filter，或忽略/抑制警告直到 Python 3.14。

此外，由于许多对 unpack_archive 的调用可能不安全，因此希望 DeprecationWarning 经常会成为审查受影响代码的有用提示。