验证文件路径以解决GitHub CodeQL的"路径表达式使用不受控制数据"警报

我正在为Python包编写函数，用于将文件系统中的文件注册到SQL数据库，但GitHub的CodeQL标记文件路径存在潜在安全风险。我已经做了基础验证——只接受存在且解析后以指定基础路径开头的文件路径，但CodeQL仍认为验证不足。想知道这是误报还是可以进一步增强验证，我用了resolve方法来获取并比较路径起始部分。

示例代码 #

# Python version: 3.9.19
# OS: GNU/Linux RHEL8 4.18.0-553.5.1.el8_10.x86_64
from pathlib import Path

# 存储路径由环境变量定义；此处为占位符
storage_path = Path("/path/to/where/files/are/stored")

# 定义文件路径验证函数
def validate_file(file: Path) -> bool:
    file = Path(file) if isinstance(file, str) else file  # 兼容字符串类型输入
    file = file.resolve()  # 获取完整路径用于验证

    # 文件不存在则验证失败
    if not file.exists():
        return False

    # 以存储路径的父目录作为验证基准
    basepath = list(storage_path.parents)[-2]  # 后续可调整为更严格的基准
    if str(file).startswith(str(basepath)):
        return True
    else:
        return False

# 验证函数的使用示例
incoming_file = Path("some_file.txt")  # 可以是相对路径或系统绝对路径

if validate_file(incoming_file) is True:
    """
    此处执行将文件注册到数据库的逻辑
    """
    return True
else:
    raise Exception("该文件未通过验证检查")

问题分析：不是误报，你的验证逻辑存在可被绕过的漏洞 #

1. 字符串前缀匹配的缺陷：用str(file).startswith(str(basepath))会出现误判，比如基准路径是/foo/bar，而待验证路径是/foo/barbaz/file.txt，字符串前缀匹配会认为合法，但实际该路径并不在基准目录的子层级中。
2. 父路径选取逻辑不稳定：list(storage_path.parents)[-2]依赖于storage_path的目录层级，如果后续storage_path的层级发生变化（比如路径更浅或更深），这个索引会拿到错误的父路径，直接导致验证逻辑失效。
3. 符号链接的潜在风险：虽然用了resolve()解析路径，但如果待验证路径是指向基准目录外的符号链接，当前逻辑无法识别这种情况，可能被攻击者利用绕过验证。

优化后的验证方案 #

利用Python 3.9+自带的Path.is_relative_to()方法（正好你的Python版本符合要求），这是官方推荐的安全判断路径从属关系的方案，同时优化基准路径的选取逻辑，增强验证严谨性：

# Python version: 3.9.19
# OS: GNU/Linux RHEL8 4.18.0-553.5.1.el8_10.x86_64
from pathlib import Path

# 存储路径由环境变量定义；提前解析为绝对路径
storage_path = Path("/path/to/where/files/are/stored").resolve()

def validate_file(file: Path | str) -> bool:
    # 统一转换为Path对象并解析绝对路径
    file = Path(file).resolve()

    # 验证文件存在且是普通文件（排除目录、符号链接等）
    if not file.exists() or not file.is_file():
        return False

    # 安全判断文件是否属于存储路径的子层级
    try:
        file.relative_to(storage_path)
        return True
    except ValueError:
        # 路径不在存储目录下时抛出异常，返回验证失败
        return False

# 使用示例
incoming_file = Path("some_file.txt")

if validate_file(incoming_file):
    """
    此处执行将文件注册到数据库的逻辑
    """
    pass
else:
    raise Exception("文件未通过验证检查")

优化点说明 #

• 替换字符串匹配为官方方法：is_relative_to()通过路径层级关系判断，而非字符串前缀，彻底避免了前缀匹配的误判问题。
• 稳定基准路径：提前将storage_path解析为绝对路径，直接用它作为验证基准，不再依赖不稳定的parents索引。
• 增强类型验证：添加is_file()检查，防止传入目录、符号链接等非预期路径。
• 简化类型处理：利用Python 3.9的联合类型注解Path | str，兼容字符串和Path对象输入，代码更简洁。

内容的提问来源于stack exchange，提问作者TheEponymousProgrammer