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 字符、路径分隔符和超过策略限制的名称。不要先把 .. 归一化掉再判断,因为这样会丢失恶意输入的直接证据。
文件创建前的安全校验链路
解析器应把元数据检查与实际文件创建分开。推荐按以下顺序处理:
- 使用有资源上限的 Bencode 解析器读取种子,限制输入大小、嵌套深度和文件条目数量。
- 验证
info字典结构,区分单文件和多文件模式,确认路径组件为字节串、长度为非负整数。 - 按明确的编码策略解码路径。解码失败时拒绝,不使用会替换非法字节的宽松模式。
- 逐个校验
info.name和path组件,拒绝空值、.、..、分隔符、控制字符及平台危险名称。 - 拼接经过校验的组件,执行路径规范化,并确认目标位于指定下载根目录之下。
- 检查文件数量、单文件长度、累计长度及目标路径冲突,通过后才进入安全创建阶段。

这里有两个不同的安全边界:字符串层面的路径约束,以及文件系统层面的实际落点约束。前者能识别 .. 等危险组件,后者还必须处理符号链接、目录替换和并发竞争。
用 Python 验证路径和长度
下面使用 Python 3.10 及以上版本的标准库实现一个不创建文件的验证器。示例输入模拟已完成 Bencode 解析与 UTF-8 解码后的路径组件,并不负责解析 .torrent 文件本身。
示例采用保守的跨平台策略:拒绝 Windows 特殊名称、分隔符和末尾空格或句点;每个组件最多 255 个 UTF-8 字节;单文件最大 1 GiB,总长度最大 4 GiB。容量限制是演示策略,不是 BitTorrent 协议规定。
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 系统上运行,预期输出:
正常: 通过
穿越: 拒绝
绝对路径: 拒绝
负数长度: 拒绝
设备名: 拒绝示例不会写入下载文件,只会创建测试根目录。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 系统上,生产实现可采用以下策略:
- 先打开可信下载根目录,保留目录文件描述符。
- 逐层通过相对目录描述符操作,禁止跟随符号链接;Linux 可考虑使用
openat2的RESOLVE_BENEATH、RESOLVE_NO_SYMLINKS等解析限制。 - 创建目标文件时使用排他创建策略,避免意外覆盖既有文件。
- 文件打开后通过文件描述符进行写入和校验,不再重新拼接未经验证的路径。
- 在独立、权限受限的下载目录内运行,并对下载完成后的文件移动执行新的目标路径校验。
验收时至少测试正常路径、父目录穿越、绝对路径、保留名称、负数长度、累计长度超限、重复路径和符号链接逃逸。所有非法输入都应在写入下载内容前被拒绝,并且不能修改下载根目录之外的任何文件。