Agent 工具返回文件路径时如何限制工作区范围

Agent 调用文件工具时，工具返回的路径不能直接交给 open() 或系统命令。稳妥做法是把工作区根目录当成唯一信任边界：工具只返回相对路径，服务端再解析、规范化并确认结果仍在根目录内，最后才执行读写。这样既能挡住 ../ 目录穿越，也能处理指向工作区外部的符号链接。

参考实现地址：https://openai.github.io/openai-agents-python/sandbox/guide/

Agent 返回的路径，先分清“标识”还是“主机路径”

工具协议最好约定返回 workspace-relative-path，例如 reports/today.json，而不是 /Users/alice/project/reports/today.json。相对路径由服务端绑定到当前运行的工作区；同一个 Agent 任务换到容器或远程沙箱时，路径语义也不会跟着主机目录泄漏。

如果确实需要返回绝对路径，也应把它当作不可信输入重新解析，不能因为它“看起来已经在项目目录下”就放行。路径校验和工具权限是两层策略：前者回答“能不能指向这里”，后者还要回答“能不能读、写或执行”。

用规范路径判断是否还在工作区内

Python 的 Path.resolve() 会消除 .. 并解析符号链接；随后用 relative_to() 判断候选路径是否能表示成工作区根目录下的相对路径。不要只用字符串前缀比较：/srv/app2 可能会被错误地当成 /srv/app 的子目录。

from pathlib import Path

def resolve_workspace_path(workspace: Path, returned: str) -> Path:
    # 返回值来自 Agent，先拒绝空值和主机绝对路径。
    if not returned or Path(returned).is_absolute():
        raise ValueError("path must be a non-empty relative path")

    root = workspace.resolve(strict=True)
    candidate = (root / returned).resolve(strict=False)
    try:
        candidate.relative_to(root)
    except ValueError as exc:
        # 统一拒绝 .. 和指向根目录外的符号链接。
        raise PermissionError("path is outside workspace") from exc
    return candidate

这里的 strict=False 适合“准备创建新文件”的场景：父级路径仍会被解析，末尾不存在的文件名可以保留。若工具只允许读取已有文件，可改用 strict=True，让不存在文件直接失败。无论哪种模式，都要在 open()、上传、删除或交给 shell 之前完成检查。

只检查字符串还不够：符号链接和竞态要单独处理

PurePath.relative_to() 属于词法判断，本身不会访问文件系统；因此必须对真实路径使用 Path.resolve()。例如 workspace/cache/link 文字上位于根目录下，但 link 如果指向 /var/log，解析后的候选就必须拒绝。

对高风险写入，还要考虑“检查后到打开前”的竞态：攻击者可能在两次操作之间替换目录或链接。更严的实现会使用目录文件描述符、openat 或平台提供的 O_NOFOLLOW 等能力，并让运行账户只拥有工作区所需权限。普通业务至少应避免把校验后的字符串交给 shell 拼接命令。

def open_workspace_text(workspace: Path, returned: str) -> str:
    # 先完成边界校验，再以只读方式打开；不把路径拼进 shell 命令。
    safe_path = resolve_workspace_path(workspace, returned)
    if not safe_path.is_file():
        raise FileNotFoundError("workspace file is not a regular file")
    return safe_path.read_text(encoding="utf-8")

用拒绝清单验证工具契约

验证时不要只测一个正常文件。至少覆盖空字符串、绝对路径、父级穿越、混合分隔符、工作区外符号链接和不存在的新文件。每次拒绝都返回稳定的错误码，例如 PATH_OUTSIDE_WORKSPACE，不要把主机绝对路径、环境变量或密钥片段回显给模型。

最后再检查权限矩阵：读取、写入、删除和执行不应共用一个“路径通过”开关。工作区限制解决的是范围问题，最小权限解决的是动作问题，两者缺一不可。

相关问题

为什么不能只禁止字符串 ..？

编码、分隔符和符号链接都可能改变最终目标。应以规范化后的真实路径做边界判断，而不是依赖单个黑名单字符串。

相对路径是否天然安全？

不是。相对路径仍可能通过父级目录或链接离开工作区，所以必须绑定根目录并解析后检查。

校验通过后能否直接交给 shell？

不建议。文件路径边界与命令注入是不同问题；优先调用文件 API，必须执行命令时使用参数数组和独立的命令白名单。