Documentation
¶
Overview ¶
Package egress 出口策略的**声明面与兑现判据**(机制面)。
生命周期: Experimental(v0.33.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
它补的是哪个洞 ¶
本仓的 netguard 判定挂在 Go 的 http.Client / Transport 上,覆盖面是 「本进程内走 netguard 的 HTTP 出站」。而工具执行的两类主流形态都在它之外:
- 子进程(ptc 的子进程 Provider 用 exec.Command 重新拉起自己);
- 宿主自己起的命令行工具(curl / git / 各种 SDK 的 native 部分)。
于是「声明了受限出口」在那一侧**没有任何东西兑现**:策略写得很严,实际流量 自由出网。这与本仓反复强调的「声明强度 ≠ 实际强度」是同一条纪律的又一次实例。
本包给什么、不给什么 ¶
**给**:① 出口策略的**词表**(三档,可比较强弱);② 子进程环境的**生成**; ③ 「声明 vs 实际」的**判据**(Verify);④ 后端能力声明接口(Enforcer)—— 词表与契约的真相在上游 guardx/sandbox,本包只做 alias(理由见 Mode 的注释)。
**不给**:代理本体与网络强制实现——那是执行环境的事(上游安全层 / 宿主)。 本包只在**声明面**与**判据面**上保证一致,不造第二套网络栈。
三档为什么这样排序 ¶
ModeUnrestricted(0) < ModeProxy(1) < ModeDenied(2)
「禁网」严格强于「经代理」:禁网的后端天然满足「经代理」的要求(没有流量能出), 反之不成立。排序让「后端能力 ≥ 要求」可以用一个整数比较表达,不需要枚举矩阵。
为什么环境变量这条路对「禁网」不成立 ¶
环境变量只是**建议**:HTTP_PROXY 可以被子进程忽略,静态链接的二进制、 UDP、原始 socket 都绕得过去。故 ModeDenied 的 Env 与 Verify **直接报错**, 而不是伪造一组「看起来禁了」的变量——伪造成功比拒绝更危险:它会让 「声明了禁网」在报告里显示为已兑现。
Index ¶
- Constants
- type EgressVerifier
- type Enforcer
- type Mode
- type Spec
- func (s Spec) Env(base []string) ([]string, error)
- func (s Spec) SatisfiedBy(provider any) error
- func (s Spec) SatisfiedVerdict(provider any) (Verdict, error)
- func (s Spec) Validate() error
- func (s Spec) Verify(env map[string]string) error
- func (s Spec) VerifyVerdict(env map[string]string) (Verdict, error)
- type Strength
- type Verdict
Constants ¶
const ( // ModeUnrestricted 不要求(默认;零值即此档,故旧调用点行为不变)。 ModeUnrestricted = sandbox.EgressUnrestricted // ModeProxy 要求出站经代理(可配合 Allow 做目标白名单)。 ModeProxy = sandbox.EgressProxy // ModeDenied 要求完全禁网(只能由执行后端强制,环境变量做不到)。 ModeDenied = sandbox.EgressDenied )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EgressVerifier ¶ added in v0.33.0
type EgressVerifier interface {
// VerifyEgress 返回**实测**得到的出站档位。
//
// 实现方负责完成探测(必要时自行缓存结果)。返回值应如实反映
// 「当前这次执行环境下,出站被挡到了哪一档」——实测不到就返回较低档位,
// 不要把「我以为挡住了」当成实测结论。
VerifyEgress() (Mode, error)
}
EgressVerifier 执行后端的**实测验证**能力。
与 Enforcer 的区别是决定性的 ¶
- Enforcer.Egress() 是**自报**:「我能强制哪一档」;
- EgressVerifier.VerifyEgress() 是**实测**:「我刚才真的去试过, 确实连不上」。
自报不等于事实:两者之间必须有信号,否则「声明强度」与「实际强度」 之间就没有落差可言——而后端自报恰恰是最容易被读成事实的那种声明。
为什么方法不带 ctx ¶
探测怎么做是**执行后端**的事(它知道在那个环境里怎么试),本包不代它 发请求;实现方可以在自己的装配阶段探测一次并缓存结果,再通过本接口 把它交出来。判据面因此保持无副作用、可重复。
为什么定义在本仓而不是上游 ¶
上游 guardx/sandbox 定了档位词表与能力声明面(Enforcer),但没有 「实测证据」这一档。本包是出口**判据**的归属地,故在此定义; 上游若日后补上同名能力,本包的别名可逐字替换(调用面不动)。
type Enforcer ¶
type Enforcer = sandbox.EgressEnforcer
Enforcer 后端能力声明:它能**强制**哪一档出站。
未实现它的后端一律判不满足(见 SatisfiedBy):它没有做出任何声明,而 「没声明」不等于「不受限」——安全判据里沉默必须按最弱处理。
type Spec ¶
type Spec struct {
// Mode 要求的档位。
Mode Mode
// Proxy 代理地址(ModeProxy 时必填),形如 "http://127.0.0.1:3128"。
Proxy string
// Allow 允许访问的目标(由**代理**判定,本包只原样携带给兑现者)。
//
// 刻意**不**写进 NO_PROXY:NO_PROXY 的语义是「绕过代理直连」,与「允许经
// 代理访问」正好相反。写进去会让允许名单变成豁免名单——代理的拒绝名单、端口
// 白名单、只读档对它全部失效,而报告里那条声明仍然显示「已兑现」。需要「不经
// 代理」的目标请写 Bypass,别借 Allow 表达相反的语义。
Allow []string
// Bypass 明确**不经代理直连**的目标(写进 NO_PROXY / no_proxy)。
//
// 默认空:整条变量都不出现。空值 "NO_PROXY=" 在部分客户端里会被读成「所有
// 主机都不经代理」,那是比不写更危险的一种形式。
Bypass []string
}
Spec 一次执行对出口策略的要求。
func (Spec) Env ¶
Env 生成子进程应携带的环境(在 base 之上叠加)。
为什么必须**通过环境显式下发**而不是靠子进程自觉:这是「声明 → 兑现」 的唯一可判定通道——Verify 判的就是这份 env。
func (Spec) SatisfiedBy ¶
SatisfiedBy 判一个后端能否兑现本声明。
未实现 Enforcer 的后端一律判**不满足**:它没有做出任何声明, 而「没声明」不等于「不受限」——在安全判据里,沉默必须按最弱处理。
兑现强度看 SatisfiedVerdict ¶
本函数只给「成立/不成立」;「以什么强度成立」(后端强制 vs 仅环境变量建议) 看 SatisfiedVerdict——判据同一份,差别只在返回值多带了强度。
func (Spec) SatisfiedVerdict ¶ added in v0.32.0
SatisfiedVerdict 判「后端能否兑现本声明」,并给出兑现强度。
与 SatisfiedBy 的差别只有一个:**多给了强度**。判定口径完全相同。
强度口径(v0.33.0 起:自报与实测分开) ¶
- 后端实现了 EgressVerifier(能**实测**)→ 实测档位达标 ⇒ StrengthEnforced;
- 后端只实现了 Enforcer(**自报**能力)→ 声明档位达标 ⇒ StrengthDeclared(**不是** enforced:自报不是实测);
- 两者都没实现 → 判**不满足**(沉默按最弱处理,见 SatisfiedBy)。
另有一条例外:同一个后端若**同时**实现了两个接口,以**实测**为准—— 实测证据优先于自报声明(证据强度不同级时,取强的那个)。
func (Spec) Verify ¶
Verify 判据:实际下发给子进程的 env 是否真的兑现了声明。
这是本包存在的理由——**声明与实际的对照**。env 由调用方在真正 spawn 之前取到, 判不过即不执行(而不是执行完再补一句「好像没生效」)。
兑现强度看 VerifyVerdict ¶
本函数只给「成立/不成立」。「以什么强度成立」(建议型 vs 强制型)看 VerifyVerdict——环境变量兑现出来的**永远是建议型**,这一点不该只写在 注释里,而该出现在判据返回值上。
两项判据(绕过名单 / 代理变量)各只有一个实现、各覆盖全部大小写变体—— 「同一机制两份实现必然漂移」的教训就来自这里:绕过名单曾按 Bypass 空不空 走两份只有大小写口径不同的实现,小写 no_proxy=* 从只查大写的那份底下绕过 (issue #63);代理变量曾判「六个里命中一个就算兑现」,只配了 HTTP_PROXY 的环境验成 enforced 而 HTTPS 裸奔(issue #62)。
func (Spec) VerifyVerdict ¶ added in v0.32.0
VerifyVerdict 判「实际下发的 env 是否兑现了声明」,并给出兑现强度。
与 Verify 的差别只有一个:**多给了强度**。判定口径完全相同 (同一份实现,见 VerifyVerdict 内部),故两者的结论不可能打架。
强度口径:环境变量兑现出来的**永远是建议型**——环境变量拦不住 静态链接二进制、UDP 与原始 socket。这一点不是判断,是事实。
type Strength ¶ added in v0.32.0
type Strength int
Strength 兑现强度:**实际兑现**出来的强度。
为什么需要这一层 ¶
本包的判据有两个入口,而它们的强度天然不同:
- Verify(env):看实际下发给子进程的环境变量。环境变量是**建议**—— 静态链接的二进制、UDP、原始 socket 都绕得过去。故它兑现出来的 永远是 StrengthAdvisory(建议型),**不是** OS 级隔离。
- SatisfiedVerdict(provider):问后端「你能强制哪一档」。
自报 ≠ 实测(v0.33.0 起拆开) ¶
后端说「我能强制哪一档」(Enforcer.Egress())是**自报**:它陈述的是 自己的能力,不是对当前这次执行的观测。把它直接判成 StrengthEnforced, 等于让「声明强度」冒充「实际强度」——这正是评估里点出的误读: 「代理档已兑现」很容易被读成「出站已被强制隔离」,而这两件事在 **威胁模型**里差着一整个量级。
故本包把两者分成两个取值:
- StrengthDeclared:后端**自报**能力,未经实测;
- StrengthEnforced:**实测**过(EgressVerifier 提供了实测证据)。
而「实测证据」必须由后端**真的去探测**得出——本包不代它发请求, 也不接受「我保证我拦得住」这种断言当证据。没拿到实测证据时, 最强只能说 declared:与本仓「沉默按最弱处理」同源—— **没证据 ≠ 已强制**。
四个取值(按「我们有多确定」排序) ¶
- StrengthNotRequired:未要求限制(ModeUnrestricted)。无从兑现,也无需兑现;
- StrengthAdvisory:建议型(环境变量等)。可被绕过;
- StrengthDeclared:后端自报能强制某档(未经实测);
- StrengthEnforced:强制型,且**有实测证据**。
const ( // StrengthNotRequired 未要求限制,无从兑现。 StrengthNotRequired Strength = iota // StrengthAdvisory 建议型兑现(环境变量等建议手段),可被绕过。 StrengthAdvisory // StrengthDeclared 后端**自报**能力:它声称能在执行环境层面强制某档, // 但**没有实测证据**。 // // 它单独一档,而不是并进 StrengthEnforced:并进去的话,只看 Strength // 的读者会把「后端自称」读成「已经强制」——那正是这一档要拆的那件事。 StrengthDeclared // StrengthEnforced 强制型兑现,且**经实测验证**(实测出站确实被挡住)。 StrengthEnforced )
type Verdict ¶ added in v0.32.0
type Verdict struct {
// Mode 本次判定的声明档位。
Mode Mode
// Strength 兑现强度(按「我们有多确定」排序)。
Strength Strength
// Detail 人可读的说明(为什么是这个强度)。
//
// 它给的是**差距**:调用方拿这条结论去做风险判断时,看到的不只是
// 「代理已就位」,还有「这只是建议型」或「这只是后端自报」。
Detail string
}
Verdict 一条兑现结论:兑现了没有,以什么强度兑现的。
为什么要有它:只有「成立/不成立」二值时,调用方无法区分 「后端在执行环境里强制了代理」与「只是把代理变量塞进了环境」。 而这两种在**威胁模型**里差着一整个量级。