CMDC.Sandbox.Local (cmdc v0.6.0)

Copy Markdown View Source

Sandbox 的本地 OS 默认实现，直接调用本地文件系统和 shell。

适合开发环境和受信任的执行场景。生产环境可替换为 Docker Sandbox 或其他隔离实现。

所有文件操作相对于 :working_dir 选项指定的目录执行。

路径安全防护（v0.6+ :virtual_mode，默认 true）

v0.6 起 :virtual_mode 默认从 false → true（唯一 minor breaking 改动）, 拒绝以下"路径越界"操作以防止 Agent 误操作 / 注入攻击逃出 working_dir:

  • path 含 .. ("../etc/passwd")
  • path 以 ~ 开头 ("~/.ssh/id_rsa")
  • 绝对路径解析后不在 working_dir 内（"/etc/passwd" 而 working_dir=/tmp）

违反时返 {:error, "路径越界（virtual_mode 防护...）"} 字符串。file_exists?/2 在越界路径上返 false（行为类似不存在）。

显式 opt-out（v0.5 老代码迁移）

确实需要跨目录访问的合法场景（Agent 跨多 working_dir 操作 / 系统级文件读写 / CLI 工具开发），显式传 :virtual_mode false 回退到 v0.5 行为：

{:ok, content} = CMDC.Sandbox.Local.read_file("/etc/hosts",
  working_dir: "/tmp",
  virtual_mode: false              # 显式 opt-out,Logger.warning 1 次
)

Process 级别只会 warn 一次以避免日志风暴。强烈建议集成方先评估 working_dir 设置是否合理，再考虑 opt-out（如可重设 working_dir 为公共祖先目录则不需要回退）。

使用示例

{:ok, content} = CMDC.Sandbox.Local.read_file("lib/app.ex",
  working_dir: "/path/to/project"
)

:ok = CMDC.Sandbox.Local.write_file("output.txt", "Hello",
  working_dir: "/tmp"
)

{:ok, result} = CMDC.Sandbox.Local.execute("mix test",
  working_dir: "/path/to/project",
  timeout: 60_000
)