Documentation
¶
Overview ¶
normalize.go —— 识别前的数字形态归一化(issue #297)。
为什么需要一层归一化 ¶
原识别只认 **ASCII 连续数字**:`138…`(全角)、`13812345678`(零宽插入)、 `138 1234 5678` / `138-1234-5678` / `138.1234.5678`(分组分隔)全部漏检, 而漏检的形态会整串原样外发、`blocked=false`——宿主以为已保护,实际什么都没有。 根因不是正则写错,是缺一层「先归一化、再判定」。
归一化口径(可预期、可反向验证) ¶
- **全角 → 半角**:U+FF01..U+FF5E 整体折半(数字、字母与 `+ - .` 都覆盖), U+3000 表意空格折成普通空格;
- **不可见字符删除**:U+200B..U+200D、U+2060、U+FEFF、U+00AD、U+180E—— 它们没有语义,留着只会让「同一串数字」在字节层面有无穷多种写法;
- **分组分隔符折叠**:空格 / `-` / `.` 仅在**数字与数字之间**删除,而且只对 「整段数字 + 分隔符的连续串」在**可识别长度**(手机号 11、身份证 18; 带 `86` / `0086` 前缀时 13 / 15)时折叠。这条限制是**误检面评估后的口径**: 无条件删分隔符会把 `版本 1 13812345678` 拼成 12 位长串、并用「前邻数字」 把本来能认出的手机号拒掉;按长度整段折叠既覆盖分组写法,又不改变 既有的空格/符号边界语义。
未折叠的分隔符保持原样(偏移不变),因此「12 位不打」「13 位毫秒时间戳不打」 「19 位数字串」「随机 18 位数字」等防误命中用例在归一化后仍绿。
偏移映射 ¶
归一化文本上的匹配必须能映射回**原串字节偏移**:处置按原串切片,span 覆盖 原串里对应的整段(含内部分隔符),打码不会只盖住「归一化后的一半」。 normalizeForDetect 返回 origIdx:归一化文本每个字节在原串中的起始偏移, 末位补原串长度,使 [start,end) 两端都能直接查表。
仍然不覆盖(文档同步声明,不假装已判定) ¶
阿拉伯-印度数字(٠١٢…)等非全角数字形态、字母/汉字夹在数字之间、 数字间夹非分隔类符号(如 `+`)——这些不在归一化口径内,仍按未命中处理。
Package pii PII 价值模式检测与打码(批次二百七十八,对标 octop-harness ¶
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
PIIMiddleware 的价值面检测):在 logredact(agentkit,凭据类值模式: key=xxx/Authorization/JWT/sk- 前缀等)之外补「个人信息价值面」——大陆手机号与 18 位居民身份证。凭据脱敏按形态命中,个人信息没有键名可依(批266「logredact 键名盲区」教训的價值面延伸:审计链永久留存+SIEM 外发,工单摘要外发 Jira, 值本身即敏感,与键名无关——键位上出现的同类值走同一条判定面,见下)。
保守检测纪律(octop 同款):宁可漏打不可错打。身份证须过四重校验——GB/T 2260 省级码白名单 + 出生日期合法(含未来拒绝)+ 顺序码非全零 + MOD 11-2 校验码—— 订单号/流水号/银行卡号等长数字串几乎不可能同时通过;手机号要求两侧不邻接 字母数字(Go RE2 无环视断言,边界在代码判定),13 位毫秒时间戳因尾邻数字不 会误命中。匹配前先做数字形态归一化(全角 → 半角、去零宽、折叠数字间的分组 分隔符;口径与已知边界见 normalize.go),归一化与处置共用一条路径。缺省策略 mask 保长度(前段+星号+尾段),日志对齐与残留定位友好;其余策略的处置形态由 宿主注入的 StrategyKind 决定(见 policy.go)。
结构面:ApplyValue(按敏感面)递归下探 map[string]any / map[string]string / []any / []string——其中 map[string]string 是 agentkit logredact.RedactValue 的已知结构盲区(alert_svc redactMap 绕行注释在案), 本包一并收口。**键与值走同一条判定面**:以手机号为键的载荷(手机号 → 订单/ 客户资料,中文业务系统的一等形态)不再整键明文外泄,键命中与值命中同样产出 span 级处置与 blocked 信号;普通键逐字不变;不同原键处置出同一形态时按原键 字典序加 "#n" 消解——不丢条目,也不依赖 map 的随机迭代序。nil 容器原样保留: JSON 的 null 与空容器在审计链上是两种形状,处置过程无权把它们合并成一种。
本包是零内部依赖的叶子层(architecture policy 模块 id=pii,requires=[], 错误走 oekit/pkg/errors 单 import):出口面(审计链/事件双出口/工单与告警外发文案) 无条件调用本包,并按各自敏感面走 Apply / ApplyValue;开关收敛在 Enabled 与面开关 (缺省全开)——run.go 从 conf security.pii_value_mask 注入全局开关(缺省开; 显式关闭时启动 WARN 显性化)。
Index ¶
- Constants
- Variables
- func Apply(s Surface, text string) (string, bool)
- func ApplyValue(s Surface, v any) (any, bool)
- func DigestKeyed() bool
- func Enabled() bool
- func Gen() uint64
- func SetDigestKey(key string) error
- func SetEnabled(on bool)
- func SetStrategy(s StrategyKind) error
- func SetSurfaces(ss SurfaceSet)
- func SurfaceEnabled(s Surface) bool
- func Unsubscribe(h Subscription)
- func ValidateShape(v any) error
- func ValidateSurface(s Surface) error
- type Kind
- type Policy
- type Span
- type StrategyKind
- type Subscription
- type Surface
- type SurfaceSet
Constants ¶
const (
// SurfaceAll 三面全开(缺省值)。
SurfaceAll = surfaceInputBit | surfaceOutputBit | surfaceToolResultsBit
)
Variables ¶
var ErrDigestKeyTooShort = errors.New("摘要密钥过短(< 16 字节,可被离线爆破)")
ErrDigestKeyTooShort 注入的摘要密钥短于 minDigestKeyLen。
var ErrNilSubscriber = errors.New("处置策略订阅回调为空")
ErrNilSubscriber 订阅回调为空。
登记一个必然 panic 的订阅者毫无意义,故直接报错并返回零句柄:调用方能**凭返回值** 知道订阅没生效,而不是等到第一次变更时才发现「原来一直没跟上」。
判在**本包**而不是 subhub:三个使用方各有自己的哨兵与语境文案,共用一个会让 `errors.Is(err, pii.ErrNilSubscriber)` 这类既有调用点判定链断掉。
var ErrUnknownStrategy = errors.New("未登记的处置策略")
ErrUnknownStrategy 未登记的处置策略。
var ErrUnknownSurface = errors.New("未登记的敏感面")
ErrUnknownSurface 未登记的敏感面名(宿主配置注入时的 fail-closed)。
var ErrUnsupportedShape = errors.New("未登记的载荷形状")
ErrUnsupportedShape 未登记的载荷形状(运行期 ApplyValue 对它 fail-closed)。
Functions ¶
func Apply ¶
Apply 对指定面处置一段文本。
返回 (处置后文本, 是否阻断):
- 面未启用 / 全局关闭 → (原文, false)
- 检出且策略为 block → (处置后文本, true),**调用方必须履行阻断**
- 其余 → (处置后文本, false)
func ApplyValue ¶
ApplyValue 递归下探常见载荷结构处置(结构面覆盖与原面无关门面一致, 另加上面/策略维度)。返回 (处置后载荷, 是否阻断)。
func DigestKeyed ¶ added in v0.42.0
func DigestKeyed() bool
DigestKeyed 当前是否已注入摘要密钥(接线期自查:StrategyHash 必须配套密钥, 否则运行期 hash 档恒 fail-closed)。
func SetDigestKey ¶ added in v0.42.0
SetDigestKey 注入 StrategyHash 的 HMAC 密钥(conf 侧建议走环境变量等密钥 通道,不得落盘明文)。空串显式清除密钥。
为什么密钥必须在 Policy 里而不是独立的原子变量 ¶
密钥与策略**合起来才是 hash 档的完整语义**。独立的原子变量会重演「不可撕裂 读」那一课:热重载窗口里读到「新策略 + 旧密钥」,一次遍历产出两种摘要形态, 可关联性当场断裂。放进 Policy 随整份快照 CAS 交换,读到的策略与密钥必然同源。
缺密钥的缺省形态是显式的:fail-closed ¶
未注入密钥(或缺密钥)时 hash 档不出摘要——span 整段替换为占位并回报 阻断(与未登记面名同档)。备选方案是降级 mask(静默、不打断),被否决的 理由:hash 档的宿主是在为审计链选「可关联且不可穷举」的形态,静默降级会 把「密钥没配上」变成永远没人看见的既成事实。fail-closed 让接线错误在 第一次处置时就炸出来。接线期自查用 DigestKeyed()。
func SetEnabled ¶
func SetEnabled(on bool)
SetEnabled 注入全局开关(conf security.pii_value_mask / env BQ_PII_VALUE_MASK)。
func Unsubscribe ¶
func Unsubscribe(h Subscription)
Unsubscribe 注销订阅。重复注销同一句柄是安全的空操作。
有了它,订阅者才能在长生命周期场景下解绑:否则回调闭包连同它捕获的一切会被订阅表 永久留住,而这条泄漏不会自己显形。
func ValidateShape ¶ added in v0.42.0
ValidateShape 校验载荷形状是否全部落在 ApplyValue 的**登记面**内,供宿主在 **接线期**自查——与 ValidateSurface 对偶:那边管「面名契约」,这边管 「载荷形状契约」。
为什么需要它 ¶
运行期 ApplyValue 对未登记形状 fail-closed(整段替换 + 要求阻断)——那是 保险,代价是该子树的数据出不去。宿主若能提前知道自己的载荷形状(工具返回 的解码产物),应该在启动时把典型样本过一遍本函数,把「运行期整段替换」 挡在装配期。放行面与运行期放行面共用同一条判据(shapeScalar):
- 登记容器:string / map[string]any / map[string]string / []any / []string (递归下探);
- 标量:数字 / 布尔 / 字符串命名类型(json.Number 等)——文档化盲区,原样放行;
- nil(无类型与带类型)——原样放行;
其余([]map[string]string、map[string][]string、[]byte、struct、数组…)报 ErrUnsupportedShape,错误信息带可定位的路径(如 `$.items[0].blob`)。
func ValidateSurface ¶
ValidateSurface 校验面名是否已登记,供宿主在**接线期**自查配置。
为什么需要它 ¶
Apply / ApplyValue 对未登记面采取 fail-closed(整段替换 + 要求阻断),那是 运行期的兜底,代价是一次误伤。宿主若把面名做成配置项,应该在启动时调一次 本函数把拼写错误挡在外面——fail-closed 是保险,不是日常路径。
// 宿主启动时:
for _, name := range cfg.PiiSurfaces {
if err := pii.ValidateSurface(pii.Surface(name)); err != nil {
return fmt.Errorf("PII 面名 %q 未登记: %w", name, err)
}
}
Types ¶
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy 一份完整的运行时策略快照。
为什么不是三个独立的原子变量 ¶
enabled / surfaces / strategy 三样东西**合起来才是一份策略**,不是三个独立开关。 本包此前正是三个各自原子的包级变量(atomic.Bool + 两个 atomic.Uint32), 逐项看每一次读写都线程安全,看起来没问题——但读侧一次处置要分三次取:
Apply: Enabled() → SurfaceEnabled(s) → applySpans → Strategy() ApplyValue: 每个字符串叶子重走上面整条序列
热重载若发生在两次取之间,读到的是**从未被任何写侧设置过的组合**。 policy_atomic_test.go 的对照组量到了这个窗口:2483 万次读取里 252 万次 (约 10%)读到非法组合。真实后果不是「多打一次码」,而是语义错误:宿主已经 `SetSurfaces(0)` 关掉了某个面,本次调用却仍读到旧的面开着 + 新的 block 策略, 于是回报 blocked=true——**面已关闭却要求阻断**,宿主可能据此中断整条编排链。
与 netguard 的改造同形(那边是把主机名与后缀两个指针并成一份 Policy)。
func CurrentPolicy ¶
func CurrentPolicy() Policy
CurrentPolicy 取当前生效策略的快照。构造后不再被任何写侧触碰(写侧只整体 替换新实例),故取出后可安全长期持有与并发遍历,无需再加锁。
处置路径必须经由本函数拿快照,不得分字段调访问器再拼——那正是撕裂读的来源。
func (Policy) DigestKeyed ¶ added in v0.43.0
DigestKeyed 该快照是否已注入摘要密钥(StrategyHash 的接线期自查口径)。
func (Policy) Strategy ¶ added in v0.43.0
func (p Policy) Strategy() StrategyKind
Strategy 该快照的处置策略。
func (Policy) SurfaceEnabled ¶ added in v0.43.0
SurfaceEnabled 该快照中指定面是否启用。
type StrategyKind ¶
type StrategyKind string
StrategyKind 处置强度(类型名不与同包的 Strategy() 访问器同名)。
const ( // StrategyMask 保长打码(缺省):前段+星号+尾段,日志对齐与残留定位友好。 StrategyMask StrategyKind = "mask" // StrategyRedact 整段删除换固定占位:不可见但长度可变。 StrategyRedact StrategyKind = "redact" // StrategyHash 换成**密钥化的可关联摘要**(域分离 HMAC-SHA256,截断 16 位 // hex):同一值同摘要、异值异摘要。机密性来自宿主注入的密钥(SetDigestKey)—— // 没有密钥的摘要只是原值的可离线穷举等价物(手机号域约 9×10⁹,字典枚举即可 // 还原),故**缺密钥时本档 fail-closed**:整段替换 + 要求阻断,不出摘要。 // 残留强度如实声明:64 bit 截断在同域大值集下存在 birthday 碰撞期望 // (9×10⁹ 值约期望 2 次),可关联用途可接受;穷举防线的关键是密钥保密。 StrategyHash StrategyKind = "hash" // StrategyBlock 检出即阻断——**必须由宿主显式开启并自行履行**, // 本包只回报 blocked=true,不代为抛错(抛错会把出口面的处置决策 // 焊进内核,与「判定语义归内核、处置归宿主」相悖)。 StrategyBlock StrategyKind = "block" )
type Subscription ¶
type Subscription uint64
Subscription 订阅句柄,传给 Unsubscribe 注销。0 表示无效。
func Subscribe ¶
func Subscribe(fn func(Policy)) (Subscription, error)
Subscribe 登记一个处置策略变更订阅者,返回句柄与是否成功。
为什么注册完立刻回调一次当前快照 ¶
不这么做,订阅者对「现在生效的是什么」一无所知,要等到下一次变更才知道。策略注入 的典型形态恰恰是「注册完之后很久没有下一次变更」,于是订阅者带着一个从没填过的 视图上线——比没有订阅更危险,因为它以为自己已经跟上了。
立即回调与登记的次序:可合并,但绝不漏掉一代 ¶
立即回调先于登记执行(此时本订阅者还不在通知名单里,绝不会与并发通知交错), 登记后再读一次当前快照:若这段时间里发生过变更,再补投一次最新的那一代。 登记之后发生的变更由 notifyPolicy 正常送达。于是「取快照 → 登记」窗口内的 变更不会漏,而并发变更可能**合并**为最新一代(单调投递门的选择,见文件头)。
立即回调同样在锁外调用、panic 同样被 recover,与变更通知完全一致。
type SurfaceSet ¶
type SurfaceSet uint8
SurfaceSet 面集合(位集合)。
func ParseSurfaces ¶
func ParseSurfaces(names ...string) (SurfaceSet, error)
ParseSurfaces 由宿主配置解析面集合(未知面名报错,不静默丢弃)。