dsh-js-reverse-plugin 0.1.0

package/skills/js-ast-deobfuscation/references/methods-and-evidence.md

@@ -0,0 +1,460 @@
+# 方法与证据
+
+本文件回答两个问题：
+
+1. 当前候选需要什么证据？
+2. 哪种方法能以最低侵入取得最小充分证据？
+
+它不重复总体主线，不规定固定 transform 顺序，也不绑定任何动态运行框架的具体 API。入口文件已经选定当前阶段；本文只完成方法与证据设计，不继续加载其他 reference。
+
+## 目录
+
+- [1. 先把候选写成具体问题](#1-先把候选写成具体问题)
+- [2. 证据模式](#2-证据模式)
+- [3. 静态方法](#3-静态方法)
+- [4. 受控局部执行](#4-受控局部执行)
+- [5. 方法选择阶梯](#5-方法选择阶梯)
+- [6. L0～L4 动态观测阶梯](#6-l0l4-动态观测阶梯)
+- [7. 静态步骤中途升级为动态](#7-静态步骤中途升级为动态)
+- [8. 动态事实映射回源码](#8-动态事实映射回源码)
+- [9. 覆盖范围与证据边界](#9-覆盖范围与证据边界)
+- [10. 方法决策记录](#10-方法决策记录)
+- [11. 常见错误](#11-常见错误)
+
+## 1. 先把候选写成具体问题
+
+“控制流混淆”“动态 decoder”“删除反调试”是主题，不是可执行问题。
+
+每个高价值候选至少记录：
+
+```text
+question_id
+当前要回答的具体问题
+该问题阻碍了什么
+Observed 事实
+静态已经证明到哪里
+唯一或最小证据缺口
+需要取得的事实
+取得事实后允许做什么
+结果怎样映射回原始文件和当前视图
+明确不能推出什么
+停止条件
+```
+
+问题必须可证伪。例如：
+
+```text
+不合格：
+动态执行 decoder。
+
+合格：
+静态已证明调用点使用 decoder D，但索引偏移依赖初始化后的闭包状态。
+本候选只需要固定输入下的偏移值和 D(17) 的返回值；
+不需要证明其他输入、其他初始化路径或完整程序行为。
+```
+
+如果不能写出“缺少哪个事实”，说明候选仍然过宽。继续静态调查或拆成更小的问题，不要直接扩大执行范围。
+
+## 2. 证据模式
+
+每个候选单独选择一次证据模式。上一个候选的模式不能自动沿用。
+
+### 2.1 `static`
+
+源码、AST、作用域、引用、常量和确定性语义已经足以证明当前结论。
+
+适用示例：
+
+- 唯一词法 binding 的引用和 shadow 关系。
+- 无副作用常量表达式的值。
+- 可静态证明的字符串索引映射。
+- 直接导出、直接别名和明确的调用关系。
+- 不依赖实际运行路径的结构变换。
+
+选择 `static` 不等于“看起来很可能”。必须说明语法前提、作用域前提、消费者范围和反证检查。
+
+### 2.2 `dynamic`
+
+必须运行才能取得当前事实，而且该事实本身成立后不需要 AST 写回。
+
+适用示例：
+
+- 固定触发下的实际参数、返回值或异常。
+- 初始化后的闭包状态。
+- 某次执行中的分支、调用顺序或宿主 API 行为。
+- 事件循环推进后出现的结果。
+
+动态结论只覆盖已记录的输入、环境、触发和路径。
+
+### 2.3 `hybrid`
+
+静态分析定位问题和观测点，动态执行取得运行事实，再由 AST 把已证明结果写入新的派生视图。
+
+选择 `hybrid` 时必须分开记录：
+
+1. 静态部分证明了什么。
+2. 动态部分只补了什么。
+3. 哪个写回动作由两者共同支持。
+
+动态运行层只返回证据，不直接决定 transform。
+
+### 2.4 `blocked`
+
+静态证据不足，同时缺少可信、可授权或可复现的运行条件。
+
+`blocked` 必须记录：
+
+- 已完成的静态调查。
+- 缺少的具体事实。
+- 为什么现有执行条件不可信或不足。
+- 解除阻塞所需的最小条件。
+- 当前仍可继续的其他候选。
+
+`blocked` 只阻塞当前候选，不阻塞无关静态工作。
+
+### 2.5 选择检查
+
+按顺序回答：
+
+```text
+1. 能否从语法、作用域和确定性语义直接证明？
+2. 结论是否依赖初始化、输入、闭包、宿主状态、时间、随机数或网络？
+3. 当前变换是否必须知道实际执行路径？
+4. 能否只执行一个闭合的局部函数？
+5. 动态结果能否稳定映射回源码？
+6. 当前覆盖是否足以支持准备执行的变换？
+7. 是否有范围更小、侵入更低的方法？
+```
+
+任一动态方案都应能回答“为什么静态不足”。不能回答时，先保持 `static` 调查或标记 `Unknown`。
+
+## 3. 静态方法
+
+静态证据优先来自当前完整分析视图和可回溯源码锚点，再用工具复核。
+
+### 3.1 语法与结构
+
+- AST 节点类型、父子关系和求值顺序。
+- 声明、初始化、赋值、调用和返回位置。
+- 条件、循环、短路、序列表达式和异常路径。
+- 模块导入导出、工厂表、加载器和公开入口。
+- 字面量、属性访问、计算属性和动态代码构造点。
+
+不要只凭节点外形命名模式。`switch` 不自动等于控制流平坦化，长数组不自动等于字符串池。
+
+### 3.2 作用域、binding 与引用
+
+至少检查：
+
+- 声明解析到的唯一 binding。
+- 读、写、调用、更新和导出引用。
+- 嵌套作用域中的同名 shadow binding。
+- 别名创建位置和生命周期。
+- 闭包捕获与重赋值。
+- 动态属性、反射和间接访问。
+
+重命名或删除不能使用标识符文本全局替换。
+
+### 3.3 数据流与消费者
+
+沿 def-use 和调用关系回答：
+
+- 值从哪里定义、修改和读取。
+- 哪些消费者阻碍当前目标。
+- 值是否进入公开输出、网络、存储、Cookie 或导出。
+- 值是否只参与防御逻辑，还是影响业务分支。
+- 当前候选是否能解锁多个后续结构。
+
+出现某个值不证明它被执行或影响最终结果。
+
+### 3.4 确定性求值
+
+只有同时满足以下条件时才静态折叠：
+
+- 运算语义确定。
+- 操作数已证明为常量。
+- 不触发 getter、Proxy、隐式类型转换或用户代码。
+- 不依赖时间、随机数、环境或可变全局状态。
+- 不改变异常、`this`、`arguments` 或求值顺序。
+
+无法证明时保留表达式，并把缺口写入候选问题。
+
+### 3.5 副作用与异常
+
+内联、删除或改写前检查：
+
+- getter、setter、Proxy 和自定义转换方法。
+- 函数调用、构造调用和动态属性。
+- 全局写入、模块状态和闭包状态。
+- 抛出、捕获、`finally` 和提前返回。
+- 短路与条件求值次数。
+- `this`、`arguments`、`new.target` 和调用形式。
+
+“返回值未使用”不等于“调用无副作用”。
+
+### 3.6 静态结论的边界
+
+静态报告应区分：
+
+```text
+Observed：源码直接显示的结构和关系。
+Inferred：由多项静态事实支持的解释。
+Unknown：仍需其他证据的问题。
+```
+
+中性坐标优于无证据的业务名称。
+
+## 4. 受控局部执行
+
+局部执行适用于可以从完整目标中隔离、输入可冻结且不依赖宿主状态的函数或 decoder。
+
+### 4.1 使用前提
+
+必须证明或显式限定：
+
+- 入口和所有直接依赖已知。
+- 输入完整且可序列化或可重建。
+- 不需要完整程序初始化，或所需初始化可单独复现。
+- 不访问真实网络、账号、凭据或用户会话。
+- 不依赖未记录的 DOM、Cookie、Storage、时间或随机状态。
+- 文件系统、进程和网络权限被限制。
+- 超时、资源上限和停止条件明确。
+
+若必须不断补 stub 才能运行，说明局部闭包边界尚未证明。
+
+### 4.2 证据限制
+
+局部执行只能证明声明输入和声明环境下的局部行为。它不能自动证明：
+
+- 完整目标会调用该函数。
+- 其他输入得到相同结果。
+- 真实宿主中的副作用相同。
+- 该值进入最终业务输出。
+
+`node:vm` 不是不可信代码的安全沙箱。不要把它作为执行未知代码的安全保证。
+
+### 4.3 最小记录
+
+```text
+提取的入口与依赖
+输入及其 hash
+运行时与版本
+权限、超时和资源限制
+时间、随机数和环境状态
+调用命令
+stdout / stderr / exception
+重复运行结果
+覆盖与非结论
+```
+
+## 5. 方法选择阶梯
+
+选择能回答当前问题的最低侵入方法：
+
+| 场景 | 首选方法 |
+|---|---|
+| AST 与确定性语义足够 | 静态分析 |
+| 局部函数闭合、输入可冻结、无宿主依赖 | 受控局部执行 |
+| 依赖闭包、初始化、真实 `this/arguments` 或实际路径 | 有界动态实验 |
+| 依赖浏览器 API、页面生命周期或事件循环 | 浏览器语义动态后端 |
+| 依赖真实会话、真实渲染、真实网络或浏览器调用栈 | 真浏览器、CDP 或等价能力 |
+| 需要 Opcode、PC、值栈、字节码或虚拟控制流 | 交接 VM Skill |
+
+运行环境已经存在不是选择动态的理由。动态不等于补环境，浏览器语义后端也不是所有动态任务的固定前置。
+
+## 6. L0～L4 动态观测阶梯
+
+始终从能回答问题的最低侵入层级开始。升级层级时记录前一层为什么不足。
+
+### 6.1 L0：引擎层旁路观测
+
+- 原始文件零修改。
+- 使用运行时已有的 API 访问、反射、网络和事件日志。
+- 适合宿主能力、环境探测和网络边界问题。
+- 保存原始日志、版本和时间范围。
+
+L0 没有改源码，但日志能力本身仍可能有覆盖限制。
+
+### 6.2 L1：调试器旁路观测
+
+- 从外部设置断点、API watch 或表达式求值。
+- 观察调用栈、scope、局部变量、参数、返回值和异常。
+- 不向原始源码写入日志。
+- 记录断点位置、命中条件、命中次数和暂停影响。
+
+断点和调试器不等于运行时零影响。
+
+### 6.3 L2：独立 harness 与 trigger
+
+- 用独立驱动加载、初始化并调用已知入口。
+- 不重写目标函数或宿主对象。
+- 记录前置状态、触发顺序和事件循环推进。
+- 只暴露当前问题需要的权限和输入。
+
+L2 证明的是声明 trigger 下的行为，不证明其他入口和路径。
+
+### 6.4 L3：独立 probe 或运行时 Hook
+
+- 用独立 probe 或 wrapper 观察参数、返回值、异常和属性访问。
+- 原始文件不变，但运行时对象已改变。
+- 必须标记 `runtime patched`。
+- 必须保存无 probe 与有 probe 的 A/B 对照。
+
+wrapper 外形接近原对象只能降低可观察差异，不能把证据提升为未修改运行时。
+
+### 6.5 L4：派生副本插桩
+
+- 仅在 L0～L3 无法回答当前问题时使用。
+- 只修改独立的运行副本。
+- 原始文件继续固定 hash 且保持不变。
+- 使用稳定节点 ID、原始位置或 source map 建立映射。
+- 明确降低行为证据等级。
+
+插桩副本的运行结果不能冒充原始目标行为。
+
+### 6.6 层级摘要
+
+| 层级 | 修改原始文件 | 改变运行时对象 | 强制要求 |
+|---|---:|---:|---|
+| L0 | 否 | 通常否 | 记录日志能力与覆盖 |
+| L1 | 否 | 通常否 | 记录断点和暂停影响 |
+| L2 | 否 | 否 | 记录 harness、前置状态和 trigger |
+| L3 | 否 | 是 | `runtime patched` 与 A/B |
+| L4 | 否 | 运行副本已改 | 映射、证据降级和原始 hash 校验 |
+
+## 7. 静态步骤中途升级为动态
+
+用户批准的静态步骤不能静默扩大为动态或 hybrid。
+
+发现动态缺口时：
+
+1. 停止当前静态步骤。
+2. 保留上一个通过验收的版本。
+3. 说明静态已经证明到哪里。
+4. 指出缺少的最小运行事实。
+5. 提出最低侵入的动态取证方案。
+6. 说明执行对象、输入、前置状态、trigger、观测点和 L0～L4 层级。
+7. 说明权限、风险、覆盖、非结论和停止条件。
+8. 等待用户批准新的取证步骤。
+
+等待批准期间，对外状态使用 `READY_FOR_USER_DECISION`；在步骤账本中把原静态步骤记录为“暂停，等待动态证据”。只有原前提不成立或验证失败时才使用 `STEP_STOPPED`。
+
+动态证据返回后：
+
+1. 核对执行目标及原始 hash。
+2. 区分 `Observed / Inferred / Unknown`。
+3. 限定输入、环境、trigger 和覆盖路径。
+4. 映射回原始位置与当前分析视图。
+5. 判断证据是否足以支持原问题。
+6. 证据不足时缩小结论、继续取证或标记 `blocked`。
+
+不得在原静态授权下执行完整目标、安装 Hook 或运行插桩副本。
+
+## 8. 动态事实映射回源码
+
+每条被采用的动态事实至少关联：
+
+```text
+question_id
+原始路径与 hash
+原始源码位置或稳定节点 ID
+当前分析视图路径与 hash
+当前视图位置
+trigger / probe / log 记录
+观察值、顺序、次数或异常
+Observed / Inferred / Unknown
+适用输入、环境和路径
+```
+
+优先使用：
+
+- 原始位置与当前视图的映射表。
+- 稳定节点 ID 或结构路径。
+- source map。
+- 调用栈中的脚本 URL、函数位置和断点位置。
+- transform 生成的逐步映射。
+
+只记录当前派生文件行号通常不够；后续 transform 会改变行列位置。
+
+映射失败时，动态结果可以保留为运行事实，但不能直接写回 AST 或支持位置敏感的变换。
+
+## 9. 覆盖范围与证据边界
+
+动态结果必须记录：
+
+- 执行文件与 hash。
+- 运行时、版本、mode 和宿主摘要。
+- 输入、配置、时间和随机数。
+- 初始化、trigger、次数和事件循环策略。
+- 文件系统、进程、网络和凭据权限。
+- 环境补丁、Hook 和插桩状态。
+- 已覆盖入口、分支和调用点。
+- 未覆盖路径和提前终止。
+- 原始日志与重放命令。
+
+### 9.1 何时覆盖足够
+
+覆盖是否足够相对于当前问题判断，而不是追求全程序覆盖。
+
+证据可以支持变换，至少需要：
+
+- 观察点与目标源码唯一映射。
+- 输入和前置状态与候选契约一致。
+- 所有准备改写的调用点都被静态证明同构，或被动态覆盖。
+- 未覆盖路径不会落入本次修改范围，或者被显式排除。
+- probe、断点或插桩的影响已评估。
+- 结果可重复，或不确定性已进入结论边界。
+
+不能满足时，缩小 mutation scope，不要扩大动态结论。
+
+### 9.2 禁止的推广
+
+一次运行不能自动证明：
+
+- 所有输入的返回值。
+- 所有环境下的分支。
+- 未命中的调用点。
+- 属性读取一定进入最终算法。
+- 模块存在一定被执行。
+- 有 probe 与无 probe 行为完全相同。
+
+## 10. 方法决策记录
+
+给用户提交候选前，内部记录至少包含：
+
+```text
+question_id：
+具体问题：
+当前阻碍：
+Observed：
+Inferred：
+Unknown：
+静态已证明：
+证据缺口：
+证据模式：
+最小充分方法：
+动态层级（如适用）：
+执行与 mutation scope：
+映射方案：
+覆盖要求：
+风险与非结论：
+停止条件：
+预期收益：
+```
+
+本文的输出止于方法、证据缺口、范围和风险。真正执行 transform 或接受动态结论前，回到入口文件进入对应验收阶段。
+
+## 11. 常见错误
+
+- 把混淆家族名称直接当成步骤。
+- 让用户替模型选择 `static` 或 `hybrid`。
+- 因为运行环境可用就默认动态。
+- 为局部 decoder 执行完整未知目标。
+- 把 `node:vm` 称为不可信代码沙箱。
+- 把源文件零修改写成运行时零影响。
+- 安装 Hook 后不做无 probe / 有 probe 对照。
+- L0～L3 尚能回答问题时直接插桩派生副本。
+- 只保存解析后的摘要，不保存原始日志。
+- 动态结果不能映射回源码仍强行写回 AST。
+- 把一次运行推广为全部输入或路径。
+- 当前候选 blocked 后停止所有静态调查。