Agent Governance Toolkit MXC Sandbox Provider基于 MXC 原生二进制的轻量级 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导读本文围绕 Agent Governance Toolkit 中agent-sandbox的MXC Sandbox Provider设计展开讲解如何用 Microsoft eXecution ContainerMXC原生二进制为自主 Agent 提供进程级、一次性、无常驻进程的代码隔离沙箱。读完本文你将掌握 MXC Provider 的会话Session模型与配置映射机制、失败闭合fail-closed的网络与挂载约束、原生治理Native Governance与静态代码扫描的执行时序以及run_once与完整生命周期两种执行方式的选择依据可直接在 Agent 代码执行场景中落地使用。一、设计总览用原生二进制驱动、无常驻沙箱进程设计文档 docs/proposals/MXC-SANDBOX-PROVIDER.md 开宗明义地定义了本模块的架构基调MxcSandboxProviderdrives the native MXC executable and keeps no long-lived sandbox process. A session owns a workspace whose scripts are mounted read-only and whose output directory is mounted read-write.一句话概括Provider 直接驱动 MXC 原生可执行文件不保留任何长期存活的沙箱进程一次会话session持有一个工作区workspace其中脚本目录只读挂载、输出目录读写挂载。MXCMicrosoft eXecution Container是一个原生、以 JSON 配置驱动的沙箱运行器支持 WindowsProcessContainer、LinuxBubblewrap / LXC、macOSSeatbelt以及实验性的 MicroVM / Hyperlight / Windows Sandbox 等包含后端。MXC不提供 Python SDK因此本 Provider 的集成方式是以子进程方式拉起wxc-execWindows/lxc-execLinux/mxc-exec-macmacOS二进制并将一个由MxcConfig渲染出的 JSON 配置文档喂给它——见 provider.py 与 config.py 的模块文档。从源码结构看该 Provider 实现了SandboxProvider抽象基类sandbox_provider.py与 Docker、Hyperlight、ACA 等 Provider 平级统一暴露create_session/execute_code/destroy_session三个核心生命周期方法。二、会话模型会话是配置包不是运行中的进程2.1 MXC 二进制是一次性的MXC 稳定版原生二进制是one-shot语义provision供应→ start启动→ exec执行→ stop停止→ deprovision销毁进程退出即沙箱销毁。它不像 Docker 容器或 Hyperlight 微虚拟机那样存在一个可跨调用复用的常驻 guest。2.2 会话 持久化的bundle为了满足基于会话的SandboxProvider契约本 Provider 把会话建模为一份持久化 bundle而非运行中的进程其组成为见_Session类与create_session实现解析后的MxcConfig已映射完成的沙箱配置可选的策略求值器evaluator来自原生治理 runtime每个会话独立的工作区目录scripts/只读挂载给沙箱与output/读写挂载给沙箱解释器命令默认python。每次execute_code或run都会基于该 bundle 拉起一个全新的 one-shot MXC 沙箱。由此带来的关键语义是同一会话内多次执行之间guest 状态不持久——内存变量、解释器状态以及写在会话读写工作区之外的数据都会在每次调用退出时被丢弃。需要跨调用持久化的调用方应写入会话的读写output/目录它会在主机侧跨执行保留。MXC 的 TypeScript SDK 与0.7.0-devschema 提供了有状态的 provision/exec/stop 生命周期但该路径被留作未来增强不在当前二进制驱动 Provider 的范围内。2.3 工作区的构造细节在create_session中Provider 会用tempfile.mkdtemp(prefixfmxc-{agent_id}-{session_id}-)创建主机侧工作区创建scripts/与output/两个子目录把scripts/追加进MxcConfig.readonly_paths把output/追加进readwrite_paths将(agent_id, session_id)注册进内部的会话字典使用RLock保护因为异步变体委托给同步实现销毁可能与注册表读取重叠。三、配置映射MxcConfig.from_sandbox_config与失败闭合约束3.1 通用配置 → MXC JSON 的映射规则MxcConfig.from_sandbox_configconfig.py将通用的SandboxConfig翻译为 Provider 专属的MxcConfig映射关系如下SandboxConfig字段MxcConfig字段渲染到 MXC JSON 的位置timeout_secondstimeout_ms×1000最小 1mstimeoutMsinput_dirreadonly_paths追加filesystem.readonlyPathsoutput_dirreadwrite_paths追加filesystem.readwritePathsnetwork_enablednetwork_allowlistallow_outboundallowed_hostsnetwork.allowOutboundnetwork.allowedHostsnetwork_defaultallow且无 allowlistallow_unrestricted_egressTruenetwork.allowOutboundtrue无 host 过滤env_varsenv_vars渲染前经sanitize_env_vars清洗process.environmentMxcConfig的默认值schema 版本0.6.0-alpha当前各平台推荐的稳定 schema、timeout_ms60000、allow_outboundFalse、allow_unrestricted_egressFalse、backendNone。3.2 网络出口默认失败闭合设计文档强调Filtered egress usesnetwork.allowedHosts. Unrestricted egress requires explicit default allow.源码中_check_egress强制执行这一契约当allow_outboundTrue但allowed_hosts为空且未显式设置allow_unrestricted_egress时直接抛出ValueError唯一的不受限出口路径是显式开启例如策略层下发defaults.network_default: allow这样配置永远不会静默地变成任意主机可访问。3.3 受保护挂载路径拒绝系统目录from_sandbox_config会对input_dir/output_dir调用validate_mount_path实现在 _hardening.py。该守卫会拒绝挂载以下系统目录Unix 系/、/etc、/proc、/sys、/usr、/var、/boot、/dev、/sbin、/bin、/libWindows 系C:\Windows、C:\Program Files、C:\ProgramData等大小写不敏感且按 realpath 比较Windows 根级目录C:\Users整目录但允许挂载其下的具体子目录如C:\Users\agent\workspace。此外sanitize_env_vars会剥除LD_PRELOAD、LD_LIBRARY_PATH、BASH_ENV、PYTHONSTARTUP、PYTHONPATH、NODE_OPTIONS、JAVA_TOOL_OPTIONS等会在解释器/加载器启动时生效、从而绕过沙箱加固的危险环境变量。3.4 工具白名单与 CPU/内存MXC 不承诺就不渲染设计文档明确指出两点边界MXC 没有工具注册通道。因此SandboxConfig.tool_allowlist非空时create_session会直接抛出ValueError——不是静默忽略而是失败闭合。需要工具门控时请改用 Docker 或 Hyperlight 后端。CPU 与内存限制不在0.6.0-alpha稳定 schema 中表达from_sandbox_config会丢弃memory_mb/cpu_limit由所选包含后端自身的资源模型负责。同样的原则延伸到 JSON 渲染to_mxc_json只输出 MXC 真实支持的键绝不输出无法兑现的声明。对于操作者需要的额外 schema 键如 UI policy、后端专属调优可通过extra_config原样合并且_reassert_security_keys会在合并之后重新钉死network.allowOutbound、allowedHosts、filesystem.*、timeoutMs防止一段 verbatim 片段削弱安全键。一个典型的渲染结果来自 mxc-quickstart 教程{ version: 0.6.0-alpha, process: { commandLine: python /scripts/run.py }, filesystem: { readonlyPaths: [/data/user-pdf], readwritePaths: [/data/agent-out] }, network: { allowOutbound: true, allowedHosts: [pypi.org, *.github.com] }, timeoutMs: 30000 }四、原生治理执行前的宿主侧把关设计文档的 Native governance 一节点出了本 Provider 的安全时序核心create_session(..., runtimeruntime, configconfig)stores aHostSession. Everyexecute_codecall evaluates before the static scan and before MXC is spawned.具体链路如下create_session时若传入runtimeProvider 通过_build_runtime_session从agent_control_specification导入并构造HostSession(runtime, agent_id..., session_id...)随会话 bundle 一并保存每次execute_code时在沙箱拉起之前先调用session.evaluator.pre_tool_call(tool_namesandbox_execute, argseval_ctx, ...)做策略判定eval_ctx携带agent_id、actionexecute、code以及可选的context若返回transform 判定applies_transform由于沙箱无法改写即将执行的代码直接拒绝抛PermissionError若判定为deny抛出PermissionError被拒策略永远不会到达 MXC通过后才进入下一步。该时序保证策略拒绝发生在任何沙箱进程产生之前实现了主机侧零成本拒绝。五、一次性执行与完整生命周期5.1run_once开箱即用的隔离执行设计文档指出run_oncecreates a session, executes once, and destroys the workspace.from agent_sandbox import MxcSandboxProvider, SandboxConfig provider MxcSandboxProvider(backendbubblewrap) execution provider.run_once( tutorial-agent, print(hello from the MXC sandbox), configSandboxConfig(timeout_seconds20, network_enabledFalse), ) result execution.result print(exit:, result.exit_code, ok:, result.success) print(result.stdout)run_once是create_session → execute_code → destroy_session的便捷封装含try/finally确保会话销毁每次调用完全隔离内存变量与读写工作区之外的写入全部丢弃。异步场景可用run_once_async通过asyncio.to_thread委托。5.2 完整生命周期跨调用共享输出当多次调用必须共享输出文件时应使用完整生命周期handle provider.create_session(pdf-agent, runtimeruntime, configconfig) try: for chunk in chunks: execution provider.execute_code( handle.agent_id, handle.session_id, chunk_code ) # 读取 session 的 output/ 目录跨调用持久 finally: provider.destroy_session(handle.agent_id, handle.session_id)destroy_session无需停止任何存活进程one-shot 沙箱每次执行后已自行销毁只需shutil.rmtree清理主机侧工作区。5.3 低层run与execute_code的差异run(agent_id, command, config, session_id...)直接以list[str]命令在沙箱内执行可复用已有会话找不到会话时构建一次性临时 bundle适合非 Python 语言或任意命令行。execute_code(agent_id, session_id, code, context...)面向 Python 代码——把代码写入scripts/{execution_id}.py以interpreter script形式执行避免 shell 引号问题context通过MXC_CONTEXT环境变量以 JSON 暴露给 guest不改写提交的代码。需要注意execute_code只支持 Python 解释器。静态扫描器enforce_no_subprocess_execution见 code_scanner.py基于 Python AST只能审查 Python配置了其他解释器时会拒绝执行否则会运行未经扫描的代码造成虚假安全感并引导调用方改用run()。六、纵深防御四次执行前的检查层结合教程与源码每次执行实际经过四层防护按顺序原生 ACS 治理门AgentControl可在任何沙箱拉起前拒绝见上文第四节静态代码扫描enforce_no_subprocess_execution拒绝subprocess.run/call/Popen、os.system、os.exec*、pty.spawn、shutil.which等明显的进程派生 API含importlib.import_module/__import__动态导入的别名解析MXC 包含文件系统/网络策略由操作系统后端执行bubblewrap 绑定、网络策略、timeoutMs进程环境隔离MXCrunner 进程只接收按平台白名单转发的最小环境Windows 转发PATH/SYSTEMROOT/LOCALAPPDATA等Linux/Darwin 转发PATH/HOME/TMPDIR等绝不继承父进程完整环境宿主密钥不会泄漏给 launcher而 guest 的环境则由配置中的process.environment单独管控。七、二进制发现与实战注意事项7.1 二进制解析顺序Provider 构造时按以下顺序解析 MXC 二进制_resolve_binary显式binary_path参数MXC_BINARY环境变量PATH中按平台查找Linux →lxc-execWindows →wxc-exec.exe/wxc-execmacOS →mxc-exec-mac。找不到二进制不会抛异常而是通过is_available()返回False并记录原因调用方可优雅降级。构造时若传入backend会先构造一个临时MxcConfig做急切实参校验让错误配置在构造期暴露而非首次使用时。7.2 后端与实验模式稳定后端processcontainerWindows、bubblewrap、lxcLinux实验后端windows_sandbox、wslc、microvm、seatbelt、isolation_session、hyperlight——选择实验后端会自动强制--experimental标志needs_experimentalbackendNone时由 MXC 选平台默认Windows 为 processcontainer、Linux 为 bubblewrap、macOS 为 seatbelt。7.3 其他运行细节超时subprocess.run的硬超时 timeout_ms/1000 5 秒_TEARDOWN_GRACE_SECONDS给 MXC 自身 provision/teardown 留出宽限只在 MXC 卡死时才强杀输出截断每路 stdout/stderr 上限 1 MiB_OUTPUT_MAX_BYTES超限追加[...output truncated at byte limit]标记agent_id 校验必须匹配[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}防止恶意 agent_id 做路径穿越或注入控制字符会用于日志、工作区目录名、配置文件名。八、可验证依据与快速上手设计文档docs/proposals/MXC-SANDBOX-PROVIDER.md核心实现provider.py、config.py公共抽象与配置sandbox_provider.py加固原语_hardening.py静态扫描器code_scanner.py可运行教程mxc-quickstart/README.md 与配套脚本 quickstart.py单元测试tests/test_mxc_sandbox.py以sys.executable充当二进制、monkeypatchsubprocess.run保证测试密闭、无需真实 MXC快速运行教程脚本export MXC_BINARY/path/to/lxc-exec # 或放入 PATH python agent-governance-python/agent-sandbox/tutorials/mxc-quickstart/quickstart.py脚本会打印 MXC 可用性、渲染出的配置 JSON并在存在二进制时实际执行一小段沙箱代码。需要提醒的是MXC 目前属于早期预览应作为纵深防御的一环而非硬性安全边界直到其稳定下来在 Agent 治理体系中它是承载不可信Ring 3Agent 代码的首选包含后端之一与上层的策略引擎、静态扫描共同构成宿主治理 沙箱隔离的完整防线。【免费下载链接】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），仅供参考