Grok Build · Sandbox Profiles

五种沙箱 Profile

workspace、devbox、read-only、strict、off 定义文件系统和子进程网络的不同能力集合。名称提供方向,真实边界要看解析后的 capability set。

课程目标

能从 ProfileNameSandboxProfile 判断读写与网络边界,能正确配置 custom extends,并识别平台支持与降级条件。

TEACHING DIAGRAM

Profile 是多维能力预设

横向位置用于帮助记忆。devbox、workspace、strict 的实际差异同时包含默认读取、可写路径与网络策略。

五种 Profile 的教学化能力光谱 offno sandbox devboxbroad writes workspacedefault profile strictallowlisted reads read-onlyno workspace write 更开放更收敛
五种内置 Profile 的源码语义
workspace

全文件系统默认可读;workspace、GROK_HOME、临时目录可写;不限制子进程网络。

default_read=true
restrict_network=false
devbox

全文件系统默认可读;枚举根目录,除 /data 与虚拟文件系统外广泛授予写权限;网络不限制。

/data 保持可读,在 Linux 通过 bwrap 做写保护
read-only

全文件系统默认可读;workspace 不可写;GROK_HOME、临时目录和必要设备仍可写。

restrict_network=true
strict

关闭全局默认读,只开放系统运行目录与 workspace;workspace、GROK_HOME、临时目录可写。

default_read=false
restrict_network=true
off

跳过 capability set 应用,记录「Sandbox disabled」。它也接受别名 none。

不可作为 custom extends 的基类
容易误读的两点:workspace 仍允许读取工作区外文件;strict 仍允许写 workspace。read-only 也保留运行所需的最小写目录。课程名称必须服从源码 capability,而不能按字面补全规则。
Custom profile 与配置边界

extends 规则

  • custom 默认从 workspace 开始。
  • 可 extends workspace、devbox、read-only、strict。
  • 不能 extends off/none。
  • 不能 extends 另一个 custom profile。
  • read_only、read_write、deny 追加到基类。需要限制子进程网络时,应在 custom 中显式设置 restrict_network=true

全局优先保护

系统先读取 ~/.grok/sandbox.toml,再读取 .grok/sandbox.toml。项目配置只能新增 profile 名称。若项目声明了全局已存在的同名 profile,merge 使用 entry.or_insert,全局定义保持生效。

crates/codegen/xai-grok-sandbox/src/profiles.rs crates/codegen/xai-grok-sandbox/src/paths.rs ProfileName load_sandbox_config merge_project_profiles
平台机制与降级条件

文件系统约束

启用 enforce 且运行在 Unix 时,nono 将 capability set 应用到 Landlock 或 Seatbelt。macOS deny 使用 Seatbelt 规则;Linux 的子路径 read-deny 还需要 bwrap bind-over。

网络约束

主进程网络保持开放以访问模型 API。restrict_network 当前通过子进程过滤表达,源码中的 seccomp 实现在 Linux 生效,非 Linux 函数为空操作。平台边界需要按实际构建与运行环境验证。

避免绝对化:若平台不支持、构建未启用 enforce,或 apply 失败,源码会记录警告并继续运行,is_active() 才能反映是否实际应用。因此不能承诺所有环境都「无法绕过」。
真实源码快照
crates/codegen/xai-grok-sandbox/src/profiles.rsREAL SOURCE
pub enum ProfileName {
    #[default]
    Workspace,
    Devbox,
    ReadOnly,
    Strict,
    Off,
    Custom(String),
}

快照说明:枚举完整保留。光谱图用于教学记忆;真实能力来自 resolve()essential_writable_paths() 与平台 apply 结果。

课堂练习:设计审查专用 Profile

要求能读仓库与系统工具、不能改 workspace、允许写临时目录、限制子进程网络,并额外 deny ~/.ssh。选择一个内置基类,写出 custom profile 的 extends 与 deny,并解释项目为何无法替换用户全局的同名定义。

Takeaway:五种 Profile 是可解析的能力模板。评估安全性要看默认读、可写路径、deny、子进程网络、平台支持和 apply 状态;custom 合并规则防止项目悄悄削弱同名全局策略。