@jshookmcp/jshook 0.2.2 → 0.2.5

package/dist/src/server/domains/platform/definitions.js

@@ -1,114 +1,123 @@
+import { tool } from '../../registry/tool-builder.js';
 export const platformTools = [
-    {
-        name: 'miniapp_pkg_scan',
-        description: '扫描本地小程序缓存目录，列出所有 小程序包文件。默认扫描常见 Windows 路径。',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                searchPath: {
-                    type: 'string',
-                    description: '可选。指定扫描根目录；不提供时使用默认路径（MiniApp/Cache 与 MiniApp/Plugin）。',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'miniapp_pkg_unpack',
-        description: '解包 小程序包文件。优先调用外部 外部解包工具，失败时自动降级为纯 Node.js 解析。',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                inputPath: {
-                    type: 'string',
-                    description: '必填。小程序包文件路径。',
-                },
-                outputDir: {
-                    type: 'string',
-                    description: '可选。输出目录；不提供时自动生成 artifacts 临时目录。',
-                },
-            },
-            required: ['inputPath'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'miniapp_pkg_analyze',
-        description: '分析解包后的小程序结构，提取 pages/subPackages/components/jsFiles/totalSize/appId。',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                unpackedDir: {
-                    type: 'string',
-                    description: '必填。已解包目录路径。',
-                },
-            },
-            required: ['unpackedDir'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'asar_extract',
-        description: '提取 Electron app.asar（纯 Node.js 实现，不依赖 @electron/asar）。支持仅列文件模式。',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                inputPath: {
-                    type: 'string',
-                    description: '必填。asar 文件路径。',
-                },
-                outputDir: {
-                    type: 'string',
-                    description: '可选。提取目录；不提供时自动生成 artifacts 临时目录。',
-                },
-                listOnly: {
-                    type: 'boolean',
-                    description: '可选。默认 false；true 时仅列出文件清单，不执行提取。',
-                    default: false,
-                },
-            },
-            required: ['inputPath'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'electron_inspect_app',
-        description: '分析 Electron 应用结构（.exe 或 app 目录）：package.json、main、preload、dependencies、devToolsEnabled。',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                appPath: {
-                    type: 'string',
-                    description: '必填。Electron .exe 路径或应用目录路径。',
-                },
-            },
-            required: ['appPath'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('miniapp_pkg_scan')
+        .desc('扫描本地小程序缓存目录，列出所有 小程序包文件。默认扫描常见 Windows 路径。')
+        .string('searchPath', '可选。指定扫描根目录；不提供时使用默认路径（MiniApp/Cache 与 MiniApp/Plugin）。')
+        .build(),
+    tool('miniapp_pkg_unpack')
+        .desc('解包 小程序包文件。优先调用外部 外部解包工具，失败时自动降级为纯 Node.js 解析。')
+        .string('inputPath', '必填。小程序包文件路径。')
+        .string('outputDir', '可选。输出目录；不提供时自动生成 artifacts 临时目录。')
+        .required('inputPath')
+        .build(),
+    tool('miniapp_pkg_analyze')
+        .desc('分析解包后的小程序结构，提取 pages/subPackages/components/jsFiles/totalSize/appId。')
+        .string('unpackedDir', '必填。已解包目录路径。')
+        .required('unpackedDir')
+        .build(),
+    tool('asar_extract')
+        .desc('提取 Electron app.asar（纯 Node.js 实现，不依赖 @electron/asar）。支持仅列文件模式。')
+        .string('inputPath', '必填。asar 文件路径。')
+        .string('outputDir', '可选。提取目录；不提供时自动生成 artifacts 临时目录。')
+        .boolean('listOnly', '可选。默认 false；true 时仅列出文件清单，不执行提取。', {
+        default: false,
+    })
+        .required('inputPath')
+        .build(),
+    tool('electron_inspect_app')
+        .desc('分析 Electron 应用结构（.exe 或 app 目录）：package.json、main、preload、dependencies、devToolsEnabled。')
+        .string('appPath', '必填。Electron .exe 路径或应用目录路径。')
+        .required('appPath')
+        .build(),
+    tool('electron_scan_userdata')
+        .desc('扫描指定目录中的所有 JSON 文件，返回 raw 内容。适用于 Electron 应用的用户数据目录（Windows: %APPDATA%, macOS: ~/Library/Application Support, Linux: ~/.config）。Agent 自行解读数据。')
+        .string('dirPath', '必填。要扫描的目录绝对路径（任意平台）。')
+        .number('maxFiles', '可选。最多读取的 JSON 文件数量。默认 20。', { default: 20 })
+        .number('maxFileSizeKB', '可选。单个文件大小上限（KB）。超限文件跳过。默认 1024。', {
+        default: 1024,
+    })
+        .required('dirPath')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('asar_search')
+        .desc('在 ASAR 归档内执行正则搜索。Agent 提供 pattern，工具返回匹配文件路径和行内容。')
+        .string('inputPath', '必填。ASAR 文件路径。')
+        .string('pattern', '必填。正则表达式字符串。')
+        .string('fileGlob', '可选。文件扩展名过滤。默认 *.js。', { default: '*.js' })
+        .number('maxResults', '可选。最大返回匹配数。默认 100。', { default: 100 })
+        .required('inputPath', 'pattern')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('electron_check_fuses')
+        .desc('检测 Electron 可执行文件中的 fuse 配置状态（ASAR 完整性校验、RunAsNode 等）。')
+        .string('exePath', '必填。Electron .exe 文件路径。')
+        .required('exePath')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('electron_patch_fuses')
+        .desc('Patch Electron binary fuses to enable/disable debug capabilities. Creates backup before patching. Use profile="debug" to enable RunAsNode, NodeOptions, InspectArguments and disable OnlyLoadAppFromAsar.')
+        .string('exePath', 'Required. Path to the Electron .exe file to patch.')
+        .enum('profile', ['debug', 'custom'], 'Patch profile. "debug" enables debug-related fuses. "custom" requires a fuses object.', { default: 'debug' })
+        .object('fuses', {}, 'For profile="custom". Map of fuse names to ENABLE/DISABLE. E.g. {"RunAsNode": "ENABLE"}.')
+        .boolean('createBackup', 'Create a .exe.bak backup before patching.', { default: true })
+        .required('exePath')
+        .destructive()
+        .build(),
+    tool('v8_bytecode_decompile')
+        .desc('Decompile V8 bytecode (.jsc / bytenode) files. Uses view8 Python package for full decompilation (preferred), falls back to built-in constant pool extraction. Returns pseudocode or extracted strings for LLM analysis.')
+        .string('filePath', 'Required. Path to the .jsc or V8 bytecode file.')
+        .required('filePath')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('electron_launch_debug')
+        .desc('Launch Electron app with dual CDP debugging: --inspect for main process (Node.js) and --remote-debugging-port for renderer (Chromium). Auto-checks fuse status.')
+        .string('exePath', 'Required. Path to the Electron .exe file.')
+        .number('mainPort', 'Main process inspect port.', { default: 9229 })
+        .number('rendererPort', 'Renderer remote debugging port.', { default: 9222 })
+        .array('args', { type: 'string' }, 'Extra command-line arguments.')
+        .boolean('skipFuseCheck', 'Skip fuse status check.', { default: false })
+        .number('waitMs', 'Milliseconds to wait for CDP ports.', { default: 8000 })
+        .required('exePath')
+        .openWorld()
+        .build(),
+    tool('electron_debug_status')
+        .desc('Check status of dual-CDP debug sessions launched by electron_launch_debug.')
+        .string('sessionId', 'Optional. Check specific session. Omit to list all.')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('frida_bridge')
+        .desc('Dynamic instrumentation bridge via Frida. Actions: check_env (verify frida installed), generate_script (hook template), attach (live-attach to process), run_script (inject script), detach (disconnect), list_sessions, guide (usage help).')
+        .enum('action', ['check_env', 'generate_script', 'attach', 'run_script', 'detach', 'list_sessions', 'guide'], 'Action to perform.', { default: 'guide' })
+        .number('pid', 'Process ID for attach/run_script.')
+        .string('processName', 'Process name for attach (alternative to pid).')
+        .string('sessionId', 'Session ID for run_script/detach.')
+        .string('script', 'Frida JS script to inject (for run_script).')
+        .enum('hookType', ['intercept', 'replace', 'stalker', 'module_export'], 'Hook template type (for generate_script).', { default: 'intercept' })
+        .string('functionName', 'Target function name (for generate_script).')
+        .string('target', 'Target process name (for generate_script usage hint).')
+        .openWorld()
+        .build(),
+    tool('electron_ipc_sniff')
+        .desc('Sniff Electron IPC messages by injecting hooks into ipcRenderer via CDP. Captures invoke/send/sendSync with channel names and arguments. Actions: start (inject hooks), dump (retrieve captured messages), stop (end session), list (show sessions), guide.')
+        .enum('action', ['start', 'dump', 'stop', 'list', 'guide'], 'Action to perform.', {
+        default: 'guide',
+    })
+        .number('port', 'Renderer CDP port (--remote-debugging-port).', { default: 9222 })
+        .string('sessionId', 'Session ID for dump/stop.')
+        .boolean('clear', 'Clear captured messages after dump.', { default: true })
+        .openWorld()
+        .build(),
+    tool('jadx_bridge')
+        .desc('JADX decompiler bridge for Android APK/DEX/AAR files. Actions: check_env (verify jadx installed), decompile (run jadx on input), guide (usage help).')
+        .enum('action', ['check_env', 'decompile', 'guide'], 'Action to perform.', { default: 'guide' })
+        .string('inputPath', 'Required for decompile. Path to APK/DEX/AAR file.')
+        .string('outputDir', 'Optional. Output directory for decompiled sources.')
+        .array('extraArgs', { type: 'string' }, 'Extra jadx CLI arguments (e.g. ["--deobf", "--show-bad-code"]).')
+        .openWorld()
+        .build(),
 ];

package/dist/src/server/domains/platform/handlers/bridge-handlers.d.ts

@@ -1,4 +1,4 @@
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import { type ExternalToolRunner } from '../../../domains/shared/modules.js';
 export declare class BridgeHandlers {
     private runner;
     constructor(runner: ExternalToolRunner);
@@ -8,6 +8,10 @@ export declare class BridgeHandlers {
             text: string;
         }[];
     }>;
+    private _handleFridaAttach;
+    private _handleFridaRunScript;
+    private _handleFridaDetach;
+    private _handleFridaListSessions;
     handleJadxBridge(args: Record<string, unknown>): Promise<{
         content: {
             type: "text";

package/dist/src/server/domains/platform/handlers/bridge-handlers.js

@@ -1,7 +1,10 @@
 import { basename, extname, resolve } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import { argStringArray } from '../../../domains/shared/parse-args.js';
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import {} from '../../../domains/shared/modules.js';
 import { toTextResponse, toErrorResponse, parseStringArg, resolveOutputDirectory, checkExternalCommand, } from '../../../domains/platform/handlers/platform-utils.js';
+const execFileAsync = promisify(execFile);
 function generateFridaTemplate(hookType, functionName) {
     const templates = {
         intercept: [
@@ -59,6 +62,7 @@ function generateFridaTemplate(hookType, functionName) {
     };
     return templates[hookType] ?? templates.intercept;
 }
+const fridaSessions = new Map();
 export class BridgeHandlers {
     runner;
     constructor(runner) {
@@ -84,6 +88,18 @@ export class BridgeHandlers {
                 tip: 'Save the script to a .js file, then use the frida CLI to inject it.',
             });
         }
+        if (action === 'attach') {
+            return this._handleFridaAttach(args);
+        }
+        if (action === 'run_script') {
+            return this._handleFridaRunScript(args);
+        }
+        if (action === 'detach') {
+            return this._handleFridaDetach(args);
+        }
+        if (action === 'list_sessions') {
+            return this._handleFridaListSessions();
+        }
         return toTextResponse({
             success: true,
             guide: {
@@ -91,16 +107,189 @@ export class BridgeHandlers {
                 install: ['pip install frida-tools', 'npm install frida  // optional Node.js bindings'],
                 workflow: [
                     '1. Use process_find / process_find_chromium to locate the target process',
-                    '2. Use frida_bridge(action="generate_script") to generate a hook template',
-                    '3. Save the script and run: frida -p <PID> -l script.js',
-                    '4. Use page_evaluate or console_execute to interact with the hooked process',
-                    '5. Combine with network_enable + network_get_requests for full-chain analysis',
+                    '2. Use frida_bridge(action="attach", pid=<PID>) to live-attach to the process',
+                    '3. Use frida_bridge(action="run_script", sessionId=<id>, script="...") to inject hooks',
+                    '4. Use frida_bridge(action="generate_script") to generate hook templates',
+                    '5. Use frida_bridge(action="detach", sessionId=<id>) to clean disconnect',
+                    '6. Combine with electron_launch_debug for main-process Frida injection',
+                ],
+                actions: [
+                    'check_env',
+                    'attach',
+                    'run_script',
+                    'detach',
+                    'list_sessions',
+                    'generate_script',
+                    'guide',
                 ],
                 links: ['https://frida.re/docs/home/', 'https://frida.re/docs/javascript-api/'],
                 integration: 'Frida hooks can call back to this MCP via fetch("http://localhost:<port>/...") for real-time data exchange.',
             },
         });
     }
+    async _handleFridaAttach(args) {
+        const pid = args.pid;
+        const processName = parseStringArg(args, 'processName');
+        if (!pid && !processName) {
+            throw new Error('Either pid or processName is required for attach');
+        }
+        const fridaArgs = [];
+        if (pid) {
+            fridaArgs.push('-p', String(pid));
+        }
+        else if (processName) {
+            fridaArgs.push('-n', processName);
+        }
+        fridaArgs.push('--no-pause');
+        try {
+            await execFileAsync('frida', ['--version'], { timeout: 5000 });
+        }
+        catch {
+            return toTextResponse({
+                success: false,
+                tool: 'frida_bridge',
+                error: 'frida CLI not found. Install with: pip install frida-tools',
+                note: 'Frida live attach requires the frida CLI tools installed and in PATH.',
+            });
+        }
+        const child = spawn('frida', fridaArgs, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const sessionId = `frida-${pid ?? processName}-${Date.now()}`;
+        const session = {
+            id: sessionId,
+            pid: pid ?? 0,
+            child,
+            output: [],
+            startedAt: Date.now(),
+        };
+        child.stdout?.on('data', (data) => {
+            session.output.push(data.toString());
+            if (session.output.length > 100)
+                session.output.shift();
+        });
+        child.stderr?.on('data', (data) => {
+            session.output.push(`[stderr] ${data.toString()}`);
+            if (session.output.length > 100)
+                session.output.shift();
+        });
+        child.on('exit', () => {
+            fridaSessions.delete(sessionId);
+        });
+        fridaSessions.set(sessionId, session);
+        await new Promise((r) => setTimeout(r, 2000));
+        return toTextResponse({
+            success: true,
+            tool: 'frida_bridge',
+            action: 'attach',
+            sessionId,
+            pid: pid ?? processName,
+            initialOutput: session.output.join('').slice(0, 2000),
+            usage: {
+                runScript: `frida_bridge(action="run_script", sessionId="${sessionId}", script="...")`,
+                detach: `frida_bridge(action="detach", sessionId="${sessionId}")`,
+            },
+        });
+    }
+    async _handleFridaRunScript(args) {
+        const sessionId = parseStringArg(args, 'sessionId', true);
+        const script = parseStringArg(args, 'script', true);
+        if (!sessionId || !script) {
+            throw new Error('sessionId and script are required');
+        }
+        const session = fridaSessions.get(sessionId);
+        if (!session) {
+            const pid = args.pid;
+            const processName = parseStringArg(args, 'processName');
+            if (!pid && !processName) {
+                return toTextResponse({
+                    success: false,
+                    tool: 'frida_bridge',
+                    error: `Session ${sessionId} not found. Provide pid or processName for one-shot execution.`,
+                    activeSessions: Array.from(fridaSessions.keys()),
+                });
+            }
+            const fridaArgs = [];
+            if (pid)
+                fridaArgs.push('-p', String(pid));
+            else if (processName)
+                fridaArgs.push('-n', processName);
+            fridaArgs.push('--no-pause', '-e', script);
+            try {
+                const { stdout, stderr } = await execFileAsync('frida', fridaArgs, {
+                    timeout: 30_000,
+                    maxBuffer: 5 * 1024 * 1024,
+                });
+                return toTextResponse({
+                    success: true,
+                    tool: 'frida_bridge',
+                    action: 'run_script',
+                    mode: 'one-shot',
+                    stdout: stdout.slice(0, 10_000),
+                    stderr: stderr.slice(0, 2000),
+                });
+            }
+            catch (error) {
+                return toErrorResponse('frida_bridge', error);
+            }
+        }
+        session.output.length = 0;
+        session.child.stdin?.write(script + '\n');
+        await new Promise((r) => setTimeout(r, 3000));
+        return toTextResponse({
+            success: true,
+            tool: 'frida_bridge',
+            action: 'run_script',
+            sessionId,
+            mode: 'interactive',
+            output: session.output.join('').slice(0, 10_000),
+        });
+    }
+    async _handleFridaDetach(args) {
+        const sessionId = parseStringArg(args, 'sessionId', true);
+        if (!sessionId)
+            throw new Error('sessionId is required');
+        const session = fridaSessions.get(sessionId);
+        if (!session) {
+            return toTextResponse({
+                success: false,
+                tool: 'frida_bridge',
+                error: `Session not found: ${sessionId}`,
+                activeSessions: Array.from(fridaSessions.keys()),
+            });
+        }
+        session.child.stdin?.write('%quit\n');
+        setTimeout(() => {
+            try {
+                session.child.kill();
+            }
+            catch {
+            }
+        }, 2000);
+        fridaSessions.delete(sessionId);
+        return toTextResponse({
+            success: true,
+            tool: 'frida_bridge',
+            action: 'detach',
+            sessionId,
+            message: 'Frida session detached.',
+        });
+    }
+    async _handleFridaListSessions() {
+        const sessions = Array.from(fridaSessions.entries()).map(([id, s]) => ({
+            sessionId: id,
+            pid: s.pid,
+            uptime: Math.round((Date.now() - s.startedAt) / 1000),
+            outputLines: s.output.length,
+        }));
+        return toTextResponse({
+            success: true,
+            tool: 'frida_bridge',
+            action: 'list_sessions',
+            sessions,
+            count: sessions.length,
+        });
+    }
     async handleJadxBridge(args) {
         const action = parseStringArg(args, 'action', true) ?? 'guide';
         if (action === 'check_env') {

package/dist/src/server/domains/platform/handlers/electron-asar-helpers.js

@@ -1,5 +1,12 @@
 import { basename, extname } from 'node:path';
 import { isRecord, sanitizeArchiveRelativePath, toDisplayPath, walkDirectory, } from '../../../domains/platform/handlers/platform-utils.js';
+function trimTrailingNulls(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0) {
+        end -= 1;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
 export function flattenAsarEntries(headerNode) {
     if (!isRecord(headerNode.files)) {
         return [];
@@ -63,14 +70,13 @@ export function parseAsarBuffer(asarBuffer) {
     for (const candidateLength of lengthCandidates) {
         const headerText = asarBuffer
             .subarray(headerStart, headerStart + candidateLength)
-            .toString('utf-8')
-            .replace(/\0+$/g, '')
-            .trim();
-        if (headerText.length === 0) {
+            .toString('utf-8');
+        const normalizedHeaderText = trimTrailingNulls(headerText).trim();
+        if (normalizedHeaderText.length === 0) {
             continue;
         }
         try {
-            const parsed = JSON.parse(headerText);
+            const parsed = JSON.parse(normalizedHeaderText);
             if (isRecord(parsed)) {
                 headerObject = parsed;
                 headerLength = candidateLength;
@@ -78,6 +84,20 @@ export function parseAsarBuffer(asarBuffer) {
             }
         }
         catch {
+            const lastBrace = normalizedHeaderText.lastIndexOf('}');
+            if (lastBrace > 0) {
+                try {
+                    const trimmed = normalizedHeaderText.substring(0, lastBrace + 1);
+                    const parsed = JSON.parse(trimmed);
+                    if (isRecord(parsed)) {
+                        headerObject = parsed;
+                        headerLength = candidateLength;
+                        break;
+                    }
+                }
+                catch {
+                }
+            }
         }
     }
     if (!headerObject) {
@@ -161,5 +181,5 @@ export async function findFilesystemPreloadScripts(rootDir) {
             matches.add(toDisplayPath(absolutePath));
         }
     });
-    return Array.from(matches).sort().slice(0, 100);
+    return Array.from(matches).toSorted().slice(0, 100);
 }

package/dist/src/server/domains/platform/handlers/electron-dual-cdp.d.ts

@@ -0,0 +1,3 @@
+import { toTextResponse } from '../../../domains/platform/handlers/platform-utils.js';
+export declare function handleElectronLaunchDebug(args: Record<string, unknown>): Promise<ReturnType<typeof toTextResponse>>;
+export declare function handleElectronDebugStatus(args: Record<string, unknown>): Promise<ReturnType<typeof toTextResponse>>;