path-safety

路径安全编码规范

编辑此目录下的文件时，请遵守以下安全规则（详见 docs/dev-guides/8-path-safety.md 和 .cursor/skills/path-safety/SKILL.md）：

ConfinedDir 是唯一的路径约束原语

所有接受用户可控路径的代码，必须通过 ConfinedDir 实例访问文件系统。

from data_formulator.security.path_safety import ConfinedDir

jail = ConfinedDir(root_dir, mkdir=False)
try:
    target = jail.resolve(user_input)
except ValueError:
    return {"error": "Access denied"}

禁止的模式

# ❌ BAD — 裸路径拼接
target = Path(root) / user_input

# ❌ BAD — 手写 resolve + relative_to（已弃用，必须用 ConfinedDir）
target = (root / user_input).resolve()
try:
    target.relative_to(root)
except ValueError: ...

# ❌ BAD — 手写 is_relative_to（已弃用，必须用 ConfinedDir）
resolved = (root / user_input).resolve()
if not resolved.is_relative_to(root.resolve()): ...

# ❌ BAD — 路径比较用 str.startswith
if str(target).startswith(str(root)): ...

正确的模式

# ✅ GOOD — Agent 工具
workspace_jail = self.workspace.confined_root
scratch_jail = self.workspace.confined_scratch
target = workspace_jail.resolve(rel_path)

# ✅ GOOD — 文件下载 route
scratch_jail = workspace.confined_scratch
target = scratch_jail.resolve(filename)
return send_file(target)

# ✅ GOOD — 文件上传（两层防御）
safe_name = secure_filename(raw_filename)
target = scratch_jail.resolve(safe_name)

# ✅ GOOD — Workspace data 文件
path = workspace.get_file_path(filename)  # 内部使用 ConfinedDir

部署守卫

• 新增读取宿主文件系统的 Loader 必须在 _enforce_deployment_restrictions() 注册多用户禁用
• 多用户模式（WORKSPACE_BACKEND != "local"）必须启用沙箱