【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载本文以 RFC 0005 实施计划 为主体逐阶段拆解 OpenShell 沙箱出口egress代理的重构路线Phase 0 的兼容性基线锁定、Phase 1–7 的适配器/授权/中继三层契约提取与切换、Phase 8–11 的 Policy DNS、透明 TCP、原生协议处理器等前瞻能力。读完本文你将理解每个阶段的交付物、切换cutover纪律与回滚策略并能对照 openshell-supervisor-network 源码验证这些契约在当前代码库中的落地形态。背景为什么要拆出一份独立实施计划主 RFC 刻意保持方向聚焦因此实施细节被独立放到 implementation-plan.md。计划的总体结构是Phase 0 – 7 构成兼容性基础重构现有的 CONNECT、forward HTTP转发式 HTTP、raw TCP 与本地服务行为不引入任何新的用户可见传输Phase 8 及以后是前瞻能力在共享契约shared contracts成为权威实现之后才允许叠加 Policy DNS、透明 TCP、原生协议处理器等新特性。这对应主 RFC 提出的三层目标形态适配器Adapters描述用户态如何到达网络组件授权Authorization决定出口是否被允许、适用哪个 endpoint 行为中继Relays拥有字节流、凭据注入、协议解析与上游拨号。风险背景是不对称执行——同一个安全修复可能只加到了 CONNECT 路径而漏掉 forward HTTP。从源码结构看这一拆分已在代码中体现为 proxy.rs 下的三个内部模块egress.rs传输中立的出口输入EgressIntent与授权结果EgressDecisiondestination.rs共享的目的地址校验与上游拨号边界UpstreamConnectorrelay.rs中继选择。Phase 0兼容性基线——把现有行为钉死实施计划的第一步不是改代码而是把现状变成可回归的资产。Phase 0 要求覆盖CONNECT 与 forward HTTP 的 allow/deny 响应精确的状态码、响应头、适配器专属错误体forward HTTP 的边界行为pipelining、keep-alive 后续请求、当前的Connection: close缓解措施、https://绝对形式absolute-form拒绝、被检查端点上 h2c 升级的拒绝重叠策略overlapping policy结果对 matched policy、L7 路由选择、TLS、allowed_ips、精确声明 host 分别单独覆盖故障注入向 L7、TLS、allowed_ips、exact-declared-host 查询注入失败逐条记录当前究竟是 fail-open 还是 fail-closed而不是把所有端点元数据错误当成等价处理特殊地址面控制面端口、云元数据地址、always-blocked 地址、精确声明私有端点、IP 字面量合成、可信网关别名、显式allowed_ips在 CONNECT 和 forward HTTP 下的表现身份语义identity-required 的成功/失败路径、平台不支持时的行为、纯端点endpoint-only求值并证明空的exec.path不能满足二进制范围策略L7 协议行为静态凭据注入、token grants、REST body 改写、WebSocket 文本帧改写、GraphQL、JSON-RPC、MCP本地服务policy.local、元数据回环metadata loopback、nftables bypass 的 reject/log 行为保持不变OCSF 事件基线捕获代表性 allow/deny 路径的稳定事件类、activity/action/disposition、severity、status、destination、actor、防火墙规则、message、status detail性能基线OPA 求值次数、每连接分配量、CONNECT/forward 请求延迟。这一步是后续所有行为不变化声明的验收依据也是测试章节中每个子阶段前后对比 OCSF 夹具的参照系。Phase 1适配器与兼容性决策信封Phase 1 在 openshell-supervisor-network 内引入CONNECT 与 forward HTTP 的EgressIntent构造一个过渡性的EgressDecision承载 L4 结果、策略代policy generation、进程证据与端点字段同时保持当前查询的时序、优先级与失败默认值。关键约束identity 为必需时LookupFailed/不支持的身份仍维持拒绝显式配置的 endpoint-only 模式行为不变适配器专属响应与 OCSF 上报保留在协议边界不得宣称过渡决策就是一次原子 OPA 结果并要在 Phase 3 切换完成前文档化它的兼容性水合compatibility hydration过程。计划明确该阶段是机械提取mechanical extraction必须可独立交付、可回退且不改变任何用户可见的策略或中继行为。这一阶段在源码中已有对应实现。egress.rs 中的核心类型与 RFC 技术设计附录technical-design.md提出的形状一致/// Transport-neutral description of an external egress request. pub(super) struct EgressIntent { pub(super) transport: EgressTransport, pub(super) destination: RequestedDestination, } /// Result of authorizing a normalized egress intent. /// /// The policy action and endpoint metadata are one atomic snapshot. Adapters /// may parse that metadata later, but they never query a second generation. pub(super) struct EgressDecision { pub(super) intent: EgressIntent, pub(super) action: NetworkAction, /// Policy generation used for the complete authorization snapshot. pub(super) policy_generation: u64, pub(super) identity: ProcessIdentityEvidence, // ... }值得注意的是EgressTransport当前枚举已包含Connect、ForwardHttp与TransparentTcp三个变体——TransparentTcp标注为由 policy DNS 注册表喂入的透明 TCP 适配器说明类型骨架先行、能力后补的实施纪律。ProcessIdentityEvidence区分Available与Unavailable(IdentityUnavailableReason)其中EndpointOnlyMode、LookupFailed、UnsupportedPlatform三个不可用原因被刻意分开建模呼应了查找失败不能被偷换成 endpoint-only 求值的安全语义。Phase 2共享目的地址校验Phase 2 把以下逻辑收敛进一个校验器DNS 解析、显式allowed_ips、精确声明端点、隐式 IP 字面量处理、可信网关别名、SSRF 检查、云元数据阻断、控制面端口阻断用显式的校验模式表示取代一堆含糊的布尔开关返回一个未打开的UpstreamConnector使适配器和中继保持当前创建上游 TCP 的时机不变证明 CONNECT 和 forward HTTP 在改用共享校验器后仍然保留现有拒绝响应、OCSF 字段与拨号时序。destination.rs 展示了这一阶段的目标形态AddressAuthorization枚举显式列出每种校验模式build_validation_plan按当前优先级选择一个模式而不改变优先级/// Address-validation mode selected from the current endpoint configuration. pub(crate) enum AddressAuthorization { DefaultPublicOnly, ExplicitAllowedIps(VecIpNet), ExactDeclaredHost, ImplicitIpLiteral(IpAddr), TrustedGatewayAlias { expected_ip: IpAddr }, BackendPinnedGateway(IpAddr), /// Addresses already resolved and authorized by policy DNS. This mode must /// never resolve DestinationRequest::host again before constructing the /// unopened connector. PinnedResolved(VecIpAddr), }从源码结构看PinnedResolved变体带有注释当 policy DNS 适配器落地时启用——它正是为 Phase 8 的透明 TCP 预留的connector 只允许拨号映射中钉住的真实地址绝不在 connect 时重新解析域名。此外DestinationDenialKindResolution、TrustedGateway、AllowedIps、DeclaredEndpoint、InternalAddress等为各适配器保留了各自的拒绝响应形状这正是共享校验逻辑、不共享响应渲染的边界设计。Phase 3代次一致的授权切换唯一的语义收紧阶段这是整个计划中唯一有意收紧歧义或错误行为的阶段计划特别强调它不得隐藏在结构性重构的提交里。其步骤先定规则要么在策略加载时拒绝重叠的端点元数据要么定义一个文档化的 policy/endpoint 优先级键——必须在改变执行之前确定单次原子 OPA 结果从同一策略代次物化出 matched policy/source、matched endpoint、目的约束、TLS、HTTP 执行、凭据计划与中间件选择代次钉住的请求策略为 relay 上下文挂一个代次钉住的TunnelPolicyEngine用于逐请求的 REST、GraphQL、JSON-RPC、MCP 与 WebSocket 求值relay不再重新物化连接级端点策略影子模式新查询与旧查询并行运行产出内部、审计安全的不一致遥测不改变现有 OCSF network/HTTP 事件与执行reload 竞态测试证明所有物化字段都匹配顶层代次且陈旧决策在上游请求写入前被终止切换纪律确定性选择与 L7/TLS 元数据错误 fail-closed 化只在不一致案例被充分理解后作为独立切换完成并临时保留旧评估器以便立即回滚。从 egress.rs 的代码注释可以看到一次原子快照契约已写入实现EgressDecision的文档明确要求策略动作与端点元数据是同一次代次内的原子快照适配器可以稍后解析这些元数据但绝不能再查询第二个代次。Phase 4–5Forward HTTP 适配器与中继收敛Phase 4 - Forward HTTP 适配器绝对形式解析与适配器专属错误保留在 forward HTTP 边界把缓冲的首个请求传入共享 HTTP 中继或者在进入 Phase 5a 之前保留带防护的单请求/Connection: close路径保持https://绝对形式拒绝与被检查路由上的 h2c 拒绝不变量任何未经求值的后续请求不得进入 raw 双向拷贝。Phase 5 - 中继收敛四个可独立交付的子阶段5a HTTP 请求循环把 HTTP 解析与逐请求 REST/GraphQL/JSON-RPC/MCP 求值集中到代次钉住的请求策略句柄之后每个请求在上游写入前求值被拒请求不得创建上游会话保持有界的 JSON-RPC/MCP 检查与审计安全日志省略 params 与工具参数。5b 凭据注入统一静态 target/query/header 改写、端点绑定的 token grants、opt-in REST 请求体改写位置固定在请求被允许之后、上游写入之前保持缓冲上限、支持的 content type、Content-Length重算、日志脱敏、token 缓存以及未解析 secret 的 fail-closed。5c WebSocket把允许的升级upgrade移入共享中继同时保留 raw 升级直通、opt-in 文本帧凭据改写、WebSocket 传输策略、GraphQL-over-WebSocket 策略与安全压缩行为。5d Supervisor 中间件仅当 supervisor middleware 依赖可用后落地。HTTP_REQUEST / PRE_CREDENTIALS在请求被允许之后、静态/动态凭据注入之前运行中间件变换后的 body 必须重新解析并重新求值GraphQL/JSON-RPC/MCP 策略输入再进入凭据注入或上游写入保持顺序、body 上限、fail_open/fail_closed、安全头、findings、metadata并拒绝中间件引入的凭据占位符测试必须覆盖允许请求被中间件改写成被拒操作的场景包括审计模式转发与 fail-closed 的畸形替换体。计划明确每个子阶段都必须可独立测试与交付Phase 5 不是一次性的 flag-day 切换。L7 各协议的具体实现可对照 l7 模块 中的分文件结构rest.rs、graphql.rs、jsonrpc.rs、mcp.rs、websocket.rs、middleware.rs、token_grant_injection.rs等理解。Phase 6共享 TLS 与 TCP 中继边界客户端 TLS 检测与终结移到 HTTP/raw-TCP 中继分叉之前不改变握手、证书或上游连接时序端点 TLS 行为继续放在EgressDecision上tls: skip保持为显式 raw 隧道路径L4 流量复用现有的单一 rawTcpRelay字节拷贝原语引入协议处理器分派契约但兼容性里程碑内不启用任何具体新协议处理器自己拥有消息循环只在协议状态允许时调用已校验的 connector允许树内in-tree、中间件支撑middleware-backed与混合处理器并带类型化中间件操作。Phase 7本地服务与清理——兼容性里程碑policy.local保持为本地适配器当前策略、有界的拒绝摘要、提案提交与提案等待决定元数据回环继续由openshell-sandbox编排还是移入本地适配器边界两种情况下启动/失败行为保持不变为 issue #1633host-local 端点保持本地路由与目的契约的扩展性但其策略面与 host-loopback 授权属于独立功能工作只有当 Phase 3 权威化之后才移除兼容性端点查询移除重复的目的/中继管道但不把适配器专属响应渲染集中化每个已实现的边界都反映当前代码后更新活文档living architecture documentation。Phase 7 完成即为兼容性里程碑现有用户可见功能在新内部结构上全部保留。之后的 Phase 8 是带功能的工作以独立 PR 或系列落地。Phase 8Policy DNS 与透明 TCP功能阶段这是前瞻能力的核心要点密集且环环相扣策略驱动的 DNS 注册为原生 TCP 端点名做策略 DNS 注册不先于资格检查做任何上游 DNS 查询——名称不匹配合格端点时在查询前拒绝取代静态 host-file 映射改为查询驱动的合成 DNS 应答。合格名称经可信 DNS 解析每个真实地址都通过目的控制过滤合成 IP 与映射状态分配 supervisor 拥有的合成 IP在活跃映射状态中存储规范化名称、endpoint ID、允许端口、已校验的真实地址、策略代次、独立的 DNS 映射代次、映射 ID 与过期时间连接相关性correlation每个被捕获的 connect 必须与其合成目的加请求端口选中的未过期映射关联不相关的裸 IP 流量不得继承 policy-DNS 决策原子发布在返回合成 DNS 应答之前从适配器视角原子发布映射与 nftables 捕获更新捕获规则在 bypass 拒绝路径之前加入 nftables REDIRECT/TPROXY 捕获规则不添加平行的 iptables 路径与 openshell-supervisor-process 的 netns 模块协调捕获规则所有权保留对未匹配流量的 reject/log 回退恢复原始目的恢复 original destination构造透明 TCP intent走正常的代次一致授权与目的校验connector限定于映射钉住的已校验真实地址不得在 connect 时独立重新解析DNS 策略保持直接外部 DNS 阻断DNS-over-HTTPS 视为普通受策略控制的 HTTPS 出口启用前置定义合成地址池并在默认启用捕获前完成复用隔离区quarantine、TTL 上限、策略 reload 失效、陈旧映射行为与回滚的设计。对应源码骨架已存在policy_dns 模块 拆分为name.rs名称规范化/资格、resolver.rs可信解析、store.rs映射状态、runtime.rs、wire.rsDNS 应答编码等文件与上述注册—解析—过滤—分配合成 IP—发布映射—应答的流程一一对应。主 RFC 中的 nftables 边界图README.md 内描述的也是同一模型包先匹配代理目的再匹配活跃的合成 IP 捕获否则落到 log reject。Phase 9–11协议处理器、运行时边界与最终清理Phase 9 - 原生协议处理器Redis、Postgres、MySQL 等处理器一次一个协议地加入各自带独立评审的策略 schema 与运维上限省略协议或tcp的端点保持 raw L4 字节拷贝绝不从流量嗅探推断原生处理器测试多消息会话、拨号前拒绝、握手必需的拨号、逐命令/查询求值、中间件钩子、超时与脱敏用能力门控capability-gate处理策略点名了当前代理构建中不可用的处理器。Phase 10 - 运行时边界嵌入式与 network-only supervisor 模式作为迁移基线为未来的独立二进制或 sidecar 定义 proxy 运行时 API已配置 listener、策略更新、provider 凭据、token grants、中间件注册表、网关调用、遥测、拒绝/活动事件与关闭通告进程身份与协议处理器能力拒绝需要不可用 binary/path 身份或处理器支持的策略把运行时身份有意不可用与现有 endpoint-only 模式、查找失败分开建模这正是 egress.rs 中IdentityUnavailableReason区分EndpointOnlyMode与LookupFailed的原因若 proxy 与 gateway 版本可能不同加入网关能力协商。Phase 11 - 最终清理在观察窗口结束后移除为确定性决策回滚而保留的兼容性查询/评估器随对应后续阶段落地从代理设计与架构文档中移除过时的静态/etc/hosts、iptables 或单进程假设保持适配器专属响应渲染与 OCSF 契约位于其协议边界。测试与运维验证实施计划的最后一节把如何证明没改坏写成了一组明确义务按主题归纳验证类别具体要求单元测试适配器 intent 构造、响应渲染、显式目的模式、身份证据、授权优先级目的校验集成测试跨 CONNECT 与 forward HTTPPhase 8 落地后同一套件复用于透明 TCP中继集成测试HTTP keep-alive/pipelining、REST、GraphQL、JSON-RPC、MCP、WebSocket、凭据、token grants、中间件、TLS/raw-TCP 选择本地服务测试policy.local与元数据回环的 body 限制、超时、脱敏、本地拒绝响应OCSF 对比每个迁移子阶段前后对比 OCSF 夹具reload 竞态在 L4 决策、端点物化、relay 启动与长生命周期逐请求求值之间演练策略 reload协议处理器先在添加 Redis/Postgres/MySQL 之前建好协议处理器测试工装harness每个具体处理器补多消息、握手、超时、拒绝、脱敏、中间件覆盖Policy DNS策略 DNS 过滤、无上游查询即拒绝、合成应答分配、TTL 与复用隔离、不同映射代次、reload 失效、原子捕获规则更新、original-destination 恢复、允许端口相关性、connector 限定于钉住的真实地址、拒绝不相关裸 IP connect相关性证明两个解析到同一真实 IP:port 的名称获得独立相关性不能互相继承端点策略运行时能力独立/sidecar 能力协商身份或处理器缺失在策略校验期失败而不是运行时放宽 allow性能在兼容信封、单次决策查询、中继收敛后各重跑一次性能基线把OPA 调用减少当作测量结果而非假设收益回滚结构性阶段通过回退其隔离提交回退影子对比与旧评估器在确定性切换的观察窗口内保持可用后续传输/运行时阶段独立门控禁用 policy DNS 或透明捕获即可恢复显式代理与 bypass-reject 行为而不必回退兼容性基础结语计划本身就是一种工程契约implementation-plan.md 的价值不止于排期它把什么可以并行、什么必须先影子运行、什么必须独立评审写成了可执行的纪律。三个关键设计判断贯穿全文兼容性阶段零语义变更——Phase 0–7 只搬代码不改行为任何行为收紧Phase 3 的 fail-closed 化、确定性端点选择都被隔离成可独立评审、可立即回滚的专项切换契约先行、能力后补——EgressIntent/EgressDecision/UpstreamConnector与AddressAuthorization::PinnedResolved等类型骨架已在 proxy/egress.rs、proxy/destination.rs 中落地并预留了透明 TCP 的挂载点而 Policy DNS 与捕获能力等到契约权威化后才作为独立功能进入兼容面即契约——适配器响应字节与 OCSF 事件字段是兼容面而非清理目标性能改善必须以前后测量证明。配套阅读建议主 RFC 看架构与非目标README.md、现状附录看当前形态current-shape.md、类型与边界细节看技术设计附录technical-design.md、代码入口看 proxy.rs 及其proxy/子模块与 proxy/tests 中的兼容性测试。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐OpenShell 沙箱代理出口适配器 RFC 0005current-shape 附录中的现状拆解与评审发现OpenShell 沙箱代理出口适配器 RFC 0005current shape 附录中的现状拆解与评审发现 本篇基于 RFC 0005 现状附录 httpOpenShell RFC 0005 解读沙箱代理出站适配器模型Egress Adapter如何统一 CONNECT、Forward HTTP 与透明 TCP 的授权边界OpenShell RFC 0005 解读沙箱代理出站适配器模型Egress Adapter如何统一 CONNECT、Forward HTTP 与透明 TOpenShell RFC 0004沙箱类型化资源需求 —— 用 ResourceRequirements 取代 GPU 专用字段的设计与实现OpenShell RFC 0004沙箱类型化资源需求 —— 用 ResourceRequirements 取代 GPU 专用字段的设计与实现 本文基于 Op上一篇如何用Hermes WebUI打造智能人力资源AI助手招聘与员工管理终极指南 下一篇掌握DebugView正则表达式打造个性化日志过滤规则创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考