Agent Governance Toolkit 沙箱挂载策略字段sandbox_mounts深度解析从 PolicyDocument 到 fail-closed 执行【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit导读本文基于 Agent Governance Toolkit 安全审计记录 docs/security/audits/2026-06-11-sandbox-mounts-policy-field.md系统讲解sandbox_mounts扩展字段如何被引入规范化策略文档PolicyDocument使 Docker、Hyperlight、MXC 等沙箱提供方能够从单一权威策略文档中读取文件系统挂载配置。文章将完整还原该变更的威胁模型分析、fail-closed 缓解措施与测试覆盖并结合 agent-sandbox 共享加固模块 的源码展开底层原理。读完本文你将掌握沙箱挂载治理的安全设计范式字段建模、受保护路径校验、环境变量净化、以及如何在不破坏既有策略兼容性的前提下做到默认零挂载、配置即校验、越权即拒绝。一、变更动机为什么需要一个规范化的sandbox_mounts字段在引入本字段之前沙箱提供方Docker、Hyperlight、ACA 以及新增的 MXC的文件系统挂载配置散落在策略文档之外的 out-of-bandSimpleNamespace包装器中存在三个现实问题配置来源不统一挂载信息与策略文档分离策略评审者无法在单一文档中看到这个沙箱能读到什么、能写到哪里Pydantic 会静默丢字段策略文档由 Pydantic 模型加载PolicyDocument默认会丢弃未知键。如果挂载配置以自由形式的 mappingduck-typed block承载加载后会被静默丢失导致配置看起来生效、实际没生效的隐蔽故障无法集中校验分散的配置缺少统一入口难以保证所有提供方对挂载路径执行一致的保护性校验。因此本次变更对应 PR 为 #2951在规范PolicyDocumentschema 中新增sandbox_mounts扩展字段让新的 MXCMxcSandboxProvider后端与既有 Docker、Hyperlight、ACA 提供方都可以从一份权威策略文档中读取挂载配置。说明审计文档中记录的 schema 位于agent-governance-python/agent-os/src/agent_os/policies/schema.py当前仓库中该模块的完整挂载校验实现位于 agent-governance-python/agent-sandbox/src/agent_sandbox/_hardening.py建议结合阅读。二、字段模型SandboxMounts与PolicyDocument.sandbox_mounts2.1 新模型SandboxMounts字段类型默认值消费方input_dirstr \| NoneNone不挂载沙箱提供方只读挂载output_dirstr \| NoneNone不挂载沙箱提供方读写挂载input_dir与output_dir的语义边界是由 schema 固定的而不是由调用方在运行期指定input_dir只能以只读方式挂载output_dir才允许读写。这意味着策略无法请求把一个输入目录变成可写挂载——读写分离是模型层面的硬约束而非约定俗成的软约束。2.2PolicyDocument上的新字段字段类型默认值消费方sandbox_mountsSandboxMountsSandboxMounts()两个路径均为None沙箱提供方Docker / Hyperlight / MXC2.3 两个关键设计决策规则引擎完全忽略该字段sandbox_mounts不参与策略评估rule engine evaluation它只在构建沙箱会话时被沙箱提供方读取。策略评估路径与变更前逐字节一致这是策略绕过面不变的重要前提原生建模而非自由 mapping字段被建模为强类型 Pydantic 模型而非 duck-typed block。原因正是第一节提到的 Pydantic 行为——未建模的自由映射键在加载时会被静默丢弃而强类型模型能保证字段在加载、校验、消费全链路中不丢失。三、威胁模型影响additive and fail-closed本次变更是**纯增量、且默认失败关闭fail-closed**的不新增任何能力也不削弱任何既有检查。审计文档给出了七个维度的完整评估维度方向沙箱的文件系统可达性默认不变配置后缩小/受校验。两个挂载路径默认None不挂载。一旦配置路径所有消费提供方都会针对共享的受保护路径黑名单做校验见下文因此策略永远无法挂载系统根目录。出站 / 网络可达性不变。本 PR 不新增网络字段MXC 复用既有network_allowlist/network_default契约fail-closed deny。错误文本中的信息泄露不变。新字段是纯数据载体唯一新增的错误文本是确定性的 protected system directory 拒绝信息回显的正是调用方自己提供的违规路径。策略绕过面不变。没有移除、削弱或条件化任何既有检查规则引擎评估路径逐字节一致。认证 / 身份 / 信任握手不变。未修改任何身份、签名或信任代码。特权边界不变。执行环execution rings、kill switch、审批门approval gates、Cedar 评估全部未触碰。工具调用面MXC 收窄。MXC 无法强制tool_allowlist因此在创建会话时拒绝任何携带非空tool_allowlist的策略而不是静默忽略该控制项。向后兼容性保持。sandbox_mounts为可选字段且默认值安全两个路径均为None既有的 YAML/JSON 策略文档无需修改即可加载。四、具体缓解措施五道 fail-closed 防线4.1 防线一默认不挂载SandboxMounts.input_dir与output_dir必须默认None。未配置挂载的策略不挂载任何目录提供方永远不会回退到宽松的默认挂载。这一点被列为评审最高优先级任何把默认值改为非None的行为都构成安全回归必须标记。4.2 防线二共享的受保护路径校验单一定义源挂载路径input_dir/output_dir以及提供方会话路径统一经过 agent-governance-python/agent-sandbox/src/agent_sandbox/_hardening.py 中的黑名单校验。该模块是叶子模块不导入任何提供方包因此可以被所有后端共享不会产生循环导入也不会把可选后端 SDK 拉进不需要它的提供方。源码中定义了三组保护路径常量PROTECTED_PATHS_UNIX/、/etc、/proc、/sys、/usr、/var、/boot、/dev、/sbin、/bin、/libPROTECTED_PATHS_WINDOWSC:\Windows、C:\Program Files、C:\Program Files (x86)、C:\ProgramData、C:\System Volume Information比较时对挂载路径的 realpath 做大小写不敏感匹配PROTECTED_PATHS_WINDOWS_ROOT_ONLYC:\Users。该集合只在精确挂载根目录时被拦截——挂载C:\Users会暴露所有用户的 profile文档、浏览器数据、SSH 密钥而挂载其下的具体子目录如C:\Users\agent\workspace是合法的每用户模式仍然允许。校验函数is_protected_path(path)按平台分流Windows 分支先normpath(realpath(path))规范化拦截盘符根C:\、D:\等长度 ≤3 且以:结尾的路径再对 Windows 系统目录做大小写不敏感匹配Unix 分支解析符号链接realpath后归一化再与PROTECTED_PATHS_UNIX精确比对。validate_mount_path(path, label)在命中保护路径时抛出ValueError错误信息为Cannot mount protected system directory {path} as {label}且发生在任何沙箱被派生之前。MXC 复用 Docker 提供方原本就使用的同一套逻辑因此所有后端共享同一个定义——不存在某后端漏校验的分叉。4.3 防线三只读/读写分离由 schema 固定input_dir只读、output_dir可写这一语义由 schema 固定而非调用方传入策略无法申请对输入目录的可写挂载。4.4 防线四MXCextra_config不能弱化安全键MXC 允许通过extra_config传入逐字verbatim的深度合并配置但合并之后会重新断言安全关键键network.allowOutbound、解析后的文件系统挂载、timeoutMs。操作者片段永远无法翻转出站开关或替换挂载布局。对应源码中的MxcConfig._reassert_security_keys是评审重点之一。4.5 防线五Guest 环境净化与 egress fail-closedGuest 环境变量过滤guest 环境变量在进入沙箱配置前经过共享的sanitize_env_vars黑名单过滤。源码中BLOCKED_ENV_VARS覆盖了各类解释器/加载器会在沙箱入口点之前读取的启动钩子变量glibc 动态链接器LD_PRELOAD、LD_LIBRARY_PATH、LD_AUDIT、LD_DEBUG、LD_PROFILE、LD_SHOW_AUXV、LD_DYNAMIC_WEAKPOSIX shell 启动钩子BASH_ENV、ENVPythonPYTHONSTARTUP、PYTHONPATH、PYTHONHOMENode.jsNODE_OPTIONSRubyRUBYOPTPerlPERL5LIB、PERL5OPTJavaJAVA_TOOL_OPTIONS、_JAVA_OPTIONS。这些变量之所以危险是因为它们会在沙箱加固逻辑运行之前重定向代码执行路径——例如LD_PRELOAD可在动态链接阶段注入任意共享库。sanitize_env_vars在剔除时会记录警告日志Blocked dangerous environment variables: ...。同时guest/policy 环境绝不混入受信任的 runner 进程环境。Egress 保持 fail-closed出站网络仅当network_allowlist非空且仅限于列出的主机或显式选择defaults.network_default: allow时才启用开启出站但不带任何主机过滤、也没有显式 opt-in的配置会被直接拒绝。五、尚未转换的边界本 PR 明确 out of scope审计文档如实列出了两项已知限制作为后续演进方向挂载路径匹配是精确路径制目前没有 globbing 或按提供方的挂载别名mount aliasing。未来 PR 可能在 schema 层引入归一化的挂载规格normalised mount specs资源上限仍委托给各提供方宿主机侧的max_cpu/max_memory_mb强制仍由各提供方负责。MXC 的0.6.0-alphaschema 无法表达这些字段因此当策略设置了资源上限时MXC 提供方记录警告日志而不是静默丢弃上限目前没有宿主机侧的双重校验。六、测试覆盖把 fail-closed 保证固化为可回归的断言本次变更的测试覆盖集中于两个文件核心目标是让默认不挂载、越权即拒绝成为可持续回归的断言文件目的agent-governance-python/agent-sandbox/tests/test_mxc_sandbox.pyTestFailClosedHardening钉住新增保证extra_config不能翻转allowOutbound或替换 mounts/timeout危险的 guest 环境变量被剥离tool_allowlistfail-closed受保护挂载路径被拒绝覆盖input_dir/output_dir/ 策略挂载caller context / 策略环境不泄漏进 runner 环境egress 契约network_default、无限制 opt-in被强制。agent-governance-python/agent-sandbox/tests/test_docker_sandbox.py受保护路径与环境净化测试被重定向到共享的agent_sandbox._hardening模块确保两个提供方都执行同一份定义。审计时agent-governance-python/agent-sandbox/目录的完整 pytest 运行通过459 passed, 62 skippedruff check --select E,F,W --ignore E501对所有变更源文件保持干净。测试矩阵同时覆盖了新字段不破坏旧文档的兼容性要求省略sandbox_mounts的旧 YAML/JSON 策略文档必须以两个路径均为None的状态加载。七、评审清单五条可复用的安全审查要点审计文档最后给出的 reviewer focus 本质上是一份可复用的安全评审清单任何涉及沙箱挂载能力的变更都值得对照执行默认必须是无挂载SandboxMounts.input_dir和output_dir必须默认None任何非None默认值都是安全回归每个挂载路径都必须过受保护路径校验确认validate_mount_path在MxcConfig.from_sandbox_config与mxc_config_from_policy中同时应用于input_dir、output_dir及策略提供的挂载且共享_hardening黑名单是唯一事实来源single source of truthextra_config不能弱化安全键检查MxcConfig._reassert_security_keys——逐字合并后网络出站、文件系统挂载、超时必须被钉回建模值MXC 保持 fail-closed 姿态验证tool_allowlist在会话创建时的拒绝逻辑、guest 环境净化、runner/guest 环境分离以及 egress 契约默认拒绝无限制出站需要显式 opt-inYAML/JSON 向后兼容省略sandbox_mounts的旧策略文档必须以两个路径均为None加载。八、总结sandbox_mounts字段的落地展示了 Agent Governance Toolkit 在沙箱安全治理上的一个完整范式强类型建模杜绝静默丢字段默认值安全保证零配置即零风险共享加固模块统一所有后端的防线逐字合并后重新断言保证操作者配置无法越权。这一设计同时满足了三类需求——策略评审者能在单一文档中看到挂载全貌、各沙箱提供方共享一套校验逻辑、既有策略文档完全向后兼容。对于任何需要为自主 Agent 配置沙箱文件系统访问的团队本文所述的字段语义、防护路径与评审清单可以直接迁移到自己的策略与沙箱实现中。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考