Apache Maka 运行时沙箱边界平台选择与命令转换机制全解析【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka导读本篇文章聚焦 Apache MakaIncubating运行时沙箱边界Runtime sandbox boundary模块即packages/runtime/src/sandbox目录所负责的「平台沙箱选择与命令转换」能力。该模块把会话中活跃的ExecutionBoundary权限配置文件翻译成真实的执行请求并委派给 macOS Seatbelt、Linux bubblewrap、Windows AppContainer 三大平台后端。读完本文你将掌握 Maka 沙箱的职责划分、PermissionProfile配置模型、SandboxManager的auto/require/forbid选择语义、各平台后端的实现路径与 fail-closed故障关闭策略以及项目提供的完整验证测试矩阵。模块定位只做翻译不做决策不亲自动手packages/runtime/src/sandbox/README.md对模块的边界给出了极其明确的定义本目录负责平台沙箱选择与命令转换。它将活跃会话ExecutionBoundary中的 profile 翻译为执行请求它不决定请求的边界扩展是否被批准也不亲自执行该请求。这句话拆解出三层职责约束翻译transform把权限配置文件转换为可执行的沙箱命令不审批no approval边界扩展是否被允许由 sandbox-boundary 交互路径负责沙箱选择不会自行扩展边界不执行no spawnSandboxManager只输出转换后的执行请求进程的拉起、重试、UI 与遥测都由调用方负责。代码与聚焦测试是最终权威Code and focused tests are the final authority。Windows 侧的强制工作跟踪在 issue #2142规范文档为 Windows sandbox backend RFC中文版。所有权划分core 说「是什么」runtime 说「怎么落地」沙箱边界语言被刻意拆成两层两个包各司其职。maka/core平台中立的边界语言模块职责execution-boundary.ts定义会话边界、其修订版本号与单调扩展monotonic expansionpermission-profile.ts定义 managed / disabled / external 三类 profile、文件系统条目、网络策略、标准 profile 与纯路径匹配器permission-profile-compiler.ts当遗留产品模式必须映射到 profile 时保持兼容性这一层刻意保持「纯」pure调用方传入归一化绝对路径与运行期上下文realpath、symlink 与平台路径预处理由 runtime 完成后再进入这些辅助函数见 permission-profile.ts 的模块注释。maka/runtime平台转换模块职责types.ts定义沙箱选择、命令、路径上下文、执行请求与类型化失败契约sandbox-manager.ts判定 profile 是否要求沙箱、选择平台后端并委派转换macos-seatbelt.ts构建 Seatbelt 策略用/usr/bin/sandbox-exec包裹内层 argvlinux-sandbox.ts构建 bubblewrap 挂载、namespace 参数与网络 seccomp 过滤器linux-capability.ts在选择可用前探测 bubblewrap 与 namespace 的可用性windows-profile.ts把 managed profile 编译为规范的 ACL、网络与环境策略windows-sandbox.ts写入一次性 manifest 并调用打包的 AppContainer brokerdefault-sandbox-manager.ts注册受支持的默认后端index.ts公共子路径表面runtime 包 barrel 再导出受支持的 APIPermissionProfile模型受限、无限制与外部三类PermissionProfile是沙箱决策的输入核心定义在 permission-profile.ts为三种类型的联合export type PermissionProfile | PermissionProfileManaged // type: managed | PermissionProfileDisabled // type: disabled | PermissionProfileExternal; // type: externalmanaged携带fileSystem文件系统策略与network网络策略两个字段disabled仅携带名字表示权限机制被禁用external文件系统隔离由外部环境注入如外部 workspace executorMaka 在当前实现中不叠加本地平台沙箱。文件系统策略文件系统沙箱种类只有三种FILE_SYSTEM_SANDBOX_KINDSrestricted受限、unrestricted无限制、external_sandbox外部沙箱。条目entry支持两种形态FileSystemSandboxEntry{ kind: path, access, path, match? }访问模式为read/write/deny路径匹配方式match可取exact精确或subtree子树向后兼容的默认值{ kind: special, access, special }特殊路径占位符取值包括:root、:workspace_roots、:tmpdir、:slash_tmp、:minimalFILE_SYSTEM_SPECIAL_PATHS由匹配上下文PermissionProfileMatchContext在运行期解析为真实路径。此外还有受保护元数据策略PROTECTED_METADATA_NAMES默认保护.git、.agents、.codex三个名字策略为deny_write防止 Agent 写入仓库元数据目录。网络策略网络沙箱种类只有两种NETWORK_SANDBOX_KINDSrestricted受限与enabled启用。四个标准 profile 工厂permission-profile.ts提供了四个开箱即用的工厂函数是ask、explore等会话入口的起点工厂函数name文件系统网络说明createReadOnlyPermissionProfile()read-onlyrestricted对:workspace_roots只读restrictedExplore 会话的起点createWorkspaceWritePermissionProfile()workspace-writerestricted对:workspace_roots、:tmpdir、:slash_tmp可写restrictedAsk 会话的起点createDangerFullAccessPermissionProfile()danger-full-accessunrestrictedenabled全量访问createExternalPermissionProfile(network?)external由外部提供默认 restricted外部隔离注意workspace-write允许写工作区根、:tmpdir与:slash_tmp它不是仅限工作区workspace-only的 profile见 README「Product coverage」一节。isReadOnlyPermissionProfile()则是从策略推导而非看name判断只读经过批准的边界扩展即使名字没变也不再被当作只读permission-profile.ts。路径判定辅助函数canReadPath(profile, path, context)先查 deny 条目再查 unrestricted/external 放行最后按 read/write 匹配canWritePath(profile, path, context)额外叠加受保护元数据 deny-write 检查isDeniedPath()/isProtectedMetadataPath()分别处理显式拒绝与受保护目录判定。Windows 上的路径匹配大小写不敏感isProtectedMetadataPath对 Windows 盘符根折叠大小写防止写.GIT\config绕过.gitdeny 规则permission-profile.ts。SandboxManager选择与转换的核心流程SandboxManager类sandbox-manager.ts持有backends映射sandboxType - backend提供四个关键方法。shouldSandbox三种偏好的语义shouldSandbox(profile, preference auto, platform process.platform): boolean { if (preference forbid) return false; if (preference require) return true; return profileRequiresSandbox(profile); }偏好SandboxablePreference三选一types.tsauto默认值DEFAULT_PREFERENCE由 profile 决定——profileRequiresSandbox只有 managed 且文件系统或网络为restricted时返回 truerequire强制选择平台沙箱forbid选择宿主机执行。注意这是内部编排输入不是审批通过的证明。selectInitial平台分派的 fail-closed 逻辑选择流程严格按平台分派darwin有macos-seatbelt后端则选中否则返回backend_not_availablelinux有linux后端则选中否则backend_not_availablewin32有windows后端则选中否则backend_not_available其他平台返回unsupported_platform。所有失败路径都带requiresSandbox: true与明确的message即故障关闭不静默降级为宿主机执行。canEnforce与transformcanEnforce(input)在热路径上回答「当前平台与 profile 是否真的可被强制」会依次检查后端已注册、isAvailable、canEnforceProfiletransform(request)先selectInitial若选中none则原样透传命令sandboxType: none否则委派给对应后端的transform。后端接口契约SandboxBackendtypes.ts只有三个成员export interface SandboxBackend { readonly type: ExcludeSandboxType, none; isAvailable?(platform?: SandboxPlatform): boolean; canEnforceProfile?(profile: PermissionProfile): boolean; transform(request: SandboxTransformRequest): SandboxTransformResult; }SandboxCommandprogram、args、cwd、env、profile、pathContextSandboxExecRequest转换产物含argv、fdInputs、cwd、env、sandboxType、effectiveProfileSandboxPathContext承载workspaceRoots、tmpdir、slashTmp、minimalRoots以及运行期辅助目录runtimeReadableRoots、executableRoots、runtimeWritableRoots还有通过开放文件描述符钉住的pinnedRuntimeWritableRoots/pinnedProfilePaths——这些是「沙箱启动前用宿主 fd 钉住运行期可写根」的机制。类型化失败原因SandboxTransformFailureReason覆盖五种unsupported_platform、backend_not_available、backend_not_implemented、sandbox_required、invalid_request。三大平台后端macOSSeatbelt sandbox-execMacosSeatbeltBackend构建 SBPLSeatbelt policy language策略并用/usr/bin/sandbox-exec包裹内层 argv。职责包括 SBPL 生成、根参数化root parameterization、受保护元数据 deny-write 规则与网络策略翻译。当后端不可用时 fail closed。index.ts导出了MACOS_SEATBELT_BASE_POLICY、MACOS_SEATBELT_EXECUTABLE、MACOS_SEATBELT_PLATFORM_DEFAULTS_POLICY、buildSeatbeltPolicy、createSeatbeltExecArgs、escapeSeatbeltRegex等构建工具index.ts。Linuxbubblewrap seccompLinuxBubblewrapBackend构建 bubblewrap 挂载、namespace 参数与网络 seccomp 过滤器。可用性由linux-capability.ts负责通过detectLinuxSandboxCapability探测 bubblewrap 可执行文件、namespace 能力LINUX_BWRAP_PROBE_ARGS与LINUX_BWRAP_REQUIRED_OPTIONS定义了探测参数与必需选项。当可执行文件、namespace 探测或请求的 profile 无法被强制时 fail closed。WindowsAppContainer broker预览WindowsBrokerSandboxBackend写入一次性 manifest 并调用打包的 AppContainer brokermaka-windows-sandbox.exe。仅当打包的原生资源存在时才被选中否则 fail closed 为不可用。windows-profile.ts的compileWindowsSandboxPolicy把 managed profile 编译为规范 ACL、网络与环境策略。Windows 可用性判定有一套精心设计的 readiness 机制default-sandbox-manager.tsprobeWindowsReadiness运行 launcher 的--readiness-probe真实拉起生产身份与一次性受限子进程超时上限 15 秒只有干净退出码 0 才算可用探测结果按 launcher 路径做模块级缓存正结果永久缓存负结果仅缓存 60 秒WINDOWS_READINESS_NEGATIVE_TTL_MS避免一次瞬时抖动杀软扫描、负载下的 spawn 超时毒化整个进程生命周期的可用性readCachedWindowsReadiness热路径上只读缓存、绝不 spawn避免spawnSync阻塞事件循环恢复被限定在下次 composition 构建或 Runtime Host 重启对应 RFC §6.4。当前行为与产品覆盖矩阵当前行为要点受限的 managed profile 在默认auto偏好下必须有平台沙箱unrestricted、disabled 与 external profile 不叠加 Maka 管理的本地沙箱require强制平台沙箱选择forbid选择宿主机执行且只是内部编排输入不是审批证明macOS 选 Seatbelt后端不可用时 fail closedLinux 选 bubblewrap可执行文件、namespace 探测或 profile 无法强制时 fail closedWindows 仅在打包原生资源存在时选 AppContainer broker否则 fail closed 为不可用其他平台返回unsupported_platform后端收到无效或不支持的 profile 返回类型化失败不静默降级为宿主机执行。产品覆盖矩阵README 原文继承SurfacemacOSLinuxWindows当不需要 Maka 托管沙箱时Agent Bash前台或后台且无 PTYSeatbeltbubblewrap受限 managed 执行 fail closed——AppContainer broker 无法启动任意 shell通过探测到的宿主 shell 运行带 PTY 的 Agent Bash当活跃 profile 要求沙箱时拒绝当活跃 profile 要求沙箱时拒绝当活跃 profile 要求沙箱时拒绝作为宿主 PTY 运行本地路径Read、Write、Edit、FormatJson、Glob、Grep、apply_patchSeatbelt 下的文件系统 workerbubblewrap 下的文件系统 workerAppContainer broker 下特制的文件系统 worker受下述 fail-closed 限制约束managed 执行使用无 OS 沙箱的 workerbypass 使用宿主本地 executorexternal 使用注入的 executor对 runtime 或 attachment 资源引用的Read资源服务非本地文件系统 worker 操作资源服务非本地文件系统 worker 操作资源服务非本地文件系统 worker 操作相同的资源服务路径客户端runtime.resource.start集成终端托管 Agent 边界之外的宿主 PTY托管 Agent 边界之外的宿主 PTY托管 Agent 边界之外的宿主 PTY相同的宿主 PTY 路径Windows AppContainer 预览的已知限制在 Windows AppContainer 预览中本地路径Read、Glob、对已存在目标的Write、Edit、FormatJson、apply_patch更新操作走文件系统 workerGrep以grep_unavailablefail closed对缺失目标的Write与apply_patch创建/删除操作同样 fail closed——因为当前 broker 策略无法在不加宽内核授权的前提下表达「对父条目的精确写权限」。会话起点与绕过边界ask从 managedworkspace-writeprofile 起步explore从 managed 只读 profile 起步两者都因文件系统或网络策略受限而要求平台沙箱bypass 边界、unrestricted managed profile 与 disabled profile 不请求 Maka 托管本地沙箱当文件系统 worker 已接入时即使SandboxManager选择了nonemanaged 执行仍可用 worker 作为后端——这是进程分离而非 OS 沙箱强制bypass 边界用宿主本地 executorexternal 边界把文件系统隔离委托给注入的 workspace executor不叠加本地平台沙箱不需要沙箱时工具可用性与权限策略依然生效选择none本身不是执行许可。边界与非目标边界Boundaries会话ExecutionBoundary是「操作当前是否位于沙箱边界内」的权威沙箱选择不会扩展该边界sandbox-boundary 交互路径拥有用户审批权并以新修订号原子落定已批准的扩展调用方负责规范 cwd 与路径上下文构造平台后端不得猜测工作区根SandboxManager只转换命令不 spawn 进程、不无沙箱重试、不弹 UI、不持有遥测macOS 后端拥有 SBPL 生成、根参数化、受保护元数据 deny-write 规则与网络策略翻译PermissionProfile.External表示文件系统隔离由环境提供Maka 当前实现不叠加本地平台沙箱。非目标Non-goals工作树或工作区副本沙箱化Diff/回写或 apply-patch UI自动无沙箱重试托管网络代理或域名白名单Windows 发布签名与完整 Phase 4 对抗支持声明第二套权限语言、shell runner 或文件策略系统默认后端注册与公开 APIcreateDefaultSandboxManager()注册MacosSeatbeltBackend与LinuxBubblewrapBackendcreateBuiltinSandboxManager()在检测到打包的 Windows launcher 时额外追加WindowsBrokerSandboxBackenddefault-sandbox-manager.ts。isBuiltinFilesystemWorkerSandboxAvailable()是文件系统 worker 可用性的单一权威来源macOS 恒为 trueWindows 依赖 launcher 存在 readiness 探测Linux 依赖 bubblewrap capability 探测default-sandbox-manager.ts。公共子路径表面由 index.ts 导出主要包括SandboxManager、createBuiltinSandboxManager/createDefaultSandboxManager/isBuiltinFilesystemWorkerSandboxAvailable、LinuxBubblewrapBackend含buildBubblewrapArgv、buildNetworkSeccompFilter、MacosSeatbeltBackend含buildSeatbeltPolicy、createSeatbeltExecArgs、WindowsBrokerSandboxBackend、compileWindowsSandboxPolicy、classifyWindowsBrokerFailure以及全部类型契约SandboxBackend、SandboxCommand、SandboxExecRequest、SandboxTransformResult等并通过 runtime 包 barrel 对外再导出。验证代码与测试是最终权威README「Verification」一节给出了完整的测试映射全部可以直接在仓库中复现core 层Profile 工厂、编译器与匹配器packages/core/src/__tests__/permission-profile*.test.tsruntime 层选择与转换选择与转换packages/runtime/src/__tests__/sandbox-manager.test.tsmacOS策略与包裹packages/runtime/src/__tests__/macos-seatbelt.test.ts平台行为packages/runtime/src/__tests__/macos-seatbelt-smoke.test.ts文件系统 worker 行为packages/runtime/src/__tests__/filesystem-worker-smoke.test.tsLinux策略与包裹packages/runtime/src/__tests__/linux-sandbox.test.ts平台行为packages/runtime/src/__tests__/linux-sandbox-smoke.test.ts文件系统 worker 行为packages/runtime/src/__tests__/filesystem-worker-linux-smoke.test.tsWindowsprofile 与 broker 转换windows-profile.test.ts与windows-sandbox.test.ts文件系统 worker 行为packages/runtime/src/__tests__/filesystem-worker-windows-smoke.test.ts产品组合与导出Runtime Host 产品组合packages/runtime-host/src/__tests__/execution-model-composition.test.ts公共导出与默认注册sandbox-export.test.ts与default-sandbox-manager.test.ts与边界语言配套的还有packages/core/src/__tests__/sandbox-boundary.test.ts与packages/runtime/src/__tests__/tool-runtime-sandbox-boundary.test.ts等测试覆盖边界扩展审批与工具运行期边界校验packages/runtime/src/__tests__/execution-boundary-test-helpers.ts则为各测试提供构造 ExecutionBoundary 的共享工具。小结Maka 的运行时沙箱边界是一个「纯翻译层」core 定义平台中立的权限语言runtime 按平台选择后端并把命令转换为带沙箱的执行请求任何无法强制的情况都以类型化失败 fail closed绝不静默降级。理解PermissionProfile三类模型、auto/require/forbid选择语义与三个平台后端的可用性探测是正确使用和扩展 Maka 沙箱能力的基础而 README 与上述测试文件共同构成该模块「代码即文档」的可验证事实来源。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考