egress

package
v0.45.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 6 Imported by: 0

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

View Source
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 Mode

type Mode = sandbox.EgressMode

Mode 出口策略档位(值越大越严)。

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

func (s Spec) Env(base []string) ([]string, error)

Env 生成子进程应携带的环境(在 base 之上叠加)。

为什么必须**通过环境显式下发**而不是靠子进程自觉:这是「声明 → 兑现」 的唯一可判定通道——Verify 判的就是这份 env。

func (Spec) SatisfiedBy

func (s Spec) SatisfiedBy(provider any) error

SatisfiedBy 判一个后端能否兑现本声明。

未实现 Enforcer 的后端一律判**不满足**:它没有做出任何声明, 而「没声明」不等于「不受限」——在安全判据里,沉默必须按最弱处理。

兑现强度看 SatisfiedVerdict

本函数只给「成立/不成立」;「以什么强度成立」(后端强制 vs 仅环境变量建议) 看 SatisfiedVerdict——判据同一份,差别只在返回值多带了强度。

func (Spec) SatisfiedVerdict added in v0.32.0

func (s Spec) SatisfiedVerdict(provider any) (Verdict, error)

SatisfiedVerdict 判「后端能否兑现本声明」,并给出兑现强度。

与 SatisfiedBy 的差别只有一个:**多给了强度**。判定口径完全相同。

强度口径(v0.33.0 起:自报与实测分开)

  • 后端实现了 EgressVerifier(能**实测**)→ 实测档位达标 ⇒ StrengthEnforced;
  • 后端只实现了 Enforcer(**自报**能力)→ 声明档位达标 ⇒ StrengthDeclared(**不是** enforced:自报不是实测);
  • 两者都没实现 → 判**不满足**(沉默按最弱处理,见 SatisfiedBy)。

另有一条例外:同一个后端若**同时**实现了两个接口,以**实测**为准—— 实测证据优先于自报声明(证据强度不同级时,取强的那个)。

func (Spec) Validate

func (s Spec) Validate() error

Validate 自检声明本身是否可兑现(配置写错即报错,不静默降级)。

func (Spec) Verify

func (s Spec) Verify(env map[string]string) error

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

func (s Spec) VerifyVerdict(env map[string]string) (Verdict, error)

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
)

func (Strength) String added in v0.32.0

func (s Strength) String() string

String 人类可读的强度名(诊断与日志面,不参与判定)。

type Verdict added in v0.32.0

type Verdict struct {
	// Mode 本次判定的声明档位。
	Mode Mode
	// Strength 兑现强度(按「我们有多确定」排序)。
	Strength Strength
	// Detail 人可读的说明(为什么是这个强度)。
	//
	// 它给的是**差距**:调用方拿这条结论去做风险判断时,看到的不只是
	// 「代理已就位」,还有「这只是建议型」或「这只是后端自报」。
	Detail string
}

Verdict 一条兑现结论:兑现了没有,以什么强度兑现的。

为什么要有它:只有「成立/不成立」二值时,调用方无法区分 「后端在执行环境里强制了代理」与「只是把代理变量塞进了环境」。 而这两种在**威胁模型**里差着一整个量级。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL