pii

package
v0.48.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: 16 Imported by: 0

Documentation

Overview

normalize.go —— 识别前的数字形态归一化(issue #297)。

为什么需要一层归一化

原识别只认 **ASCII 连续数字**:`138…`(全角)、`138​12345678`(零宽插入)、 `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

View Source
const (

	// SurfaceAll 三面全开(缺省值)。
	SurfaceAll = surfaceInputBit | surfaceOutputBit | surfaceToolResultsBit
)

Variables

View Source
var ErrDigestKeyTooShort = errors.New("摘要密钥过短(< 16 字节,可被离线爆破)")

ErrDigestKeyTooShort 注入的摘要密钥短于 minDigestKeyLen。

View Source
var ErrNilSubscriber = errors.New("处置策略订阅回调为空")

ErrNilSubscriber 订阅回调为空。

登记一个必然 panic 的订阅者毫无意义,故直接报错并返回零句柄:调用方能**凭返回值** 知道订阅没生效,而不是等到第一次变更时才发现「原来一直没跟上」。

判在**本包**而不是 subhub:三个使用方各有自己的哨兵与语境文案,共用一个会让 `errors.Is(err, pii.ErrNilSubscriber)` 这类既有调用点判定链断掉。

View Source
var ErrUnknownStrategy = errors.New("未登记的处置策略")

ErrUnknownStrategy 未登记的处置策略。

View Source
var ErrUnknownSurface = errors.New("未登记的敏感面")

ErrUnknownSurface 未登记的敏感面名(宿主配置注入时的 fail-closed)。

View Source
var ErrUnsupportedShape = errors.New("未登记的载荷形状")

ErrUnsupportedShape 未登记的载荷形状(运行期 ApplyValue 对它 fail-closed)。

Functions

func Apply

func Apply(s Surface, text string) (string, bool)

Apply 对指定面处置一段文本。

返回 (处置后文本, 是否阻断):

  • 面未启用 / 全局关闭 → (原文, false)
  • 检出且策略为 block → (处置后文本, true),**调用方必须履行阻断**
  • 其余 → (处置后文本, false)

func ApplyValue

func ApplyValue(s Surface, v any) (any, bool)

ApplyValue 递归下探常见载荷结构处置(结构面覆盖与原面无关门面一致, 另加上面/策略维度)。返回 (处置后载荷, 是否阻断)。

func DigestKeyed added in v0.42.0

func DigestKeyed() bool

DigestKeyed 当前是否已注入摘要密钥(接线期自查:StrategyHash 必须配套密钥, 否则运行期 hash 档恒 fail-closed)。

func Enabled

func Enabled() bool

Enabled 当前是否启用(关闭时 Apply / ApplyValue 原样透传,零改写)。

func Gen

func Gen() uint64

Gen 当前策略代次(与快照同步递增,供可观测性使用)。

func SetDigestKey added in v0.42.0

func SetDigestKey(key string) error

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 SetStrategy

func SetStrategy(s StrategyKind) error

SetStrategy 注入处置策略(未知策略报错并保持原值,不静默降级)。

func SetSurfaces

func SetSurfaces(ss SurfaceSet)

SetSurfaces 注入面集合。

func SurfaceEnabled

func SurfaceEnabled(s Surface) bool

SurfaceEnabled 指定面当前是否启用。

func Unsubscribe

func Unsubscribe(h Subscription)

Unsubscribe 注销订阅。重复注销同一句柄是安全的空操作。

有了它,订阅者才能在长生命周期场景下解绑:否则回调闭包连同它捕获的一切会被订阅表 永久留住,而这条泄漏不会自己显形。

func ValidateShape added in v0.42.0

func ValidateShape(v any) error

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

func ValidateSurface(s Surface) error

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 Kind

type Kind string

Kind PII 类型(span 标注与打码策略分派用)。

const (
	KindMobile     Kind = "cn_mobile"      // 大陆手机号(可带 +86/0086 前缀)
	KindResidentID Kind = "cn_resident_id" // 18 位居民身份证(末位 X 大小写均可)
)

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

func (p Policy) DigestKeyed() bool

DigestKeyed 该快照是否已注入摘要密钥(StrategyHash 的接线期自查口径)。

func (Policy) Enabled added in v0.43.0

func (p Policy) Enabled() bool

Enabled 该快照的全局开关。

func (Policy) Gen added in v0.43.0

func (p Policy) Gen() uint64

Gen 该快照的代次(订阅者据此断言单调:后收到的快照代次不得更小)。

func (Policy) Strategy added in v0.43.0

func (p Policy) Strategy() StrategyKind

Strategy 该快照的处置策略。

func (Policy) SurfaceEnabled added in v0.43.0

func (p Policy) SurfaceEnabled(s Surface) bool

SurfaceEnabled 该快照中指定面是否启用。

func (Policy) Surfaces added in v0.43.0

func (p Policy) Surfaces() SurfaceSet

Surfaces 该快照的面集合。

type Span

type Span struct {
	Kind  Kind
	Start int
	End   int
}

Span 一段命中(s 的字节偏移,[Start,End))。

func Detect

func Detect(s string) []Span

Detect 找出 s 中全部 PII span(已完成语义校验与边界判定,重叠时保留更长者)。 返回按 Start 升序、互不重叠,偏移是**原串字节偏移**。

匹配前先做数字形态归一化(全角 → 半角、去零宽、折叠数字间的分组分隔符, 口径见 normalize.go),再把命中映射回原串。归一化与处置共用同一条路径: Apply 打码、StrategyHash 摘要都按归一化后的值计算,同一值的不同书写形态 因此得到同一处置形态与同一摘要。

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"
)

func Strategy

func Strategy() StrategyKind

Strategy 当前处置策略。

type Subscription

type Subscription uint64

Subscription 订阅句柄,传给 Unsubscribe 注销。0 表示无效。

func Subscribe

func Subscribe(fn func(Policy)) (Subscription, error)

Subscribe 登记一个处置策略变更订阅者,返回句柄与是否成功。

为什么注册完立刻回调一次当前快照

不这么做,订阅者对「现在生效的是什么」一无所知,要等到下一次变更才知道。策略注入 的典型形态恰恰是「注册完之后很久没有下一次变更」,于是订阅者带着一个从没填过的 视图上线——比没有订阅更危险,因为它以为自己已经跟上了。

立即回调与登记的次序:可合并,但绝不漏掉一代

立即回调先于登记执行(此时本订阅者还不在通知名单里,绝不会与并发通知交错), 登记后再读一次当前快照:若这段时间里发生过变更,再补投一次最新的那一代。 登记之后发生的变更由 notifyPolicy 正常送达。于是「取快照 → 登记」窗口内的 变更不会漏,而并发变更可能**合并**为最新一代(单调投递门的选择,见文件头)。

立即回调同样在锁外调用、panic 同样被 recover,与变更通知完全一致。

type Surface

type Surface string

Surface 敏感面。

const (
	// SurfaceInput 进入模型前的外部输入(用户消息、抓取正文、命令输出)。
	SurfaceInput Surface = "input"
	// SurfaceOutput 模型产出(给人看的)。
	SurfaceOutput Surface = "output"
	// SurfaceToolResults 工具返回——独立成面的理由:它会被回灌进下一轮上下文,
	// 泄漏路径与「给人看」完全不同,用同一处置无法同时满足两边。
	SurfaceToolResults Surface = "tool_results"
)

type SurfaceSet

type SurfaceSet uint8

SurfaceSet 面集合(位集合)。

func ParseSurfaces

func ParseSurfaces(names ...string) (SurfaceSet, error)

ParseSurfaces 由宿主配置解析面集合(未知面名报错,不静默丢弃)。

func SurfaceBit

func SurfaceBit(s Surface) (SurfaceSet, error)

SurfaceBit 单个面在集合中的位。

func Surfaces

func Surfaces() SurfaceSet

Surfaces 当前面集合。

func (SurfaceSet) Has

func (ss SurfaceSet) Has(s Surface) bool

Has 该集合是否含指定面。

Jump to

Keyboard shortcuts

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