Python tarfile extraction_filter 怎么阻止危险路径

如果 tar 包来自上传接口、构建产物或外部依赖，解包时不要只写 extractall(target)。更稳妥的做法是显式传入 filter="data"：它会限制绝对路径、目录穿越、越界链接、设备文件和一部分危险元数据。业务还有文件数量、目录深度等要求时，再在官方过滤器之上增加一个 callable。

一、先显式选择 data 过滤器

Python 的过滤器能力在 Python 3.12 引入，并在部分旧版本中以安全更新形式回补。对跨版本程序，优先用能力检测；对明确支持该能力的运行环境，直接传入命名过滤器即可。

import tarfile
from pathlib import Path

archive_path = Path("incoming/bundle.tar.gz")
target = Path("work/extracted")
target.mkdir(parents=True, exist_ok=True)

# data 过滤器限制绝对路径、越界链接和设备文件等风险
with tarfile.open(archive_path, "r:gz") as tar:
    tar.extractall(target, filter="data")

fully_trusted 适合你完全信任归档，或已经实现复杂检查的场景；它不是上传文件解包的通用安全选项。Python 3.12 和 3.13 在未明确设置过滤器时会发出弃用警告，Python 3.14 起默认趋向 data，但应用仍应把策略写在调用点，避免依赖运行时默认值。

二、data_filter 到底阻止了什么

过滤器会在每个成员真正写入磁盘前收到 TarInfo 和目标路径。它可以返回调整后的成员、返回 None 跳过成员，或抛出异常终止流程。data 策略重点是把归档当作跨平台数据包：链接不能指向目标目录外，设备文件和管道不应被释放，属主信息也不会原样带入。

这解决的是“归档成员携带危险语义”的问题，不等于替应用完成所有资源限制。大归档仍可能耗尽磁盘，合法文件也可能造成过深目录、过多小文件或业务目录污染，所以还要增加应用自己的上限。

import tarfile

try:
    with tarfile.open("incoming/bundle.tar", "r") as tar:
        # 显式传入 data，避免跟随不同 Python 版本的默认行为
        tar.extractall("work/extracted", filter="data")
except tarfile.FilterError as exc:
    # 记录被拒绝的成员名，日志中不要写入归档内容本身
    member_name = getattr(exc.member, "name", "unknown")
    print(f"拒绝归档成员: {member_name}")

三、用自定义过滤器补上业务限制

不要重新手写路径规范化逻辑来替换官方过滤器。更可靠的顺序是先调用 tarfile.data_filter，再对返回的 TarInfo 增加业务限制。例如，导入包只允许有限层级和少数扩展名；超过边界就抛出 FilterError，让调用方知道这不是普通文件读取失败。

import tarfile

ALLOWED_SUFFIXES = {".json", ".yaml", ".txt"}

def import_filter(member: tarfile.TarInfo, destination: str) -> tarfile.TarInfo | None:
    # 先复用官方策略，避免遗漏链接、设备文件等危险语义
    safe_member = tarfile.data_filter(member, destination)
    name = safe_member.name

    # 业务包只接受有限目录深度和配置类文件
    if name.count("/") > 6:
        raise tarfile.FilterError("目录层级超过导入上限")
    if safe_member.isfile() and safe_member.name.lower().endswith(tuple(ALLOWED_SUFFIXES)) is False:
        return None  # 跳过不需要导入的普通文件
    return safe_member

with tarfile.open("incoming/config.tar", "r") as tar:
    # 过滤器按成员调用，返回 None 的成员不会写入目标目录
    tar.extractall("work/config", filter=import_filter)

如果业务需要统计成员数量或总大小，可以把计数器放在可调用对象中，而不是把状态藏在全局变量里。过滤器抛出异常时，extractall 可能已经完成前面的成员，因此目标目录应位于一次性临时目录；全部成功后再原子替换到正式位置。

四、兼容版本与发布检查

需要兼容旧解释器时，用 hasattr(tarfile, "data_filter") 检测能力，而不要只按版本号猜测，因为部分安全更新可能回补了过滤器。若能力不存在，应明确告警并阻止处理不可信归档，或把解包任务隔离到专门的低权限环境。

最后检查四件事：是否显式传入过滤器；失败目录是否会删除；日志是否保留拒绝成员名与归档标识；目标目录是否使用最小权限。过滤器只解决成员语义，不能替代磁盘配额、进程隔离和来源校验。

相关问题

可以直接把 extraction_filter 设成 data 吗？

不能把字符串写入 TarFile.extraction_filter。这个属性需要可调用对象，例如 tarfile.data_filter；字符串形式应传给 extractall(filter="data")。

FilterError 发生后需要重新打开归档吗？

通常不需要为了“继续解包”而重试同一归档。先记录拒绝成员并删除部分输出，再让上层返回清晰错误；盲目重试不会改变归档内容，反而可能重复写入已存在的文件。