P2P 与分布式存储 / 系统课时

种子文件路径为何必须做安全校验

种子文件路径为何必须做安全校验

BitTorrent 种子文件中的路径来自外部元数据,不能直接用于创建本地文件。恶意种子可能利用绝对路径、父目录跳转、非法文件名或伪造长度覆盖下载目录外的数据。本课实现一套安全解析规则,并通过 Python 示例验证路径边界和长度约束。

学习目标

  • 识别种子元数据中的路径穿越、绝对路径、非法组件和长度异常。
  • 掌握路径组件校验、目标目录约束及文件创建前的验证顺序。
  • 使用可运行的 Python 示例拒绝危险路径,并理解符号链接和跨平台边界。

不可信路径会造成什么问题

BitTorrent v1 多文件种子的 info.files 列表包含每个文件的 length 和 path。其中 path 是路径组件列表,而不是可信的本地文件路径。单文件种子使用 info.name 和 info.length;多文件种子的 info.name 通常作为顶层目录名。

假设下载根目录为 /srv/downloads,正常文件应写入 /srv/downloads/demo/readme.txt。如果客户端直接拼接未经校验的路径,就可能出现以下情况。

不可信输入 潜在风险 正确处理
../private.txt 跳出下载根目录 拒绝父目录组件
/etc/config 绝对路径绕过目标目录 拒绝绝对路径
C:\\Windows\\Temp\\x Windows 盘符或分隔符歧义 拒绝盘符、反斜杠和冒号
folder/../../x 多级路径穿越 拒绝任何 .. 组件
CON、NUL.txt Windows 保留设备名 跨平台模式下拒绝
length = -1 非法文件长度 拒绝负数

还应拒绝空组件、.、NUL 字符、路径分隔符和超过策略限制的名称。不要先把 .. 归一化掉再判断,因为这样会丢失恶意输入的直接证据。

文件创建前的安全校验链路

解析器应把元数据检查与实际文件创建分开。推荐按以下顺序处理:

  1. 使用有资源上限的 Bencode 解析器读取种子,限制输入大小、嵌套深度和文件条目数量。
  2. 验证 info 字典结构,区分单文件和多文件模式,确认路径组件为字节串、长度为非负整数。
  3. 按明确的编码策略解码路径。解码失败时拒绝,不使用会替换非法字节的宽松模式。
  4. 逐个校验 info.name 和 path 组件,拒绝空值、.、..、分隔符、控制字符及平台危险名称。
  5. 拼接经过校验的组件,执行路径规范化,并确认目标位于指定下载根目录之下。
  6. 检查文件数量、单文件长度、累计长度及目标路径冲突,通过后才进入安全创建阶段。

种子元数据路径校验与文件创建安全边界流程

这里有两个不同的安全边界:字符串层面的路径约束,以及文件系统层面的实际落点约束。前者能识别 .. 等危险组件,后者还必须处理符号链接、目录替换和并发竞争。

用 Python 验证路径和长度

下面使用 Python 3.10 及以上版本的标准库实现一个不创建文件的验证器。示例输入模拟已完成 Bencode 解析与 UTF-8 解码后的路径组件,并不负责解析 .torrent 文件本身。

示例采用保守的跨平台策略:拒绝 Windows 特殊名称、分隔符和末尾空格或句点;每个组件最多 255 个 UTF-8 字节;单文件最大 1 GiB,总长度最大 4 GiB。容量限制是演示策略,不是 BitTorrent 协议规定。

python
from pathlib import Path, PureWindowsPath

MAX_FILE = 1 << 30
MAX_TOTAL = 4 << 30
MAX_COMPONENT_BYTES = 255


def check_component(name: str) -> None:
    if not isinstance(name, str) or name in ('', '.', '..'):
        raise ValueError('非法路径组件')
    if any(ord(c) < 32 or ord(c) == 127 for c in name):
        raise ValueError('包含控制字符')
    if any(c in name for c in '/\\:*?"<>|'):
        raise ValueError('包含危险路径字符')
    if name.endswith((' ', '.')) or PureWindowsPath(name).is_reserved():
        raise ValueError('Windows 不安全名称')
    if len(name.encode('utf-8')) > MAX_COMPONENT_BYTES:
        raise ValueError('路径组件过长')


def validate_files(root: Path, files: list[dict]) -> list[Path]:
    base = root.resolve(strict=True)
    if not base.is_dir():
        raise ValueError('下载根目录不是目录')

    total = 0
    targets = []
    seen = set()
    for item in files:
        parts = item['path']
        size = item['length']
        if not isinstance(parts, list) or not parts:
            raise ValueError('路径组件列表无效')
        for part in parts:
            check_component(part)
        if type(size) is not int or not 0 <= size <= MAX_FILE:
            raise ValueError('文件长度无效')

        total += size
        if total > MAX_TOTAL:
            raise ValueError('累计长度超限')
        target = base.joinpath(*parts).resolve(strict=False)
        if not target.is_relative_to(base) or target == base:
            raise ValueError('目标路径越界')
        key = tuple(part.casefold() for part in parts)
        if key in seen:
            raise ValueError('目标路径重复')
        seen.add(key)
        targets.append(target)
    return targets


def main() -> None:
    root = Path('/tmp/bt-safe-demo')
    root.mkdir(parents=True, exist_ok=True)
    cases = [
        ('正常', [{'path': ['demo', 'readme.txt'], 'length': 1024}]),
        ('穿越', [{'path': ['..', 'secret.txt'], 'length': 8}]),
        ('绝对路径', [{'path': ['/etc', 'passwd'], 'length': 8}]),
        ('负数长度', [{'path': ['demo', 'bad.bin'], 'length': -1}]),
        ('设备名', [{'path': ['CON'], 'length': 8}]),
    ]
    for label, files in cases:
        try:
            validate_files(root, files)
            print(f'{label}: 通过')
        except ValueError:
            print(f'{label}: 拒绝')


if __name__ == '__main__':
    main()

在支持 /tmp 的 POSIX 系统上运行,预期输出:

text
正常: 通过
穿越: 拒绝
绝对路径: 拒绝
负数长度: 拒绝
设备名: 拒绝

示例不会写入下载文件,只会创建测试根目录。resolve(strict=False) 可以检查验证时已经存在的符号链接,但不能防止检查后目录被替换,因此不能把这段代码直接当作完整的生产级文件写入沙箱。

另外,PureWindowsPath.is_reserved() 在较新的 Python 版本中存在弃用差异;生产实现应使用目标平台对应的保留名称规则,并对大小写不敏感文件系统进行碰撞检查。

文件长度和目标路径还要检查什么

BitTorrent 的 length 表示文件字节数,不能仅因为它是整数就接受。Python 整数没有固定宽度,但后续文件分配接口、数据库字段和其他语言实现可能存在整数溢出风险。

例如,三个文件分别声明 700 MiB、900 MiB、600 MiB,总计 2200 MiB。即使每个文件均低于 1 GiB,如果项目总配额为 2 GiB,仍必须拒绝整个任务,而不是写到第三个文件时才发现空间不足。

实际工程还应检查:

  • 文件条目数量,例如最多 100000 条,避免大量空文件消耗 inode。
  • 路径深度,例如最多 32 层,防止过深目录结构。
  • 文件与目录前缀冲突,例如同时出现 a 文件和 a/b.txt。
  • 大小写或 Unicode 规范化后的名称碰撞,避免在目标文件系统上覆盖同一对象。
  • 种子声明总长度与实际分块布局的一致性,并在分配空间前检查磁盘配额。

这些数值均属于应用层可调整的资源策略。若需要支持超大种子,应显式提升限制并测试整数范围,而不是直接取消全部限制。

符号链接和并发替换如何防护

即使字符串检查通过,文件系统仍可能改变最终写入位置。假设下载目录中的 demo 是指向外部目录的符号链接,直接打开 demo/readme.txt 就可能写到下载根目录之外。

更危险的是检查与创建之间的竞争:验证器确认目录安全后,其他进程把目录替换为符号链接,后续写入便可能越界。这类问题称为 TOCTOU(检查时刻与使用时刻不一致)。

在支持相应接口的 POSIX 系统上,生产实现可采用以下策略:

  1. 先打开可信下载根目录,保留目录文件描述符。
  2. 逐层通过相对目录描述符操作,禁止跟随符号链接;Linux 可考虑使用 openat2 的 RESOLVE_BENEATH、RESOLVE_NO_SYMLINKS 等解析限制。
  3. 创建目标文件时使用排他创建策略,避免意外覆盖既有文件。
  4. 文件打开后通过文件描述符进行写入和校验,不再重新拼接未经验证的路径。
  5. 在独立、权限受限的下载目录内运行,并对下载完成后的文件移动执行新的目标路径校验。

验收时至少测试正常路径、父目录穿越、绝对路径、保留名称、负数长度、累计长度超限、重复路径和符号链接逃逸。所有非法输入都应在写入下载内容前被拒绝,并且不能修改下载根目录之外的任何文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

种子文件路径为何必须做安全校验

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通