462 lines
19 KiB
Markdown
462 lines
19 KiB
Markdown
# 补环境前置流程
|
||
|
||
本文件用于指导写补环境代码之前的详细流程。
|
||
|
||
## 阶段 -1：新 case 第一回复硬门禁
|
||
|
||
每次用户给出新网站、新接口、新 cURL / HAR、旧补环境文件，或要求“帮我分析 / 补环境 / 成功请求到数据”时，第一回复先做门禁检查，不直接进入取证或补环境。
|
||
|
||
即使用户提供了很长的 cURL、Cookie、403/200 现象、JS 文件线索、旧代码文件名，仍然不能把它视为已经通过主流程。cURL 只是请求样本，不等于取证模式已确认，也不等于最终请求 TLS 客户端已确认。
|
||
|
||
第一回复必须输出：
|
||
|
||
```markdown
|
||
## 信息完整性检查
|
||
|
||
### 已识别信息
|
||
- 目标网站 / 页面：
|
||
- 目标 API：
|
||
- 请求方法：
|
||
- 已提供请求样本：
|
||
- 已知响应现象：
|
||
- 已知旧代码 / JS 文件：
|
||
- 用户已明确的目标参数：
|
||
|
||
### 缺失 / 待确认信息
|
||
- 取证模式：未确认 / ruyiPage + RuyiTrace / 仅 ruyiPage / Camoufox + camoufox-reverse-mcp / 仅 Camoufox / CloakBrowser / 用户手动取证 / AI 自行决定
|
||
- 最终请求 TLS 指纹兼容客户端：未确认 / Node.js CycleTLS / Node.js impers / Node.js curl-cffi / Python curl_cffi / Python cffi_curl / Python cyCronet / 不发真实请求
|
||
- 是否有授权测试权限：
|
||
- 是否需要登录：
|
||
- 本次确认要分析的加密 / 风控参数：
|
||
- 是否允许创建 case 目录和阶段报告：
|
||
|
||
### 初步发现的可疑参数候选
|
||
| 参数名 | 位置 | 疑似原因 | 是否等待用户确认 |
|
||
|---|---|---|---|
|
||
| | Query / Header / Body / Cookie | | 是 |
|
||
|
||
### 暂停说明
|
||
在你确认取证模式、最终请求客户端和本次分析参数前，我不会启动浏览器取证、下载 JS、运行 Hook、修改或运行旧补环境代码、复用 cURL 中的动态参数，也不会发送真实请求。
|
||
```
|
||
|
||
如果缺少取证模式或最终请求 TLS 客户端，第一回复必须停在本阶段和阶段 0.5 / 0.6；只能继续做离线整理、列缺失项和生成 `case/阶段报告/01-需求信息确认.md`，不能进入请求验证、JS 收集、入口定位、Node trace 或补环境代码。
|
||
|
||
## 阶段 0：范围确认
|
||
|
||
确认以下事项：
|
||
|
||
- 目标是网页端 / 浏览器端 JavaScript。
|
||
- 用户要求的是 Node.js 补环境。
|
||
- 排除 App、移动端、小程序、Windows、Native 等方向。
|
||
- 当前目标不是纯算重写。
|
||
- 浏览器自动化只用于前置取证，不用于批量采集。
|
||
- 用户有授权测试范围。
|
||
|
||
任一条件不满足时，停止并说明 Skill 边界。
|
||
|
||
## 阶段 0.5：取证模式确认
|
||
|
||
在信息校验、请求样本验证、JS 文件收集、Hook、断点、截图、RuyiTrace 日志采集等任何取证动作之前，必须先让用户选择取证模式：
|
||
|
||
1. ruyiPage + RuyiTrace（推荐）。
|
||
2. 仅 ruyiPage。
|
||
3. Camoufox + camoufox-reverse-mcp。
|
||
4. 仅 Camoufox。
|
||
5. CloakBrowser。
|
||
6. 用户手动取证。
|
||
7. AI 自行决定。
|
||
|
||
确认后把选择记录为本 case 的取证模式，并在后续所有浏览器取证动作中沿用。不要等确认有自动化检测后再启用 ruyiPage / RuyiTrace。不要在用户已选择 ruyiPage / CloakBrowser / 手动取证后，自行改用普通 Playwright、Puppeteer 或系统 Firefox。
|
||
|
||
如果所选工具不可用或后续需要切换工具，暂停并重新让用户确认。
|
||
|
||
如果用户选择 ruyiPage + RuyiTrace，但检测到 RuyiTrace 未安装或目录不完整，不能自动降级为仅 ruyiPage。必须先提示用户选择“安装 / 提供 RuyiTrace 路径”或“明确降级为仅 ruyiPage”；用户选择安装时，等待用户完成安装并重新检测通过后，才继续需要 NDJSON 的流程。
|
||
|
||
如果用户没有明确选择取证模式，不能因为用户提供了 cURL、Cookie、目标站 URL、旧代码或“请成功请求到数据”的要求而默认启动任何浏览器工具。只能给出取证模式选项并等待确认；如果用户选择“AI 自行决定”，也必须先检测工具并回报拟用方案，等待用户确认后再启动。
|
||
|
||
## 阶段 0.6：最终请求 TLS 指纹兼容客户端确认
|
||
|
||
如果本 case 最终需要发送真实请求或交付 `final.js` / `final.py`，必须在前置阶段就选择最终请求客户端，不要等普通 `fetch` / `requests` 失败后再临时切换。
|
||
|
||
可选项：
|
||
|
||
1. Node.js CycleTLS。
|
||
2. Node.js impers。
|
||
3. Python curl_cffi。
|
||
4. Python cffi_curl。
|
||
5. Python cyCronet。
|
||
6. 不发真实请求，只输出本地 sign / 参数。
|
||
|
||
确认后立即运行：
|
||
|
||
```bash
|
||
node scripts/check_tls_clients.js --markdown
|
||
node scripts/check_tls_clients.js --python python --markdown
|
||
```
|
||
|
||
如果用户选择的库未安装，先让用户确认安装、改选其他已安装客户端，或选择“不发真实请求”。TLS 指纹兼容仅用于授权范围内少量最终验证请求，不用于批量访问、绕过登录、验证码、MFA、付费墙或访问控制。
|
||
|
||
## 阶段 0.7：阶段报告初始化
|
||
|
||
从用户提供第一轮需求信息开始，默认创建 `case/阶段报告/01-需求信息确认.md`，记录目标 URL、API、取证选项、加密参数、加密文件 / JS 文件、已提供样本、缺失项和下一步待确认问题。即使信息不完整，也要生成该阶段报告。
|
||
|
||
推荐命令：
|
||
|
||
```bash
|
||
node scripts/write_stage_report.js --case-dir case --stage 需求信息确认 --data case/notes/需求信息.json --markdown
|
||
node scripts/check_stage_reports.js --case-dir case --require-stage 需求信息确认 --markdown
|
||
```
|
||
|
||
后续阶段结束时继续写入 `02-取证方案确认.md`、`03-请求样本与可疑参数确认.md`、`04-JS文件与入口定位.md`、`05-补环境前置分析.md`、`06-补环境实现记录.md`、`07-验证与清理记录.md`。所有 Markdown 文件名必须包含中文。
|
||
|
||
## 阶段 1：信息完整性检查
|
||
|
||
必填信息：
|
||
|
||
1. 目标网站或目标页面 URL。
|
||
2. 目标接口 API URL。
|
||
3. 请求方法。
|
||
4. 目标加密参数名。
|
||
5. 参数位置：Query / Header / Body / Cookie。
|
||
6. 至少一份成功请求样本，优先 Copy as cURL。
|
||
7. 取证模式：ruyiPage + RuyiTrace / 仅 ruyiPage / Camoufox + camoufox-reverse-mcp / 仅 Camoufox / CloakBrowser / 用户手动取证 / AI 自行决定。
|
||
8. 最终请求 TLS 指纹兼容客户端：Node.js CycleTLS / Node.js impers / Node.js curl-cffi / Python curl_cffi / Python cffi_curl / Python cyCronet / 不发真实请求。
|
||
|
||
如果信息不完整，列出缺失项，并使用 `intake-template.md` 让用户补充。
|
||
|
||
如果信息完整，先整理任务摘要并请求用户确认，不要直接进入分析。
|
||
|
||
强制阻断项：
|
||
|
||
- 未确认取证模式：不得打开网页、抓包、Hook、截图、下载 JS 或采集 RuyiTrace。
|
||
- 未确认最终请求 TLS 客户端且任务要求成功请求：不得发送真实请求，也不得先用普通 HTTP 客户端试错。
|
||
- 未确认本次分析参数：不得只盯用户指定参数进入补环境；必须先列出 Query / Header / Body / Cookie 中所有可疑候选并让用户确认。
|
||
- 未确认授权 / 登录状态：不得尝试绕过登录、验证码、MFA、风控或访问控制。
|
||
|
||
## 阶段 2：请求样本检查
|
||
|
||
检查内容：
|
||
|
||
| 检查项 | 目的 |
|
||
|---|---|
|
||
| URL 是否完整 | 是否包含协议、域名、路径 |
|
||
| 请求方法是否明确 | GET / POST / PUT 等 |
|
||
| 请求头是否完整 | UA、Content-Type、Cookie、Referer、Origin 等 |
|
||
| Body 是否完整 | POST / PUT 请求是否包含请求体 |
|
||
| 目标参数是否存在 | 是否能在用户声明的位置找到参数 |
|
||
| 响应样本是否成功 | 判断样本是否是有效请求 |
|
||
| 取证模式是否一致 | 后续抓包、JS 收集、Hook、截图和日志采集是否都沿用用户选择的工具 |
|
||
| Cookie/token 是否过期 | 先判断是登录态授权 Cookie，还是非登录生成型 Cookie |
|
||
| 最终请求客户端是否已选 | 从一开始确认 CycleTLS / impers / curl_cffi / cffi_curl / cyCronet / 不发真实请求 |
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## 请求样本检查结果
|
||
|
||
- 请求是否完整：
|
||
- 目标参数是否存在：
|
||
- 参数位置是否一致：
|
||
- 是否缺少关键 Header：
|
||
- 是否缺少 Cookie / token：
|
||
- Cookie/token 是否过期：
|
||
- Cookie 分类：登录态 / 非登录生成型 / 未确认
|
||
- 最终请求 TLS 指纹兼容客户端：
|
||
- 是否可以进入下一步：
|
||
```
|
||
|
||
## 阶段 2.2：可疑加密参数发现与用户确认
|
||
|
||
在正式补环境前，必须先从 cURL / HAR / 请求样本中列出所有可疑加密参数，并让用户确认本次要分析哪些。不要只复用用户给出的 `--param`，也不要只盯一个参数。
|
||
|
||
执行建议：
|
||
|
||
```bash
|
||
node scripts/parse_curl.js --input request.curl --json
|
||
node scripts/parse_curl.js --input request.curl --markdown
|
||
```
|
||
|
||
必须覆盖的位置：Query、Header、Body、Cookie。重点关注 sign、token、a_bogus、h5st、x-s、x-t、mtgsig、w_rid、_signature、nonce、hash、设备 Cookie、风控 Cookie、JS 生成 Cookie 等。
|
||
|
||
输出给用户确认：
|
||
|
||
```markdown
|
||
## 发现的可疑加密参数
|
||
|
||
| 参数名 | 位置 | 样本值摘要 | 疑似原因 | 是否建议分析 |
|
||
|---|---|---|---|---|
|
||
| | Query/Header/Body/Cookie | 脱敏 | | 是/否 |
|
||
|
||
请确认本次要分析哪些参数。确认前我不会进入正式补环境。
|
||
```
|
||
|
||
同时写入 `case/阶段报告/03-请求样本与可疑参数确认.md`，记录候选参数、用户确认状态和未确认项。
|
||
|
||
确认规则：
|
||
|
||
- 如果用户已经指定目标参数，也要提示其他候选参数，询问是否需要一并分析。
|
||
- 用户未确认目标参数列表前，不进入 `env.js` 编写、Node trace 或补环境阶段。
|
||
- cURL 中已有参数值只能作为浏览器真实样本 / fixture expected，不能作为最终产物中的固定值。
|
||
- 如果某个候选是登录态 token / Authorization，先回到登录与授权边界，不做绕过。
|
||
|
||
## 阶段 2.5：Cookie 过期与来源分类
|
||
|
||
当请求失败疑似由 Cookie/token 过期、Cookie 缺失、Cookie 写入失败或参数位置为 Cookie 引起时，先分类，不要默认要求用户重新给一份新 Cookie。
|
||
|
||
| 类型 | 处理方式 |
|
||
|---|---|
|
||
| 登录态 / 授权 Cookie | 不绕过登录；让用户手动登录或提供授权样本 |
|
||
| 服务端 `Set-Cookie` 首访 Cookie | 分析是否可通过前置 Node.js / Python 请求刷新，并写入最终请求客户端 |
|
||
| `document.cookie` 写入 Cookie | Hook setter 或用 RuyiTrace 查 `document.cookie` / `Document.cookie` 调用栈，定位 writer |
|
||
| JS 计算生成 Cookie | 按 `source → entry → builder → writer` 定位生成函数，并纳入补环境 |
|
||
| Storage / 指纹 / challenge 派生 Cookie | 分析 localStorage / sessionStorage / 指纹对象 / server seed / timestamp 等依赖 |
|
||
| 一次性服务端 challenge 或账号绑定 Cookie | 说明不可或不应复现，要求用户授权交互或离线样本 |
|
||
|
||
输出模板：
|
||
|
||
```markdown
|
||
## Cookie 过期处理判断
|
||
|
||
- Cookie 名称：
|
||
- 是否需要登录：
|
||
- 是否账号 / 授权相关：
|
||
- 来源判断：Set-Cookie / document.cookie / JS 计算 / Storage 派生 / challenge / 未确认
|
||
- 是否可生成或刷新：
|
||
- 生成链路 source / entry / builder / writer：
|
||
- 是否纳入补环境：
|
||
- 是否需要用户手动登录：是 / 否
|
||
```
|
||
|
||
结论规则：
|
||
|
||
- 对不需要登录的网站，优先分析非登录 Cookie 如何生成 / 刷新。
|
||
- 只有 Cookie 明确属于登录态 / 授权态、服务端一次性下发且无法 / 不应复现、或用户确认只做一次离线样本复现时，才要求用户重新提供有效 Cookie。
|
||
|
||
## 阶段 3：加密参数画像
|
||
|
||
仅对用户确认要分析的参数做画像。对未确认的候选参数，只保留在 notes 中作为备选证据，不要擅自进入补环境。
|
||
|
||
在补环境前先描述参数特征：
|
||
|
||
| 维度 | 要回答的问题 |
|
||
|---|---|
|
||
| 参数名 | sign / x-s / a_bogus / h5st / token 等 |
|
||
| 参数位置 | Query / Header / Body / Cookie |
|
||
| 是否动态 | 每次请求是否变化 |
|
||
| 是否依赖请求体 | Body 改变后参数是否变化 |
|
||
| 是否依赖 URL | path / query 是否参与签名 |
|
||
| 是否依赖 Cookie | 是否受登录态影响 |
|
||
| 是否依赖存储 | 是否读取 localStorage / sessionStorage |
|
||
| 是否依赖浏览器指纹 | navigator / canvas / WebGL / screen 等 |
|
||
| 是否依赖时间或随机数 | timestamp / nonce / random / server seed 等 |
|
||
| 是否已有 RuyiTrace 日志 | 是否有 NDJSON 环境访问日志可用于补环境优先级 |
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## 加密参数画像
|
||
|
||
- 参数名：
|
||
- 位置：
|
||
- 是否动态：
|
||
- 已知依赖：
|
||
- 疑似依赖：
|
||
- 需要补充的样本：
|
||
```
|
||
|
||
## 阶段 4：加密入口定位
|
||
|
||
目标是找到生成加密参数的函数或模块。
|
||
|
||
定位必须按 `source → entry → builder → writer` 四层链路记录：
|
||
|
||
| 层级 | 必须回答 |
|
||
|---|---|
|
||
| source | 签名输入来自 URL、Body、Cookie、Storage、时间随机数、指纹中的哪些字段 |
|
||
| entry | 哪个函数或模块生成签名或中间签名 |
|
||
| builder | 哪个请求构造函数把签名拼入请求对象 |
|
||
| writer | 最终由 fetch/XHR/Header/Query/Body/Cookie 哪个位置写入网络请求 |
|
||
|
||
如果只找到 `entry` 但无法确认 `writer`，只能标记为“疑似入口”，不能进入正式补环境。阶段结束时写入 `case/阶段报告/04-JS文件与入口定位.md`。
|
||
|
||
优先方法：
|
||
|
||
1. 查看 Network Initiator。
|
||
2. 使用 XHR / fetch 断点。
|
||
3. 搜索参数名。
|
||
4. Hook 关键 API 记录调用栈。
|
||
5. 分析 Stack Trace。
|
||
6. 如果有 sourcemap，优先结合 sourcemap。
|
||
7. 定位 webpack / vite / runtime 模块和动态 chunk。
|
||
|
||
Hook 模板见 `hook-templates.md`。复杂链路见 `crypto-entry-location.md`。
|
||
|
||
常用搜索词：
|
||
|
||
```text
|
||
sign
|
||
token
|
||
x-s
|
||
a_bogus
|
||
h5st
|
||
setRequestHeader
|
||
fetch(
|
||
XMLHttpRequest
|
||
JSON.stringify
|
||
localStorage.getItem
|
||
document.cookie
|
||
crypto
|
||
```
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## 加密入口定位
|
||
|
||
- 入口函数：
|
||
- 所在 JS 文件：
|
||
- 行列号：
|
||
- 调用链：
|
||
- 输入参数：
|
||
- 输出参数：
|
||
- 是否依赖浏览器环境：
|
||
- 是否需要继续补充 DevTools 信息：
|
||
```
|
||
|
||
## 阶段 5：JS 文件收集
|
||
|
||
只收集加密链路需要的文件：
|
||
|
||
- 主 bundle。
|
||
- 动态 chunk。
|
||
- runtime chunk。
|
||
- sourcemap。
|
||
- WASM 文件仅限网页端 JS 依赖，不扩展到 Native 逆向。
|
||
- 加密入口函数所在文件。
|
||
|
||
建议 case 目录：
|
||
|
||
```text
|
||
case/
|
||
├── js/
|
||
│ ├── original/
|
||
│ ├── pretty/
|
||
│ └── extracted/
|
||
├── requests/
|
||
├── fixtures/
|
||
├── notes/
|
||
└── tmp/
|
||
```
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## JS 文件收集结果
|
||
|
||
- 已获取 JS 文件：
|
||
- 未获取 JS 文件：
|
||
- 是否存在 sourcemap：
|
||
- 是否存在动态 chunk：
|
||
- 是否存在 runtime：
|
||
- 是否存在 WASM：
|
||
- 是否可以进入补环境准备：
|
||
```
|
||
|
||
## 阶段 5.2：动态 HTML / JS 资源保鲜检查
|
||
|
||
下载或保存 HTML、JS bundle、动态 chunk、challenge JS、403/风控页面和内联脚本后，先判断这些资源是长期静态文件，还是会随时间、会话、Cookie、seed、nonce、地域或 TLS 指纹变化的动态资源。
|
||
|
||
强制规则：
|
||
|
||
- 本地动态 HTML / JS 只能作为分析快照，不得直接进入最终产物主路径。
|
||
- 对每个资源记录 URL、请求时间、状态码、响应头、Set-Cookie、body sha256、Cache-Control、Expires、ETag、Last-Modified、依赖 Cookie / seed / nonce、动态性判定、最终使用方式。
|
||
- 将清单写入 `case/notes/resource-manifest.json`。
|
||
- 命中 `no-store/no-cache/private/max-age=0`、短 TTL、随机 query、同 URL 多次 hash 变化、HTML 内 seed / nonce / challenge 变化、403 challenge JS、会话绑定 Cookie 时，最终入口必须实现运行时刷新。
|
||
- 最终入口应先重新请求当前 HTML / JS / challenge / seed，再运行补环境生成参数和发送请求。
|
||
|
||
推荐命令：
|
||
|
||
```bash
|
||
node scripts/check_dynamic_resources.js --case-dir case --markdown
|
||
node scripts/check_dynamic_resources.js --case-dir case --require-runtime-refresh --markdown
|
||
```
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## 动态资源保鲜检查
|
||
|
||
- 动态 HTML / JS：有 / 无
|
||
- 分析快照目录：
|
||
- 资源 manifest：
|
||
- 影响最终生成参数的动态资源：
|
||
- 最终运行时刷新模块：
|
||
- 是否允许进入补环境准备：
|
||
```
|
||
|
||
如果动态资源影响目标参数生成，但尚未设计运行时刷新链路，不得进入最终交付；如果因此请求失败，先刷新资源和 seed，再判断是否继续补 WebAPI。
|
||
|
||
## 阶段 5.5：RuyiTrace NDJSON 优先分析
|
||
|
||
如果取证模式为 ruyiPage + RuyiTrace，本阶段必须在进入 Node.js 补环境前执行。不要等 Node.js 报错后才临时查看日志。
|
||
|
||
1. 确认是否已有 RuyiTrace NDJSON。
|
||
- 如果 RuyiTrace 未安装或目录不完整，先回到“阶段 0.5：取证模式确认”，要求用户安装 / 提供路径或明确降级；不得直接跳过本阶段进入 Node trace。
|
||
2. 尚未导入时先执行：
|
||
|
||
```bash
|
||
node scripts/import_ruyitrace_log.js --input <trace.ndjson> --case-dir case --markdown
|
||
```
|
||
|
||
3. 阅读 `notes/ruyitrace-summary.md`，按目标参数生成、目标 API 请求发起、writer 写入附近的 `api` 和 `stack.file / line / col` 汇总环境依赖。
|
||
4. 将结论写入：
|
||
- `notes/ruyitrace-summary.md`
|
||
- `notes/missing-env-priority.md`
|
||
- `notes/entry-chain.md`
|
||
5. 只有日志缺失、未覆盖当前逻辑或结论不足时，才把 Node trace / Proxy trace 作为主要发现来源。
|
||
|
||
遇到后续环境问题时，也先回到本阶段复查 NDJSON，再决定是否补充 Node trace。
|
||
|
||
推荐输出：
|
||
|
||
```markdown
|
||
## RuyiTrace NDJSON 优先分析
|
||
|
||
- 日志状态：已导入 / 未提供 / 未覆盖当前逻辑
|
||
- 摘要文件：
|
||
- 目标参数生成附近 API：
|
||
- 关键调用栈：
|
||
- 优先补齐环境模块：
|
||
- 需要 Node trace 补充的原因：
|
||
```
|
||
|
||
## 阶段 6：前置总结
|
||
|
||
在真正写 `env.js` 前，再次让用户确认：
|
||
|
||
```markdown
|
||
补环境前置任务已完成，请确认：
|
||
|
||
- 目标网站 URL：
|
||
- 目标 API：
|
||
- 发现的可疑加密参数：
|
||
- 用户确认要分析的参数：
|
||
- 参数位置：
|
||
- 加密入口：
|
||
- source / entry / builder / writer：
|
||
- 相关 JS 文件：
|
||
- 样本数量：
|
||
- 当前判断的依赖：
|
||
- 取证模式：
|
||
- 最终请求 TLS 指纹兼容客户端：
|
||
- TLS 客户端可用性：已安装 / 未安装需用户确认 / 不发真实请求
|
||
- 是否需要切换取证工具：否 / 是，原因：
|
||
- RuyiTrace 日志：已导入并优先分析 / 未提供 / 未覆盖当前逻辑 / 不需要
|
||
- RuyiTrace 优先证据：api / stack.file / line / col 摘要
|
||
- Node 泄露阻断检查：
|
||
- 六项纯计算预检：
|
||
- 最终交付要求：生成规范项目目录；只有 `result/final.js` 或 `result/final.py` 一个执行入口；入口运行后通过补环境后的目标 JS 入口 / signer 生成加密参数，并使用已确认的 TLS 指纹兼容客户端发送少量授权模拟请求，或按用户选择只输出本地参数；不交付自动化取证代码；不得硬编码或复用 cURL / fixture 中的加密参数样本值。
|
||
|
||
确认后将进入 Node.js 补环境阶段。
|
||
```
|