sandbox

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
const SandboxUnavailableErrorCode = "SANDBOX_UNAVAILABLE"

SandboxUnavailableErrorCode 是沙箱不可用错误的稳定分类码。

Variables

View Source
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 表示审批通道不可用。
	ErrEscalationUnavailable = errors.New("escalation requires approval, but no approval channel is available")
)
View Source
var InvariantEnabled = true

InvariantEnabled 控制不变量校验是否启用。 开发模式下默认启用,生产模式可设置为 false 以跳过校验。

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 AssertValidMode

func AssertValidMode(mode SandboxMode)

AssertValidMode 校验沙箱模式是否合法。

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

func CanonicalPath(path string) string

CanonicalPath 解析路径到执行层实际比较的形式: 规范化(符号链接解析),因为 Seatbelt 过滤器和 FS 防护栏的包含检查 都匹配解析后的路径——macOS 上 /tmp 就是 /private/tmp,按拼写的授权会匹配不到任何东西。

解析失败时(路径或其前缀不存在/不可读)返回原路径: 不存在的根在它存在之前匹配不到任何东西——这是保守的结果; 发明回退路径会授予调用方从未命名过的路径。

func EscalationHintMarker

func EscalationHintMarker(subject string) string

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

func ValidateEscalationArgs(sandboxPermissions, justification string) error

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 表示没有可用的本地后端。
	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 表示审批通道不可用。
	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) Available

func (p *LocalProvider) Available() bool

Available 检查本地沙箱是否可用。

func (*LocalProvider) Backend

func (p *LocalProvider) Backend() BackendType

Backend 返回当前探测到的后端类型。

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 匹配)。

func (*LocalProvider) Runner

func (p *LocalProvider) Runner() string

Runner 返回当前探测到的 runner 命令。

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 在执行命令前失败」的证据规则。

func (RunnerFailureRule) Matches

func (r RunnerFailureRule) Matches(exitCode int, stderr string) (string, bool)

Matches 应用规则:先按退出码门控,移除 info 行,再在剩余 stderr 行内做致命子串匹配。

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 在任何执行之前解析沙箱升级请求:

  1. 针对调用的生效模式检查严格更宽(非更宽绝不询问用户);
  2. 校验参数配对;
  3. 解析审批通道(无审批者 fail-closed);
  4. 映射每种结果——返回授予的模式(仅本次调用),或抛出每种路径的精确错误文本。

返回的授予模式仅消费于发起请求的那一次调用。

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

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 {
	Msg string
}

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

type SessionAppender interface {
	Append(data session.EventData) (uint64, error)
}

SessionAppender 是可追加事件的会话抽象(SessionLog 实现此接口)。

type UnavailableProvider

type UnavailableProvider struct{}

UnavailableProvider 是 fail-closed 桩:任何 confine 都报 SANDBOX_UNAVAILABLE, 用于「无可用后端」的生产缺省。

func (*UnavailableProvider) Confine

Confine 实现 fail-closed:始终不可用。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL