[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 相关: Tool Runtime, Permission Boundary
• Agent 工具应用: Tool Sandbox

Sandbox

一句话定义

Sandbox 是把不可信或高风险工作负载放入受控执行边界的通用隔离机制；Agent 工具执行只是其中一种应用。

角色边界

• 本页解释 Sandbox 这一通用隔离原语：隔离什么、靠哪些边界实现、失效时会发生什么。
• Tool Sandbox 解释 Agent/Tool Calling 场景如何把 sandbox 约束映射到具体工具策略。
• 权限允许什么操作由 Permission Boundary 决定；Sandbox 负责即使允许执行，也尽量把影响范围限制住。

它解决什么问题

Agent 执行的工具可能是：

• 运行用户提供的代码
• 执行 Shell 命令
• 读写文件系统
• 调用外部 API

这些操作如果直接在宿主系统执行，可能导致：

• 代码注入攻击
• 文件系统被破坏
• 系统资源被耗尽
• 敏感数据泄露

核心原理

沙箱实现方式

方式	隔离级别	启动速度	适用场景
Docker 容器	高	慢（秒级）	生产环境
gVisor	高	中	生产环境
Firecracker	最高	中	多租户
进程隔离	中	快	开发环境
语言级沙箱	低	最快	简单脚本

Python 实现（Docker 沙箱）

class DockerSandbox:
    def __init__(self, image: str = "python:3.11-slim"):
        self.image = image

    async def execute(self, code: str, timeout: int = 30) -> SandboxResult:
        # 创建容器
        container = await docker.containers.create(
            image=self.image,
            command=["python", "-c", code],
            mem_limit="256m",
            cpu_quota=50000,  # 50% CPU
            network_disabled=True,  # 禁用网络
            read_only=True,  # 只读文件系统
            tmpfs={"/tmp": "size=64m"},  # 临时目录
        )

        try:
            # 启动并等待完成
            await container.start()
            result = await asyncio.wait_for(
                container.wait(),
                timeout=timeout,
            )

            # 获取输出
            logs = await container.logs(stdout=True, stderr=True)
            return SandboxResult(
                exit_code=result["StatusCode"],
                output=logs.decode(),
            )
        except asyncio.TimeoutError:
            await container.kill()
            return SandboxResult(error="Execution timeout")
        finally:
            await container.remove()

OpenAI Code Interpreter 的沙箱

OpenAI 的 Code Interpreter 在隔离容器中执行代码：

• 网络隔离
• 文件系统隔离
• 资源限制（CPU、内存、时间）
• 临时环境（执行后销毁）

常见坑

1. 不做资源限制: 代码死循环吃满 CPU
2. 不做网络隔离: 恶意代码访问外部服务
3. 不做文件系统隔离: 代码读写宿主文件
4. 沙箱启动太慢: 每次工具调用都创建新容器

学习检查

1. Sandbox 与权限控制为什么不是同一个问题？
2. 文件系统、网络、CPU/内存和生命周期隔离分别防什么风险？
3. 为什么容器并不天然等于强安全沙箱？
4. 在 Agent 工具调用里，什么时候应进一步查看 Tool Sandbox？

参考资料

• OpenAI Code Interpreter
• Docker Security
• gVisor