设定先例

如果和何时其他归档提取库（如 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 对象的副本，其属性将根据仅限关键字的参数进行替换。

• name
• mtime
• mode
• 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

一个新的异常 FilterError 将添加到 tarfile 模块中。它将有几个新的子类，每个子类对应于上述拒绝原因之一。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 选项

问题 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 通常会成为一个有用的提示，以便审查受影响的代码。