Documentation
¶
Overview ¶
本文件实现沙箱升级机制(Escalation):严格更宽阶梯 + 审批集成 + 标记。
对齐官方:packages/sandbox/sandbox/src/escalation.ts
设计要点:
- WIDER_MODES 严格更宽阶梯表:read-only → [workspace-write, danger-full-access], workspace-write → [danger-full-access];danger 是顶点,不能再升级;
- ESCALATION_TARGETS 封闭目标词汇:[workspace-write, danger-full-access], read-only 是底线,不在目标中(任何模式都不会升级到 read-only);
- 严格更宽是执行时检查(针对本次调用的 effectiveMode),不是 schema 约束 (schema 枚举是封闭目标词汇,effectiveMode 是每次调用的真实状态);
- 升级需要 sandbox_permissions + justification 成对参数,缺一不可, justification 必须是非空句子;
- approveEscalation 是有序 fail-closed 流程: 严格更宽检查 → 审批通道(approver.Request)→ 结果映射 (allowed-once 返回目标模式,rejected/cancelled/unavailable 抛精确错误);
- 非更宽请求绝不询问用户(先检查再问人)。
本文件实现沙箱不变量校验。
对齐官方:packages/sandbox/sandbox/src/invariant.ts + sandbox-policy/src/invariant.ts + sandbox-local/src/invariant.ts
设计要点:
- 不变量校验在开发模式下启用,生产模式下可关闭(通过 InvariantEnabled 开关);
- 校验失败时 panic 并携带包归属信息(sandbox),便于定位;
- 覆盖:模式合法性、policy 字段一致性、workspace-write 必须有 root、 danger 模式不能 ToConfined、升级目标合法性、ConfinedArgv 非空等。
本文件实现本地后端多探测链 + LocalProvider。
对齐官方:packages/sandbox/sandbox-local/src/index.ts
设计要点:
- 平台检测:Linux 链 bwrap → landlock,macOS 链 seatbelt,Windows 链 windows-acl;
- 功能探测:用 read-only profile + true 命令实际运行,成功则后端可用;
- 探测结果缓存:进程级单例,只探测一次;
- LocalProvider 实现 SandboxProvider 接口:Confine() 根据后端类型组装完整 argv;
- 后端特定 denialSignatures:bwrap EROFS、landlock EACCES、seatbelt EPERM;
- Config 支持 runnerCommand 覆盖(跳过探测,直接使用指定 runner)。
本文件实现本地后端的 profile 参数构建:bwrap / landlock / seatbelt。
对齐官方:packages/sandbox/sandbox-local/src/profiles.ts
设计要点:
- BwrapProfileArgs:Linux Bubblewrap,--ro-bind / / 挂载只读根, workspace-write 时额外 --tmpfs /tmp + --bind workspaceRoot;
- LandlockProfileArgs:Linux Landlock 内核安全模块,白名单授权, readOnly=[/], readWrite=[/dev/null](必需),workspace-write 时 额外添加 /tmp 和 workspaceRoot;
- SeatbeltProfileArgs:macOS sandbox-exec,SBPL(Sandbox Profile Language)脚本, (version 1)(allow default)(deny file-write*)(allow file-write* (literal /dev/null)), workspace-write 时额外 (allow file-write* (subpath root));
- 三个函数都只返回 profile 参数(runner 之后、分隔符 -- 之前的部分), 由 LocalProvider 组装完整 argv。
本文件实现可写根目录的共享计算:canonicalPath + writableRoots。
对齐官方:packages/sandbox/sandbox/src/roots.ts
设计要点:
- canonicalPath 使用 filepath.EvalSymlinks 解析符号链接(macOS 上 /tmp 实际是 /private/tmp); 解析失败时返回原路径(保守策略:路径不存在时匹配不到任何东西,不发明回退路径);
- writableRoots 是沙箱后端和进程内 FS 防护栏共享的单一真相源: workspace-write 模式返回 [workspaceRoot, /tmp, os.TempDir()] 的规范化去重列表; read-only 和 danger-full-access 返回空列表;
- 这确保"FS 防护栏说可以写的目录"和"沙箱实际允许写的目录"永远一致, 消除"FS 说可以但沙箱拒绝"(或反过来)的不对称 bug。
Package sandbox 提供进程沙箱(Process Sandbox)接缝。
对齐上游:packages/sandbox/sandbox + sandbox-policy
本文件对应任务 M26:Sandbox 接缝 3 模式 + {root, enforced} 元组。
设计要点:
- SandboxMode 只约束文件系统副作用:read-only / workspace-write / danger-full-access。
- SandboxExecutionPolicy 是「每次能力调用」都携带的完整文件效果策略: 即便是 danger 模式也会带上 workspaceRoot,以便消费者一次性解析再决定是否绕过。
- 消费者(Bash / FS)各自调用 SandboxPolicyService.Resolve(),得到对同一会话一致的策略, 这避免了两个消费者各自重复实现模式优先级与根回落逻辑。
- Provider.confine() 只对受约束(非 danger)模式生效;无可用后端必须 fail-closed, 绝不静默放行(SANDBOX_UNAVAILABLE)。
本文件实现会话沙箱模式覆盖的持久化:sandbox/mode 事件 + fold + set。
对齐官方:packages/sandbox/sandbox-policy/src/session-mode.ts
设计要点:
- 会话模式切换通过 sandbox/mode 事件持久化到事件日志(log-only,不进模型 transcript);
- effective = fold(events) ?? 部署默认:取最后一个 sandbox/mode 事件的 mode;
- 重启后通过 replay 恢复,两个会话永远看不到彼此的状态(无外部配置存储);
- source: 'delegation' 标记子代理委派时植入的覆盖;
- 执行层 SandboxPolicyService.Resolve() 遵循同一 fold,升级授权优先级最低。
Index ¶
- Constants
- Variables
- func AssertConfinedArgv(result ConfinedArgv)
- func AssertConfinedPolicy(policy SandboxPolicy)
- func AssertEscalationTarget(target SandboxMode)
- func AssertExecutionPolicy(policy SandboxExecutionPolicy)
- func AssertNotDangerBeforeConfine(mode SandboxMode)
- func AssertValidMode(mode SandboxMode)
- func AssertWritableRoots(mode SandboxMode, roots []string)
- func BwrapProfileArgs(policy SandboxPolicy) []string
- func CanEscalateTo(effectiveMode, targetMode SandboxMode) bool
- func CanonicalPath(path string) string
- func EscalationHintMarker(subject string) string
- func LandlockProfileArgs(policy SandboxPolicy) []string
- func SandboxDenialMarker(mode SandboxMode) string
- func SeatbeltProfileArgs(policy SandboxPolicy) []string
- func SetSandboxMode(sess SessionAppender, mode SandboxMode) error
- func SetSandboxModeWithSource(sess SessionAppender, mode SandboxMode, source ModeSource) error
- func ValidateEscalationArgs(sandboxPermissions, justification string) error
- func WritableRoots(policy SandboxExecutionPolicy) []string
- type BackendType
- type ConfinedArgv
- type ConfinedSandboxMode
- type EscalationApprovalRequest
- type EscalationApprover
- type EscalationOutcome
- type EscalationRequest
- type LocalConfig
- type LocalProvider
- type ModeSource
- type RunnerFailureRule
- type SandboxEnforcement
- type SandboxExecutionPolicy
- type SandboxMode
- type SandboxPolicy
- type SandboxPolicyRequest
- type SandboxPolicyService
- type SandboxProvider
- type SandboxUnavailableError
- type Session
- type SessionAppender
- type UnavailableProvider
Constants ¶
SandboxUnavailableErrorCode 是沙箱不可用错误的稳定分类码。
Variables ¶
var ( // ErrEscalationNotWider 表示请求的目标模式不比当前生效模式严格更宽。 ErrEscalationNotWider = errors.New("escalation not strictly wider") // ErrEscalationNoApprover 表示没有审批服务(fail-closed)。 ErrEscalationNoApprover = errors.New("escalation requires approval, but no approver is available") // ErrEscalationRejected 表示用户拒绝了升级。 ErrEscalationRejected = errors.New("escalation rejected by user") // ErrEscalationCancelled 表示审批被取消。 ErrEscalationCancelled = errors.New("escalation approval cancelled") ErrEscalationUnavailable = errors.New("escalation requires approval, but no approval channel is available") )
var InvariantEnabled = true
InvariantEnabled 控制不变量校验是否启用。 开发模式下默认启用,生产模式可设置为 false 以跳过校验。
var SandboxModes = []SandboxMode{ ModeReadOnly, ModeWorkspaceWrite, ModeDangerFullAccess, }
SandboxModes 是全部合法沙箱模式的常量数组(用于选项广告与运行时校验)。
Functions ¶
func AssertConfinedArgv ¶
func AssertConfinedArgv(result ConfinedArgv)
AssertConfinedArgv 校验 Confine 返回的 ConfinedArgv 非空且合法。
func AssertConfinedPolicy ¶
func AssertConfinedPolicy(policy SandboxPolicy)
AssertConfinedPolicy 校验 SandboxPolicy 的字段一致性(受约束模式)。
func AssertEscalationTarget ¶
func AssertEscalationTarget(target SandboxMode)
AssertEscalationTarget 校验升级目标是否在封闭目标词汇中。
func AssertExecutionPolicy ¶
func AssertExecutionPolicy(policy SandboxExecutionPolicy)
AssertExecutionPolicy 校验 SandboxExecutionPolicy 的字段一致性。
func AssertNotDangerBeforeConfine ¶
func AssertNotDangerBeforeConfine(mode SandboxMode)
AssertNotDangerBeforeConfine 校验在调用 ToConfined 之前模式不是 danger。
func AssertWritableRoots ¶
func AssertWritableRoots(mode SandboxMode, roots []string)
AssertWritableRoots 校验可写根列表:workspace-write 模式非空,其他模式为空。
func BwrapProfileArgs ¶
func BwrapProfileArgs(policy SandboxPolicy) []string
BwrapProfileArgs 为指定文件效果策略构建 bwrap profile 参数。 返回 runner 之后、分隔符 -- 之前的参数列表。
基础参数(所有模式):
- --ro-bind / /:根目录以只读方式挂载
- --dev /dev:提供 /dev
- --unshare-pid:隔离 PID 命名空间
- --proc /proc:挂载 /proc
- --die-with-parent:父进程死亡时杀掉沙箱
workspace-write 模式额外添加:
- --tmpfs /tmp:/tmp 为可写临时文件系统
- --bind workspaceRoot workspaceRoot:工作区可读写挂载
func CanEscalateTo ¶
func CanEscalateTo(effectiveMode, targetMode SandboxMode) bool
CanEscalateTo 判断从 effectiveMode 是否可以严格更宽升级到 targetMode。 严格更宽:只能向上,不能横向或向下;danger 是顶点,不能再升级。
func CanonicalPath ¶
CanonicalPath 解析路径到执行层实际比较的形式: 规范化(符号链接解析),因为 Seatbelt 过滤器和 FS 防护栏的包含检查 都匹配解析后的路径——macOS 上 /tmp 就是 /private/tmp,按拼写的授权会匹配不到任何东西。
解析失败时(路径或其前缀不存在/不可读)返回原路径: 不存在的根在它存在之前匹配不到任何东西——这是保守的结果; 发明回退路径会授予调用方从未命名过的路径。
func EscalationHintMarker ¶
EscalationHintMarker 返回同轮升级提示——当组合通告了升级字段时, 拒绝响应携带此提示,指导模型用 sandbox_permissions(足够的最窄更宽模式) + justification 重试完全相同的操作。提示位于决策点,这样合规重试 不依赖模型回忆工具描述。
subject 是被拒绝操作的家族名词(bash 用 "command",fs 用 "operation")。
func LandlockProfileArgs ¶
func LandlockProfileArgs(policy SandboxPolicy) []string
LandlockProfileArgs 为指定文件效果策略构建 Landlock launcher 授权参数。 返回 launcher 授权参数(readOnly / readWrite 标志)。
read-only 模式:
- readOnly: [/]
- readWrite: [/dev/null](必需,否则很多程序无法正常运行)
workspace-write 模式:
- readOnly: [/]
- readWrite: [/dev/null, /tmp, workspaceRoot]
func SandboxDenialMarker ¶
func SandboxDenialMarker(mode SandboxMode) string
SandboxDenialMarker 返回面向模型的拒绝标记——Bash 和 FS 两个强制执行家族 都使用并报告这个统一词汇,这样模型无论内核拒绝了 bash 文件效果还是 FS 防护栏拒绝了变更,都能一致地识别策略拒绝。
func SeatbeltProfileArgs ¶
func SeatbeltProfileArgs(policy SandboxPolicy) []string
SeatbeltProfileArgs 为指定文件效果策略构建 macOS sandbox-exec 参数。 返回 [-p, sbplScript]。
SBPL 脚本基础规则:
- (version 1)
- (allow default):默认允许
- (deny file-write*):拒绝所有文件写入
- (allow file-write* (literal /dev/null)):允许写入 /dev/null
workspace-write 模式额外添加:
- (allow file-write* (subpath root)):允许写入工作区根目录及其子路径
func SetSandboxMode ¶
func SetSandboxMode(sess SessionAppender, mode SandboxMode) error
SetSandboxMode 是会话沙箱模式覆盖的**唯一写路径**: 向会话 append 一条 sandbox/mode 事件——切换本身就是事件,不做任何带外状态修改。 在下一次受约束调用(bash 或 fs)时生效——消费者每次读取都 fold。
func SetSandboxModeWithSource ¶
func SetSandboxModeWithSource(sess SessionAppender, mode SandboxMode, source ModeSource) error
SetSandboxModeWithSource 同 SetSandboxMode,但携带 source 标记(如 'delegation')。
func ValidateEscalationArgs ¶
ValidateEscalationArgs 校验升级参数配对: sandbox_permissions 和 justification 必须同时出现或同时不出现, 且 justification 必须是非空句子(trim 后非空)。
没有理由的审批请求,或不驱动任何事情的理由,都是格式错误。
func WritableRoots ¶
func WritableRoots(policy SandboxExecutionPolicy) []string
WritableRoots 返回一次受约束执行可以写入的根目录——模式的含义作为规范化、去重的白名单。
- read-only:不允许任何写入,返回空列表;
- workspace-write:允许策略的 workspace 根、主机 /tmp、以及 per-user 平台临时目录 (os.TempDir()——mkstemp 系列工具的真实临时区域;省略它会拒绝模式承诺的东西);
- danger-full-access:绕过沙箱,不需要可写根列表,返回空列表。
返回的根经过 CanonicalPath 规范化并去重。
Types ¶
type BackendType ¶
type BackendType string
BackendType 是本地沙箱后端类型。
const ( // BackendBwrap 是 Linux Bubblewrap 后端。 BackendBwrap BackendType = "bwrap" // BackendLandlock 是 Linux Landlock 后端。 BackendLandlock BackendType = "landlock" // BackendSeatbelt 是 macOS Seatbelt 后端。 BackendSeatbelt BackendType = "seatbelt" // BackendWindowsACL 是 Windows ACL 后端。 BackendWindowsACL BackendType = "windows-acl" BackendUnavailable BackendType = "unavailable" )
type ConfinedArgv ¶
type ConfinedArgv struct {
// Argv 是包裹后的 argv(runner、profile、分隔符再到调用方 argv)。
Argv []string `json:"argv"`
// Enforcement 是所选后端对该策略能实现的强制完整度。
Enforcement SandboxEnforcement `json:"enforcement"`
// DenialSignatures 是该后端被某些命令拒绝时的 stderr dialect 子串集合。
DenialSignatures []string `json:"denialSignatures"`
// RunnerFailureRules 是结构化 runner 失败证据规则。
RunnerFailureRules []RunnerFailureRule `json:"runnerFailureRules"`
}
ConfinedArgv 是 Provider.confine 的产物:替换后的 argv + 该后端达到的强制程度 + 两个正交的 stderr 分类器(denial + runner-failure)。
type ConfinedSandboxMode ¶
type ConfinedSandboxMode string
ConfinedSandboxMode 是可交给 Provider 的受约束模式(排除 danger-full-access)。 danger-full-access 的消费者直接使用原始 argv,不调用 ctx.sandbox。
const ( ConfinedReadOnly ConfinedSandboxMode = "read-only" ConfinedWorkspaceWrite ConfinedSandboxMode = "workspace-write" )
受约束模式集合。
type EscalationApprovalRequest ¶
type EscalationApprovalRequest struct {
// ToolName 是工具名(记录在审批请求上)。
ToolName string
// CallID 是工具调用 ID(审批提示附着的调用)。
CallID string
// Reason 是审计理由(包含目标模式 + justification)。
Reason string
}
EscalationApprovalRequest 是升级审批请求——审计自包含(agent、工具、调用 ID、理由)。
type EscalationApprover ¶
type EscalationApprover interface {
// Request 向用户请求批准一次操作,返回封闭结果。
Request(ctx context.Context, req EscalationApprovalRequest) (EscalationOutcome, error)
}
EscalationApprover 是升级审批者接口——工具层持有 ctx.approval, 本包只判断结果,不导入审批或 agent 包。
type EscalationOutcome ¶
type EscalationOutcome string
EscalationOutcome 是一次升级询问的封闭结果词汇—— 结构上与审批接缝的 ApprovalOutcome 相同。
const ( // EscalationAllowedOnce 表示用户准许了本次升级(仅本次调用,非永久)。 EscalationAllowedOnce EscalationOutcome = "allowed-once" // EscalationRejected 表示用户拒绝了升级。 EscalationRejected EscalationOutcome = "rejected" // EscalationCancelled 表示审批被取消。 EscalationCancelled EscalationOutcome = "cancelled" EscalationUnavailable EscalationOutcome = "unavailable" )
type EscalationRequest ¶
type EscalationRequest struct {
// RequestedMode 是请求的目标模式(schema 固定为 EscalationTargets)。
RequestedMode SandboxMode
// Justification 是模型的一句话理由,原样展示给用户在审计理由中。
Justification string
// EffectiveMode 是调用的生效模式(会话覆盖 ?? 组合默认),请求必须严格更宽。
EffectiveMode SandboxMode
// Subject 是用户可见文本中被升级操作的家族名词(bash 用 "command",fs 用 "operation")。
Subject string
// ToolName 是记录在审批请求上的工具名。
ToolName string
// CallID 是审批提示附着的工具调用 ID。
CallID string
}
EscalationRequest 是一次升级请求,由 ApproveEscalation 判断。
type LocalConfig ¶
type LocalConfig struct {
// RunnerCommand 覆盖自动探测的 runner 命令(如 "bwrap"、"sandbox-exec")。
// 非空时跳过探测,直接使用此命令。
RunnerCommand string
// BackendType 强制指定后端类型(配合 RunnerCommand 使用)。
BackendType BackendType
}
LocalConfig 是 LocalProvider 的配置。
type LocalProvider ¶
type LocalProvider struct {
// contains filtered or unexported fields
}
LocalProvider 是本地沙箱提供者,实现 SandboxProvider 接口。 通过多后端探测链选择当前平台可用的最强后端。
func NewLocalProvider ¶
func NewLocalProvider(config *LocalConfig) *LocalProvider
NewLocalProvider 创建本地沙箱提供者。 config 为 nil 时使用默认配置(自动探测)。
func (*LocalProvider) Confine ¶
func (p *LocalProvider) Confine(argv []string, policy SandboxPolicy) (ConfinedArgv, error)
Confine 实现 SandboxProvider 接口:根据后端类型组装受约束的 argv。
func (*LocalProvider) DenialSignatures ¶
func (p *LocalProvider) DenialSignatures() []string
DenialSignatures 返回当前后端的拒绝签名(用于 RunnerFailureRule 匹配)。
type ModeSource ¶
type ModeSource string
ModeSource 是 sandbox/mode 事件的来源标记。
const ( // ModeSourceDelegation 标记子代理委派时植入的覆盖。 ModeSourceDelegation ModeSource = "delegation" )
type RunnerFailureRule ¶
type RunnerFailureRule struct {
// AllowedExitCodes 非零进程退出码白名单;省略表示允许任意非零退出码。
AllowedExitCodes []int `json:"allowedExitCodes,omitempty"`
// FatalSignatures 单条 stderr 行上的致命诊断子串(不区分大小写)。
FatalSignatures []string `json:"fatalSignatures"`
// InformationalLines 在致命匹配前被排除的无害 stderr 全行(不区分大小写精确匹配)。
InformationalLines []string `json:"informationalLines,omitempty"`
}
RunnerFailureRule 是辨识「沙箱 runner 在执行命令前失败」的证据规则。
type SandboxEnforcement ¶
type SandboxEnforcement string
SandboxEnforcement 是强制完成的报告事实:full 表示后端覆盖该模式承诺的全部文件效果; partial 表示活动后端或旧内核 ABI 只覆盖子集,要求绝对边界的消费者不得当 full 使用。
const ( EnforcementFull SandboxEnforcement = "full" EnforcementPartial SandboxEnforcement = "partial" )
强制枚举。
type SandboxExecutionPolicy ¶
type SandboxExecutionPolicy struct {
// Mode 是本次执行的文件效果模式。
Mode SandboxMode `json:"mode"`
// WorkspaceRoot 是 workspace-write 可写作业的绝对根目录。
WorkspaceRoot string `json:"workspaceRoot"`
// SessionID 是调用会话的标识(无头调用时为空,后端退化为每次调用的自有状态)。
SessionID brand.SessionID `json:"sessionId,omitempty"`
}
SandboxExecutionPolicy 是一次能力调用解析出的完整文件效果策略。 即便在 danger 模式下也携带 workspaceRoot,供消费者一次性解析后决定执行路径。
func (SandboxExecutionPolicy) IsDanger ¶
func (p SandboxExecutionPolicy) IsDanger() bool
IsDanger 报告该策略是否为危险全访问(需绕过沙箱直接 spawn 原始 argv)。
func (SandboxExecutionPolicy) ToConfined ¶
func (p SandboxExecutionPolicy) ToConfined() (SandboxPolicy, error)
ToConfined 把执行策略降级为受约束策略(调用方需先确认非 danger)。
type SandboxMode ¶
type SandboxMode string
SandboxMode 沙箱模式:只约束文件系统副作用。
const ( ModeReadOnly SandboxMode = "read-only" ModeWorkspaceWrite SandboxMode = "workspace-write" ModeDangerFullAccess SandboxMode = "danger-full-access" )
沙箱模式枚举(与 pkg/session.SandboxMode 对齐)。
func ApproveEscalation ¶
func ApproveEscalation(ctx context.Context, req EscalationRequest, approver EscalationApprover) (SandboxMode, error)
ApproveEscalation 在任何执行之前解析沙箱升级请求:
- 针对调用的生效模式检查严格更宽(非更宽绝不询问用户);
- 校验参数配对;
- 解析审批通道(无审批者 fail-closed);
- 映射每种结果——返回授予的模式(仅本次调用),或抛出每种路径的精确错误文本。
返回的授予模式仅消费于发起请求的那一次调用。
func EffectiveSandboxMode ¶
func EffectiveSandboxMode(events []session.SessionEvent) (SandboxMode, bool)
EffectiveSandboxMode 从事件列表 fold 出会话的沙箱模式覆盖: 从后往前找最后一个 sandbox/mode 事件,返回其 mode;没有则返回 ok=false。 纯 fold 函数——resume 不需要 catch-up 机制,因为重放日志就是状态本身。
func EscalationTargets ¶
func EscalationTargets() []SandboxMode
EscalationTargets 返回封闭的升级目标词汇:[workspace-write, danger-full-access]。 read-only 是底线,不在目标中(任何模式都不会升级到 read-only)。 在挂载的能力通告升级字段时使用此词汇。
type SandboxPolicy ¶
type SandboxPolicy struct {
SandboxExecutionPolicy
// Mode 覆盖为受约束模式(read-only / workspace-write)。
Mode ConfinedSandboxMode `json:"mode"`
}
SandboxPolicy 是每次受约束执行允许触及的边界,按调用携带而非固定在后端上。
type SandboxPolicyRequest ¶
type SandboxPolicyRequest struct {
// Session 是调用会话;其不可变 cwd 成为 workspace 边界。
Session Session
// Mode 是显式审批/覆盖后的模式,优先级高于会话策略。
Mode *SandboxMode
}
SandboxPolicyRequest 是选择一次能力调用的沙箱策略的输入。
type SandboxPolicyService ¶
type SandboxPolicyService struct {
// DefaultMode 是部署默认模式(agentless 时回落)。
DefaultMode SandboxMode
// FallbackRoot 是 agentless / 无 cwd 会话的回落工作区根。
FallbackRoot string
}
SandboxPolicyService 是 ctx.sandboxPolicy 的 Go 实现。 它拥有默认模式优先级与根回落逻辑,Bash/FS 两个消费者复用同一份解析。
func NewPolicyService ¶
func NewPolicyService(defaultMode SandboxMode, fallbackRoot string) *SandboxPolicyService
NewPolicyService 创建策略服务。
func (*SandboxPolicyService) OverrideOf ¶
func (s *SandboxPolicyService) OverrideOf(session Session) (SandboxMode, bool)
OverrideOf 读取会话的沙箱模式覆盖,不应用部署默认;无覆盖返回 ok=false。
func (*SandboxPolicyService) Resolve ¶
func (s *SandboxPolicyService) Resolve(req SandboxPolicyRequest) SandboxExecutionPolicy
Resolve 为一次能力调用解析完整策略。
优先级(高 → 低):显式审批覆盖 req.Mode → 会话最后 logged 模式 → 部署默认模式。 workspaceRoot:会话 cwd(已规范化)→ 配置的回落根(agentless)。
type SandboxProvider ¶
type SandboxProvider interface {
// Confine 把 argv 包裹使其在 policy 下受约束执行;必须 fail-closed
// (无可用后端或包裹失败返回错误),绝不允许静默无约束放行。
Confine(argv []string, policy SandboxPolicy) (ConfinedArgv, error)
}
SandboxProvider 是抽象进程沙箱服务(ctx.sandbox)。
type SandboxUnavailableError ¶
type SandboxUnavailableError struct {
}
SandboxUnavailableError 表示没有可用后端。
func (*SandboxUnavailableError) Error ¶
func (e *SandboxUnavailableError) Error() string
type Session ¶
type Session interface {
// ID 返回会话标识(branded SessionId)。
ID() brand.SessionID
// Cwd 返回会话不可变工作目录(workspace-write 的边界);空串表示无 cwd。
Cwd() string
// SandboxMode 返回会话日志中最后一次沙箱模式覆盖;未记录时 ok=false。
SandboxMode() (SandboxMode, bool)
}
Session 是策略服务所依赖的会话抽象:不可变 cwd 即 workspace 边界, 最后一次 logged 的沙箱模式作为会话级覆盖。
type SessionAppender ¶
SessionAppender 是可追加事件的会话抽象(SessionLog 实现此接口)。
type UnavailableProvider ¶
type UnavailableProvider struct{}
UnavailableProvider 是 fail-closed 桩:任何 confine 都报 SANDBOX_UNAVAILABLE, 用于「无可用后端」的生产缺省。
func (*UnavailableProvider) Confine ¶
func (*UnavailableProvider) Confine([]string, SandboxPolicy) (ConfinedArgv, error)
Confine 实现 fail-closed:始终不可用。