mistral.rs Python SDK 中的 Shell 工具与 OS 级沙箱ShellConfig 与 SandboxPolicy 实战【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs在让大模型执行真实 Shell 命令时安全隔离与工具装配是两个核心问题。本篇基于 mistral.rs 仓库中的官方示例 shell.md 及其源码示例 shell.py讲解如何通过 Python SDK 的ShellConfig与SandboxPolicy为模型注册一个受沙箱保护的 shell 工具命令在每会话独立的工作目录中运行内存、CPU、进程数、网络访问都被 OS 级机制约束。读完后你将能够独立配置沙箱策略的各项参数、理解每个参数在底层如何实现、并区分 CLI 与 SDK 两种入口在沙箱默认行为上的关键差异。运行沙箱化 Shell 执行官方示例的完整源码位于 shell.py运行方式如下需要启用code-executionfeature 安装 Python 绑定pip install -e mistralrs-pyo3 --features code-execution python examples/python/shell.py示例程序的核心结构from mistralrs import ( ChatCompletionRequest, NetworkMode, Runner, SandboxPolicy, ShellConfig, Which, ) def main(): sandbox SandboxPolicy( max_memory_mb1024, max_cpu_secs120, max_procs32, networkNetworkMode.Loopback, ) runner Runner( whichWhich.Plain(model_idQwen/Qwen3-4B), shell_configShellConfig(sandbox_policysandbox), ) response runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: Use the shell to print the current directory and list its files., } ], enable_shellTrue, max_tool_rounds4, ) ) for choice in response.choices: print(choice.message.content) if __name__ __main__: main()整个流程分三步构造SandboxPolicy定义子进程可使用的资源上限示例中把默认策略收紧为 1024 MB 内存、120 秒 CPU 时间、32 个进程并声明网络模式为仅回环Loopback把策略挂到ShellConfig上再传给Runner只要构造并挂上了SandboxPolicy沙箱即被启用不传则子进程拥有完整的宿主访问权限这一点后文详述发起对话请求ChatCompletionRequest中enable_shellTrue声明本次请求允许使用 shell 工具max_tool_rounds4限制模型最多进行 4 轮生成命令 → 执行 → 观察输出的工具循环。模型收到用户指令后会自主生成commands参数调用 shell 工具示例中即打印当前目录并列出文件。SandboxPolicy 参数详解SandboxPolicy是 Python 绑定层定义的类源码见 code_execution.rs。构造签名与默认值如下参数类型默认值含义max_memory_mbu642048地址空间上限MB在支持资源限制的平台上强制max_cpu_secsu64300CPU 时间上限秒在支持资源限制的平台上强制max_procsu3264子进程数量上限max_open_fdsu321024打开文件描述符上限max_file_sz_mbu64256单个可写文件的大小上限MBnetworkNetworkModeLoopback子进程允许的网络访问范围extra_fs_readlist[Path]空追加到系统只读白名单之外的额外可读路径extra_fs_writelist[Path]空追加到会话工作目录之外的额外可写路径extra_envlist[str]空环境清洗之外额外放行透传的环境变量名strictboolFalse为True时缺失的请求层如文件系统隔离不可用直接变成硬错误network参数接受三种NetworkMode枚举值见 code_execution.rsNetworkMode.NoNetwork完全禁止 socketLinux 上在 seccomp 层拒绝socket(2)系统调用NetworkMode.Loopback仅允许回环地址。这是默认值——源码注释指出许多 Python 库在 import 阶段会探测127.0.0.1因此保留回环可以避免大量库直接报错NetworkMode.Full不限制网络等价于沙箱前的行为。这些参数在核心层对应mistralrs_sandbox::SandboxPolicy结构体定义于 sandbox/src/lib.rs此外还有session_workdir字段由调用方在执行前填入每会话工作目录用于授予沙箱读写权限。两个值得注意的联动规则由 shell.rs 中的raise_cpu_limit_for_timeout实现当资源限制rlimits实际生效且配置的 shell 单次超时超过max_cpu_secs时运行时会把max_cpu_secs自动抬升到与超时一致并记录警告避免长任务被更低的 CPU 上限提前掐断strictTrue时validate_strict_policy会在初始化阶段检查 rlimits、文件系统隔离、网络隔离是否真正可用任一缺失即报错退出见 shell.rs。ShellConfig工具注册与其余配置ShellConfig控制 shell 工具本身的装配Python 绑定见 code_execution.rs核心结构见 shell.rs参数默认值含义shell_pathUnix 为/bin/shWindows 为cmd执行的 Shell 可执行文件创建时会被校验能否运行validate_shelltimeout_secs600单次命令调用的墙钟超时秒超时返回timed_out: true的 JSONworking_directory每会话临时目录指定后所有会话共享该目录产物跨会话可见sandbox_policyNone即不启用沙箱如示例所示传入SandboxPolicy即启用 OS 级沙箱permissionauto取值auto/ask/deny决定模型请求的命令能否启动与沙箱职责分离权限与沙箱是两个正交的安全层permission 决定这条命令能不能跑沙箱决定命令跑起来之后能碰到什么。需要人工审批时可将permission设为ask并提供审批回调参考文档 permissions-and-approvals。每会话工作目录与输出收集从源码结构看ShellManagershell.rs按session_id维护会话映射。每个会话首次调用 shell 工具时ShellSession::new会创建独立工作目录未指定working_directory时生成mistralrs-shell-随机前缀的临时目录命令之间共享状态前一条命令写入的文件后续命令可见指定了工作目录时则在其下按session_id建子目录。后台 reaper 任务每 300 秒扫描一次回收超过 1 小时SESSION_TTL未活跃的会话及其目录。每次执行前运行时还会把工作目录快照一次执行后通过collect_output_files与append_auto_output_files收集新增或模型显式声明的产物文件。模型可以用两种方式把文件交给调用方在 shell 调用的outputs参数里声明或调用内建的mistralrs_surface_outputs工具。详细语义见 enable-shell 指南 的 File outputs 一节。命令执行结果以结构化 JSON 返回给模型包含status、working_directory、stdout、stderr、exit_code、timed_out字段见 shell.rs。沙箱底层实现Linux 与 macOS 的隔离层沙箱抽象定义在 mistralrs-sandbox/src/lib.rsSandboxtrait 提供两个钩子hardenspawn 之前强化命令可安装pre_exec钩子、清洗环境与attachspawn 之后附加Linux 上用于写 cgroup 成员关系。平台探测由detect()完成Linux 返回LinuxSandboxmacOS 返回MacosSandbox其他平台退化为NullSandbox并打印警告。SandboxManager侧的选型逻辑在 shell.rs配置了sandbox_policy就走detect()否则走null()。按官方参考文档 sandbox.md 的说明Linux 上各层按以下顺序施加环境清洗env scrub丢弃全部继承的环境变量只回放PATH、LANG、HOME、TMPDIR等少量白名单项HF_TOKEN、AWS_*、OPENAI_API_KEY等凭据默认不透传HOME与 XDG 目录被重指向会话工作目录。需要放行其他变量时用extra_env声明进程数 rlimitRLIMIT_NPROC按真实 UID 计为当前 UID 任务数之上的额外配额命名空间在支持非特权用户命名空间时施加CLONE_NEWUSER|CLONE_NEWIPC|CLONE_NEWUTSnetworkloopback且支持网络命名空间时追加CLONE_NEWNET内部 UID 0 映射回调用者 UIDLandlock内核 5.13只读白名单覆盖/usr、/lib、/etc、/proc/self等系统路径会话工作目录获读写权限白名单之外一律EACCESrlimits按策略设置RLIMIT_AS、RLIMIT_CPU、RLIMIT_NOFILE、RLIMIT_FSIZE并置零 core dumpseccomp-bpf 拒绝清单对ptrace、mount、unshare、bpf、init_module、reboot等特权系统调用返回EPERMnetworknone时追加拒绝socketloopback时拒绝AF_NETLINK/AF_PACKET套接字。另有一个尽力而为的 cgroup v2 层当/sys/fs/cgroup/cgroup.controllers可委派时创建独立 scope写入memory.max与pids.max并把子 PID 移入。若宿主机缺少命名空间或 seccomp缺失层会被跳过希望缺层即失败时把策略设为 strict 或使用 CLI 的--sandbox on模式。macOS 上实现走 Seatbeltargv被sandbox-exec -p profile包装生成的 SBPL 配置文件默认拒绝放行运行时所需的系统路径、dyld 与时区数据库、Homebrew/MacPorts 前缀等会话工作目录与配置写入路径获读写权限网络策略按none/loopback/full翻译为对应规则。macOS 不施加资源 rlimits源码注释说明这要求从已运行的多线程进程里加pre_exec钩子会强制 fork因此max_memory_mb等字段在 macOS 上仅作配置兼容文件系统和网络隔离仍然生效。SDK 与 CLI 的默认行为差异这是本示例最值得强调的一点sandbox.md 中专门用 caution 提示CLI 与 TOML 配置在 Linux/macOS 上默认--sandbox auto沙箱开箱即启用Python 与 Rust SDK 默认不启用沙箱——ShellConfig/CodeExecutionConfig的sandbox_policy默认为None等价于--sandbox off。内嵌 mistral.rs 的应用不会继承 CLI 的安全默认必须像示例那样自行构造并挂上SandboxPolicy。此外还有两个相关控制面环境变量MISTRALRS_SANDBOX{auto|on|off}常量定义见 lib.rs可在运行时覆盖 CLI/TOML 的 mode优先级低于显式 CLI/TOML 值、高于默认auto但它不改变 profile 与网络策略沙箱的威胁模型是针对模型误操作删文件、外传数据、fork 炸弹、ptrace宿主进程等文档明确它不能替代面向强攻击者的 OS 级隔离高可信场景建议把 mistral.rs 进程本身再放进容器/VM或使用--tool-dispatch-url把执行完全移出宿主。小结关注点配置入口关键事实启用 shell 工具Runner(shell_configShellConfig(...)) 请求级enable_shellTrue每会话独立工作目录max_tool_rounds控制工具轮数启用沙箱ShellConfig(sandbox_policySandboxPolicy(...))SDK 默认无沙箱必须显式挂载资源限制max_memory_mb/max_cpu_secs/max_procs等Linux 经 rlimits 可选 cgroup v2macOS 不强制网络策略NetworkMode.NoNetwork / Loopback / Full默认 Loopbacknone依赖 seccomp 拒绝socket严格模式strictTrue或 CLI--sandbox on缺失的隔离层从静默降级变为启动硬错误配套阅读沙箱完整参考 reference/sandbox.md、启用 shell 的指南 guides/agents/enable-shell.mdx、Rust 侧示例 examples/rust/advanced/shell以及核心实现 mistralrs-code-exec/src/shell.rs 与 mistralrs-sandbox/src/lib.rs。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mistral.rs Python SDK 中的 Shell 工具与 OS 级沙箱：ShellConfig 与 SandboxPolicy 实战
mistral.rs Python SDK 中的 Shell 工具与 OS 级沙箱ShellConfig 与 SandboxPolicy 实战【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs在让大模型执行真实 Shell 命令时安全隔离与工具装配是两个核心问题。本篇基于 mistral.rs 仓库中的官方示例 shell.md 及其源码示例 shell.py讲解如何通过 Python SDK 的ShellConfig与SandboxPolicy为模型注册一个受沙箱保护的 shell 工具命令在每会话独立的工作目录中运行内存、CPU、进程数、网络访问都被 OS 级机制约束。读完后你将能够独立配置沙箱策略的各项参数、理解每个参数在底层如何实现、并区分 CLI 与 SDK 两种入口在沙箱默认行为上的关键差异。运行沙箱化 Shell 执行官方示例的完整源码位于 shell.py运行方式如下需要启用code-executionfeature 安装 Python 绑定pip install -e mistralrs-pyo3 --features code-execution python examples/python/shell.py示例程序的核心结构from mistralrs import ( ChatCompletionRequest, NetworkMode, Runner, SandboxPolicy, ShellConfig, Which, ) def main(): sandbox SandboxPolicy( max_memory_mb1024, max_cpu_secs120, max_procs32, networkNetworkMode.Loopback, ) runner Runner( whichWhich.Plain(model_idQwen/Qwen3-4B), shell_configShellConfig(sandbox_policysandbox), ) response runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: Use the shell to print the current directory and list its files., } ], enable_shellTrue, max_tool_rounds4, ) ) for choice in response.choices: print(choice.message.content) if __name__ __main__: main()整个流程分三步构造SandboxPolicy定义子进程可使用的资源上限示例中把默认策略收紧为 1024 MB 内存、120 秒 CPU 时间、32 个进程并声明网络模式为仅回环Loopback把策略挂到ShellConfig上再传给Runner只要构造并挂上了SandboxPolicy沙箱即被启用不传则子进程拥有完整的宿主访问权限这一点后文详述发起对话请求ChatCompletionRequest中enable_shellTrue声明本次请求允许使用 shell 工具max_tool_rounds4限制模型最多进行 4 轮生成命令 → 执行 → 观察输出的工具循环。模型收到用户指令后会自主生成commands参数调用 shell 工具示例中即打印当前目录并列出文件。SandboxPolicy 参数详解SandboxPolicy是 Python 绑定层定义的类源码见 code_execution.rs。构造签名与默认值如下参数类型默认值含义max_memory_mbu642048地址空间上限MB在支持资源限制的平台上强制max_cpu_secsu64300CPU 时间上限秒在支持资源限制的平台上强制max_procsu3264子进程数量上限max_open_fdsu321024打开文件描述符上限max_file_sz_mbu64256单个可写文件的大小上限MBnetworkNetworkModeLoopback子进程允许的网络访问范围extra_fs_readlist[Path]空追加到系统只读白名单之外的额外可读路径extra_fs_writelist[Path]空追加到会话工作目录之外的额外可写路径extra_envlist[str]空环境清洗之外额外放行透传的环境变量名strictboolFalse为True时缺失的请求层如文件系统隔离不可用直接变成硬错误network参数接受三种NetworkMode枚举值见 code_execution.rsNetworkMode.NoNetwork完全禁止 socketLinux 上在 seccomp 层拒绝socket(2)系统调用NetworkMode.Loopback仅允许回环地址。这是默认值——源码注释指出许多 Python 库在 import 阶段会探测127.0.0.1因此保留回环可以避免大量库直接报错NetworkMode.Full不限制网络等价于沙箱前的行为。这些参数在核心层对应mistralrs_sandbox::SandboxPolicy结构体定义于 sandbox/src/lib.rs此外还有session_workdir字段由调用方在执行前填入每会话工作目录用于授予沙箱读写权限。两个值得注意的联动规则由 shell.rs 中的raise_cpu_limit_for_timeout实现当资源限制rlimits实际生效且配置的 shell 单次超时超过max_cpu_secs时运行时会把max_cpu_secs自动抬升到与超时一致并记录警告避免长任务被更低的 CPU 上限提前掐断strictTrue时validate_strict_policy会在初始化阶段检查 rlimits、文件系统隔离、网络隔离是否真正可用任一缺失即报错退出见 shell.rs。ShellConfig工具注册与其余配置ShellConfig控制 shell 工具本身的装配Python 绑定见 code_execution.rs核心结构见 shell.rs参数默认值含义shell_pathUnix 为/bin/shWindows 为cmd执行的 Shell 可执行文件创建时会被校验能否运行validate_shelltimeout_secs600单次命令调用的墙钟超时秒超时返回timed_out: true的 JSONworking_directory每会话临时目录指定后所有会话共享该目录产物跨会话可见sandbox_policyNone即不启用沙箱如示例所示传入SandboxPolicy即启用 OS 级沙箱permissionauto取值auto/ask/deny决定模型请求的命令能否启动与沙箱职责分离权限与沙箱是两个正交的安全层permission 决定这条命令能不能跑沙箱决定命令跑起来之后能碰到什么。需要人工审批时可将permission设为ask并提供审批回调参考文档 permissions-and-approvals。每会话工作目录与输出收集从源码结构看ShellManagershell.rs按session_id维护会话映射。每个会话首次调用 shell 工具时ShellSession::new会创建独立工作目录未指定working_directory时生成mistralrs-shell-随机前缀的临时目录命令之间共享状态前一条命令写入的文件后续命令可见指定了工作目录时则在其下按session_id建子目录。后台 reaper 任务每 300 秒扫描一次回收超过 1 小时SESSION_TTL未活跃的会话及其目录。每次执行前运行时还会把工作目录快照一次执行后通过collect_output_files与append_auto_output_files收集新增或模型显式声明的产物文件。模型可以用两种方式把文件交给调用方在 shell 调用的outputs参数里声明或调用内建的mistralrs_surface_outputs工具。详细语义见 enable-shell 指南 的 File outputs 一节。命令执行结果以结构化 JSON 返回给模型包含status、working_directory、stdout、stderr、exit_code、timed_out字段见 shell.rs。沙箱底层实现Linux 与 macOS 的隔离层沙箱抽象定义在 mistralrs-sandbox/src/lib.rsSandboxtrait 提供两个钩子hardenspawn 之前强化命令可安装pre_exec钩子、清洗环境与attachspawn 之后附加Linux 上用于写 cgroup 成员关系。平台探测由detect()完成Linux 返回LinuxSandboxmacOS 返回MacosSandbox其他平台退化为NullSandbox并打印警告。SandboxManager侧的选型逻辑在 shell.rs配置了sandbox_policy就走detect()否则走null()。按官方参考文档 sandbox.md 的说明Linux 上各层按以下顺序施加环境清洗env scrub丢弃全部继承的环境变量只回放PATH、LANG、HOME、TMPDIR等少量白名单项HF_TOKEN、AWS_*、OPENAI_API_KEY等凭据默认不透传HOME与 XDG 目录被重指向会话工作目录。需要放行其他变量时用extra_env声明进程数 rlimitRLIMIT_NPROC按真实 UID 计为当前 UID 任务数之上的额外配额命名空间在支持非特权用户命名空间时施加CLONE_NEWUSER|CLONE_NEWIPC|CLONE_NEWUTSnetworkloopback且支持网络命名空间时追加CLONE_NEWNET内部 UID 0 映射回调用者 UIDLandlock内核 5.13只读白名单覆盖/usr、/lib、/etc、/proc/self等系统路径会话工作目录获读写权限白名单之外一律EACCESrlimits按策略设置RLIMIT_AS、RLIMIT_CPU、RLIMIT_NOFILE、RLIMIT_FSIZE并置零 core dumpseccomp-bpf 拒绝清单对ptrace、mount、unshare、bpf、init_module、reboot等特权系统调用返回EPERMnetworknone时追加拒绝socketloopback时拒绝AF_NETLINK/AF_PACKET套接字。另有一个尽力而为的 cgroup v2 层当/sys/fs/cgroup/cgroup.controllers可委派时创建独立 scope写入memory.max与pids.max并把子 PID 移入。若宿主机缺少命名空间或 seccomp缺失层会被跳过希望缺层即失败时把策略设为 strict 或使用 CLI 的--sandbox on模式。macOS 上实现走 Seatbeltargv被sandbox-exec -p profile包装生成的 SBPL 配置文件默认拒绝放行运行时所需的系统路径、dyld 与时区数据库、Homebrew/MacPorts 前缀等会话工作目录与配置写入路径获读写权限网络策略按none/loopback/full翻译为对应规则。macOS 不施加资源 rlimits源码注释说明这要求从已运行的多线程进程里加pre_exec钩子会强制 fork因此max_memory_mb等字段在 macOS 上仅作配置兼容文件系统和网络隔离仍然生效。SDK 与 CLI 的默认行为差异这是本示例最值得强调的一点sandbox.md 中专门用 caution 提示CLI 与 TOML 配置在 Linux/macOS 上默认--sandbox auto沙箱开箱即启用Python 与 Rust SDK 默认不启用沙箱——ShellConfig/CodeExecutionConfig的sandbox_policy默认为None等价于--sandbox off。内嵌 mistral.rs 的应用不会继承 CLI 的安全默认必须像示例那样自行构造并挂上SandboxPolicy。此外还有两个相关控制面环境变量MISTRALRS_SANDBOX{auto|on|off}常量定义见 lib.rs可在运行时覆盖 CLI/TOML 的 mode优先级低于显式 CLI/TOML 值、高于默认auto但它不改变 profile 与网络策略沙箱的威胁模型是针对模型误操作删文件、外传数据、fork 炸弹、ptrace宿主进程等文档明确它不能替代面向强攻击者的 OS 级隔离高可信场景建议把 mistral.rs 进程本身再放进容器/VM或使用--tool-dispatch-url把执行完全移出宿主。小结关注点配置入口关键事实启用 shell 工具Runner(shell_configShellConfig(...)) 请求级enable_shellTrue每会话独立工作目录max_tool_rounds控制工具轮数启用沙箱ShellConfig(sandbox_policySandboxPolicy(...))SDK 默认无沙箱必须显式挂载资源限制max_memory_mb/max_cpu_secs/max_procs等Linux 经 rlimits 可选 cgroup v2macOS 不强制网络策略NetworkMode.NoNetwork / Loopback / Full默认 Loopbacknone依赖 seccomp 拒绝socket严格模式strictTrue或 CLI--sandbox on缺失的隔离层从静默降级变为启动硬错误配套阅读沙箱完整参考 reference/sandbox.md、启用 shell 的指南 guides/agents/enable-shell.mdx、Rust 侧示例 examples/rust/advanced/shell以及核心实现 mistralrs-code-exec/src/shell.rs 与 mistralrs-sandbox/src/lib.rs。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考