| name | web-env-patcher |
| description | Web JS Node 补环境工程化 skill。接在 ruyi-reverse / mcp-js-reverse-playbook 的浏览器取证之后，用于 cURL/HAR 输入检查、动态资源保鲜、Trace API 覆盖矩阵、Node 宿主泄露阻断、fixture 对比、浏览器指纹终端 API 回放设计和最终请求 TLS 客户端门禁。所有补环境 runtime 必须独立隔离，禁止切换或污染项目主 Node/MCP 环境。
|
Web Env Patcher（网页端 Node 补环境工程）
定位
本 skill 专门处理网页端 JavaScript 从浏览器取证材料落到 Node.js 补环境工程的中间层。
它不是 Web 逆向入口，也不是协议采集器交付入口：
ruyi-reverse / mcp-js-reverse-playbook
-> web-deobfuscation（当混淆、JSVMP 或 WASM 边界是核心阻塞）
-> web-env-patcher（当浏览器环境依赖是核心阻塞）
-> protocol-recovery
ruyi-reverse：负责反检测浏览器、RuyiTrace、网络取证、源码和运行时定位。mcp-js-reverse-playbook：仅在无强反检测且需要 CDP 断点/单步时使用。web-deobfuscation：负责 safe AST、可验证 JSVMP 和可观察 JS/WASM 边界的证据门禁。web-env-patcher：负责把浏览器证据工程化为 Node.js 补环境、fixtures、coverage matrix 和最终请求验证门禁。protocol-recovery：在 signer / decoder / session chain 已确认后，打包 Python 采集器或协议复现工程。
补环境判断矩阵
| 现象 / 阻塞点 | 路由 | 说明 |
|---|
| 页面打不开、需要过风控 / 验证码 / 指纹 / 行为 / RuyiTrace | ruyi-reverse | 先拿到可信浏览器证据，不要直接补环境。 |
| 需要 CDP 断点、单步、作用域，且目标无强反检测 | mcp-js-reverse-playbook | 先完成 request initiator、断点样本和源码定位。 |
| 已有浏览器取证，但目标 JS 脱离浏览器在 Node 中跑不起来 | web-env-patcher | 本 skill 主场：补 WebAPI、Node 泄露阻断和 fixtures。 |
sign / token / x-s / a_bogus / h5st 依赖 window/document/navigator/storage/crypto/performance/canvas/webgl | web-env-patcher | 先做 Trace API inventory 和 env coverage matrix。 |
| 需要 Trace API inventory、env coverage matrix、Node 泄露阻断、fixtures 对齐 | web-env-patcher | 必须有浏览器真实样本作为对照。 |
| 纯算法签名，无浏览器环境依赖，样本字段已确认 | protocol-recovery | 不要为了纯 MD5/AES/HMAC 强行补环境。 |
| Node 输出已与浏览器 fixtures 对齐，需要 Python collector / final request | protocol-recovery | 本 skill 到此结束，进入协议交付。 |
| AST 混淆、JSVMP / VM opcode 或 JS/WASM 边界是核心阻塞 | web-deobfuscation | 先跑只读 gate；有 opcode/boundary Trace 与 fixture 才允许 L3/partial，否则保持 triage-only。 |
硬边界
- 只处理网页端 / 浏览器端 JavaScript 的 Node.js 补环境。
- 不处理 Android、iOS、小程序、EXE、DLL、SO、Frida、IDA、JADX、Native patch。
- 不替代
ruyi-reverse 做页面打开、反检测、trace 采集和交互取证。
- 不替代
protocol-recovery 做最终 Python 采集器交付。
- 默认不主动分析 JSVMP / WASM / VM 字节码；遇到该类目标时记录环境依赖，并切换到
web-deobfuscation 做独立证据分级，不在本 skill 内冒充算法恢复。
环境隔离硬约束
补环境可能引入 Node ABI 敏感的 .node addon、魔改 isolated-vm、TLS 指纹客户端、浏览器 profile 和临时依赖。为避免弄坏整个 D:\reverse_ENV，必须遵守以下规则：
- 禁止切换项目主 Node：
D:\reverse_ENV\tools\node\node.exe 是 MCP / 项目默认 Node，不得为了补环境 addon 改版本、覆盖目录或替换二进制。
- 独立 runtime 目录：需要 Node 25/26、xbs addon、魔改 isolated-vm、CycleTLS、impers、curl-cffi-node 时，只能放在
D:\reverse_ENV\tools\web-env\runtimes\ 或 D:\reverse_ENV\workspace\<项目名>\.runtime\。
- 显式路径调用：所有
node、python、npm、浏览器、RuyiTrace、TLS 客户端检测都必须使用绝对路径；不得依赖系统 PATH。
- 不自动安装依赖：不得未经用户确认运行
npm install、pip install、nvm use、nvm install 或覆盖 runtime。缺依赖时只报告候选命令和隔离落点。
- 不全局设置环境变量：只允许在当前进程或 wrapper 脚本内临时设置
RUYI_TRACE_HOME、WEB_JS_ENV_PATCHER_ADDON 等变量；不得写入系统用户环境变量。
- 不把外部 skill 直接启用为项目 skill：
storage\xbsReverseSkill 仅作为参考/可选脚本来源；项目唯一入口是本 skill 和 tools\web-env wrapper。
- case 内隔离状态：浏览器 profile、Cookie jar、HAR、fixtures、日志、临时 JS、TLS 采样结果必须落在
D:\reverse_ENV\workspace\<项目名>\ 下，不得散落 workspace\ 根目录或 tools\。
- ABI 先检后用：任何
.node addon 或 isolated-vm 在使用前必须运行隔离检查；ABI 不匹配时不得 fallback 成“已成功”，只能降级为纯 JS 流程或记录 native capability gap。
标准工作流
0. 前置门禁
启动前必须已完成至少一种浏览器取证：
ruyi-reverse 产出的请求、脚本、trace、Cookie/Storage、fingerprint baseline；或mcp-js-reverse-playbook 产出的 request initiator、断点样本、源码片段、运行时参数。
如果还没有这些证据，返回上游 skill，不要直接补环境。
1. 输入检查
目标：确认用户提供的 cURL / HAR / HTML / JS / 响应样本是否足以开始补环境。
应检查：
- 目标 URL、方法、Header、Cookie、Body 是否完整。
- sign / token / x-s / a_bogus / h5st / w_rid / captcha 参数位于 query、header、body 还是 cookie。
- 样本中的动态值是否只是历史 fixture，不能硬编码复用。
- 用户样本浏览器族与取证 baseline 是否冲突。
- 敏感字段是否需要 scrub 后进入 evidence。
2. 动态资源保鲜
目标：防止固定过期 HTML / JS bundle / challenge JS。
必须记录：
- 资源 URL、hash、采集时间、响应头、cache-control、etag、last-modified。
- 是否运行时刷新资源。
- 最终
runner.js / final.js 是否仍使用旧快照。
3. Trace API inventory
目标：把浏览器/RuyiTrace/Node trace 中出现的 WebAPI 转成补环境待办，而不是等报错才补。
标准产物：
D:\reverse_ENV\workspace\<项目名>\evidence\trace-api-inventory.json
D:\reverse_ENV\workspace\<项目名>\evidence\env-coverage-matrix.md
覆盖矩阵至少包含：
| 字段 | 说明 |
|---|
api | 被访问的 WebAPI / 属性 / 方法 |
source | RuyiTrace / browser hook / Node trace / manual evidence |
count | 调用次数 |
stack | 脱敏调用栈或脚本位置 |
strategy | implement / fixture-replay / sample-browser / native-gap / ignore |
status | pending / done / blocked / triage-only |
evidence | 本地证据路径 |
4. Node 泄露阻断
补环境运行前必须检查宿主 Node 泄露：
process、Buffer、require、module、global。- Node 自带
navigator、localStorage、sessionStorage。
performance.nodeTiming、eventLoopUtilization、timerify。- 宿主
fetch、WebSocket、Streams、Events。
crypto、URL、TextEncoder、WebAssembly 是否与浏览器 baseline 冲突。
5. Env 模块实现
按 coverage matrix 补环境，禁止一个巨型 env.js 糊到底。推荐结构：
workspace\<项目名>\src\env\
window.js
document.js
navigator.js
storage.js
crypto.js
performance.js
fingerprint.js
原则：
- 先补实际命中的 API，再补推断 API。
- 指纹终端 API 优先真实浏览器采样回放，不瞎模拟渲染结果。
document.all、prototype chain、descriptor、getter/setter、Function.prototype.toString、Symbol.toStringTag 必须作为高强度检测项单独记录。- addon / isolated-vm 不可用时，明确记录 JS fallback 风险。
6. Fixtures 验证
必须用浏览器真实样本对比 Node 输出。
标准产物：
workspace\<项目名>\fixtures\browser-output.fixture.json
workspace\<项目名>\fixtures\node-output.fixture.json
workspace\<项目名>\fixtures\fingerprint.fixture.json
workspace\<项目名>\notes\fixture-validation.md
至少记录：
- 样本数量、通过数量、失败数量。
- 是否固定时间、随机数、Cookie、Storage、UA、语言、时区、代理。
- 失败字段、first divergence、下一步补环境策略。
7. 最终请求 TLS 门禁
如果需要发送真实请求或交付可请求 final.js / final.py，必须先选择最终请求客户端：
- Node.js：CycleTLS / impers / curl-cffi-node / 不发真实请求。
- Python：curl_cffi / cffi_curl / cyCronet / 不发真实请求。
规则：
- 最终请求必须 Session 模式。
- UA、Client Hints、Accept-Language、Header 顺序、Cookie jar、代理、TLS / JA3 / JA4 / HTTP2 指纹必须来自同一取证 baseline。
- Firefox baseline 不得混用 Chrome
sec-ch-ua。
- 普通
fetch / requests 失败后临时切 TLS 客户端不合格；客户端选择必须前置记录。
工作区推荐结构
D:\reverse_ENV\workspace\<项目名>\
captures\
request.har
request.curl
ruyitrace.ndjson
samples\
raw\
scrubbed\
fixtures\
request.fixture.json
browser-output.fixture.json
node-output.fixture.json
fingerprint.fixture.json
src\
env\
signer\
runner.js
evidence\
trace-api-inventory.json
env-coverage-matrix.md
redaction-map.json
notes\
runtime-precheck.md
node-leakage.md
final-request-validation.md
code-change-memory.md
report.md
findings.json
triage.md
工具入口
项目封装脚本位于 D:\reverse_ENV\tools\web-env\：
| 脚本 | 用途 |
|---|
check-isolation.ps1 | 检查主 Node、可选 xbs clone、RuyiTrace 路径、addon ABI 状态，确认补环境隔离边界。 |
invoke-xbs-script.ps1 | 只读调用 storage\xbsReverseSkill\web-js-env-patcher\scripts\*.js 中的纯 JS 检查器，强制绝对路径和临时环境变量。 |
调用示例：
powershell -File "D:\reverse_ENV\tools\web-env\check-isolation.ps1"
powershell -File "D:\reverse_ENV\tools\web-env\invoke-xbs-script.ps1" -Script "check_tls_clients.js" -ScriptArgs "--markdown"
借鉴来源
本 skill 吸收了 D:\reverse_ENV\storage\xbsReverseSkill\web-js-env-patcher 的补环境流程思想，但不直接启用其外部 skill，也不默认加载其 native addon / isolated-vm 二进制。该仓库为 MIT License；若后续复制具体实现代码到 Git 管理范围，应保留来源说明并做路径、编码、隔离改造。
交付标准
一次合格的 web-env-patcher 任务最终必须提供：
report.md：结论、证据路径、复用来源、环境隔离状态。findings.json：结构化 claim、evidence、redaction、confidence、rebuild_status。triage.md：未补 API、native capability gap、TLS/指纹差异、JS fallback 风险。evidence/env-coverage-matrix.md：Trace 命中 API 的处理状态。notes/final-request-validation.md：如果发送真实请求，记录 TLS/session/client baseline；如果不发送，明确说明。
不得声称“补环境完成”，除非 fixtures 已对齐、coverage matrix 无未解释关键 API、最终请求门禁已通过或明确标注不发真实请求。
