progmune-runtime 3.7.36 → 3.7.37

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [3.7.37] — 2026-09-19
+
+### G2：自定义校验函数的调用点抑制（判别力）
+
+缺口实证（taintpath_B `dispatchToolGuarded`，measured）：
+
+```ts
+assertTemplateName(args.name);   // 函数体内是 /^[A-Za-z0-9_-]+$/ —— 真校验
+return loadTemplate(args.name);  // 仍被标记（误报）
+```
+
+`assertTemplateName` 名字不含路径语义后缀——`Name` 在修 `ensureDir()` 误判时被
+整体移出了 G-C 后缀表，于是调用点侧认不出来。这是 G1 收紧词表的已知代价。
+
+修法**不是**把 `Name` 加回词表（那是按名字猜语义，G-C 已经为这份宽松付过代价：
+fr-007 pre 侧召回归零），而是看**被调用方函数体内到底有没有校验证据**：
+
+- `pathGuardFunctionNames` 拆两档：tier-0 `direct`（自身含证据）/ tier-1+ `all`（推断）
+- `collectSanitizedExprs`：被调用方属 tier-0 ⇒ 把调用实参里的取值表达式收进
+  「已净化」集合；sink 实参命中污点但已被净化 ⇒ 不算污点
+
+### 三处精度取舍（全部比 G1 的函数级 selfGuarded 窄）
+
+| 取舍 | 说明 |
+|---|---|
+| 表达式级，非函数级 | G1 是一个校验词汇压掉整个函数体的所有流；G2 只净化被传进守卫调用的那个表达式，同函数体里另一条未校验的流仍标记 |
+| 只认 tier-0 | 推断出来的守卫不用于抑制 —— 升为方法学规则 **R9-no-inferred-suppression**（抑制不可逆，压掉的真阳性不会出现在任何回归统计里） |
+| 前缀 `(?:^\|[^\w$.])` | 净化 `name` 不连坐 `other.name`；但 `args.name` 能命中 `path.join(DIR, args.name)` |
+
+### 验收
+
+- taintpath 闸门 **24/24**（`dispatchToolGuarded` mark → suppressed；正对照
+  `dispatchToolBare` 仍 mark）
+- **fr-007 openhop 真实语料维持 pre 5 / post 0** —— G2 未压掉真阳性
+- TS 盲测（102 项目）：**LOST 1 / ADDED 0**，唯一变化就是本条；覆盖力 19 → 18
+- `extract-ir-taint-guard.test.ts` 新增 G2 组 6 条（含正/负对照，R6）
+- 反向验证：回退 v3.7.36 后 G2 两条正例失败，其余 18 条仍绿
+- 新增 `blind-benchmark/check-fr-corpus.ts` —— 把 fr-007 的 pre/post 复测固化成
+  一条命令；快照置于 `blind-benchmark/fr-corpus/`（**受保护资产**，不再放 /tmp）
+
+### 已知缺口 G2b
+
+经项目自有 helper 转手的校验证据不生效（`checkName(n)` 内部再调守卫函数）——
+只认 tier-0 的代价，与 C4b 同族。缺口是可见的（仍有误报），压掉的真阳性不可见。
+
 ## [3.7.36] — 2026-09-19
 
 ### C4：污点经路径塑形表达式包装后仍传播

package/dist/extract-ir-taint-guard.test.js

@@ -356,6 +356,157 @@ export function read(req: any) {
         }
     });
 });
+(0, vitest_1.describe)("G2：调用点抑制 —— 按被调用方的实际证据定案（种子=taintpath_B assertTemplateName）", () => {
+    // 缺口形态（2026-09-19 measured，taintpath_B dispatchToolGuarded）：
+    //   `assertTemplateName(args.name); return loadTemplate(args.name);`
+    // `assertTemplateName` 函数体内是锚定字符集白名单（G-D），是真校验，
+    // 但它的名字不含路径语义后缀 —— `Name` 在修 `ensureDir()` 误判时被整体
+    // 移出了 G-C 守卫后缀表，于是调用点侧认不出来，仍被标记。
+    //
+    // G2 的修法不是把 `Name` 加回词表（那是按【名字】猜语义，G-C 已经为这份
+    // 宽松付过一次代价：fr-007 pre 侧召回归零），而是看**被调用方函数体内
+    // 到底有没有校验证据**。
+    //
+    // 精度取舍：净化作用在【表达式】上，不是整函数 —— 同函数体里另一条未被
+    // 校验的流仍会标记。这是 G2 相对 G1（函数级 selfGuarded）的收窄。
+    const body = (guardCall) => `
+import * as fs from "fs";
+export function read(req: any) {
+  const name = req.params.name;
+${guardCall}  return fs.readFileSync("/data/" + name, "utf-8");
+}
+function assertTemplateName(name: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error("bad template name");
+}
+`;
+    (0, vitest_1.it)("正对照：去掉自定义校验调用后必须标记", () => {
+        const dir = makeProject({ "a.ts": body("") });
+        try {
+            (0, vitest_1.expect)(marksFor(dir, "read")).toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("自定义校验函数（名字不含路径语义后缀）被调用 → 不得标记", () => {
+        const dir = makeProject({ "a.ts": body("  assertTemplateName(name);\n") });
+        try {
+            (0, vitest_1.expect)(marksFor(dir, "read")).not.toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("负对照：被调用方体内**没有**校验证据时，调用它不得抑制（不能见调用就净化）", () => {
+        const dir = makeProject({
+            "a.ts": `
+import * as fs from "fs";
+export function read(req: any) {
+  const name = req.params.name;
+  logIt(name);
+  return fs.readFileSync("/data/" + name, "utf-8");
+}
+function logIt(x: string): void { console.log(x); }
+`,
+        });
+        try {
+            (0, vitest_1.expect)(marksFor(dir, "read")).toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("表达式级净化：同函数体里另一条未被校验的流仍要标记", () => {
+        // G1 的函数级 selfGuarded 会把整个函数体一起静默；G2 只净化真正被传进
+        // 守卫调用的表达式 —— 这条用例锁住这个差别。
+        const dir = makeProject({
+            "a.ts": `
+import * as fs from "fs";
+export function read(req: any) {
+  const name = req.params.name;
+  const other = req.params.other;
+  assertTemplateName(name);
+  fs.readFileSync("/data/" + name, "utf-8");
+  return fs.writeFileSync("/data/" + other, "x");
+}
+function assertTemplateName(name: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error("bad template name");
+}
+`,
+        });
+        try {
+            (0, vitest_1.expect)(marksFor(dir, "read")).toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("跨函数（taintpath_B 形态）：净化只发生在调用点，被调用方定义照旧被反标", () => {
+        // 语料里 `loadTemplate` 自身不含任何不可信根，它被标记是因为调用点命中了
+        // 跨函数一跳（onMethodHit 反标）。故本用例在同一文件里放两个几乎相同的
+        // 调用点 —— 一个净化、一个不净化 —— 才能同时锁住两侧。
+        const dir = makeProject({
+            "store.ts": `
+import * as fs from "fs";
+export function loadTemplate(p: string): string {
+  return fs.readFileSync("/srv/templates/" + p, "utf-8");
+}
+`,
+            "handler.ts": `
+import { loadTemplate } from "./store";
+export function dispatchToolGuarded(params: any) {
+  const args = params.arguments;
+  assertTemplateName(args.name);
+  return loadTemplate(args.name);
+}
+export function dispatchToolBare(params: any) {
+  const args = params.arguments;
+  return loadTemplate(args.name);
+}
+function assertTemplateName(name: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error("bad template name");
+}
+`,
+        });
+        try {
+            // 净化侧：污点表达式已被校验 ⇒ 调用点不标记
+            (0, vitest_1.expect)(marksFor(dir, "dispatchToolGuarded")).not.toContain(PATH_MARK);
+            // 正对照：同形状去掉校验 ⇒ 照旧标记，且被调用方被反标
+            (0, vitest_1.expect)(marksFor(dir, "dispatchToolBare")).toContain(PATH_MARK);
+            (0, vitest_1.expect)(marksFor(dir, "loadTemplate")).toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("已知缺口 G2b：经项目自有 helper 转手的校验证据不生效（保守边界，仍标记）", () => {
+        // 只认 tier-0（函数体自身含校验证据）。经 helper 转手 ⇒ 那是【推断】出来
+        // 的守卫，拿推断结果做抑制会把推断误差直接放大成误报消除。
+        // 代价：这类形态仍会误报，与 C4b（helper 不传播）是同一族缺口。
+        const dir = makeProject({
+            "a.ts": `
+import * as fs from "fs";
+export function read(req: any) {
+  const name = req.params.name;
+  checkName(name);
+  return fs.readFileSync("/data/" + name, "utf-8");
+}
+function checkName(name: string): void {
+  assertTemplateName(name);
+}
+function assertTemplateName(name: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error("bad template name");
+}
+`,
+        });
+        try {
+            (0, vitest_1.expect)(marksFor(dir, "read")).toContain(PATH_MARK);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
 /**
  * ── 已知边界（本次写用例时实测踩到，记录以免后人重复踩）──
  *

package/dist/extract-ir.js

@@ -516,15 +516,20 @@ function escapeRe(s) {
  */
 function pathGuardFunctionNames(project) {
     const guarded = new Set();
+    /** tier-0：函数体自身含校验证据的名字（G1 原语义） */
+    const direct = new Set();
     const bodies = [];
     const note = (names, text) => {
         if (!text)
             return;
         bodies.push({ names, text });
-        if (hasPathGuardEvidence(text))
+        if (hasPathGuardEvidence(text)) {
             for (const n of names)
-                if (n)
+                if (n) {
                     guarded.add(n);
+                    direct.add(n);
+                }
+        }
     };
     for (const sf of project.getSourceFiles()) {
         for (const cls of sf.getClasses()) {
@@ -567,7 +572,55 @@ function pathGuardFunctionNames(project) {
         if (!added)
             break;
     }
-    return guarded;
+    return { all: guarded, direct };
+}
+// ═══════════════════════════════════════════════════════════════
+// G2（2026-09-19）：调用点抑制 —— 污点【表达式级】净化
+// ═══════════════════════════════════════════════════════════════
+// 缺口实证（taintpath_B，2026-09-19 measured）：
+//   `assertTemplateName(args.name); return loadTemplate(args.name);`
+// 仍被标记。`assertTemplateName` 的函数体内是锚定字符集白名单（G-D），
+// 是**真的**校验，但它的名字不含路径语义后缀 —— `Name` 在修 `ensureDir()`
+// 误判时被整体移出了 G-C 守卫后缀表，于是调用点侧认不出来。
+//
+// 为什么不直接放宽后缀表：那是按【名字】猜语义，会把判别力稀释成猜函数名
+// （G-C 的实证代价已经量过一次：放宽 ⇒ fr-007 pre 侧召回归零）。
+// 本实现改为按【被调用方的实际证据】定案：
+//   函数体内调用了 tier-0 守卫函数（自身含校验证据），且污点表达式被当作
+//   实参传进去 ⇒ 该表达式视为已净化，再流进 sink 不算污点。
+//
+// 精度取舍（关键点）：净化作用在【表达式】上，不是整函数。
+//   G1 的 selfGuarded 是函数级的（一个校验词汇压掉整个函数体所有流）；
+//   G2 只净化真正被传进守卫调用的那个表达式 —— 同函数体里另一条未被校验
+//   的流仍会标记。这是 G2 相对 G1 的收窄，而不是又一次放宽。
+// ═══════════════════════════════════════════════════════════════
+/**
+ * 收集函数体内「被传进 tier-0 守卫函数」的实参表达式，编译成一个判定正则。
+ *
+ * 边界：只收**简单取值表达式**（标识符 / 成员 / 下标 / 字符串字面量），
+ * 复杂表达式（模板串、拼接、调用）不收 —— 那些形态无法在 sink 侧可靠比对。
+ */
+function collectSanitizedExprs(text, directGuardFns) {
+    if (!directGuardFns || directGuardFns.size === 0)
+        return null;
+    const names = [...directGuardFns].filter((n) => !n.includes("."));
+    if (names.length === 0)
+        return null;
+    const callRe = new RegExp(`(?:^|[^\\w$.])(?:${names.map(escapeRe).join("|")})\\s*\\(([\\s\\S]{0,250}?)\\)`, "g");
+    const exprs = new Set();
+    let m;
+    while ((m = callRe.exec(text)) !== null) {
+        for (const a of splitArgWindow(m[1] || "")) {
+            const t = a.trim();
+            if (t && /^[A-Za-z_$][\w$]*(?:\s*\.\s*[\w$]+|\[[^\]]*\])*$/.test(t))
+                exprs.add(t.replace(/\s+/g, ""));
+        }
+    }
+    if (exprs.size === 0)
+        return null;
+    // 前缀 `(?:^|[^\w$.])` 是精度关键：`name` 不能匹配 `other.name` 里的 name，
+    // 但 `args.name` 能匹配 `path.join(DIR, args.name)` 里的 args.name。
+    return new RegExp([...exprs].map((e) => `(?:^|[^\\w$.])${escapeRe(e)}\\b`).join("|"));
 }
 const TS_FILE_SINK_NAMES = [
     "readFile", "readFileSync", "writeFile", "writeFileSync",
@@ -712,16 +765,33 @@ function taintPattern(tainted) {
     }
     return new RegExp(parts.join("|"));
 }
-/** 本函数体内：文件 sink 的实参窗口含 request 污点 → true */
-function hasTaintedSinkCall(text, tainted) {
+/**
+ * 本函数体内：文件 sink 的实参窗口含 request 污点 → true。
+ *
+ * `sanitizedRe` 非空时（G2）：实参里被净化过的表达式不再算污点 ——
+ * 逐实参判定，只要还有一个实参含【未被净化】的污点就照旧标记。
+ */
+function hasTaintedSinkCall(text, tainted, sanitizedRe) {
     const taint = taintPattern(tainted);
     if (!taint)
         return false;
     const sinkRe = tsSinkCallRegex();
     let m;
     while ((m = sinkRe.exec(text)) !== null) {
-        if (taint.test(m[2] || ""))
-            return true;
+        const win = m[2] || "";
+        if (!taint.test(win))
+            continue;
+        if (sanitizedRe) {
+            const args = splitArgWindow(win);
+            if (args.length > 0) {
+                if (!args.some((a) => taint.test(a) && !sanitizedRe.test(a)))
+                    continue;
+            }
+            else if (sanitizedRe.test(win)) {
+                continue;
+            }
+        }
+        return true;
     }
     return false;
 }
@@ -833,7 +903,7 @@ function collectUrlParamNames(params) {
  *   项目方法体内的文件 sink（跨函数一跳，onMethodHit 回调登记方法条目）
  * - SSRF：URL 形参/request 污点 → HTTP fetch sink，无守卫词汇
  */
-function computeMarkerCalls(text, paramNames, sinkParams, onMethodHit, guardFns) {
+function computeMarkerCalls(text, paramNames, sinkParams, onMethodHit, guardFns, directGuardFns) {
     const markers = [];
     // ── 路径穿越 ──
     // G1（2026-09-19）：有流还不够，必须【没有校验证据】才标记——
@@ -842,6 +912,10 @@ function computeMarkerCalls(text, paramNames, sinkParams, onMethodHit, guardFns)
     if (hasRequestRootedExpr(text)) {
         const tainted = collectTaintedNames(text);
         const selfGuarded = guardFns ? hasPathGuardEvidence(text) !== null : false;
+        // G2：调用点抑制 —— 被传进「自身含校验证据的函数」的表达式视为已净化。
+        // 与 selfGuarded（函数级、按词形）互补：这条按【被调用方的实际证据】定案，
+        // 因此认得出 assertTemplateName 这类不含路径语义后缀的自定义校验函数。
+        const sanitizedRe = collectSanitizedExprs(text, directGuardFns);
         // C5（2026-09-19）：不可信根可以直接写在 sink 实参里，不需要中间变量。
         // 此前外层要求 collectTaintedNames 非空，于是
         //   `fs.readFileSync("/data/" + req.params.name)` —— 真实工程里最常见的形态
@@ -849,7 +923,7 @@ function computeMarkerCalls(text, paramNames, sinkParams, onMethodHit, guardFns)
         // SSRF 侧从来不是这样（它把 UNTRUSTED_ROOT_SRC 并进 taint 模式去匹配实参窗口），
         // 这是同一条数据流上的又一处口径不一致。
         if (!selfGuarded) {
-            if (hasTaintedSinkCall(text, tainted)) {
+            if (hasTaintedSinkCall(text, tainted, sanitizedRe)) {
                 markers.push("__progmune_path_traversal__");
             }
             else {
@@ -872,7 +946,7 @@ function computeMarkerCalls(text, paramNames, sinkParams, onMethodHit, guardFns)
                             if (guardFns && guardFns.has(m[1]))
                                 continue;
                             const args = splitArgWindow(m[2] || "");
-                            const hit = args.some((arg, i) => rec.idxs.has(i) && taint.test(arg));
+                            const hit = args.some((arg, i) => rec.idxs.has(i) && taint.test(arg) && !(sanitizedRe && sanitizedRe.test(arg)));
                             if (hit) {
                                 markers.push("__progmune_path_traversal__");
                                 onMethodHit(rec);
@@ -990,7 +1064,10 @@ function _extractSingleProject(absRoot, tsconfigPath) {
     // pendingMethodMarks = 跨函数命中待标记的方法条目（主循环后统一应用）
     const sinkParams = methodSinkParamMap(project, absRoot);
     // G1（2026-09-19）：路径校验识别。自身含校验证据的函数名 + 向调用方传播一跳。
-    const guardFns = pathGuardFunctionNames(project);
+    // direct = tier-0（自身含校验证据）；all = 再向调用方传播一跳后的集合。
+    // G2 只用 direct —— 传播得到的名字是「被推断为守卫」，拿它做抑制会把
+    // 推断误差直接放大成误报消除。
+    const { all: guardFns, direct: directGuardFns } = pathGuardFunctionNames(project);
     const pendingMethodMarks = new Set();
     const onMethodHit = (rec) => {
         for (const me of rec.entries)
@@ -1008,7 +1085,7 @@ function _extractSingleProject(absRoot, tsconfigPath) {
             const fParams = f.getParameters();
             const fText = f.getText();
             const fCalls = extractDirectCalls(f, fText);
-            fCalls.push(...computeMarkerCalls(fText, fParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns));
+            fCalls.push(...computeMarkerCalls(fText, fParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns, directGuardFns));
             funcs.push({
                 name,
                 params: fParams.map(p => ({
@@ -1038,7 +1115,7 @@ function _extractSingleProject(absRoot, tsconfigPath) {
                 const initParams = init.getParameters();
                 const initText = init.getText();
                 const initCalls = extractDirectCalls(init, initText);
-                initCalls.push(...computeMarkerCalls(initText, initParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns));
+                initCalls.push(...computeMarkerCalls(initText, initParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns, directGuardFns));
                 funcs.push({
                     name,
                     params: initParams.map(p => ({
@@ -1064,7 +1141,7 @@ function _extractSingleProject(absRoot, tsconfigPath) {
                         const argParams = arg.getParameters();
                         const argText = arg.getText();
                         const argCalls = extractDirectCalls(arg, argText);
-                        argCalls.push(...computeMarkerCalls(argText, argParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns));
+                        argCalls.push(...computeMarkerCalls(argText, argParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns, directGuardFns));
                         funcs.push({
                             name,
                             params: argParams.map(p => ({
@@ -1098,7 +1175,7 @@ function _extractSingleProject(absRoot, tsconfigPath) {
                     continue;
                 const mParams = m.getParameters();
                 const mText = m.getText();
-                const mCalls = computeMarkerCalls(mText, mParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns);
+                const mCalls = computeMarkerCalls(mText, mParams.map((p) => p.getName()), sinkParams, onMethodHit, guardFns, directGuardFns);
                 funcs.push({
                     name: `${cn}.${mn}`,
                     params: mParams.map((p) => ({ name: p.getName(), type: getParamType(p), typeDetail: getParamTypeDetail(p) })),

package/dist/sdk.js

@@ -20,7 +20,7 @@ const risk_model_1 = require("./risk-model");
 const protocol_knowledge_1 = require("./protocol-knowledge");
 const evidence_repository_1 = require("./evidence-repository");
 /** Runtime version — stable public identifier. Internal layers evolve underneath. */
-exports.RUNTIME_VERSION = "3.7.36";
+exports.RUNTIME_VERSION = "3.7.37";
 function verify(filePath) {
     const cert = (0, certify_1.certify)(filePath);
     const kb = (0, protocol_knowledge_1.buildKnowledgeBase)();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "progmune-runtime",
-  "version": "3.7.36",
+  "version": "3.7.37",
   "description": "Progmune — AI Trust Decision Engine. Verify AI-generated code before it reaches production. Outputs APPROVED / NEEDS_REVIEW / BLOCKED with evidence.",
   "files": [
     "dist/",