OpenSandbox CLI 网络出口管控实战osb egress 运行时策略检查、修补与行为验证【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 的osb egress命令组把沙箱出站网络策略当作一条完整的策略工作流来管理而不是一行孤立的命令。本文基于仓库中的 skill 文档 opensandbox-network-egress.md系统讲解运行前配置解析、egress get/egress patch的黄金路径、创建期策略文件的写法以及如何在补丁之后用真实命令验证网络行为读完你可以独立完成检查现状 → 最小化修补 → 双重验证的出站策略操作并理解 CLI 背后对接的 Egress API 与 Python SDK 调用链。一、运行时出口策略的模型defaultAction 与有序规则列表在给出任何osb egress命令之前先要理解运行时出口策略runtime egress policy由两部分构成defaultAction当没有任何规则命中时的兜底动作取值为allow或denyegress按顺序排列的 allow/deny 规则列表。Skill 文档强调了几条关键语义这些语义在 OpenAPI 规范 中有逐条对应若defaultAction缺省策略模型默认按deny处理见 egress-api.yaml 中NetworkPolicy的描述IfdefaultActionis omitted, the sidecar defaults to deny运行时修补patch使用合并语义merge semantics不是整个策略对象的替换目标target应是域名形式例如pypi.org或*.example.com不要假设 IP 或 CIDR 目标受支持——规范明确写道 IP/CIDR not yet supported in the egress MVPegress-api.yaml。由此引出两条命令分工对已创建的沙箱做运行时策略调整osb egress patch对尚未创建的沙箱在创建时就定义策略osb sandbox create --network-policy-file ...。二、前置步骤先解析当前生效的连接配置建议任何 egress 命令之前都应先解析 CLI 实际将使用的连接配置osb config show -o json重点检查解析后的三个值domainapi_keyprotocol注意osb config show会对 API key 做打码处理从 config_cmd.py 的源码看api_key属于_SENSITIVE_CONFIG_KEYS_mask_secret只保留首尾两个字符、中间以*填充它的用途是确认生效目标而不是恢复凭据本身。也不要假设用户只通过环境变量配置 OpenSandbox一切以 CLI 真正会用到的解析结果为准。文档将其定义为硬停止点Hard stopdomain缺失时先停下来设置再谈策略变更osb config set connection.domain host:port -o json osb config show -o json若需要鉴权而api_key缺失同样先设置再继续osb config set connection.api_key api-key -o json osb config show -o json从源码看config set 要求 key 必须是section.field形式例如connection.domain并通过正则定位 TOML 段落进行值替换或追加若配置文件不存在会直接报错提示先运行osb config init。三、Golden Path检查、修补、验证的完整工作流Skill 文档给出的两条黄金路径是本文的核心操作模板。路径一检查并修补osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowpypi.org -o json osb egress get sandbox-id -o json路径二检查、修补并验证真实行为osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://www.github.com osb command run sandbox-id -o raw -- curl -I https://pypi.org两条路径体现了同一原则把运行时 egress 修补当作策略工作流始终先看当前状态、只补需要的规则、再同时验证策略文本与真实网络行为。四、osb egress get先读当前策略osb egress get sandbox-id -o json任何现有状态很重要的场景都应先执行这条命令再谈修补。从 egress.py 的源码看egress get会先通过obj.connect_sandbox(sandbox_id)连接沙箱再调用sandbox.get_egress_policy()输出支持table/json/yaml三种格式默认 table。对应到 Python SDKsandbox.py 中get_egress_policy委托给 egress service 的get_policy()。按 egress-api.yaml 的定义GET /policy返回的PolicyStatusResponse除了policy本身外还带有 sidecar 派生的运行时元数据status、mode如deny_all与enforcementMode如dns规范中的示例如下{ status: ok, mode: deny_all, enforcementMode: dns, policy: { defaultAction: deny, egress: [ { action: allow, target: pypi.org } ] } }这些派生字段帮助你在看规则文本之外同时确认 sidecar 当前处于哪种执行模式。五、osb egress patch最小化、可审计的规则合并只修补用户真正需要的规则osb egress patch sandbox-id --rule allowpypi.org -o json osb egress patch sandbox-id --rule denyinternal.example.com -o json osb egress patch sandbox-id --rule allow*.example.com -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json规则书写与执行须遵守三点修补要保持窄范围且可审计变更必须表达为显式的allow或deny条目不要把 patch 描述成对整个策略对象的替换。参数格式方面--rule必须是ACTIONTARGET形式且可重复。从 _parse_rule 源码看解析逻辑会先按第一个切分action 统一转小写后必须是allow或deny否则抛出click.BadParameter提示 Invalid rule. Use ACTIONTARGET, for example allowpypi.org.。而 patch 的合并语义由 Egress API 明确规定egress-api.yaml现有规则在未被入站规则覆盖时保持不变入站规则相对同 target 的现有规则拥有更高优先级同一次 patch 载荷中若出现多个相同target的规则第一条生效。SDK 侧 patch_egress_rules 的文档字符串也重申了这一点本次 patch 载荷中的规则优先于同 target 的现有规则其他 target 的规则不受影响单次载荷内同 target 以首条为准且该操作does not replace the entire policy and does not change the current defaultAction。六、创建期策略--network-policy-file 的 JSON 形状如果沙箱还没有创建应当走生命周期创建期的策略文件而不是事后再补。参见 sandbox-lifecycle skill 中的用法与示例osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json示例network-policy.json{ defaultAction: deny, egress: [ { action: allow, target: pypi.org }, { action: allow, target: files.pythonhosted.org } ] }从 sandbox.py 源码看--network-policy-file指向的 JSON 会被解析后构造为NetworkPolicy对象传入创建请求。还有一个强约束值得注意--credential-proxy启用 Credential Vault 透明代理必须与--network-policy-file一起使用否则 CLI 会直接报错 --credential-proxy requires --network-policy-file because Credential Vault injection needs egress policy这与 egress-api.yaml 中创建 Credential Vault 要求 sidecar 运行于dnsnft模式且存在 egress 策略、强烈建议defaultAction: deny的描述一致。七、行为验证策略文本之外用真实命令确认放行/拦截当用户在排查连通性问题时不能止步于策略文本。用沙箱内真实命令验证运行时行为osb command run sandbox-id -o raw -- curl -I https://pypi.org osb command run sandbox-id -o raw -- curl -I https://www.github.com验证手段的组合是用egress get确认当前规则集合用osb command run ... -o raw -- curl ...确认出站访问实际是被允许还是被拒绝。八、底层访问模型与调用链理解CLI 到底连到哪里有助于排障。按 egress-api.yaml 的描述Egress API 由沙箱内的egress sidecar提供与生命周期 API 不同客户端分两步访问先用 Sandbox Lifecycle API 解析出沙箱 egress 端口的 endpoint直接向该 endpoint 的/policy或/credential-vault路由发请求。鉴权方面sidecar 可要求OPENSANDBOX-EGRESS-AUTH头当 endpoint 解析器返回所需 headers 时客户端必须在每次 egress API 请求中转发它们。从源码结构看完整调用链为osb egress get/patchegress.py→SandboxSync.get_egress_policy() / patch_egress_rules()sync/sandbox.py→ egress service 的get_policy / patch_rulesservices/egress.py 定义了 Egress 服务协议→ sidecar 的GET/PATCH /policy。Python SDK 还提供了delete_egress_rulessandbox.py对应 API 的DELETE /policy按 target 删除规则、未命中的 target 被静默忽略幂等、保留当前defaultAction——目前 CLI 的osb egress命令组未暴露该子命令但 SDK 层可用。九、运行时注意事项与最小闭环Skill 文档给出的运行时注意事项沙箱尚未创建时使用生命周期创建期策略文件osb egress patch仅用于已创建或已运行的沙箱若 patch 正确但网络访问仍然异常继续走sandbox-troubleshooting流程而不是假设 patch 命令静默失败参见 sandbox-troubleshooting skill。两个最小闭环Minimal Closed Loops可直接复制放行一个域名并验证osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowpypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://pypi.org在两个域名之间翻转行为osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://www.github.com osb command run sandbox-id -o raw -- curl -I https://pypi.org十、最佳实践与响应模式汇总 skill 文档的 Best Practices在特定服务器上修补策略前先解析当前生效的连接配置优先用osb config show而不是检查孤立的环境变量先检查、后修补只修补最小必要的域名集合验证真实行为而不只是规则文本除非用户确实需要否则优先显式域名而非宽泛通配符初始沙箱供给优先用创建期策略文件事后调整再用运行时 patch。面向用户的回答应遵循固定结构精确的osb egress命令该命令应用了什么策略变更接下来要运行的验证命令。命令示例务必具体、可直接粘贴执行。适用前提与限制本文所有命令均以 OpenSandbox CLIosb与 Python SDK 的当前仓库代码为准--rule的ACTIONTARGET解析、合并语义、鉴权头要求等细节若后续版本演进请以仓库内 egress 命令实现 与 Egress API 规范 为准当前工作流的目标仅支持 FQDN 与通配域名IP/CIDR 在 egress MVP 中不受支持运行osb egress需要能访问 OpenSandbox server 且已配置connection.domain及需要鉴权时的connection.api_key若沙箱尚未创建请先用osb sandbox create --network-policy-file在创建期注入策略。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenSandbox CLI 网络出口管控实战osb egress 运行时策略检查、修补与行为验证【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 的osb egress命令组把沙箱出站网络策略当作一条完整的策略工作流来管理而不是一行孤立的命令。本文基于仓库中的 skill 文档 opensandbox-network-egress.md系统讲解运行前配置解析、egress get/egress patch的黄金路径、创建期策略文件的写法以及如何在补丁之后用真实命令验证网络行为读完你可以独立完成检查现状 → 最小化修补 → 双重验证的出站策略操作并理解 CLI 背后对接的 Egress API 与 Python SDK 调用链。一、运行时出口策略的模型defaultAction 与有序规则列表在给出任何osb egress命令之前先要理解运行时出口策略runtime egress policy由两部分构成defaultAction当没有任何规则命中时的兜底动作取值为allow或denyegress按顺序排列的 allow/deny 规则列表。Skill 文档强调了几条关键语义这些语义在 OpenAPI 规范 中有逐条对应若defaultAction缺省策略模型默认按deny处理见 egress-api.yaml 中NetworkPolicy的描述IfdefaultActionis omitted, the sidecar defaults to deny运行时修补patch使用合并语义merge semantics不是整个策略对象的替换目标target应是域名形式例如pypi.org或*.example.com不要假设 IP 或 CIDR 目标受支持——规范明确写道 IP/CIDR not yet supported in the egress MVPegress-api.yaml。由此引出两条命令分工对已创建的沙箱做运行时策略调整osb egress patch对尚未创建的沙箱在创建时就定义策略osb sandbox create --network-policy-file ...。二、前置步骤先解析当前生效的连接配置建议任何 egress 命令之前都应先解析 CLI 实际将使用的连接配置osb config show -o json重点检查解析后的三个值domainapi_keyprotocol注意osb config show会对 API key 做打码处理从 config_cmd.py 的源码看api_key属于_SENSITIVE_CONFIG_KEYS_mask_secret只保留首尾两个字符、中间以*填充它的用途是确认生效目标而不是恢复凭据本身。也不要假设用户只通过环境变量配置 OpenSandbox一切以 CLI 真正会用到的解析结果为准。文档将其定义为硬停止点Hard stopdomain缺失时先停下来设置再谈策略变更osb config set connection.domain host:port -o json osb config show -o json若需要鉴权而api_key缺失同样先设置再继续osb config set connection.api_key api-key -o json osb config show -o json从源码看config set 要求 key 必须是section.field形式例如connection.domain并通过正则定位 TOML 段落进行值替换或追加若配置文件不存在会直接报错提示先运行osb config init。三、Golden Path检查、修补、验证的完整工作流Skill 文档给出的两条黄金路径是本文的核心操作模板。路径一检查并修补osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowpypi.org -o json osb egress get sandbox-id -o json路径二检查、修补并验证真实行为osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://www.github.com osb command run sandbox-id -o raw -- curl -I https://pypi.org两条路径体现了同一原则把运行时 egress 修补当作策略工作流始终先看当前状态、只补需要的规则、再同时验证策略文本与真实网络行为。四、osb egress get先读当前策略osb egress get sandbox-id -o json任何现有状态很重要的场景都应先执行这条命令再谈修补。从 egress.py 的源码看egress get会先通过obj.connect_sandbox(sandbox_id)连接沙箱再调用sandbox.get_egress_policy()输出支持table/json/yaml三种格式默认 table。对应到 Python SDKsandbox.py 中get_egress_policy委托给 egress service 的get_policy()。按 egress-api.yaml 的定义GET /policy返回的PolicyStatusResponse除了policy本身外还带有 sidecar 派生的运行时元数据status、mode如deny_all与enforcementMode如dns规范中的示例如下{ status: ok, mode: deny_all, enforcementMode: dns, policy: { defaultAction: deny, egress: [ { action: allow, target: pypi.org } ] } }这些派生字段帮助你在看规则文本之外同时确认 sidecar 当前处于哪种执行模式。五、osb egress patch最小化、可审计的规则合并只修补用户真正需要的规则osb egress patch sandbox-id --rule allowpypi.org -o json osb egress patch sandbox-id --rule denyinternal.example.com -o json osb egress patch sandbox-id --rule allow*.example.com -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json规则书写与执行须遵守三点修补要保持窄范围且可审计变更必须表达为显式的allow或deny条目不要把 patch 描述成对整个策略对象的替换。参数格式方面--rule必须是ACTIONTARGET形式且可重复。从 _parse_rule 源码看解析逻辑会先按第一个切分action 统一转小写后必须是allow或deny否则抛出click.BadParameter提示 Invalid rule. Use ACTIONTARGET, for example allowpypi.org.。而 patch 的合并语义由 Egress API 明确规定egress-api.yaml现有规则在未被入站规则覆盖时保持不变入站规则相对同 target 的现有规则拥有更高优先级同一次 patch 载荷中若出现多个相同target的规则第一条生效。SDK 侧 patch_egress_rules 的文档字符串也重申了这一点本次 patch 载荷中的规则优先于同 target 的现有规则其他 target 的规则不受影响单次载荷内同 target 以首条为准且该操作does not replace the entire policy and does not change the current defaultAction。六、创建期策略--network-policy-file 的 JSON 形状如果沙箱还没有创建应当走生命周期创建期的策略文件而不是事后再补。参见 sandbox-lifecycle skill 中的用法与示例osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json示例network-policy.json{ defaultAction: deny, egress: [ { action: allow, target: pypi.org }, { action: allow, target: files.pythonhosted.org } ] }从 sandbox.py 源码看--network-policy-file指向的 JSON 会被解析后构造为NetworkPolicy对象传入创建请求。还有一个强约束值得注意--credential-proxy启用 Credential Vault 透明代理必须与--network-policy-file一起使用否则 CLI 会直接报错 --credential-proxy requires --network-policy-file because Credential Vault injection needs egress policy这与 egress-api.yaml 中创建 Credential Vault 要求 sidecar 运行于dnsnft模式且存在 egress 策略、强烈建议defaultAction: deny的描述一致。七、行为验证策略文本之外用真实命令确认放行/拦截当用户在排查连通性问题时不能止步于策略文本。用沙箱内真实命令验证运行时行为osb command run sandbox-id -o raw -- curl -I https://pypi.org osb command run sandbox-id -o raw -- curl -I https://www.github.com验证手段的组合是用egress get确认当前规则集合用osb command run ... -o raw -- curl ...确认出站访问实际是被允许还是被拒绝。八、底层访问模型与调用链理解CLI 到底连到哪里有助于排障。按 egress-api.yaml 的描述Egress API 由沙箱内的egress sidecar提供与生命周期 API 不同客户端分两步访问先用 Sandbox Lifecycle API 解析出沙箱 egress 端口的 endpoint直接向该 endpoint 的/policy或/credential-vault路由发请求。鉴权方面sidecar 可要求OPENSANDBOX-EGRESS-AUTH头当 endpoint 解析器返回所需 headers 时客户端必须在每次 egress API 请求中转发它们。从源码结构看完整调用链为osb egress get/patchegress.py→SandboxSync.get_egress_policy() / patch_egress_rules()sync/sandbox.py→ egress service 的get_policy / patch_rulesservices/egress.py 定义了 Egress 服务协议→ sidecar 的GET/PATCH /policy。Python SDK 还提供了delete_egress_rulessandbox.py对应 API 的DELETE /policy按 target 删除规则、未命中的 target 被静默忽略幂等、保留当前defaultAction——目前 CLI 的osb egress命令组未暴露该子命令但 SDK 层可用。九、运行时注意事项与最小闭环Skill 文档给出的运行时注意事项沙箱尚未创建时使用生命周期创建期策略文件osb egress patch仅用于已创建或已运行的沙箱若 patch 正确但网络访问仍然异常继续走sandbox-troubleshooting流程而不是假设 patch 命令静默失败参见 sandbox-troubleshooting skill。两个最小闭环Minimal Closed Loops可直接复制放行一个域名并验证osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowpypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://pypi.org在两个域名之间翻转行为osb egress get sandbox-id -o json osb egress patch sandbox-id --rule allowwww.github.com --rule denypypi.org -o json osb egress get sandbox-id -o json osb command run sandbox-id -o raw -- curl -I https://www.github.com osb command run sandbox-id -o raw -- curl -I https://pypi.org十、最佳实践与响应模式汇总 skill 文档的 Best Practices在特定服务器上修补策略前先解析当前生效的连接配置优先用osb config show而不是检查孤立的环境变量先检查、后修补只修补最小必要的域名集合验证真实行为而不只是规则文本除非用户确实需要否则优先显式域名而非宽泛通配符初始沙箱供给优先用创建期策略文件事后调整再用运行时 patch。面向用户的回答应遵循固定结构精确的osb egress命令该命令应用了什么策略变更接下来要运行的验证命令。命令示例务必具体、可直接粘贴执行。适用前提与限制本文所有命令均以 OpenSandbox CLIosb与 Python SDK 的当前仓库代码为准--rule的ACTIONTARGET解析、合并语义、鉴权头要求等细节若后续版本演进请以仓库内 egress 命令实现 与 Egress API 规范 为准当前工作流的目标仅支持 FQDN 与通配域名IP/CIDR 在 egress MVP 中不受支持运行osb egress需要能访问 OpenSandbox server 且已配置connection.domain及需要鉴权时的connection.api_key若沙箱尚未创建请先用osb sandbox create --network-policy-file在创建期注入策略。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
