Skip to content

Commit 8e28601

Browse files
committed
feat(admission): 写入边界的密钥/PII 判据(#164 A2 → #254 第 1 级)
判据独立成 src/sensitive-scan.js:纯确定性、零 LLM,先认形状再认关键词。写入准入 (#332 就留好的 sensitiveScan 注入点)从此拿到真判据,审计位不变 (metadata.deny.reason='sensitive' + kind/label)。 自己的闸是顶层键 sensitiveScanEnabled(默认关):与 writeAdmission.enabled 分开, 两批判据的误杀面差一个量级,绑一个开关上就没法单独看 A2 的命中分布。命中之后是仅 告警还是真拦仍由 enforce 决定(#164 口径:默认仅告警、拦截 opt-in),判据不碰决策。 假阳率按 09-28 的口径由那 12 条负样本定:26 条语料原样跑,正样本不漏、负样本不误杀。 实现期额外探针另修了一处漏放(AWS secret access key 无前缀,多词键够不着关键词规则)。
1 parent 6283ee9 commit 8e28601

15 files changed

Lines changed: 678 additions & 15 deletions

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## [Unreleased]
4+
5+
## 🆕 新增
6+
7+
- **写入边界的密钥 / PII 判据(`sensitiveScanEnabled`,默认关)**:写入准入(#254 第 1 级)此前只跑空白 / 噪声两类判据,密钥 / PII 那一档按设计留了注入点而没实现。现在补上 `src/sensitive-scan.js`——纯确定性、零 LLM,先认形状再认关键词(赋值型规则带占位符守卫,所以「把 API key 放进环境变量」这类讨论句不报)。命中落审计 `metadata.deny.reason='sensitive'` + `kind`(密钥 / PII 分档,便于先看分布再决定放行策略),审计位与 #332 定的形状一致。开关分层:本键只决定「这类判据参不参与」,命中之后是仅告警还是真拦仍由 `writeAdmission.enforce` 决定(默认仅告警、拦截 opt-in)。回归样本集(10 条密钥 + 4 条 PII 正样本、12 条负样本)原样跑真判据:正样本不漏、负样本不误杀。
8+
39
## [0.8.12] - 2026-10-01
410

511
## 🐛 修复

‎dsh-mneme/lib/api.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
143143
"llmAudit.enabled": ["llmAudit", "enabled"],
144144
"writeAdmission.enabled": ["writeAdmission", "enabled"],
145145
"writeAdmission.enforce": ["writeAdmission", "enforce"]
146+
// sensitiveScanEnabled(#164 A2)是顶层扁平键,不需要进这张表——走 configFlagValue
147+
// 的默认分支即可。
146148
};
147149
function configFlagValue(key) {
148150
const path = NESTED_FLAG_PATHS[key];

‎dsh-mneme/lib/client.js‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -493,6 +493,10 @@ window.__ModuleLoader__.load({
493493
"memory.features.writeAdmission.enabled.hint": "写入前判空白/噪声,命中留审计(不拦)",
494494
"memory.features.writeAdmission.enforce": "写入准入拦截",
495495
"memory.features.writeAdmission.enforce.hint": "真拦下命中的写入;关闭时只留审计不拦",
496+
// #164 A2:密钥/PII 判据自己的闸。文案要写清它管的是哪一批判据(与上面的
497+
// 空白/噪声分开),以及「开着也不拦」——拦是上面那项的事。
498+
"memory.features.sensitiveScanEnabled": "密钥/PII 扫描",
499+
"memory.features.sensitiveScanEnabled.hint": "写入前扫密钥与个人信息;命中只留审计,真要拦需同时打开写入准入拦截",
496500
"memory.features.bm25SearchEnabled": "BM25 关键词检索",
497501
"memory.features.bm25SearchEnabled.hint": "传统关键词打分检索,与向量召回互补",
498502
"memory.features.conflictFreezeEnabled": "冲突冻结",
@@ -925,6 +929,11 @@ window.__ModuleLoader__.load({
925929
"memory.features.writeAdmission.enabled.hint": "Flag blank / noise writes before storing, with an audit row (never blocks)",
926930
"memory.features.writeAdmission.enforce": "Write admission enforcement",
927931
"memory.features.writeAdmission.enforce.hint": "Actually reject flagged writes; off keeps the audit row only",
932+
// #164 A2 — its own gate for the secret / PII rules (separate from the
933+
// blank/noise pair above). On its own it only records an audit row;
934+
// enforcement stays with the key above.
935+
"memory.features.sensitiveScanEnabled": "Secret / PII scan",
936+
"memory.features.sensitiveScanEnabled.hint": "Scan writes for credentials and personal data; hits are audited only — enforcement needs write admission enforcement too",
928937
"memory.features.bm25SearchEnabled": "BM25 keyword search",
929938
"memory.features.bm25SearchEnabled.hint": "Classic keyword scoring, complementary to vector recall",
930939
"memory.features.conflictFreezeEnabled": "Conflict freezing",
@@ -2122,7 +2131,7 @@ window.__ModuleLoader__.load({
21222131
// test/inject-parent-gate.test.js 钉住。
21232132
const FEATURE_CHILDREN = { autoInject: ["injectGuidanceEnabled", "continuityRescueEnabled"] };
21242133
const FEATURE_GROUPS = [
2125-
{ key: "group.core", items: ["autoInject", "autoSummarize", "hotMemoryEnabled", "injectTimePrefix", "memoryQualityFilter.enabled", "llmAudit.enabled", "writeAdmission.enabled", "writeAdmission.enforce"] },
2134+
{ key: "group.core", items: ["autoInject", "autoSummarize", "hotMemoryEnabled", "injectTimePrefix", "memoryQualityFilter.enabled", "llmAudit.enabled", "writeAdmission.enabled", "writeAdmission.enforce", "sensitiveScanEnabled"] },
21262135
{ key: "group.enhance", items: ["entityExtractionEnabled", "codingRetrospect", "rerankEnabled", "resilientModelDownload", "searchSemanticDedup", "bm25SearchEnabled", "heatEnabled", "documentMemoryEnabled"] },
21272136
{ key: "group.dream", items: ["autoDream", "sleepModeEnabled"] },
21282137
// v0.8.0 A4(issue #17):作用域隔离组——标注总开关 + 严格硬过滤。

‎dsh-mneme/lib/config.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -651,6 +651,22 @@ export const Config = z.object({
651651
enforce: z.boolean().default(false)
652652
}).default({}),
653653

654+
// --- #164 A2: secret / PII scan at the write boundary ----------------------
655+
// 写入边界的密钥 / PII 判据(src/sensitive-scan.js)自身的闸。与 writeAdmission
656+
// 的 enabled 分开是有意的:那一个管 #254 第 1 级的空白 / 噪声判据,本键管 A2 这
657+
// 一类判据,两批的误杀面差一个量级(空白 / 噪声没有解释空间,邮箱 / 手机号有),
658+
// 绑在同一个开关上就没法单独观察 A2 的命中分布。
659+
//
660+
// 默认关 = 只计量那一阶段的行为逐字节保留(#332 合并时 sensitiveScan 就是 null)。
661+
// 打开后最狠也只是「仅告警」:命中落一条审计(metadata.deny.kind)但照常写入,
662+
// 真要拦得同时打开 writeAdmission.enabled + writeAdmission.enforce。#164 的口径
663+
// 就是这一句——「默认仅告警、拦截 opt-in」——所以本键与 enforce 配合使用:
664+
// sensitiveScanEnabled 关 → 这一类判据整个不参与
665+
// sensitiveScanEnabled 开 + enforce 关 → 命中留审计,写入照常(观察档)
666+
// sensitiveScanEnabled 开 + enforce 开 → 命中即拒绝
667+
// 也走 feature_flags(FEATURE_FLAG_BOOLEANS 白名单),面板可启停=线上回滚开关。
668+
sensitiveScanEnabled: z.boolean().default(false),
669+
654670
// --- recall evaluation: test-result storage (v0.4.6, 方案 B) --------------
655671
// Separate retrieval evaluation snapshots from the production recall audit.
656672
// When false (default) evaluateRetrieval still computes precision/recall/mrr

‎dsh-mneme/lib/index.js‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ import { resolveDocumentDir } from "./document.js";
55
import { createService } from "./service.js";
66
// #254 写入准入(第一阶段只计量,不拦截):见 src/write-admission.js 的文件头。
77
import { createWriteAdmission } from "./write-admission.js";
8+
// #164 A2:写入边界的密钥 / PII 判据,注入给上面的写入准入。
9+
import { createSensitiveScan } from "./sensitive-scan.js";
810
import { createTools } from "./tools.js";
911
import { createInjector } from "./inject.js";
1012
import { createContinuityRescue } from "./continuity.js";
@@ -278,11 +280,17 @@ export const apply = (ctx, config) => {
278280
// 关掉,在无保留期的表里按写入频次增长是不能接受的)。
279281
//
280282
// sensitiveScan 是密钥 / PII 那一类判据的注入点。按 #254 验收第 4 条它是 #164 A2
281-
// 的判据来源(A2 记在维护者排期里),所以本批不实现它,只把接口形状定在这里——
282-
// 接上时只改这一行:
283-
// createWriteAdmission({ ..., sensitiveScan: createSensitiveScan({ config: cfg }) })
284-
// 缺省 null 时第 1 级只跑空白 / 噪声两类判据,其余一切照旧。
285-
const writeAdmission = createWriteAdmission({ store, config: cfg, logger: ctx.logger });
283+
// 的判据来源,现在由 src/sensitive-scan.js 实现(维护者 09-28 把 A2 的认领转给
284+
// 本侧)。这里只做接线:判据开不开由它自己的键 sensitiveScanEnabled 决定,工厂在
285+
// 关时返回 null,闸门的行为就与 #332 合并时逐字段一致(那一版根本没有这个函数);
286+
// 命中之后是仅告警还是真拦,仍是 writeAdmission.enforce 的事(#164 口径:
287+
// 默认仅告警、拦截 opt-in),判据不碰决策。
288+
const writeAdmission = createWriteAdmission({
289+
store,
290+
config: cfg,
291+
logger: ctx.logger,
292+
sensitiveScan: createSensitiveScan({ config: cfg })
293+
});
286294
const service = createService({ store, mirror, config: cfg, logger: ctx.logger, documentIndex, writeAdmission });
287295

288296
// F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry

‎dsh-mneme/lib/sensitive-scan.js‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
// #164 A2:写入边界的密钥 / PII 判据。判据来源是 #164 A2(维护者 09-28 把认领转给
2+
// 本侧),消费方是 #254 的写入准入——`write-admission.js` 从 #332 起就留了
3+
// `sensitiveScan` 注入点,本模块是那个占位的实现。
4+
//
5+
// 为什么判据独立成文件、不写进 write-admission.js:判据的归属是 #164 A2,闸门的归属
6+
// 是 #254。闸门只消费 `{kind, label}`(deny 面已在 #332 定死),判据自己既不认识
7+
// 「会话预算」也不认识 `llm_audit_logs`——换一个判据(比如将来接更重的 PII 分类器)
8+
// 只换注入的那一行。写入边界的另外两个出口(autoSummarize / dream 输出)要复用同一份
9+
// 判据时也直接 import 本模块的 `scanSensitive`,不必各写一套形状。
10+
//
11+
// 三条判据口径(前两条是 #254 已定的硬约束,第三条是本模块自己的):
12+
//
13+
// 1. 零 LLM、纯确定性。写入路径在最上游,这里多花的时间会乘上每一次写入;EdgeMem
14+
// (2609.05553)那句「能不用模型判定就不用」说的就是这一层。
15+
//
16+
// 2. 假阳率由负样本定。`test/helpers/write-admission-samples.js` 的 12 条负样本是
17+
// #332 就配好的验收面,维护者把话说死了:「同一套负样本原样跑,抓错任何一条就不
18+
// 算落地」。所以本模块的形状是**先认形状再认关键词**——纯关键词匹配在那组负样本
19+
// 上全军覆没(「把 API key 放进环境变量」这类讨论句里一个凭据值都没有)。
20+
//
21+
// 3. 报最严重的那一类(`kind` 落审计)。同一个字符串可能同时像两类(`sk_live_` 前缀
22+
// 既是 Stripe 的形状、也能被通用的 `sk-` 规则吃下),所以规则表按「越具体越靠前」
23+
// 排,命中即返回。密钥在前、PII 在后:两者误杀面差一个量级(密钥串出现在正常项目
24+
// 记忆里就是事故,邮箱 / 手机号完全可能是正当内容),同时命中时报更严重的那一类。
25+
// `kind` 是稳定判据键(不是展示文案),enforce 打开前先按它看分布,将来要按类放行
26+
// 也只改策略、不动判据。
27+
//
28+
// 已知边界(都是「宁漏不误杀」的取舍,不是遗漏):
29+
// - 只扫文本(title / content / tags)。不扫路径、id、时间戳这类元数据字段——它们
30+
// 由系统生成,不是用户写进来的内容,扫它们只会引入假阳。
31+
// - 中文关键词(密码 / 令牌)不认。补进去会让「密码必须脱敏后再入库」这类讨论句
32+
// 命中,而那正是负样本 group 的形状。要覆盖中文赋值得先设计「关键词语种 × 值形状」
33+
// 的两维判据,不在本批。
34+
// - 手机号只认大陆移动号段(1[3-9] + 9 位),固定电话与带国家码的写法不认。宽一位
35+
// 就会把长度相近的订单号 / 内部编号吃进来,而 PII 这一档的误杀面已经比密钥大一档。
36+
// - 银行卡号加 Luhn 校验:`0000000000000000`、`4111111111111112` 这类形状对但校验
37+
// 不过的串不报。少了这道校验,任何 16 位数字串(订单号、时间戳拼接)都会命中。
38+
//
39+
// 归一化:这里**不**用 content-hash.js 的 normalizeForHash。那套口径(NFKC → 小写 →
40+
// 去标点)是为「只差格式的两条写入是否同一件事」定的,判据要的是原串的形状——大小写
41+
// 是密钥 alphabet 的一部分(`AKIA` 与 `akia` 不是同一个值),去掉 `-` / `_` 会把 JWT
42+
// 与 Slack token 的分段结构一起折没。两个口径别互换。
43+
44+
/** 判据命中的返回形状(与 `createWriteAdmission` 的 sensitiveScan 契约一致)。 */
45+
// kind 是稳定键、label 是给人看的一行说明;两者都落 llm_audit_logs 的
46+
// metadata.deny,所以别在其中塞运行时的值(命中的凭据本身绝不落盘 / 不回显)。
47+
const SECRET_RULES = [
48+
{ kind: "aws_access_key", label: "AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
49+
// AWS 的 secret access key 没有前缀,只能靠赋值键认:`AWS_SECRET_ACCESS_KEY` /
50+
// `aws_secret_access_key` 这个键名是它的形状。最早的一批 `secret` 关键词规则被
51+
// 「必须在赋值号前」的位置要求挡在外面(多词键里 `secret` 后面跟的是 `_`,不是
52+
// `:`/`=`),所以它得单独一条。40 位下限取 AWS 官方密钥的固定长度。
53+
{
54+
kind: "aws_secret_key",
55+
label: "AWS secret access key",
56+
// 键名不分大小写,所以挂 `/i` 而不是行内修饰符组 `(?i:...)`:后者是 ES2025 语法,
57+
// CI 矩阵里的 Node 22 直接抛 SyntaxError(本文件其余规则也没有用它的)。
58+
// 值那一半本来就是 `[A-Za-z0-9/+=]`,带上 `/i` 不改变大小写敏感度。
59+
re: /(?:aws[_-]?secret[_-]?access[_-]?key)\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])/i
60+
},
61+
{ kind: "github_token", label: "GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/ },
62+
{ kind: "slack_token", label: "Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
63+
// PEM 头是明文私钥的确定标志,带不带正文都一样判——`BEGIN` 与 `PRIVATE KEY` 之间
64+
// 可能有 `RSA` / `EC` / `OPENSSH`,所以中间那段是 [A-Z ]*。
65+
{ kind: "private_key", label: "PEM private key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
66+
{ kind: "jwt", label: "JSON Web Token", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
67+
{ kind: "connection_string", label: "credentials in URL", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/:@]{6,}@/ },
68+
// Stripe 排在通用 `sk-` 之前:`sk_live_…` 两条规则都吃,先到的那条决定 kind。
69+
// 只认 sk_live_(生产密钥):sk_test_ 是公开测试密钥,报它是纯误杀。
70+
{ kind: "stripe_key", label: "Stripe secret key", re: /\bsk_live_[A-Za-z0-9]{16,}\b/ },
71+
{ kind: "npm_token", label: "npm auth token", re: /_authToken\s*=\s*[A-Za-z0-9_-]{20,}/ },
72+
// 下限 24 而不是 20:这是一条纯收紧、不动语料读数的加固——OpenAI 的 key 没有校验
73+
// 位,前缀 + 长度是唯一形状,20 位会把更长的假阳性面留在表里。`sk-` 后面跟短串的
74+
// 赋值句仍会被赋值型那条认下(那是**对的**:值长了 8 位以上就该报)。
75+
{ kind: "openai_key", label: "OpenAI API key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b/ },
76+
{
77+
// 赋值型:最常见的一类,也是负样本组(占位符 / 环境变量 / 模板变量 / 只提关键词)
78+
// 的主要靶子。判据是「关键词 + 赋值号 + 右边真的是个值的形状」,值本身不校验
79+
// alphabet——凭据值没有通用形状,能通用的只有「它不像占位符」。
80+
kind: "assigned_secret",
81+
label: "assigned credential literal",
82+
re: /(?:^|[^A-Za-z0-9_])(?:password|passwd|pwd|secret|api[_-]?key|token)\b\s*[:=]\s*["']?([^\s"']{8,})/i,
83+
// 占位符守卫:右边是尖括号占位、shell / 模板变量、环境变量读取、或一串 x / * / …
84+
// 时不算命中。少这道守卫,`password: <redacted>` 与 `token: ${TOKEN}` 都会被报,
85+
// 而它们正是「配置里该怎么写」的示例文本。
86+
guard: (value) => !/^(?:<[^>]*>|\$\{|\$[A-Z_]+$|process\.env|redacted|xx+|\*+|\u2026)/i.test(value)
87+
}
88+
];
89+
90+
const PII_RULES = [
91+
{
92+
kind: "email",
93+
label: "email address",
94+
// 先看 TLD 再看 `@`:反过来的 `(?:[A-Za-z]{2,}\.)+[A-Za-z]{2,}` 对
95+
// `[email protected]` 这类可以回溯出指数条路径。
96+
re: /\b[A-Za-z0-9._%+-]+@(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}\b/
97+
},
98+
{ kind: "cn_mobile", label: "mainland mobile number", re: /(?<!\d)1[3-9]\d{9}(?!\d)/ },
99+
{ kind: "cn_id_card", label: "mainland ID number", re: /(?<![0-9A-Za-z])\d{17}[\dXx](?![0-9A-Za-z])/ },
100+
{ kind: "bank_card", label: "payment card number", re: /(?<!\d)(?:\d{13,19})(?!\d)/, luhn: true }
101+
];
102+
103+
/**
104+
* Luhn(模 10)校验。银行卡号这一档只靠位数与首字符形状会把所有 13–19 位数字串
105+
* 都吃进来,而项目记忆里长度差不多的数字串(订单号、拼接的时间戳)很常见;校验位
106+
* 是卡号自带的、零成本的第二道形状。负样本里没有卡号形状的串,这道校验是防未列举
107+
* 的那一类(同时它也不影响正样本:4111111111111111 是 Luhn 通过的公开测试卡号)。
108+
* @param {string} value 归一后的数字串(可能含分隔符)
109+
*/
110+
function passesLuhn(value) {
111+
const digits = value.replace(/\D/g, "");
112+
if (digits.length < 13 || digits.length > 19) return false;
113+
let sum = 0;
114+
let double = false;
115+
for (let i = digits.length - 1; i >= 0; i--) {
116+
let d = digits.charCodeAt(i) - 48;
117+
if (double) {
118+
d *= 2;
119+
if (d > 9) d -= 9;
120+
}
121+
sum += d;
122+
double = !double;
123+
}
124+
return sum % 10 === 0;
125+
}
126+
127+
/**
128+
* 扫一段文本里的密钥 / PII。命中返回 `{kind, label}`、未命中返回 null,不抛。
129+
*
130+
* 只认第一处命中(按规则表顺序 = 严重度顺序)。一次写入里出现第二条凭据时不再报——
131+
* deny 面只记判据类别,报多条只是把同一件事写几遍。
132+
* @param {unknown} value
133+
* @returns {{kind: string, label: string}|null}
134+
*/
135+
export function scanSensitive(value) {
136+
const text = typeof value === "string" ? value : String(value ?? "");
137+
if (!text) return null;
138+
for (const rule of [...SECRET_RULES, ...PII_RULES]) {
139+
const match = text.match(rule.re);
140+
if (!match) continue;
141+
// 守卫只看捕获组:没有捕获组的规则天然没有守卫。
142+
if (rule.guard && !rule.guard(match[1] ?? "")) continue;
143+
if (rule.luhn && !passesLuhn(match[0])) continue;
144+
return { kind: rule.kind, label: rule.label };
145+
}
146+
return null;
147+
}
148+
149+
/**
150+
* 判据的两种调用面,共用同一份规则表:
151+
* `scanSensitive(text)` — 任意文本,给写入边界之外的消费方(autoSummarize /
152+
* dream 输出)直接调;它们手里是文本,不是记忆行。
153+
* `createSensitiveScan({config})` — `write-admission.js` 的 `sensitiveScan` 契约,
154+
* 入参是记忆对象、返回 `{kind, label}` 或 null。
155+
*
156+
* 开关在工厂里判一次:`sensitiveScanEnabled` 关时返回 null,闸门侧连函数都拿不到,
157+
* 于是「第 1 级只跑空白 / 噪声」这条路与 #332 合并时**逐字段一致**(那一版根本没有
158+
* 这个函数)。这个键是 A2 自己的闸,不是 writeAdmission.enabled 的子开关——A2 落在
159+
* 写入边界(#164 的措辞是「默认仅告警、拦截 opt-in」),与 #254 第 1 级的空白 / 噪声
160+
* 是两批判据,不该被同一个开关绑死。
161+
*
162+
* @param {{config?: object}} [deps]
163+
* @returns {((memory: object) => ({kind: string, label: string}|null))|null}
164+
*/
165+
export function createSensitiveScan({ config } = {}) {
166+
if (config?.sensitiveScanEnabled !== true) return null;
167+
const scan = (memory) => {
168+
const text = [memory?.title, memory?.content, ...(Array.isArray(memory?.tags) ? memory.tags : [])]
169+
.filter((s) => typeof s === "string")
170+
.join("\n");
171+
return scanSensitive(text);
172+
};
173+
// 工厂只认「开 / 关」;enforce 由 write-admission 决定(命中即 deny 还是仅告警),
174+
// 判据自己不碰决策——那一步在闸门里。两层分开就能先开检测看分布、再开拦截。
175+
return scan;
176+
}

0 commit comments

Comments
 (0)