sandbox

沙箱执行提供了额外的安全隔离层，防止命令影响主系统。

设计理念

即使通过了权限检查，某些命令仍然可能：

• 产生意外副作用

• 消耗过多资源

• 影响系统稳定性

沙箱执行提供隔离环境。

实现方式

Docker 容器

async function executeSandboxed(
  command: string,
  cwd: string
): Promise<ExecResult> {
  const sandboxCommand = `
    docker run --rm \
      -v ${cwd}:/workspace:ro \
      -w /workspace \
      --network none \
      --memory 512m \
      --cpus 1 \
      alpine:latest \
      sh -c "${escapeCommand(command)}"
  `;
  
  return executeCommand(sandboxCommand);
}

限制:

• 只读文件系统

• 无网络访问

• 内存限制 512MB

• CPU 限制 1 核

VM 隔离

async function executeInVM(
  command: string
): Promise<ExecResult> {
  // 使用 vm2 或类似库
  const vm = new VM({
    timeout: 5000,
    sandbox: {
      console: sandboxConsole,
      require: sandboxRequire,
    },
  });
  
  return vm.run(command);
}

触发条件

自动沙箱

某些命令自动在沙箱中执行：

function shouldSandbox(command: string): boolean {
  // 未知命令
  if (classifyCommand(command).level === 'unknown') {
    return true;
  }
  
  // 用户脚本
  if (command.startsWith('./') || command.startsWith('node ')) {
    return true;
  }
  
  // 复杂管道
  if (command.split('|').length > 3) {
    return true;
  }
  
  return false;
}

用户选择

// 用户可以强制沙箱执行
await executePwsh({
  command: 'npm run build',
  sandbox: true,
});

资源限制

时间限制

const SANDBOX_TIMEOUT = 30000; // 30 秒

async function executeWithTimeout(
  command: string,
  timeout: number
): Promise<ExecResult> {
  return Promise.race([
    executeCommand(command),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Timeout')), timeout)
    ),
  ]);
}

内存限制

// Docker 内存限制
--memory 512m --memory-swap 512m

CPU 限制

// Docker CPU 限制
--cpus 1 --cpu-shares 512

文件系统隔离

只读挂载

// 工作目录只读
-v ${cwd}:/workspace:ro

// 如果需要写入，使用临时目录
-v ${tmpDir}:/tmp:rw

写时复制

async function executeWithCOW(command: string): Promise<ExecResult> {
  // 1. 创建文件系统快照
  const snapshot = await createSnapshot(cwd);
  
  // 2. 在快照上执行
  const result = await executeCommand(command, { cwd: snapshot });
  
  // 3. 如果成功，应用更改
  if (result.code === 0) {
    await applySnapshot(snapshot, cwd);
  }
  
  // 4. 清理快照
  await deleteSnapshot(snapshot);
  
  return result;
}

网络隔离

禁用网络

// Docker 无网络
--network none

白名单主机

// 允许特定主机
--add-host registry.npmjs.org:104.16.0.0

// 使用代理
--env HTTP_PROXY=http://proxy:8080

性能影响

开销

• Docker 启动: ~500ms

• 文件挂载: ~100ms

• 命令执行: 正常时间

• 总开销: ~600ms

优化

// 复用容器
const containerPool = new Map<string, Container>();

async function getOrCreateContainer(): Promise<Container> {
  const key = 'sandbox-pool';
  
  if (containerPool.has(key)) {
    return containerPool.get(key);
  }
  
  const container = await docker.createContainer({
    Image: 'alpine:latest',
    // ...
  });
  
  await container.start();
  containerPool.set(key, container);
  
  return container;
}

配置选项

用户配置

{
  "sandbox": {
    "enabled": true,
    "mode": "docker",
    "autoSandbox": ["unknown", "user-script"],
    "resources": {
      "memory": "512m",
      "cpus": 1,
      "timeout": 30000
    }
  }
}

下一步

• 了解 分类器 的智能审批

• 查看 权限模式 的配置

• 探索 BashTool 的完整实现