沙箱系统 — 概念

跨平台沙箱架构

Codex 的 Sandbox 系统采用平台适配的分层隔离策略，通过 SandboxManager（sandboxing/src/manager.rs）统一抽象：

SandboxType 枚举定义了三种平台沙箱类型：

平台	SandboxType 变体	底层技术	核心文件
macOS	MacosSeatbelt	Seatbelt（sandbox-exec）	sandboxing/src/seatbelt/
Linux	LinuxSeccomp	Seccomp + Bubblewrap	sandboxing/src/bwrap/、linux-sandbox/
Windows	WindowsRestrictedToken	Restricted Token	sandboxing/src/

SandboxManager 的核心接口：

pub struct SandboxManager;  // 无状态，Default trait

impl SandboxManager {
    pub fn new() -> Self
    pub fn select_initial(preference: SandboxablePreference) -> Result<SandboxType>
    pub fn transform(req: SandboxTransformRequest) -> Result<SandboxExecRequest>
}

pub enum SandboxablePreference { Auto, Require, Forbid }

SandboxTransformRequest 包含待执行的命令、权限配置、沙箱类型和网络策略。transform() 方法将其转换为 SandboxExecRequest——一个被沙箱包装后的可执行命令。

Landlock Linux 沙箱

Landlock 是 Linux 5.1+ 内核提供的 Linux Security Module（LSM）框架，Codex 在其基础上结合 Bubblewrap（bwrap）实现双层隔离：

Linux 沙箱的执行流程：

1. 辅助二进制：codex-linux-sandbox 是独立的沙箱辅助程序，入口 run_main() 应用 seccomp 限制
2. 命令包装：SandboxManager::transform() 将原始命令包装为 codex-linux-sandbox -- <original_command>
3. 文件系统隔离：Bubblewrap 创建新的 mount namespace，将 workspace 目录设为可读写，系统目录设为只读
4. 权限过滤：Landlock LSM 规则限制文件访问范围，确保代理只能操作 workspace 内的文件
5. 网络策略：通过 NetworkSandboxPolicy 控制网络访问，NetworkRule 定义允许/禁止的域名

// 网络策略规则
pub struct NetworkRule {
    pub host: String,
    pub protocol: Option<String>,
    pub decision: Decision,       // Allow / Forbidden
    pub justification: String,
}

Seatbelt macOS 沙箱

Seatbelt 是 macOS 原生的沙箱机制（sandbox-exec），Codex 通过生成 plist 规则 实现权限控制：

Seatbelt 的规则配置特点：

• 声明式规则：通过 plist 文件声明允许/禁止的文件系统路径和操作类型
• 动态生成：每次命令执行时根据当前 workspace 和权限配置动态生成规则
• 继承限制：子进程继承父进程的沙箱限制，确保工具链不会绕过隔离
• 权限提升：用户审批后可通过 additional_permissions 临时扩展访问范围

ExecPolicy 执行策略

ExecPolicy 定义了命令执行的权限评估规则，是沙箱系统之上的策略层：

Policy 和 Rule 的核心结构（execpolicy/src/policy.rs）：

pub struct Policy {
    rules_by_program: MultiMap<String, RuleRef>,
    network_rules: Vec<NetworkRule>,
    host_executables_by_name: HashMap<String, Arc<[AbsolutePathBuf]>>,
}

pub struct Evaluation {
    pub decision: Decision,
    pub matched_rules: Vec<RuleMatch>,
}

pub enum Decision { Allow, Forbidden, Prompt }

策略的加载和管理：

组件	功能	源码位置
Policy::check()	评估命令的执行权限	execpolicy/src/policy.rs
Policy::add_prefix_rule()	添加前缀匹配规则	execpolicy/src/policy.rs
Policy::add_network_rule()	添加网络规则	execpolicy/src/policy.rs
Policy::merge_overlay()	合并策略覆盖层	execpolicy/src/policy.rs
load_exec_policy()	从配置加载策略	core/src/lib.rs
check_execpolicy_for_warnings()	检查策略警告	core/src/lib.rs

相关概念

• Sandbox — 沙箱系统的整体设计
• Landlock — Linux 内核级文件系统沙箱
• Seatbelt — macOS 原生沙箱机制
• ExecPolicy — 执行策略和权限评估
• Ephemeral — 临时执行环境的安全策略