Skip to content

sandbox.md

Latest commit

 

History

History
220 lines (175 loc) · 5.33 KB

sandbox.md

File metadata and controls

220 lines (175 loc) · 5.33 KB

沙箱安全

沙箱（Sandbox）在操作系统层面限制 Agent 的命令执行能力，防止意外的文件删除、网络访问等危险操作。它与权限系统互补——权限控制「是否询问」，沙箱控制「能做什么」。

快速开始

import { createSession } from '@blade-ai/agent-sdk';

const session = await createSession({
  provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
  model: 'gpt-4o',
  sandbox: {
    enabled: true,
    autoAllowBashIfSandboxed: true,
  },
});

::: tip enabled: true + autoAllowBashIfSandboxed: true 是本地开发推荐配置：命令在沙箱内执行（安全），同时不需要每次确认（便捷）。 :::

SandboxSettings 完整参考

interface SandboxSettings {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: NetworkSandboxSettings;
  ignoreViolations?: SandboxIgnoreViolations;
  enableWeakerNestedSandbox?: boolean;
}
字段 类型 默认值 说明
enabled boolean false 开启沙箱
autoAllowBashIfSandboxed boolean false 沙箱内的 Bash 命令自动批准（不弹权限确认）
excludedCommands string[] [] 排除在沙箱外执行的命令
allowUnsandboxedCommands boolean false 当沙箱不可用时，是否允许命令无沙箱执行
network NetworkSandboxSettings — 网络访问策略
ignoreViolations SandboxIgnoreViolations — 忽略特定违规
enableWeakerNestedSandbox boolean false 在已有沙箱内允许较弱的嵌套沙箱

网络配置

interface NetworkSandboxSettings {
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
}
字段 说明 典型场景
allowLocalBinding 允许绑定本地端口 启动开发服务器（vite、next dev）
allowUnixSockets 允许访问指定 Unix Socket Docker (/var/run/docker.sock)
allowAllUnixSockets 允许所有 Unix Socket 复杂 IPC 环境
httpProxyPort HTTP 代理端口 网络代理转发
socksProxyPort SOCKS 代理端口 SOCKS 代理转发

违规忽略

当某些文件访问或网络连接会触发沙箱违规但属于预期行为时，可以配置忽略：

interface SandboxIgnoreViolations {
  file?: string[];     // glob 模式
  network?: string[];  // 主机:端口 模式
}
sandbox: {
  enabled: true,
  ignoreViolations: {
    file: ['/tmp/**', '/var/cache/**'],
    network: ['localhost:*', '127.0.0.1:3000'],
  },
}

沙箱 vs 权限

维度 沙箱（Sandbox） 权限（Permission）
层级 操作系统级 应用逻辑级
作用 限制命令能做什么 控制命令是否询问
配置项 sandbox permissionMode / canUseTool
绕过方式 无法绕过（OS 强制） 可通过 yolo 跳过

组合配置对比：

沙箱 权限模式 效果
✅ enabled + autoAllow default 命令安全执行，无需确认（推荐开发）
✅ enabled default 命令安全执行，每次确认
❌ disabled yolo 无沙箱无确认（危险）
❌ disabled default 无沙箱，每次确认

::: danger 不建议同时关闭沙箱和使用 yolo 权限模式，这意味着 Agent 可以不受限制地执行任何命令。 :::

常见配置场景

本地开发（推荐）

sandbox: {
  enabled: true,
  autoAllowBashIfSandboxed: true,
  network: {
    allowLocalBinding: true,  // 允许 vite/next 绑定端口
  },
}

Docker 工作流

sandbox: {
  enabled: true,
  autoAllowBashIfSandboxed: true,
  network: {
    allowUnixSockets: ['/var/run/docker.sock'],
  },
}

CI/CD 严格模式

sandbox: {
  enabled: true,
  // 不自动批准，每个命令都需要权限检查
  autoAllowBashIfSandboxed: false,
}

Web 爬虫/网络访问

sandbox: {
  enabled: true,
  autoAllowBashIfSandboxed: true,
  ignoreViolations: {
    network: ['*.example.com:443'],  // 允许特定域名
  },
}

不使用沙箱

当你在已有的安全环境（如容器内）运行，或沙箱与你的工作流不兼容时：

sandbox: {
  enabled: false,
}

排错指南

命令被意外阻止

症状： Bash 工具报告命令被沙箱阻止。

解决：

  1. 检查是否启用了 autoAllowBashIfSandboxed
  2. 查看是否需要将命令加入 excludedCommands
  3. 检查 ignoreViolations 是否需要添加文件/网络规则

网络访问被拒绝

症状： curl、wget 等命令无法访问外部网络。

解决：

sandbox: {
  enabled: true,
  ignoreViolations: {
    network: ['target-host.com:443'],
  },
}

Docker 命令失败

症状： docker 命令无法连接到 Docker daemon。

解决：

sandbox: {
  enabled: true,
  network: {
    allowUnixSockets: ['/var/run/docker.sock'],
  },
}

端口绑定失败

症状： 开发服务器无法启动，端口绑定被拒绝。

解决：

sandbox: {
  enabled: true,
  network: {
    allowLocalBinding: true,
  },
}