安全沙箱与审批 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

Crab Claw 采用零信任安全模型：所有 Agent 执行的命令默认在 Rust 原生沙箱中运行，通过 OS 级隔离确保 LLM 输出不会危害宿主系统。这不是简单的 Docker 容器隔离——而是直接对接操作系统内核安全机制的原生级防护。

为什么选择 Rust 原生沙箱

四级安全模型（L0-L3）

安全级别详解

L0 - 完全封锁：适用于不可信环境。阻断所有 socket 系统调用，文件系统只读。LLM 只能思考和对话，无法执行任何副作用操作。

L1 - 白名单（默认）：日常使用推荐级别。允许工作区内读写和公网访问（HTTP/HTTPS + DNS），阻断本地网络（localhost/LAN/Unix socket）。绝大多数开发任务在此级别完成。

L2 - 沙箱增强：需要访问工作区外文件时使用。通过 mount_access 审批临时挂载外部路径，权限按任务作用域管理，任务结束自动回收。

L3 - 完全开放：裸机运行，不经过沙箱。由向导/配置永久授权，开启后零审批。仅在完全信任环境中使用。

配置方式

{
  "agents": {
    "defaults": {
      "sandbox": {
        "securityLevel": "allowlist"
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "sandbox": {
        "securityLevel": "allowlist"
      }
    }
  }
}

Rust 原生沙箱引擎

三平台降级链

每个平台都有从强到弱的降级策略，确保在任何环境中都有安全保障：

macOS:

Seatbelt FFI → Docker fallback

Seatbelt FFI → Docker fallback

• Seatbelt：macOS 原生 App Sandbox 技术
• 通过 FFI 直接调用 macOS 内核沙箱接口
• 策略在 Worker 启动时通过 pre_exec 固定，运行时无法变更

Linux:

Namespace + Seccomp + Landlock → Landlock + Seccomp → Docker fallback

Namespace + Seccomp + Landlock → Landlock + Seccomp → Docker fallback

• Namespace：进程/网络/文件系统命名空间隔离
• Seccomp：系统调用过滤（白名单模式）
• Landlock：文件系统访问控制（Linux 5.13+）

Windows:

RestrictedToken + JobObject → JobObject only → Docker fallback

RestrictedToken + JobObject → JobObject only → Docker fallback

• RestrictedToken：降权令牌，剥离危险权限
• JobObject：进程组资源限制和隔离
• ACL 硬化：可配合 NTFS 权限进一步收紧

双路径执行架构

沙箱执行按安全级别选择不同路径：

NativeSandboxRouter.ExecuteSandboxed(securityLevel)
  │
  ├── L1 "allowlist"
  │   └── l1Bridge.Execute() — 持久 Worker IPC
  │       延迟 <1ms，复用长连接
  │
  ├── L2 "sandboxed"
  │   └── executeOneShot() — 一次性 CLI
  │       延迟 ~50ms，支持 --mount 临时挂载
  │       任务结束自动回收
  │
  └── L3 → 不经过沙箱路由（裸机执行）

NativeSandboxRouter.ExecuteSandboxed(securityLevel)
  │
  ├── L1 "allowlist"
  │   └── l1Bridge.Execute() — 持久 Worker IPC
  │       延迟 <1ms，复用长连接
  │
  ├── L2 "sandboxed"
  │   └── executeOneShot() — 一次性 CLI
  │       延迟 ~50ms，支持 --mount 临时挂载
  │       任务结束自动回收
  │
  └── L3 → 不经过沙箱路由（裸机执行）

为什么 L1 和 L2 使用不同路径？

持久 Worker 的 Seatbelt/Landlock 策略在启动时固定（pre_exec），无法运行时变更。L2 的"工作区外临时挂载"需要每次执行时动态绑定路径，因此使用一次性 CLI 执行，自然绑定到当前任务生命周期。

Worker 生命周期

启动: launch_worker(config)
  → apply_sandbox_policy() (pre_exec, 不可逆)
  → JSON-Lines IPC 通道建立
  → 心跳检测 (5s 间隔)

执行: 接收命令 → 沙箱内执行 → 返回结果
  → stdout/stderr 捕获
  → 超时控制 (可配置)
  → 退出码传递

终止: 优雅关闭 → 子进程回收 → IPC 通道关闭

启动: launch_worker(config)
  → apply_sandbox_policy() (pre_exec, 不可逆)
  → JSON-Lines IPC 通道建立
  → 心跳检测 (5s 间隔)

执行: 接收命令 → 沙箱内执行 → 返回结果
  → stdout/stderr 捕获
  → 超时控制 (可配置)
  → 退出码传递

终止: 优雅关闭 → 子进程回收 → IPC 通道关闭

网络策略

自定义网络白名单：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "networkAllowlist": ["api.example.com", "*.github.com"]
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "sandbox": {
        "networkAllowlist": ["api.example.com", "*.github.com"]
      }
    }
  }
}

三级审批制度

L1 通知级（自动放行）

只读操作无需用户确认，静默执行：

• 文件读取 (read_file, list_dir)
• 网页搜索 (web_search, web_fetch)
• 记忆查询 (memory_search)
• 屏幕截图 (argus_capture_screen)

L2 确认级（人类在环）

写入操作需要用户在消息频道中一键确认：

L3 审批级（严格管控）

高风险操作需要严格审批：

挂载请求 (MountRequests)

当 Agent 需要访问工作区外的路径时，触发 mount_access 审批：

Agent 请求挂载 /usr/local/bin（只读）
原因：需要检查已安装的 CLI 工具版本

[批准] [拒绝]

Agent 请求挂载 /usr/local/bin（只读）
原因：需要检查已安装的 CLI 工具版本

[批准] [拒绝]

挂载生命周期：

1. Agent 请求挂载外部路径
2. 用户确认批准
3. L2 一次性 CLI 执行，通过 --mount host:sandbox:mode 传递
4. 任务结束后自动回收，无残留权限

挂载模式：

• ro（只读）：默认模式，仅允许读取
• rw（读写）：需要更高级别确认

Rust 命令工具集

沙箱不仅提供隔离，还内置丰富的安全命令工具：

沙箱管理命令

# 在沙箱中执行命令
crabclaw sandbox run --security allowlist -- ls -la

# 指定工作区
crabclaw sandbox run --workspace /path/to/project -- npm test

# L2 带挂载
crabclaw sandbox run --security sandboxed \
  --mount /usr/local/bin:/usr/local/bin:ro \
  -- which node

# 输出格式 (JSON 结构化)
crabclaw sandbox run --format json -- echo hello

# 在沙箱中执行命令
crabclaw sandbox run --security allowlist -- ls -la

# 指定工作区
crabclaw sandbox run --workspace /path/to/project -- npm test

# L2 带挂载
crabclaw sandbox run --security sandboxed \
  --mount /usr/local/bin:/usr/local/bin:ro \
  -- which node

# 输出格式 (JSON 结构化)
crabclaw sandbox run --format json -- echo hello

安全审计命令

# 查看审批历史
crabclaw security audit

# 查看当前安全策略
crabclaw security status

# 查看活跃的挂载请求
crabclaw security mounts

# 查看审批历史
crabclaw security audit

# 查看当前安全策略
crabclaw security status

# 查看活跃的挂载请求
crabclaw security mounts

诊断命令

# 系统诊断
crabclaw doctor

# 检查沙箱可用性
crabclaw doctor --check sandbox

# 检查 TCC 权限 (macOS)
crabclaw doctor --check tcc

# 系统诊断
crabclaw doctor

# 检查沙箱可用性
crabclaw doctor --check sandbox

# 检查 TCC 权限 (macOS)
crabclaw doctor --check tcc

安全审计

所有审批决策记录在 ~/.crabclaw/state/exec-approvals.json，支持回溯审查：

• 每条记录包含：时间戳、操作类型、审批级别、审批结果、执行上下文
• 持久化值使用规范名称（allowlist/sandboxed/full），legacy alias 仅作输入兼容
• 支持查询历史审批、统计审批通过率、导出审计报告

八层纵深防御

Crab Claw 的安全不仅仅是沙箱，而是八层纵深防御体系：

相关文档：能力树与权限 · 编程子智能体 · 视觉理解智能体