desensitize —— 请求体 / 查询串脱敏
审计中间件要把"这次请求改了什么"记进
sys_operation_log,那两张列是request_body TEXT -- 脱敏后与response_summary TEXT。 desensitize 负责把明文变成能入审计表的文本。
功能
desensitize 提供两组能力:
- 按类型脱敏(调用方知道这个字段是什么类型)
Phone/IDCard/Name/Email/BankCard/ContractNo
- 按字段名脱敏(调用方不知道结构 —— 请求体是结构未知的 JSON)
IsSensitiveKey—— 判断字段名要不要遮RedactJSON—— 递归遍历 JSON,命中的字段值替换成***RedactQuery—— query string 用同一份词表脱敏
外加盲索引:PhoneHash / IDCardHash —— 不可逆但可做"完全相等"查询。
不解决什么:不判断"这次请求该不该带这个字段"(那是业务的事);不写审计表
(那是 middleware.Audit() 与 piiaudit);不加密 ——
加密是 crypto 的事。
配置
该包无 yaml 配置块 —— 它是纯函数包,没有构造器、没有配置结构体。
唯一与配置相关的是盲索引 key 的来源,这是一条代码侧的优先级链
(desensitize.BlindKeySource() 可查当前用的是哪个):
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | crypto.blind_key(crypto.Blind()) |
唯一正解,见 crypto |
| 2 | 环境变量 PHONE_HASH_KEY(≥16 字节) |
兜底 |
| 3 | dev 占位常量 | ⚠️ 写在仓库里 = 公开的,只限本地开发 |
使用方法
按类型脱敏
desensitize.Phone("13800001234") // 138****1234
desensitize.IDCard("110101199001011234")// 1101**********1234
desensitize.Name("张伟丰") // 张*丰
desensitize.Email("zhangwei@example.com")// z*******@example.com
desensitize.BankCard("6222021234567890123")
desensitize.ContractNo("HT20261101000123")
盲索引
desensitize.PhoneHash("13800001234") // HMAC-SHA256 hex
desensitize.IDCardHash("110101199001011234")
审计采集端(主要用途)
// 请求体
body, ok := desensitize.RedactJSON(raw)
// ok=false ⇒ 不是合法 JSON,调用方不要把原文写进审计表
// query string
qs := desensitize.RedactQuery(c.Request.URI().QueryString())
判断单个字段
desensitize.IsSensitiveKey("user_phone") // true
desensitize.IsSensitiveKey("order_id") // false
注意事项
- ⚠️ 脱敏词表是"宁可多遮"的子串匹配。
token_count、email_flag这类无害字段 会被误伤(只是审计记录少一个数字);漏遮一个password就是明文落库。 - ⚠️
code/key/name/address/sign刻意不在词表里。 遮蔽code等于把审计记录废掉(业务错误码 / 字典码);key太泛 (idempotency_key/cache_key都会被误伤);name/address是业务内容 —— 审计日志要回答的是"谁、什么时候、把哪个用户的什么字段改成了什么",全遮成***谁也查不出问题。验证码另用sms_code/captcha_code/verify_code精确匹配。 - ⚠️
RedactJSON的第二个返回值是"是否成功解析",不是"有没有改动"。解析失败 返回("", false)—— 调用方绝不能把原文写进审计表(本仓约定写"<非 JSON, N 字节>")。 - ⚠️ 非 JSON 一律
ok=false。尾部还有内容({}{})也判无效。 - ⚠️ 数字用
json.Number保留原文。sonyflake 是 19 位整数,float64 只能保 15~16 位有效数字 —— 不开UseNumber的话审计记录里的 ID 会变成1.2345678901234568e+18,和库里对不上。 - ⚠️ 有上限:深度 8 层 / 数组 50 项(超出丢并标注
<超出条数上限>)/ 单字符串 200 字符 / 总体积 4096 字节。截断时按 rune 切,不劈开 UTF-8(直接s[:n]会切出 半个字符 ⇒ 非法 UTF-8 ⇒ JSON 编码成U+FFFD乱码)。 - ⚠️ 太短的串原样返回。
Phone< 7 位、IDCard< 8 位、BankCard< 8 位、ContractNo< 6 位 ⇒ 直接返回原文(盖了等于全没了)。别把"原样返回"当漏洞 —— 那些长度的值本来就不是合法的对应类型。 - ⚠️
maskMiddle在"藏不住 1/3"时改用首尾各 1/4。标准切法(手机 3+4 / 身份证 4+4 / 银行卡只留尾 4)只在藏得住 ≥ 1/3 时用,否则Phone("1234567")会变成"123****4567"—— 看着打了码,一个字没藏。 - ⚠️
Name两字时输出张*(以前Repeat("*", n-2)= 0 个星号 ⇒ 原样返回, 等于完全没脱敏);≥ 3 字时是"首字 + n-2 个星号 + 尾字"。 - ⚠️
Email按 rune 切。以前按字节切,local-part 首字符是多字节(中文 / 带音标 字母)时切出半个字符 ⇒ 输出非法 UTF-8,json.Marshal编码成U+FFFD乱码。 - ⚠️
desensitize.PhoneHash不做归一化。它直接调crypto.Blind().Compute()—— 而归一化在另一个方法crypto.BlindIndex.ComputeNorm里。所以"138 0000 1234"与"13800001234"算出不同的索引 ⇒ 按phone_hash查用户时手机号带空格就查不到。 建索引与查询两侧必须用同一个方法。 - ⚠️ dev 占位 key 是公开的。
BlindKeySource()返回"dev-placeholder"⇒ 生产环境这是事故:盲索引等于明文哈希,拿到库的人算一遍就能反查手机号。 启动日志要对这个值对账。 - ⚠️ 换 key ⇒ 已有的
phone_hash/real_name_hash/email_hash全部失效 (索引是对明文的派生值,key 一变就对不上)。dev 库里运行时创建的数据需要重灌种子。 - ⚠️ 本包自带的
README.md与源码不一致:README 函数清单里写的NameHash/MaskByRule/ToOwnerViews在源码里不存在。以源码为准。
相关
- 源码:
internal/pkg/desensitize/ - 可运行示例:
examples/desensitize/main.go——go run ./examples/desensitize - 盲索引的密钥从 crypto 借 → crypto
- PII 访问审计(谁看了完整手机号)→ ../audit/piiaudit.md