安全沙箱与审批

Rust 原生 OS 级沙箱隔离、四级安全模型、三平台降级链、命令工具集与分级审批制度

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

为什么选择 Rust 原生沙箱

OS 内核级隔离

直接对接 macOS Seatbelt、Linux Landlock/Seccomp、Windows AppContainer。系统级强隔离，无法从内部突破。

亚毫秒延迟

持久化 Worker IPC 模式下命令执行延迟 <1ms，远快于 Docker 容器（~50ms+）。编程体验零感知。

三平台降级链

macOS/Linux/Windows 各有原生沙箱方案，不可用时自动降级到 Docker，确保任何环境都有安全保障。

不可逆沙箱化

Worker 进程自沙箱化后无法解除约束，子进程自动继承。即使 LLM 尝试提权也无法逃逸。

任务级挂载审批

需要工作区外文件时，按任务临时授权挂载路径，任务结束后自动回收。最小权限原则。

智能审批门控

三级审批制度：只读自动放行、写入确认审批、高危严格管控。不干扰日常操作又守住安全底线。

四级安全模型（L0-L3）

级别	配置值	沙箱	网络策略	文件系统	触发方式
L0	`deny`	启用	完全禁止（socket 阻断）	只读	配置/合约约束
L1	`allowlist`	启用	受限（公网 TCP+DNS）	工作区读写	默认级别
L2	`sandboxed`	启用	全网络	工作区 + 临时挂载	mount_access 审批
L3	`full`	禁用	全网络	全权限	向导/配置永久授权

安全级别详解

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

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

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

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

配置方式

json

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

Rust 原生沙箱引擎

三平台降级链

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

macOS:

shell

Seatbelt FFI → Docker fallback
Seatbelt FFI → Docker fallback

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

Linux:

shell

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

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

Windows:

shell

RestrictedToken + JobObject → JobObject only → Docker fallback
RestrictedToken + JobObject → JobObject only → Docker fallback

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

双路径执行架构

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

shell

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 生命周期

shell

启动: 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 通道关闭

网络策略

策略	含义	适用级别
`None`	无网络（socket 系统调用阻断）	L0
`Restricted`	公网 TCP+DNS；阻断 localhost/LAN/Unix socket	L1
`Host`	全宿主机网络	L2, L3

自定义网络白名单：

json

{
  "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 确认级（人类在环）

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

操作	审批类型	说明
文件写入/修改	`plan_confirm`	展示变更预览
定时任务创建	`plan_confirm`	展示 cron 表达式
内容发布	`plan_confirm`	展示发布内容
文件发送/邮件	`data_export`	确认导出目标

L3 审批级（严格管控）

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

操作	审批类型	说明
Shell 命令执行	`exec_escalation`	展示完整命令
工作区外文件访问	`mount_access`	确认挂载路径和权限
批量删除操作	`exec_escalation`	二次确认
系统管理操作	`exec_escalation`	展示影响范围

挂载请求 (MountRequests)

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

shell

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

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

[批准] [拒绝]

挂载生命周期：

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

挂载模式：

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

Rust 命令工具集

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

沙箱管理命令

bash

# 在沙箱中执行命令
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

安全审计命令

bash

# 查看审批历史
crabclaw security audit

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

# 查看活跃的挂载请求
crabclaw security mounts
# 查看审批历史
crabclaw security audit

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

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

诊断命令

bash

# 系统诊断
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 的安全不仅仅是沙箱，而是八层纵深防御体系：

层级	防御机制	说明
L1	OS 沙箱隔离	Rust 原生沙箱，内核级强隔离
L2	委托合约	DelegationContract 定义子智能体行为边界
L3	审批门控	三级审批制度，危险操作人类在环
L4	权限升级管理	EscalationManager，TTL 自动过期
L5	安全规则引擎	SupervisorPolicyEngine，硬编码黑名单
L6	写入检测	自动检测文件系统写入操作
L7	网络策略	分级网络访问控制
L8	审计追踪	完整操作日志和审批历史

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