windows-exe-decompiler-mcp-server 0.1.0

package/dist/tools/strings-extract.d.ts

@@ -0,0 +1,375 @@
+/**
+ * strings.extract tool implementation
+ * Extracts readable strings (ASCII and Unicode) from PE files
+ * Requirements: 4.1, 4.2, 4.3
+ */
+import { z } from 'zod';
+import type { ToolDefinition, ToolArgs, WorkerResult } from '../types.js';
+import type { WorkspaceManager } from '../workspace-manager.js';
+import type { DatabaseManager } from '../database.js';
+import type { CacheManager } from '../cache-manager.js';
+/**
+ * Input schema for strings.extract tool
+ * Requirements: 4.1, 4.2, 4.3
+ */
+export declare const StringsExtractInputSchema: z.ZodObject<{
+    sample_id: z.ZodString;
+    min_len: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    encoding: z.ZodDefault<z.ZodOptional<z.ZodEnum<["ascii", "unicode", "all"]>>>;
+    max_strings: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_string_length: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    context_window_bytes: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_context_windows: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    category_filter: z.ZodDefault<z.ZodOptional<z.ZodEnum<["all", "ioc", "url", "network", "ipc", "command", "registry", "file_path", "suspicious_api"]>>>;
+    force_refresh: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    sample_id: string;
+    encoding: "ascii" | "all" | "unicode";
+    force_refresh: boolean;
+    min_len: number;
+    max_strings: number;
+    max_string_length: number;
+    context_window_bytes: number;
+    max_context_windows: number;
+    category_filter: "all" | "registry" | "network" | "command" | "ioc" | "url" | "ipc" | "file_path" | "suspicious_api";
+}, {
+    sample_id: string;
+    encoding?: "ascii" | "all" | "unicode" | undefined;
+    force_refresh?: boolean | undefined;
+    min_len?: number | undefined;
+    max_strings?: number | undefined;
+    max_string_length?: number | undefined;
+    context_window_bytes?: number | undefined;
+    max_context_windows?: number | undefined;
+    category_filter?: "all" | "registry" | "network" | "command" | "ioc" | "url" | "ipc" | "file_path" | "suspicious_api" | undefined;
+}>;
+export type StringsExtractInput = z.infer<typeof StringsExtractInputSchema>;
+/**
+ * Output schema for strings.extract tool
+ * Requirements: 4.1, 4.2, 4.3, 4.6
+ */
+export declare const StringsExtractOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodObject<{
+        strings: z.ZodArray<z.ZodObject<{
+            offset: z.ZodNumber;
+            string: z.ZodString;
+            encoding: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            string: string;
+            encoding: string;
+            offset: number;
+        }, {
+            string: string;
+            encoding: string;
+            offset: number;
+        }>, "many">;
+        count: z.ZodNumber;
+        total_count: z.ZodOptional<z.ZodNumber>;
+        pre_filter_count: z.ZodOptional<z.ZodNumber>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        max_strings: z.ZodOptional<z.ZodNumber>;
+        max_string_length: z.ZodOptional<z.ZodNumber>;
+        min_len: z.ZodNumber;
+        encoding_filter: z.ZodString;
+        category_filter: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodObject<{
+            cluster_counts: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            clusters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>;
+            top_high_value: z.ZodArray<z.ZodObject<{
+                offset: z.ZodNumber;
+                string: z.ZodString;
+                encoding: z.ZodString;
+                categories: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }, {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }>, "many">;
+            context_windows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                start_offset: z.ZodNumber;
+                end_offset: z.ZodNumber;
+                score: z.ZodNumber;
+                categories: z.ZodArray<z.ZodString, "many">;
+                strings: z.ZodArray<z.ZodObject<{
+                    offset: z.ZodNumber;
+                    string: z.ZodString;
+                    encoding: z.ZodString;
+                    categories: z.ZodArray<z.ZodString, "many">;
+                }, "strip", z.ZodTypeAny, {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }, {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }>, "many">;
+            }, "strip", z.ZodTypeAny, {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }, {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        }, {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        strings: {
+            string: string;
+            encoding: string;
+            offset: number;
+        }[];
+        count: number;
+        min_len: number;
+        encoding_filter: string;
+        summary?: {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        } | undefined;
+        max_strings?: number | undefined;
+        max_string_length?: number | undefined;
+        category_filter?: string | undefined;
+        total_count?: number | undefined;
+        pre_filter_count?: number | undefined;
+        truncated?: boolean | undefined;
+    }, {
+        strings: {
+            string: string;
+            encoding: string;
+            offset: number;
+        }[];
+        count: number;
+        min_len: number;
+        encoding_filter: string;
+        summary?: {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        } | undefined;
+        max_strings?: number | undefined;
+        max_string_length?: number | undefined;
+        category_filter?: string | undefined;
+        total_count?: number | undefined;
+        pre_filter_count?: number | undefined;
+        truncated?: boolean | undefined;
+    }>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    metrics: z.ZodOptional<z.ZodObject<{
+        elapsed_ms: z.ZodNumber;
+        tool: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        elapsed_ms: number;
+        tool: string;
+    }, {
+        elapsed_ms: number;
+        tool: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    ok: boolean;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    data?: {
+        strings: {
+            string: string;
+            encoding: string;
+            offset: number;
+        }[];
+        count: number;
+        min_len: number;
+        encoding_filter: string;
+        summary?: {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        } | undefined;
+        max_strings?: number | undefined;
+        max_string_length?: number | undefined;
+        category_filter?: string | undefined;
+        total_count?: number | undefined;
+        pre_filter_count?: number | undefined;
+        truncated?: boolean | undefined;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}, {
+    ok: boolean;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    data?: {
+        strings: {
+            string: string;
+            encoding: string;
+            offset: number;
+        }[];
+        count: number;
+        min_len: number;
+        encoding_filter: string;
+        summary?: {
+            cluster_counts: Record<string, number>;
+            clusters: Record<string, string[]>;
+            top_high_value: {
+                string: string;
+                encoding: string;
+                offset: number;
+                categories: string[];
+            }[];
+            context_windows?: {
+                score: number;
+                strings: {
+                    string: string;
+                    encoding: string;
+                    offset: number;
+                    categories: string[];
+                }[];
+                categories: string[];
+                start_offset: number;
+                end_offset: number;
+            }[] | undefined;
+        } | undefined;
+        max_strings?: number | undefined;
+        max_string_length?: number | undefined;
+        category_filter?: string | undefined;
+        total_count?: number | undefined;
+        pre_filter_count?: number | undefined;
+        truncated?: boolean | undefined;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}>;
+export type StringsExtractOutput = z.infer<typeof StringsExtractOutputSchema>;
+/**
+ * Tool definition for strings.extract
+ */
+export declare const stringsExtractToolDefinition: ToolDefinition;
+/**
+ * Create strings.extract tool handler
+ * Requirements: 4.1, 4.2, 4.3
+ */
+export declare function createStringsExtractHandler(workspaceManager: WorkspaceManager, database: DatabaseManager, cacheManager: CacheManager): (args: ToolArgs) => Promise<WorkerResult>;
+//# sourceMappingURL=strings-extract.d.ts.map

package/dist/tools/strings-extract.js

@@ -0,0 +1,314 @@
+/**
+ * strings.extract tool implementation
+ * Extracts readable strings (ASCII and Unicode) from PE files
+ * Requirements: 4.1, 4.2, 4.3
+ */
+import { z } from 'zod';
+import { spawn } from 'child_process';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { generateCacheKey } from '../cache-manager.js';
+import { resolvePackagePath } from '../runtime-paths.js';
+import { lookupCachedResult, formatCacheWarning } from './cache-observability.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TOOL_NAME = 'strings.extract';
+const TOOL_VERSION = '1.0.0';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// ============================================================================
+// Input/Output Schemas
+// ============================================================================
+/**
+ * Input schema for strings.extract tool
+ * Requirements: 4.1, 4.2, 4.3
+ */
+export const StringsExtractInputSchema = z.object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    min_len: z.number().int().min(1).optional().default(4).describe('Minimum string length'),
+    encoding: z.enum(['ascii', 'unicode', 'all']).optional().default('all').describe('Encoding type to extract'),
+    max_strings: z.number().int().min(1).optional().default(500).describe('Maximum number of strings to return (default: 500)'),
+    max_string_length: z.number().int().min(16).optional().default(512).describe('Maximum length for each returned string'),
+    context_window_bytes: z
+        .number()
+        .int()
+        .min(32)
+        .max(65536)
+        .optional()
+        .default(1024)
+        .describe('Maximum byte gap used to regroup nearby strings into context windows'),
+    max_context_windows: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(12)
+        .describe('Maximum number of context windows returned in the summary'),
+    category_filter: z.enum(['all', 'ioc', 'url', 'network', 'ipc', 'command', 'registry', 'file_path', 'suspicious_api'])
+        .optional()
+        .default('all')
+        .describe('Optional category filter; use `ioc` to prioritize IOC-related strings'),
+    force_refresh: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Bypass cache lookup and recompute from source sample'),
+});
+/**
+ * Output schema for strings.extract tool
+ * Requirements: 4.1, 4.2, 4.3, 4.6
+ */
+export const StringsExtractOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z.object({
+        strings: z.array(z.object({
+            offset: z.number(),
+            string: z.string(),
+            encoding: z.string(),
+        })),
+        count: z.number(),
+        total_count: z.number().optional(),
+        pre_filter_count: z.number().optional(),
+        truncated: z.boolean().optional(),
+        max_strings: z.number().optional(),
+        max_string_length: z.number().optional(),
+        min_len: z.number(),
+        encoding_filter: z.string(),
+        category_filter: z.string().optional(),
+        summary: z.object({
+            cluster_counts: z.record(z.string(), z.number()),
+            clusters: z.record(z.string(), z.array(z.string())),
+            top_high_value: z.array(z.object({
+                offset: z.number(),
+                string: z.string(),
+                encoding: z.string(),
+                categories: z.array(z.string()),
+            })),
+            context_windows: z.array(z.object({
+                start_offset: z.number(),
+                end_offset: z.number(),
+                score: z.number(),
+                categories: z.array(z.string()),
+                strings: z.array(z.object({
+                    offset: z.number(),
+                    string: z.string(),
+                    encoding: z.string(),
+                    categories: z.array(z.string()),
+                })),
+            })).optional(),
+        }).optional(),
+    }).optional(),
+    warnings: z.array(z.string()).optional(),
+    errors: z.array(z.string()).optional(),
+    artifacts: z.array(z.any()).optional(),
+    metrics: z.object({
+        elapsed_ms: z.number(),
+        tool: z.string(),
+    }).optional(),
+});
+// ============================================================================
+// Tool Definition
+// ============================================================================
+/**
+ * Tool definition for strings.extract
+ */
+export const stringsExtractToolDefinition = {
+    name: TOOL_NAME,
+    description: '提取 PE 文件中的可读字符串（ASCII 和 Unicode），支持多种编码',
+    inputSchema: StringsExtractInputSchema,
+    outputSchema: StringsExtractOutputSchema,
+};
+/**
+ * Spawn Python Static Worker and communicate via stdin/stdout JSON protocol
+ *
+ * Requirements: Worker communication
+ *
+ * @param request - Worker request object
+ * @returns Worker response object
+ */
+async function callStaticWorker(request) {
+    return new Promise((resolve, reject) => {
+        // Get Python worker path
+        const workerPath = resolvePackagePath('workers', 'static_worker.py');
+        // Spawn Python process
+        const pythonCommand = process.platform === 'win32' ? 'python' : 'python3';
+        const pythonProcess = spawn(pythonCommand, [workerPath], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        // Collect stdout
+        pythonProcess.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        // Collect stderr
+        pythonProcess.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        // Handle process exit
+        pythonProcess.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`Python worker exited with code ${code}. stderr: ${stderr}`));
+                return;
+            }
+            // Parse response from stdout
+            try {
+                const lines = stdout.trim().split('\n');
+                const lastLine = lines[lines.length - 1];
+                const response = JSON.parse(lastLine);
+                resolve(response);
+            }
+            catch (error) {
+                reject(new Error(`Failed to parse worker response: ${error.message}. stdout: ${stdout}`));
+            }
+        });
+        // Handle process error
+        pythonProcess.on('error', (error) => {
+            reject(new Error(`Failed to spawn Python worker: ${error.message}`));
+        });
+        // Send request to worker via stdin
+        try {
+            pythonProcess.stdin.write(JSON.stringify(request) + '\n');
+            pythonProcess.stdin.end();
+        }
+        catch (error) {
+            reject(new Error(`Failed to write to worker stdin: ${error.message}`));
+        }
+    });
+}
+// ============================================================================
+// Tool Handler
+// ============================================================================
+/**
+ * Create strings.extract tool handler
+ * Requirements: 4.1, 4.2, 4.3
+ */
+export function createStringsExtractHandler(workspaceManager, database, cacheManager) {
+    return async (args) => {
+        const input = args;
+        const startTime = Date.now();
+        try {
+            // 1. Generate cache key
+            const sample = database.findSample(input.sample_id);
+            if (!sample) {
+                return {
+                    ok: false,
+                    errors: [`Sample not found: ${input.sample_id}`],
+                };
+            }
+            const cacheKey = generateCacheKey({
+                sampleSha256: sample.sha256,
+                toolName: TOOL_NAME,
+                toolVersion: TOOL_VERSION,
+                args: {
+                    min_len: input.min_len,
+                    encoding: input.encoding,
+                    max_strings: input.max_strings,
+                    max_string_length: input.max_string_length,
+                    context_window_bytes: input.context_window_bytes,
+                    max_context_windows: input.max_context_windows,
+                    category_filter: input.category_filter,
+                },
+            });
+            // 2. Check cache
+            if (!input.force_refresh) {
+                const cachedLookup = await lookupCachedResult(cacheManager, cacheKey);
+                if (cachedLookup) {
+                    return {
+                        ok: true,
+                        data: cachedLookup.data,
+                        warnings: ['Result from cache', formatCacheWarning(cachedLookup.metadata)],
+                        metrics: {
+                            elapsed_ms: Date.now() - startTime,
+                            tool: TOOL_NAME,
+                            cached: true,
+                            cache_key: cachedLookup.metadata.key,
+                            cache_tier: cachedLookup.metadata.tier,
+                            cache_created_at: cachedLookup.metadata.createdAt,
+                            cache_expires_at: cachedLookup.metadata.expiresAt,
+                            cache_hit_at: cachedLookup.metadata.fetchedAt,
+                        },
+                    };
+                }
+            }
+            // 3. Get sample path from workspace
+            const workspace = await workspaceManager.getWorkspace(input.sample_id);
+            // Find the sample file in the original directory
+            const fs = await import('fs/promises');
+            const files = await fs.readdir(workspace.original);
+            if (files.length === 0) {
+                return {
+                    ok: false,
+                    errors: ['Sample file not found in workspace'],
+                };
+            }
+            const samplePath = path.join(workspace.original, files[0]);
+            // 4. Prepare worker request
+            const workerRequest = {
+                job_id: uuidv4(),
+                tool: TOOL_NAME,
+                sample: {
+                    sample_id: input.sample_id,
+                    path: samplePath,
+                },
+                args: {
+                    min_len: input.min_len,
+                    encoding: input.encoding,
+                    max_strings: input.max_strings,
+                    max_string_length: input.max_string_length,
+                    context_window_bytes: input.context_window_bytes,
+                    max_context_windows: input.max_context_windows,
+                    category_filter: input.category_filter,
+                },
+                context: {
+                    request_time_utc: new Date().toISOString(),
+                    policy: {
+                        allow_dynamic: false,
+                        allow_network: false,
+                    },
+                    versions: {
+                        tool_version: TOOL_VERSION,
+                    },
+                },
+            };
+            // 5. Call Static Worker
+            // Requirements: 4.1, 4.2, 4.3
+            const workerResponse = await callStaticWorker(workerRequest);
+            if (!workerResponse.ok) {
+                return {
+                    ok: false,
+                    errors: workerResponse.errors,
+                    warnings: workerResponse.warnings,
+                };
+            }
+            // 6. Cache result
+            await cacheManager.setCachedResult(cacheKey, workerResponse.data, CACHE_TTL_MS);
+            // 7. Return result
+            return {
+                ok: true,
+                data: workerResponse.data,
+                warnings: input.force_refresh
+                    ? ['force_refresh=true; bypassed cache lookup', ...(workerResponse.warnings || [])]
+                    : workerResponse.warnings,
+                errors: workerResponse.errors,
+                artifacts: workerResponse.artifacts,
+                metrics: {
+                    ...workerResponse.metrics,
+                    elapsed_ms: Date.now() - startTime,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errors: [error.message],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=strings-extract.js.map