438 lines
17 KiB
Markdown
438 lines
17 KiB
Markdown
# 复杂入口分析规则
|
||
|
||
本文用于处理复杂的加密入口场景，包括异步函数、Promise、Web Crypto API、WebAssembly、Webpack 模块、Vite/Rollup/ESM 以及闭包作用域限制。
|
||
|
||
---
|
||
|
||
## 1. 异步与 Promise 入口
|
||
|
||
### 适用条件
|
||
|
||
- 目标入口返回 Promise，例如 crypto.subtle.digest(...)、Webpack 动态 import() 或 async function。
|
||
- JSRPC 动作处理器必须等待 Promise 完成后再返回结果。
|
||
|
||
### 识别方式
|
||
|
||
- 函数返回带有 .then() 方法的对象。
|
||
- analysis_result.json 中的 call_signature.async 为 true。
|
||
- 源码使用 async function 或返回 new Promise()。
|
||
- 运行时 Hook 会在 crypto[] 事件中记录返回 Promise 的函数。
|
||
- 在依赖提取阶段调用入口，并检查 typeof result.then === 'function'。
|
||
|
||
### JSRPC 处理要求
|
||
|
||
动作处理器必须识别 Promise 并等待结果。这适用于所有调用，不仅限于源码显式声明为异步的函数。
|
||
|
||
~~~js
|
||
var result = fn.apply(ctx, args);
|
||
if (result && typeof result.then === 'function') {
|
||
result.then(function(asyncResult) {
|
||
// 处理 crypto.subtle 返回的 ArrayBuffer/Uint8Array
|
||
if (asyncResult instanceof ArrayBuffer) {
|
||
resolve(Array.from(new Uint8Array(asyncResult)));
|
||
} else {
|
||
resolve(asyncResult);
|
||
}
|
||
}).catch(function(error) {
|
||
resolve(normalizeError(parameter, error));
|
||
});
|
||
return;
|
||
}
|
||
resolve(result);
|
||
~~~
|
||
|
||
当 invocation.mode 为 "async" 或 "promise" 时，生成器必须包含 Promise 处理逻辑，否则 JSRPC /go 可能返回 undefined。
|
||
|
||
### 异步入口前置条件
|
||
|
||
- 调用 crypto.subtle.encrypt/decrypt/sign/verify 前，可能必须先导入或生成 CryptoKey。
|
||
- Webpack 动态导入可能要求目标分块先完成加载。
|
||
- 将这些条件记录到 invocation.preconditions 和 parameters[].runtime.bootstrap。
|
||
|
||
### 异步入口证据
|
||
|
||
- 运行时 Hook 从 crypto[] 中记录带有业务调用栈的事件。
|
||
- Promise 完成后填写的 outputLen 可以证明算法产生了输出。
|
||
- 与 requests[] 交叉比对：如果加密事件后很快出现 fetch/XHR 请求，说明业务函数可能把加密结果写入了请求体。
|
||
|
||
---
|
||
|
||
## 2. Web Crypto API（crypto.subtle）
|
||
|
||
### 特征
|
||
|
||
- 所有方法返回 Promise<ArrayBuffer>。
|
||
- digest(algorithm, data)：摘要。
|
||
- sign(algorithm, key, data)：数字签名（HMAC/RSASSA/ECDSA）。
|
||
- encrypt(algorithm, key, data)：加密（AES/RSA）。
|
||
- decrypt(algorithm, key, data)：解密。
|
||
- importKey(...)：导入密钥。
|
||
- exportKey(...)：导出密钥。
|
||
- 输入通常是 ArrayBuffer/TypedArray，输出是 ArrayBuffer。
|
||
|
||
### 识别
|
||
|
||
运行时 Hook 会自动包装核心方法，证据记录在 window.__JSRA_TRACE__.crypto[]。
|
||
|
||
### 算法识别
|
||
|
||
- crypto[] 事件的 algorithm 字段：对象取 algorithm.name，字符串直接记录原值。
|
||
- 常见算法名包括：SHA-1、SHA-256、SHA-384、SHA-512、AES-CBC、AES-GCM、AES-CTR、RSA-OAEP、RSASSA-PKCS1-v1_5、ECDSA、HMAC。
|
||
|
||
### Hook 示例（摘要）
|
||
|
||
~~~js
|
||
var origDigest = crypto.subtle.digest.bind(crypto.subtle);
|
||
crypto.subtle.digest = function(algorithm, data) {
|
||
var entry = { type: 'digest', algorithm: algorithm.name || algorithm, inputLen: data.byteLength };
|
||
trace.crypto.push(entry);
|
||
return origDigest(algorithm, data).then(function(hash) {
|
||
entry.outputLen = hash.byteLength;
|
||
entry.outputHex = Array.from(new Uint8Array(hash)).map(function(b) {
|
||
return b.toString(16).padStart(2, '0');
|
||
}).join('').substring(0, 32) + '...';
|
||
return hash;
|
||
});
|
||
};
|
||
~~~
|
||
|
||
### 密钥材料
|
||
|
||
- crypto.subtle.sign/encrypt/decrypt 的第二个参数必须是 CryptoKey。
|
||
- 如果密钥通过 crypto.subtle.importKey 在运行时导入，导入事件也会出现在 crypto[] 中。
|
||
- CryptoKey 对页面脚本通常不可直接读取；但通过 importKey Hook 可以观察 keyData 原始参数。
|
||
|
||
### 补充 importKey Hook
|
||
|
||
如果运行时探针尚未覆盖 importKey，可以临时补充：
|
||
|
||
~~~js
|
||
(function() {
|
||
'use strict';
|
||
if (!window.crypto || !window.crypto.subtle) return;
|
||
var origImportKey = crypto.subtle.importKey.bind(crypto.subtle);
|
||
crypto.subtle.importKey = function(format, keyData, algorithm, extractable, usages) {
|
||
console.log('[JSRA] crypto.subtle.importKey', {
|
||
format: format,
|
||
algorithm: typeof algorithm === 'string' ? algorithm : algorithm.name,
|
||
usages: usages,
|
||
keyDataSnippet: keyData instanceof ArrayBuffer
|
||
? '[ArrayBuffer:' + keyData.byteLength + ']'
|
||
: (keyData instanceof Uint8Array ? '[Uint8Array:' + keyData.length + ']' : String(keyData))
|
||
});
|
||
return origImportKey(format, keyData, algorithm, extractable, usages);
|
||
};
|
||
})();
|
||
~~~
|
||
|
||
### ArrayBuffer 转十六进制
|
||
|
||
~~~js
|
||
function arrayBufferToHex(buffer) {
|
||
return Array.from(new Uint8Array(buffer))
|
||
.map(function(b) { return b.toString(16).padStart(2, '0'); })
|
||
.join('');
|
||
}
|
||
~~~
|
||
|
||
### crypto.subtle 的 JSRPC 生成要求
|
||
|
||
- 入口策略使用 async_crypto。
|
||
- JSRPC 必须使用正确的算法、密钥和数据调用函数，等待 Promise 完成，并按目标协议将 ArrayBuffer 转为十六进制或 Base64。
|
||
- 入口为 crypto.subtle.* 时，处理器必须使用 ArrayBuffer 参数、识别返回的 Promise，并在完成后转换输出。
|
||
- 如果必须先导入密钥，应在处理器中完成导入，或将其记录为启动依赖。
|
||
|
||
### 限制
|
||
|
||
- CryptoKey 不能传出浏览器上下文；JSRPC 必须在密钥被导入的同一页面上下文中执行。
|
||
- 使用 extractable: false 生成的密钥不能导出，必须直接使用页面内的密钥引用执行签名或加密。
|
||
- chrome-devtools-mcp 无法直接拦截浏览器内部密码学运算，只能通过软 Hook 观察输入和输出。
|
||
|
||
---
|
||
|
||
## 3. WebAssembly（WASM）
|
||
|
||
### 识别信号
|
||
|
||
- 网络请求加载 .wasm 文件。
|
||
- window 上存在 WebAssembly 对象。
|
||
- 页面调用 WebAssembly.instantiate 或 WebAssembly.instantiateStreaming。
|
||
- 存在仅含数字的函数名，或参数/返回值为 Number、BigInt 的不透明函数。
|
||
|
||
### 可以执行的操作
|
||
|
||
- Hook WebAssembly.instantiate / WebAssembly.instantiateStreaming。
|
||
- 使用 WebAssembly.Module.exports(module) 查看导出函数。
|
||
- 从 JavaScript 调用已导出的 WASM 函数。
|
||
|
||
### 不可以执行的操作
|
||
|
||
- 调用 WASM 模块未导出的函数。
|
||
- 查看 WASM 内部内存或调用栈。
|
||
- 读取 WASM 源码。
|
||
- 绕过 WASM 完整性校验。
|
||
|
||
### WASM 实例化 Hook
|
||
|
||
用于观察 WASM 模块导出的函数：
|
||
|
||
~~~js
|
||
var origInstantiate = WebAssembly.instantiate;
|
||
WebAssembly.instantiate = function(bytes, imports) {
|
||
console.log('[JSRA] WebAssembly.instantiate called, bytes length:', bytes ? bytes.byteLength || bytes.length : 'unknown');
|
||
return origInstantiate(bytes, imports).then(function(result) {
|
||
var module = result.module || result;
|
||
if (module instanceof WebAssembly.Module) {
|
||
window.__JSRA_WASM_EXPORTS = WebAssembly.Module.exports(module);
|
||
console.log('[JSRA] WASM exports:', window.__JSRA_WASM_EXPORTS);
|
||
}
|
||
if (result.instance) {
|
||
window.__JSRA_WASM_INSTANCE = result.instance;
|
||
var exportNames = Object.keys(result.instance.exports);
|
||
console.log('[JSRA] WASM instance exports:', exportNames);
|
||
for (var i = 0; i < exportNames.length; i++) {
|
||
var name = exportNames[i];
|
||
if (typeof result.instance.exports[name] === 'function') {
|
||
console.log('[JSRA] WASM export function:', name, 'arity:', result.instance.exports[name].length);
|
||
}
|
||
}
|
||
}
|
||
return result;
|
||
});
|
||
};
|
||
~~~
|
||
|
||
### 调用 WASM 导出函数
|
||
|
||
- 如果模块导出函数且页面通过 JavaScript 包装器暴露，例如 window.wasmEncrypt(data)，可以将其作为 JSRPC 入口。
|
||
- 入口策略使用 wasm_export。
|
||
- WASM 通常使用 Number、BigInt 或内存指针；JavaScript 包装器负责字符串/数组与内存之间的转换。
|
||
|
||
### 证据要求
|
||
|
||
确认 WASM 函数是入口至少需要：
|
||
|
||
1. 网络证据：请求体包含 WASM 函数产生的结果。
|
||
2. 运行时证据：观察到 JavaScript 包装器以目标参数调用，并且返回值与请求字段一致。
|
||
|
||
仅观察到 WASM 加载、没有确认导出函数参与目标请求时，标记为 manual_observed_only。
|
||
|
||
### 限制
|
||
|
||
- WASM 内部逻辑未导出时，不能从 JavaScript 上下文调用，标记 strategy=unsupported，并填写 unsupported_reason。
|
||
- chrome-devtools-mcp 不能直接读取 WASM 内存。
|
||
- 不在范围内反编译 WASM 字节码。
|
||
- WASM 混淆时仍可使用导出函数接口，但不能仅凭接口理解内部逻辑。
|
||
|
||
---
|
||
|
||
## 4. Webpack 模块发现
|
||
|
||
### 概述
|
||
|
||
现代 Web 应用通常使用 Webpack 打包。目标入口可能位于 Webpack 模块闭包中，无法通过 window.* 直接访问。模块探针会发现模块系统，并尝试捕获 __webpack_require__，从而访问模块导出。
|
||
|
||
### 探针安装
|
||
|
||
生成：
|
||
|
||
~~~bash
|
||
python3 scripts/emit_module_probe.py --output generated/module_probe.js
|
||
~~~
|
||
|
||
注入：
|
||
|
||
- 通过 evaluate_script 注入。
|
||
- 安装前检查 window.__JSRA_MODULES__，保证重复注入不会重复安装。
|
||
|
||
### 探针检测内容
|
||
|
||
#### 分块数组
|
||
|
||
探针会在 window 上检测 Webpack 分块数组：
|
||
|
||
- Webpack 3/4：window.webpackJsonp，格式为 [chunkIds, modules, executeModules]。
|
||
- Webpack 5：符合 window.webpackChunk* 的数组，格式为 [[chunkIds], modules, runtime]。
|
||
- Loadable 组件：window.__LOADABLE_LOADED_CHUNKS__。
|
||
|
||
发现分块数组后，设置 module_runtime.detected = true，并将类型记录为 webpack4、webpack5 或 unknown。
|
||
|
||
#### 捕获 __webpack_require__
|
||
|
||
按以下顺序尝试三种策略：
|
||
|
||
**策略一：Hook webpackJsonp.push**
|
||
|
||
- 覆盖分块数组上的 Array.prototype.push。
|
||
- 新分块进入时，从模块工厂创建可加载模块的伪 require 函数。
|
||
- 将捕获到的函数保存为 window.__JSRA_require。
|
||
|
||
**策略二：检查已有暴露对象**
|
||
|
||
- 检查 window.__webpack_require__、window.__webpack_modules__ 和 window.webpackJsonp 中是否已有可用函数。
|
||
|
||
**策略三：扫描 window 中的 require 类函数**
|
||
|
||
- 遍历 window 属性，寻找带有 .c 模块缓存属性的函数。
|
||
|
||
#### 模块缓存枚举
|
||
|
||
捕获 __webpack_require__ 后，枚举 require.c 或 require.cache：
|
||
|
||
~~~js
|
||
var cache = require.c || require.cache || {};
|
||
var keys = Object.keys(cache);
|
||
for (var i = 0; i < keys.length; i++) {
|
||
var mod = cache[keys[i]];
|
||
if (mod && mod.exports) {
|
||
// 检查 mod.exports 中的函数
|
||
}
|
||
}
|
||
~~~
|
||
|
||
- 最多列出 500 个模块 ID。
|
||
- 导出值是函数时，记录 moduleId、exportName、type、前 200 个字符的 srcSnippet 和参数个数 arity。
|
||
- 导出值是带函数属性的对象时，记录形如 exportName.subKey 的子导出。
|
||
|
||
结果保存到 window.__JSRA_MODULES__.candidateExports。
|
||
|
||
### 证据读取
|
||
|
||
读取模块发现结果：
|
||
|
||
~~~js
|
||
evaluate_script("window.__JSRA_MODULES__.dump()")
|
||
~~~
|
||
|
||
结果包含：detected、type、requireAvailable、requirePath、moduleCacheKeys（最多 200 个）、candidateExports、chunkArrays、globalExports（最多 100 个）和 errors。
|
||
|
||
### 与运行时 Hook 证据交叉验证
|
||
|
||
必须把模块探针结果与运行时 Hook 证据交叉比对：
|
||
|
||
1. 从运行时追踪的 requests[].stack 中提取函数名或源码文件引用。
|
||
2. 在 candidateExports 中查找匹配的 exportName 或 srcSnippet 特征。
|
||
3. 只有同时出现在 Hook 调用栈和模块导出中的候选，才能标记为 confidence=high。
|
||
4. 仅出现在模块导出中、没有运行时 Hook 证据的候选，标记为 confidence=low。
|
||
|
||
交叉验证规则：候选导出必须与运行时 Hook 调用栈中观察到的函数匹配；不匹配时标记为 manual_observed_only。
|
||
|
||
### Webpack 导出的 JSRPC 生成
|
||
|
||
- 入口类型：webpack_export。
|
||
- entrypoint 必须包含 module_id 和 export_path，分别表示模块 ID 和导出名称路径，例如 encrypt 或 default.encrypt。
|
||
- JSRPC 使用 window.__JSRA_require(module_id) 获取模块，再通过 getByPath(module, export_path) 调用导出。
|
||
|
||
### 限制
|
||
|
||
- 如果应用不使用 webpackJsonp 或分块数组不可访问，捕获可能失败，标记 require_available: false。
|
||
- Webpack 动态 import() 产生的分块可能不在已捕获缓存中；探针可以观察请求，但不能稳定获取导出。
|
||
- 模块 ID 可能随构建变化；JSRPC 应使用运行时捕获的 require，不要硬编码模块 ID。
|
||
- 启用热更新时模块缓存可能失效，应关闭热更新，或在热更新运行前捕获 require。
|
||
|
||
---
|
||
|
||
## 5. Vite、Rollup 与 ESM
|
||
|
||
### 识别
|
||
|
||
- 文档中出现 <script type="module">。
|
||
- Vite 特征：import.meta.hot、window.__vite_plugin_meta__。
|
||
- Rollup 特征：window.__rollup_plugin__。
|
||
|
||
识别后，将 module_runtime.type 设置为 vite 或 rollup。
|
||
|
||
### 全局导出发现
|
||
|
||
即使使用 Vite/Rollup，部分库仍会暴露全局对象。模块探针的 detectGlobalExports() 会扫描 window：
|
||
|
||
- 带有密码学相关名称的函数：CryptoJS、JSEncrypt、md5、sha256、sha1、aes、Base64、encrypt、decrypt、sign、verify、hash、hmac。
|
||
- 函数属性名称符合密码学特征的对象。
|
||
|
||
结果保存在 window.__JSRA_MODULES__.globalExports。
|
||
|
||
### 限制
|
||
|
||
- ES 模块使用原生 import/export，不存在全局 require。
|
||
- 浏览器模块加载器属于内部实现，没有可直接 Hook 的导入解析入口，chrome-devtools-mcp 不能观察或修改原生模块解析。
|
||
- 动态 import() 返回 Promise，探针可以观察模块网络请求，但只有模块同时暴露到全局时才能捕获导出。
|
||
- Vite 的导入映射只提供 DOM 层面的映射信息，不能访问模块内部运行时对象。
|
||
- 如果加密逻辑运行在服务端，例如 Next.js SSR，则无法从浏览器上下文获取。
|
||
- 只能观察全局对象、模块脚本请求和 DOM 元素；不能可靠地动态调用 import() 并捕获导出。
|
||
|
||
### Vite/Rollup 页面处理策略
|
||
|
||
1. 在 globalExports 中查找暴露的密码学库。
|
||
2. 找到后使用 global_path 策略。
|
||
3. 未找到时，检查目标参数是否流经运行时 Hook 捕获的 fetch/XHR，再根据源码位置从请求体回溯。
|
||
4. 入口位于没有全局导出的 ES 模块闭包时，标记 manual_observed_only，记录观察结果供人工复现。
|
||
|
||
---
|
||
|
||
## 6. 闭包作用域函数
|
||
|
||
### 可以执行的操作
|
||
|
||
- 函数通过模块系统导出：使用 Webpack 捕获。
|
||
- 函数流经 fetch/XHR/crypto Hook：通过调用栈回溯。
|
||
- 函数位于 window：直接查找路径。
|
||
|
||
### 不可以执行的操作
|
||
|
||
- 调用未导出的闭包函数。
|
||
- 从外部重建词法作用域。
|
||
- 访问闭包捕获的变量。
|
||
|
||
### 可接受的替代方案
|
||
|
||
1. **Hook 边界**：闭包调用 fetch、XMLHttpRequest.send 或 JSON.stringify 时，Hook 外层边界截获数据。
|
||
2. **Hook 密码学 API**：闭包使用 crypto.subtle、CryptoJS 或 JSEncrypt 时，Hook 库获取输入和输出。
|
||
3. **解析器策略**：闭包通过动态解析器暴露目标函数时，捕获解析器。
|
||
4. **Webpack 模块访问**：闭包属于 Webpack 模块时，使用模块探针捕获 __webpack_require__ 并访问导出。
|
||
|
||
### 何时标记为不支持
|
||
|
||
以上方案都无法访问函数时，标记为：
|
||
|
||
~~~json
|
||
{
|
||
"entrypoint_discovery": {
|
||
"strategy": "unsupported",
|
||
"confidence": "high",
|
||
"unsupported_reason": "入口位于没有导出引用、没有可 Hook 边界且无法访问模块系统的闭包中。"
|
||
}
|
||
}
|
||
~~~
|
||
|
||
### 禁止事项
|
||
|
||
- 不得声称未导出的闭包函数可调用。
|
||
- 不得为运行时无法解析的函数生成 JSRPC 动作。
|
||
- 不能仅凭静态源码分析猜测闭包内部结构。
|
||
|
||
---
|
||
|
||
## 7. 策略选择参考
|
||
|
||
| 场景 | 策略 | 是否生成 JSRPC 动作 |
|
||
|---|---|---|
|
||
| 函数位于 window.xxx.yyy | global_path | 是 |
|
||
| 通过软 Hook 调用栈发现函数 | runtime_hook | 是 |
|
||
| 函数位于 Webpack 模块缓存 | webpack_export | 是（需要已捕获的 require） |
|
||
| 异步函数（crypto.subtle、Promise） | async_crypto | 是（必须处理 Promise） |
|
||
| 函数由 WASM 模块导出 | wasm_export | 是 |
|
||
| 有证据但尚未确认入口 | manual_observed_only | 否（输出证据供人工使用） |
|
||
| 函数不可访问（未导出闭包、WASM 内部函数、Service Worker 内部闭包） | unsupported | 否（输出 unsupported_reason） |
|
||
|
||
---
|
||
|
||
## 8. 复杂场景的置信度要求
|
||
|
||
| 场景 | high 置信度的最低要求 |
|
||
|---|---|
|
||
| async_crypto | 网络证据（请求体）+ 匹配算法和调用栈的 crypto[] 事件 |
|
||
| webpack_export | 网络证据 + candidateExports 匹配 + 运行时 Hook 调用栈交叉验证 |
|
||
| wasm_export | 网络证据 + 观察到 JavaScript 包装器调用且输入输出匹配 |
|
||
| global_path | 网络证据 + 通过 evaluate_script 观察到函数调用 |
|
||
| runtime_hook | 网络证据 + Hook 捕获的、经过业务函数的调用栈 |
|