deepspider 0.1.0

package/docs/GUIDE.md

@@ -0,0 +1,334 @@
+# DeepSpider 开发使用指南
+
+> JavaScript 逆向分析引擎 - Claude Code Plugin
+
+## 目录
+
+1. [项目概述](#项目概述)
+2. [安装配置](#安装配置)
+3. [使用方式](#使用方式)
+4. [核心功能](#核心功能)
+5. [MCP 工具](#mcp-工具)
+6. [调试排查](#调试排查)
+7. [开发扩展](#开发扩展)
+
+---
+
+## 项目概述
+
+DeepSpider 是一个专业的 JavaScript 逆向分析引擎，作为 Claude Code Plugin 运行。
+
+### 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| 代码预处理 | Webpack/Browserify 解包，Vite/Rollup 直接反混淆 |
+| 环境补全 | 检测并补全浏览器环境 (window/document/navigator) |
+| 混淆分析 | AST 解析、控制流分析、字符串解密 |
+| 加密逆向 | Hook 捕获 CryptoJS/RSA 加密调用 |
+| 动态调试 | Patchright 反检测浏览器 + CDP 断点 |
+
+### 项目结构
+
+```
+deepspider/
+├── src/
+│   ├── agent/               # DeepAgent 系统
+│   │   ├── tools/           # 39个工具
+│   │   ├── subagents/       # 3个子代理
+│   │   └── prompts/         # 系统提示
+│   ├── browser/             # 浏览器运行时 (Patchright)
+│   │   ├── client.js        # 反检测浏览器客户端
+│   │   ├── cdp.js           # CDP 会话管理
+│   │   └── hooks/           # Hook 脚本
+│   ├── analyzer/            # 静态分析器
+│   ├── core/                # 核心引擎
+│   ├── env/                 # 环境补丁模块
+│   ├── store/               # 知识库
+│   └── mcp/                 # MCP Server
+└── test/                    # 测试
+```
+
+---
+
+## 安装配置
+
+### 依赖安装
+
+```bash
+cd /path/to/deepspider
+pnpm install
+```
+
+### 作为 Plugin 安装
+
+```bash
+claude /install /path/to/deepspider
+```
+
+### 本地开发测试 (不安装)
+
+```bash
+claude --plugin-dir /path/to/deepspider
+```
+
+### 独立 CLI 使用
+
+```bash
+pnpm run cli run target.js      # 执行代码
+pnpm run cli analyze target.js  # 分析代码
+```
+
+---
+
+## 使用方式
+
+### 方式一: Commands (斜杠命令)
+
+```
+/deepspider:run <file.js>      # 在沙箱中执行并自动补环境
+/deepspider:analyze <file.js>  # 分析代码结构和加密
+/deepspider:deob <file.js>     # 反混淆代码
+/deepspider:trace <param>      # 追踪参数生成逻辑
+```
+
+### 方式二: Agent 对话
+
+直接与 DeepSpider Agent 对话:
+
+```
+分析这段 JS 代码的加密逻辑
+帮我补全这段代码的浏览器环境
+反混淆这个文件
+追踪 sign 参数的生成过程
+```
+
+### 方式三: MCP 工具调用
+
+Claude 会自动调用 MCP 工具，工具命名格式:
+- `mcp__deepspider__sandbox_execute`
+- `mcp__deepspider__analyze_ast`
+- `mcp__deepspider__deobfuscate`
+
+---
+
+## 核心功能
+
+### 4.1 沙箱执行
+
+在隔离环境中安全执行 JS 代码:
+
+```javascript
+// 工具: sandbox_execute
+{
+  code: "var a = 1 + 1; a;",
+  timeout: 5000
+}
+// 返回: { success: true, result: 2 }
+```
+
+### 4.2 环境补全
+
+自动检测并补全缺失的浏览器环境:
+
+| 环境对象 | 补全内容 |
+|----------|----------|
+| window | location, innerWidth, devicePixelRatio |
+| document | cookie, createElement, getElementById |
+| navigator | userAgent, platform, language |
+| localStorage | getItem, setItem |
+
+### 4.3 加密识别
+
+支持识别的加密算法:
+
+| 类型 | 算法 |
+|------|------|
+| 哈希 | MD5, SHA1, SHA256, SHA512, SM3 |
+| 对称 | AES, DES, 3DES, SM4, RC4 |
+| 非对称 | RSA, SM2, ECC |
+| MAC | HMAC-MD5, HMAC-SHA256, HMAC-SM3 |
+
+### 4.4 反混淆
+
+支持的混淆类型:
+
+| 类型 | 特征 | 处理方式 |
+|------|------|----------|
+| eval 包装 | `eval(...)` | 解包执行 |
+| 字符串数组 | `_0x` 变量 | 还原字符串 |
+| Unicode | `\u0061` | 解码 |
+| 控制流平坦化 | switch-case | 简化 |
+
+---
+
+## MCP 工具
+
+### 工具列表 (39个)
+
+**预处理与解包**
+| 工具名 | 说明 |
+|--------|------|
+| preprocess_code | 智能预处理（自动解包或反混淆） |
+| unpack_bundle | Webpack/Browserify 解包 |
+| analyze_bundle | 分析 Bundle 结构 |
+
+**静态分析**
+| 工具名 | 说明 |
+|--------|------|
+| analyze_ast | AST 结构分析 |
+| analyze_callstack | 调用栈分析 |
+| analyze_encryption | 加密模式识别 |
+| deobfuscate | 反混淆 |
+| deobfuscate_pipeline | 反混淆流水线 |
+| detect_obfuscator | 识别混淆器类型 |
+| decode_strings | 解密字符串 |
+
+**追踪分析**
+| 工具名 | 说明 |
+|--------|------|
+| trace_variable | 变量数据流追踪 |
+| trace_request_params | 请求参数追踪 |
+| find_call_pattern | 查找调用模式 |
+
+**浏览器运行时**
+| 工具名 | 说明 |
+|--------|------|
+| launch_browser | 启动反检测浏览器 |
+| navigate_to | 导航到 URL |
+| browser_close | 关闭浏览器 |
+| set_breakpoint | 设置断点 |
+| set_xhr_breakpoint | 设置 XHR 断点 |
+| collect_env | 采集环境数据 |
+| get_hook_logs | 获取 Hook 日志 |
+
+**页面交互**
+| 工具名 | 说明 |
+|--------|------|
+| click_element | 点击元素 |
+| fill_input | 填充输入框 |
+| take_screenshot | 截图 |
+| wait_for_selector | 等待元素 |
+
+**沙箱执行**
+| 工具名 | 说明 |
+|--------|------|
+| sandbox_execute | 沙箱执行代码 |
+| sandbox_inject | 注入补丁 |
+| sandbox_reset | 重置沙箱 |
+
+**环境补全**
+| 工具名 | 说明 |
+|--------|------|
+| generate_patch | 生成环境补丁 |
+| match_module | 批量匹配缺失属性 |
+| list_env_modules | 列出环境模块 |
+| load_env_module | 加载环境模块 |
+| list_profiles | 列出浏览器配置 |
+| load_profile | 加载配置 |
+
+**知识库**
+| 工具名 | 说明 |
+|--------|------|
+| save_to_store | 保存到知识库 |
+| query_store | 查询知识库 |
+| list_store | 列出知识库 |
+
+**报告**
+| 工具名 | 说明 |
+|--------|------|
+| generate_report | 生成分析报告 |
+
+---
+
+## 调试排查
+
+### 调试模式
+
+```bash
+# 开启调试模式
+claude --debug --plugin-dir /path/to/deepspider
+```
+
+### MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node src/mcp/server.js
+```
+
+### 查看工具调用日志
+
+```bash
+tail -f logs/deepspider-debug.log
+```
+
+### 常见问题
+
+| 问题 | 排查方法 |
+|------|----------|
+| MCP Server 启动失败 | `node src/mcp/server.js` |
+| 工具未找到 | `node test/plugin.test.js` |
+| 沙箱执行失败 | 检查 isolated-vm 依赖 |
+
+---
+
+## 开发扩展
+
+### 添加新工具
+
+在 `src/agent/tools/` 下创建工具文件：
+
+```javascript
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+
+export const myTool = tool(
+  async ({ param }) => {
+    return JSON.stringify({ result: param });
+  },
+  {
+    name: 'my_tool',
+    description: '工具描述',
+    schema: z.object({
+      param: z.string().describe('参数描述'),
+    }),
+  }
+);
+```
+
+然后在 `src/agent/tools/index.js` 中导出。
+
+### 子代理架构
+
+| 子代理 | 职责 |
+|--------|------|
+| static-agent | 预处理、解包、反混淆、加密定位 |
+| dynamic-agent | 浏览器控制、断点、Hook、数据采集 |
+| sandbox-agent | 环境补全、代码执行、补丁生成 |
+
+### 知识库
+
+知识库存储在 `.deepspider-store/` 目录:
+
+```
+.deepspider-store/
+├── index.json      # 索引
+├── env/            # 环境补丁
+└── analysis/       # 分析结果
+```
+
+### 运行测试
+
+```bash
+pnpm test                    # 运行所有测试
+node test/plugin.test.js     # 验证工具定义
+node test/samples.test.js    # 测试样本执行
+```
+
+---
+
+## 参考资料
+
+- [Claude Code Hooks](https://code.claude.com/docs/en/hooks)
+- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
+- [Plugin 开发文档](https://code.claude.com/docs/en/plugins)

package/docs/PROMPT.md

@@ -0,0 +1,60 @@
+# DeepSpider Subagent 系统提示
+
+> 此文件为 Subagent 系统提示的参考文档。
+> 实际 Subagent 定义位于 `.claude/agents/deepspider.md`
+
+你是 DeepSpider，一个专业的 JavaScript 逆向工程 Subagent。
+
+## 核心能力
+
+1. **环境补全** - 检测并补全浏览器环境依赖
+2. **混淆分析** - AST 解析、控制流分析、字符串解密
+3. **加密逆向** - 识别加密函数、追踪参数流向
+4. **请求分析** - 调用栈追踪、请求参数生成逻辑
+
+## 工作原则
+
+1. **最小补丁**: 只补充必要的环境
+2. **迭代验证**: 每次补丁后验证执行结果
+3. **清晰输出**: 生成可独立运行的代码
+
+## 可用工具
+
+Subagent 使用 Claude Code 内置工具：
+
+| 工具 | 用途 |
+|------|------|
+| `Read` | 读取文件内容 |
+| `Bash` | 执行命令（node 运行 JS） |
+| `Glob` | 文件模式匹配 |
+| `Grep` | 代码搜索 |
+| `Write` | 写入文件 |
+| `Edit` | 编辑文件 |
+
+## 任务处理流程
+
+### 补环境任务
+```
+1. Read 读取目标 JS 文件
+2. Bash node 执行，捕获错误
+3. 分析缺失的环境属性
+4. 生成补丁代码
+5. Write 保存补丁文件
+6. Bash 再次执行验证
+```
+
+### 加密分析任务
+```
+1. Read 读取代码
+2. Grep 搜索加密关键词
+3. 分析函数结构和调用关系
+4. 输出分析报告
+```
+
+### 反混淆任务
+```
+1. Read 读取混淆代码
+2. 识别混淆类型
+3. 手动或使用工具还原
+4. Write 保存还原后的代码
+```

package/docs/USAGE.md

@@ -0,0 +1,226 @@
+# DeepSpider 使用指南
+
+> JS 逆向分析引擎 - 四类加密场景分析指南
+
+## 快速开始
+
+### 1. 启动 Agent
+
+```bash
+pnpm run agent
+```
+
+### 2. 基本流程
+
+```
+启动浏览器 → 注入Hook → 访问目标 → 触发请求 → 分析日志 → 定位源码 → 提取逻辑
+```
+
+---
+
+## 场景一：Headers 动态加密
+
+**适用于：** X-Sign、X-Token、Authorization 等动态签名
+
+### 操作步骤
+
+**第一步：启动浏览器并注入 Hook**
+
+```
+请启动浏览器，注入网络和加密 Hook
+```
+
+Agent 会执行：
+- `launch_browser` - 启动浏览器
+- `generate_xhr_hook` / `generate_fetch_hook` - 生成网络 Hook
+- `generate_cryptojs_hook` - 生成加密 Hook
+
+**第二步：访问目标网站**
+
+```
+访问 https://example.com
+```
+
+**第三步：触发目标请求**
+
+```
+点击登录按钮触发请求
+```
+
+或使用工具：
+```
+请点击页面上的登录按钮
+```
+
+**第四步：分析加密来源**
+
+```
+分析 X-Sign 这个 Header 是如何生成的
+```
+
+Agent 会：
+1. 获取日志 `__deepspider__.getAllLogs()`
+2. 调用 `analyze_header_encryption` 分析
+3. 调用 `locate_crypto_source` 定位源码
+
+**第五步：提取加密逻辑**
+
+```
+提取生成 X-Sign 的加密函数代码
+```
+
+---
+
+## 场景二：Cookie 动态加密
+
+**适用于：** 反爬虫 Cookie、__jsl_clearance、acw_sc__v2 等
+
+### 操作步骤
+
+**第一步：启动浏览器，页面加载前注入 Hook**
+
+```
+启动浏览器，需要在页面加载前注入 Hook 来捕获 Cookie 生成
+```
+
+Agent 会使用 `add_init_script` 在页面加载前注入。
+
+**第二步：清除 Cookie 并访问**
+
+```
+清除 Cookie 后访问 https://example.com，触发 Cookie 生成
+```
+
+**第三步：分析 Cookie 来源**
+
+```
+分析 __token__ 这个 Cookie 是如何生成的
+```
+
+Agent 会调用 `analyze_cookie_encryption` 分析。
+
+**第四步：提取生成逻辑**
+
+```
+提取生成该 Cookie 的完整代码
+```
+
+---
+
+## 场景三：请求参数加密
+
+**适用于：** POST Body 加密、查询参数加密
+
+### 操作步骤
+
+**第一步：注入 Hook 并触发请求**
+
+```
+启动浏览器，访问目标网站，触发登录请求
+```
+
+**第二步：分析加密参数**
+
+```
+分析请求体中的加密参数是如何生成的
+```
+
+Agent 会：
+1. 从 `linkedCrypto` 找到关联的加密调用
+2. 定位加密函数
+
+**第三步：提取加密逻辑**
+
+```
+提取参数加密的函数，我需要在 Node.js 中复现
+```
+
+---
+
+## 场景四：响应结果加密
+
+**适用于：** 接口返回加密数据
+
+### 操作步骤
+
+**第一步：注入 Hook 并触发请求**
+
+```
+启动浏览器，访问目标网站，触发数据请求
+```
+
+**第二步：分析解密逻辑**
+
+```
+分析响应数据是如何解密的
+```
+
+Agent 会调用 `analyze_response_decryption` 分析。
+
+**第三步：提取解密逻辑**
+
+```
+提取解密函数代码
+```
+
+---
+
+## 常用命令参考
+
+### 浏览器操作
+
+| 命令 | 说明 |
+|------|------|
+| 启动浏览器 | 启动并注入基础 Hook |
+| 访问 URL | 导航到指定页面 |
+| 点击 XXX | 点击页面元素 |
+| 截图 | 保存当前页面截图 |
+| 关闭浏览器 | 关闭浏览器释放资源 |
+
+### 分析操作
+
+| 命令 | 说明 |
+|------|------|
+| 分析 Header XXX | 分析指定 Header 的加密来源 |
+| 分析 Cookie XXX | 分析指定 Cookie 的生成逻辑 |
+| 分析请求加密 | 分析请求参数的加密方式 |
+| 分析响应解密 | 分析响应数据的解密方式 |
+
+### 调试操作
+
+| 命令 | 说明 |
+|------|------|
+| 设置断点 | 在指定位置设置断点 |
+| 设置 XHR 断点 | 拦截指定 URL 的请求 |
+| 查看调用栈 | 查看当前断点的调用栈 |
+| 查看变量 | 查看当前作用域的变量 |
+
+### 提取操作
+
+| 命令 | 说明 |
+|------|------|
+| 提取函数 XXX | 提取指定函数的代码 |
+| 列出所有函数 | 列出代码中的函数列表 |
+
+---
+
+## 沙箱验证
+
+提取代码后，可以在沙箱中验证：
+
+```
+在沙箱中执行以下代码验证加密结果：
+[粘贴提取的代码]
+```
+
+如果报错缺少环境：
+
+```
+自动补全缺失的环境并重新执行
+```
+
+Agent 会：
+1. 分析缺失的环境属性
+2. 从真实浏览器采集
+3. 生成补丁代码
+4. 重新执行验证

package/eslint.config.js

@@ -0,0 +1,51 @@
+import js from '@eslint/js';
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        // Node.js
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        // Web APIs
+        URL: 'readonly',
+        fetch: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearTimeout: 'readonly',
+        clearInterval: 'readonly',
+        // Browser (用于生成注入代码)
+        window: 'readonly',
+        document: 'readonly',
+        navigator: 'readonly',
+        localStorage: 'readonly',
+        sessionStorage: 'readonly',
+        screen: 'readonly',
+        Image: 'readonly',
+        btoa: 'readonly',
+        atob: 'readonly',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-console': 'off',
+      'no-case-declarations': 'off',
+      'no-control-regex': 'off',
+      'no-useless-escape': 'warn',
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      '.deepspider-data/**',
+      'dist/**',
+      'test/samples/**',
+    ],
+  },
+];