debug-rule

技能：调试规则

通过追踪污点在哪里丢失，诊断规则或近似模型为何在某个模型上的行为出乎意料，并判断修复应由谁负责：规则、缺失的库模型，还是引擎。

输入

由调用方提供；省略时使用默认值。仅当缺少必需输入且没有合理默认值时才询问

• project-root（可选）——目标项目的根目录。Opentaint 会将所有分析产物保存在固定的 <project-root>/.opentaint/ 目录下，因此下面每个 .opentaint/... 路径都会解析到该目录。默认值：当前目录
• rule（必需）——其样例或流会让污点经过被测代码的那条规则，格式为 <ruleSetRelativePath>.yaml:<shortId>。对于近似模型，填写其样例会让污点经过被近似方法的规则
• model（必需）——行为出现的项目模型

工作流

1. 重现问题并定位污点消失处

重现出现问题时的确切运行——使用相同的 model、规则集和已应用的近似模型目录——并通过事实可达性运行追踪污点消失的位置。直接以前台阻塞命令运行并等待退出；绝不要将其放到后台运行或使用 Monitor：

opentaint test rule reachability <rule> \
  --project-model <model> \
  -o <results-dir>/report.sarif \
  --ruleset builtin --ruleset .opentaint/rules \
  --passthrough-approximations .opentaint/pass-through \
  --dataflow-approximations .opentaint/dataflow

<results-dir> 对于测试模型为 .opentaint/test-results/<name>，对于主扫描为 .opentaint/results。每条指令对应的事实位于同级目录中的 <results-dir>/debug-ifds-fact-reachability.sarif，而非 -o 文件中；-o SARIF 仅显示规则是否触发。读取这个同级文件以找到污点消失处：

• 漏报（本应通过的阳性样例未通过，或扫描中缺少某条流）——确认源处存在事实；如果不存在，问题出在 pattern-sources，而非数据流中。否则，沿着事实追踪，找到最后一个仍携带该事实的指令，以及第一个不再携带该事实的指令——这两者之间就是污点消失处
• 误报（阴性样例触发）——反向查找：找到一个事实出现的位置，但没有带污点的输入到达那里

追踪行为异常的确切运行——换用不同的 model 或规则集会追踪其他内容；如果污点在近似调用处消失，说明该近似模型没有传播污点。如果流漏报，且入口方法可能从未被分析，请使用 --entry-points "<method-fqn>" 重新运行：只有此时才出现的发现，说明是入口点发现问题，而非数据流问题。在 Spring 中，该标志是追加式的——自动发现的端点会保留，同时加入你指定的方法；因此，应使用它强制包含分析器从未开始分析的端点，而不是将分析范围缩小到单个方法。

2. 判断原因

导致污点消失的指令决定由谁负责修复。引擎错误的可能性远低于其他原因——将其作为最后的假设，仅在排除另外两种原因后才考虑；几乎每次污点消失都是库模型缺失或有误，或是规则缺陷。这两种原因虽然排查起来都很费劲，但远比引擎错误常见，不能因为排查麻烦就直接认定是“引擎”问题。可能有以下三种情况：

• 污点在外部库方法处消失 → 模型问题。交叉检查本次运行生成的 dropped-external-methods.yaml（如果文件不存在，使用 --track-external-methods 扫描会重新生成）：如果方法列在其中，说明尚未为其建模——原因是缺少模型，应由近似模型阶段负责建模。如果未列出，但内置模型声称会对其建模，而污点仍在此处消失 → 该模型不适用于此情形：passThrough 覆盖规则适用于规则级别，因此优先为该方法使用一个；数据流覆盖会在加载时与内置模型冲突，因此应改用 passThrough，或者在只有数据流形态才能表达这种传播时将其判定为引擎问题
• 污点在规则本应匹配的位置消失——净化器误触发，或接收器、源变体未匹配 → 规则缺陷，应由规则编写者修复
• 污点在引擎必须传播污点的普通指令处消失（赋值、类型转换、字段读取、已有模型的调用），且规则正确、模型完整 → 引擎问题

3. 报告诊断结果

此技能用于诊断并确定修复方向，不会编写规则或近似逻辑，也不会重新运行流水线。请按“输出”部分的要求报告诊断结果。

输出

产物

• debug-ifds-fact-reachability.sarif — CLI 在 -o SARIF 文件旁生成的逐指令事实可达性跟踪

摘要

• 诊断结果：file:line 以及污点被消除（或被错误引入）的指令，并指出修复归属于三种原因中的哪一种
• 对于引擎原因：截至最后一个可达事实的事实可达性跟踪（供引擎问题报告使用），以及确切的调试命令和这些命令运行时使用的模型