Python tarfile 解压时如何检查成员路径

用 tarfile.extractall() 解压外部上传的 tar 包时，不要只判断文件名是否以目标目录开头。更稳妥的做法是：先把成员名按归档路径规则检查一遍，拒绝绝对路径、..、驱动器路径和不需要的链接；真正解压时再显式使用 Python 3.12+ 的 filter='data'，并把输出放进新的临时目录。

先把成员名当作不可信输入

归档里的成员名可能是 docs/readme.txt，也可能是 ../outside.txt、/etc/config 或 Windows 风格的 C:/temp/a.txt。如果直接执行 root / member.name，字符串看起来在目录内，不等于最终写入位置一定在目录内；符号链接还可能影响后续成员。

因此检查规则要针对归档语义，而不是只做一次字符串前缀比较。这里采用保守策略：把反斜杠按分隔符处理，拒绝空字节、绝对路径、盘符路径和任意 .. 组件；业务不需要链接时，符号链接与硬链接也一并拒绝。

预检普通路径与链接成员

先遍历 TarInfo，把通过检查的对象保存下来。预检阶段不写磁盘，只回答“这个包的成员是否符合我的输入策略”。

from pathlib import PurePosixPath
import re
import tarfile

DRIVE_PATH = re.compile(r"^[A-Za-z]:/")

def check_member(member: tarfile.TarInfo) -> None:
    # 归档路径统一按 POSIX 分隔符解析，避免漏掉跨平台写法。
    name = member.name.replace("\\", "/")
    if "\x00" in name:
        raise ValueError("成员名包含空字节")

    path = PurePosixPath(name)
    # 绝对路径、盘符路径和父目录跳转都可能越出目标目录。
    if path.is_absolute() or DRIVE_PATH.match(name) or ".." in path.parts:
        raise ValueError(f"拒绝越界成员: {member.name}")
    # 不需要保留链接时，拒绝链接可以减少后续成员被重定向的风险。
    if member.issym() or member.islnk():
        raise ValueError(f"拒绝链接成员: {member.name}")

def inspect_tar(tar_path: str) -> list[tarfile.TarInfo]:
    # getmembers() 只读取归档目录，不会把内容写入目标目录。
    with tarfile.open(tar_path, "r:*") as archive:
        members = archive.getmembers()
        for member in members:
            check_member(member)
        return members

这里没有把 member.name 直接交给 os.path.abspath() 就结束检查，因为链接成员和抽取时的文件系统状态仍然需要由抽取过滤器处理。若业务必须支持链接，至少要为链接目标单独设置允许范围，并在隔离目录中解压。

用 data 过滤器做最后一道边界

Python 3.12 为 extract() 和 extractall() 增加了 filter 参数。官方文档提供的 data 过滤器会限制绝对路径、父目录越界以及危险的 Unix 元数据；Python 3.14 起，在没有显式指定过滤器时默认也会转向 data。生产代码仍建议显式传参，让策略在代码审查中可见。

from pathlib import Path
import shutil
import tarfile
import tempfile

def extract_archive(tar_path: str, output_root: str) -> Path:
    # 新目录避免归档利用目标目录里原有的链接或残留文件。
    output = Path(tempfile.mkdtemp(prefix="tar-extract-", dir=output_root))
    try:
        with tarfile.open(tar_path, "r:*") as archive:
            # data 会在每个成员真正处理前再次应用路径和元数据限制。
            archive.extractall(output, filter="data")
        return output
    except Exception:
        # 失败时清理部分解压结果，避免调用方误用半成品。
        shutil.rmtree(output, ignore_errors=True)
        raise

如果需要兼容没有过滤器参数的旧解释器，不能把预检误认为完整等价替代；应优先升级 Python，或者把解压放在权限受限的外部沙箱中。还要注意，过滤器拒绝成员时归档可能已经部分解压，调用方必须处理清理。

把解压放进临时目录并限制资源

filter='data' 主要解决“写到哪里”和“保留哪些元数据”，不能阻止归档炸弹、超大单文件或大量小文件带来的拒绝服务。上线前至少加上下面这张检查清单：

最后才把临时目录中的业务文件移动到正式位置，并在移动前再次确认文件类型、数量和总大小。这样即使归档被拒绝，外部输入也不会直接污染应用的工作目录。

相关问题

只检查 member.name 是否以目标目录开头可以吗？

不建议。绝对路径、父目录组件、不同路径分隔符和符号链接都会让简单前缀判断失真；应使用路径组件检查并配合 filter='data'。

Python 3.14 还需要显式写 filter="data" 吗？

仍建议显式写。默认值会随解释器版本变化，而显式参数能表达当前业务策略，也方便兼容不同版本。

过滤器能防止归档炸弹吗？

不能。它不是 CPU、内存、磁盘或文件数量配额；这些限制要在解压前后由应用或外部运行环境补充。