windows-exe-decompiler-mcp-server 0.1.0 → 0.1.3

package/dist/tools/pe-pdata-extract.d.ts

@@ -0,0 +1,448 @@
+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';
+export declare const pePdataExtractInputSchema: z.ZodObject<{
+    sample_id: z.ZodString;
+    force_refresh: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    sample_id: string;
+    force_refresh: boolean;
+}, {
+    sample_id: string;
+    force_refresh?: boolean | undefined;
+}>;
+export type PEPdataExtractInput = z.infer<typeof pePdataExtractInputSchema>;
+export declare const pePdataExtractOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodObject<{
+        machine: z.ZodNumber;
+        machine_name: z.ZodString;
+        image_base: z.ZodNumber;
+        entry_point_rva: z.ZodNumber;
+        exception_directory_rva: z.ZodNumber;
+        exception_directory_size: z.ZodNumber;
+        pdata_present: z.ZodBoolean;
+        xdata_present: z.ZodBoolean;
+        count: z.ZodNumber;
+        sections: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            virtual_address: z.ZodNumber;
+            virtual_size: z.ZodNumber;
+            raw_size: z.ZodNumber;
+            raw_pointer: z.ZodNumber;
+            characteristics: z.ZodNumber;
+            executable: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }, {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }>, "many">;
+        exports: z.ZodArray<z.ZodObject<{
+            rva: z.ZodNumber;
+            name: z.ZodString;
+            ordinal: z.ZodNumber;
+            is_forwarder: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }, {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }>, "many">;
+        entries: z.ZodArray<z.ZodObject<{
+            begin_rva: z.ZodNumber;
+            end_rva: z.ZodNumber;
+            size: z.ZodNumber;
+            begin_va: z.ZodNumber;
+            end_va: z.ZodNumber;
+            begin_address: z.ZodString;
+            end_address: z.ZodString;
+            unwind_info_rva: z.ZodNumber;
+            section_name: z.ZodNullable<z.ZodString>;
+            executable_section: z.ZodBoolean;
+            confidence: z.ZodNumber;
+            unwind: z.ZodNullable<z.ZodObject<{
+                version: z.ZodNumber;
+                flags: z.ZodNumber;
+                flag_names: z.ZodArray<z.ZodString, "many">;
+                prolog_size: z.ZodNumber;
+                unwind_code_count: z.ZodNumber;
+                frame_register: z.ZodNullable<z.ZodString>;
+                frame_register_id: z.ZodNumber;
+                frame_offset: z.ZodNumber;
+                handler_rva: z.ZodOptional<z.ZodNumber>;
+                chained_runtime_function: z.ZodOptional<z.ZodObject<{
+                    begin_rva: z.ZodNumber;
+                    end_rva: z.ZodNumber;
+                    unwind_info_rva: z.ZodNumber;
+                }, "strip", z.ZodTypeAny, {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                }, {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                }>>;
+            }, "strip", z.ZodTypeAny, {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            }, {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }, {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }>, "many">;
+        warnings: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        entries: {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }[];
+        count: number;
+        warnings: string[];
+        sections: {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }[];
+        machine: number;
+        machine_name: string;
+        image_base: number;
+        entry_point_rva: number;
+        exports: {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }[];
+        exception_directory_rva: number;
+        exception_directory_size: number;
+        pdata_present: boolean;
+        xdata_present: boolean;
+    }, {
+        entries: {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }[];
+        count: number;
+        warnings: string[];
+        sections: {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }[];
+        machine: number;
+        machine_name: string;
+        image_base: number;
+        entry_point_rva: number;
+        exports: {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }[];
+        exception_directory_rva: number;
+        exception_directory_size: number;
+        pdata_present: boolean;
+        xdata_present: boolean;
+    }>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "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;
+    data?: {
+        entries: {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }[];
+        count: number;
+        warnings: string[];
+        sections: {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }[];
+        machine: number;
+        machine_name: string;
+        image_base: number;
+        entry_point_rva: number;
+        exports: {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }[];
+        exception_directory_rva: number;
+        exception_directory_size: number;
+        pdata_present: boolean;
+        xdata_present: boolean;
+    } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+}, {
+    ok: boolean;
+    data?: {
+        entries: {
+            size: number;
+            confidence: number;
+            section_name: string | null;
+            executable_section: boolean;
+            begin_rva: number;
+            end_rva: number;
+            unwind_info_rva: number;
+            unwind: {
+                version: number;
+                flags: number;
+                flag_names: string[];
+                prolog_size: number;
+                unwind_code_count: number;
+                frame_register: string | null;
+                frame_register_id: number;
+                frame_offset: number;
+                handler_rva?: number | undefined;
+                chained_runtime_function?: {
+                    begin_rva: number;
+                    end_rva: number;
+                    unwind_info_rva: number;
+                } | undefined;
+            } | null;
+            begin_va: number;
+            end_va: number;
+            begin_address: string;
+            end_address: string;
+        }[];
+        count: number;
+        warnings: string[];
+        sections: {
+            name: string;
+            executable: boolean;
+            virtual_address: number;
+            virtual_size: number;
+            raw_size: number;
+            characteristics: number;
+            raw_pointer: number;
+        }[];
+        machine: number;
+        machine_name: string;
+        image_base: number;
+        entry_point_rva: number;
+        exports: {
+            name: string;
+            rva: number;
+            ordinal: number;
+            is_forwarder: boolean;
+        }[];
+        exception_directory_rva: number;
+        exception_directory_size: number;
+        pdata_present: boolean;
+        xdata_present: boolean;
+    } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+}>;
+export declare const pePdataExtractToolDefinition: ToolDefinition;
+export declare function createPEPdataExtractHandler(workspaceManager: WorkspaceManager, database: DatabaseManager, cacheManager: CacheManager): (args: ToolArgs) => Promise<WorkerResult>;
+//# sourceMappingURL=pe-pdata-extract.d.ts.map

package/dist/tools/pe-pdata-extract.js

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+import { generateCacheKey } from '../cache-manager.js';
+import { lookupCachedResult, formatCacheWarning } from './cache-observability.js';
+import { extractPdataFromPE } from '../pe-runtime-functions.js';
+import { resolvePrimarySamplePath } from '../sample-workspace.js';
+const TOOL_NAME = 'pe.pdata.extract';
+const TOOL_VERSION = '0.1.0';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const pePdataExtractInputSchema = z.object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    force_refresh: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Bypass cache lookup and recompute from source sample'),
+});
+export const pePdataExtractOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z
+        .object({
+        machine: z.number(),
+        machine_name: z.string(),
+        image_base: z.number(),
+        entry_point_rva: z.number(),
+        exception_directory_rva: z.number(),
+        exception_directory_size: z.number(),
+        pdata_present: z.boolean(),
+        xdata_present: z.boolean(),
+        count: z.number(),
+        sections: z.array(z.object({
+            name: z.string(),
+            virtual_address: z.number(),
+            virtual_size: z.number(),
+            raw_size: z.number(),
+            raw_pointer: z.number(),
+            characteristics: z.number(),
+            executable: z.boolean(),
+        })),
+        exports: z.array(z.object({
+            rva: z.number(),
+            name: z.string(),
+            ordinal: z.number(),
+            is_forwarder: z.boolean(),
+        })),
+        entries: z.array(z.object({
+            begin_rva: z.number(),
+            end_rva: z.number(),
+            size: z.number(),
+            begin_va: z.number(),
+            end_va: z.number(),
+            begin_address: z.string(),
+            end_address: z.string(),
+            unwind_info_rva: z.number(),
+            section_name: z.string().nullable(),
+            executable_section: z.boolean(),
+            confidence: z.number(),
+            unwind: z
+                .object({
+                version: z.number(),
+                flags: z.number(),
+                flag_names: z.array(z.string()),
+                prolog_size: z.number(),
+                unwind_code_count: z.number(),
+                frame_register: z.string().nullable(),
+                frame_register_id: z.number(),
+                frame_offset: z.number(),
+                handler_rva: z.number().optional(),
+                chained_runtime_function: z
+                    .object({
+                    begin_rva: z.number(),
+                    end_rva: z.number(),
+                    unwind_info_rva: z.number(),
+                })
+                    .optional(),
+            })
+                .nullable(),
+        })),
+        warnings: z.array(z.string()),
+    })
+        .optional(),
+    warnings: z.array(z.string()).optional(),
+    errors: z.array(z.string()).optional(),
+    metrics: z
+        .object({
+        elapsed_ms: z.number(),
+        tool: z.string(),
+    })
+        .optional(),
+});
+export const pePdataExtractToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Parse the PE exception directory / .pdata section and extract x64 RUNTIME_FUNCTION entries with unwind metadata.',
+    inputSchema: pePdataExtractInputSchema,
+    outputSchema: pePdataExtractOutputSchema,
+};
+export function createPEPdataExtractHandler(workspaceManager, database, cacheManager) {
+    return async (args) => {
+        const input = args;
+        const startTime = Date.now();
+        try {
+            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: {},
+            });
+            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,
+                        },
+                    };
+                }
+            }
+            const { samplePath } = await resolvePrimarySamplePath(workspaceManager, input.sample_id);
+            const result = extractPdataFromPE(samplePath);
+            const normalized = {
+                machine: result.machine,
+                machine_name: result.machineName,
+                image_base: result.imageBase,
+                entry_point_rva: result.entryPointRva,
+                exception_directory_rva: result.exceptionDirectoryRva,
+                exception_directory_size: result.exceptionDirectorySize,
+                pdata_present: result.pdataPresent,
+                xdata_present: result.xdataPresent,
+                count: result.count,
+                sections: result.sections.map((section) => ({
+                    name: section.name,
+                    virtual_address: section.virtualAddress,
+                    virtual_size: section.virtualSize,
+                    raw_size: section.rawSize,
+                    raw_pointer: section.rawPointer,
+                    characteristics: section.characteristics,
+                    executable: section.executable,
+                })),
+                exports: result.exports.map((record) => ({
+                    rva: record.rva,
+                    name: record.name,
+                    ordinal: record.ordinal,
+                    is_forwarder: record.isForwarder,
+                })),
+                entries: result.entries.map((entry) => ({
+                    begin_rva: entry.beginRva,
+                    end_rva: entry.endRva,
+                    size: entry.size,
+                    begin_va: entry.beginVa,
+                    end_va: entry.endVa,
+                    begin_address: entry.beginAddress,
+                    end_address: entry.endAddress,
+                    unwind_info_rva: entry.unwindInfoRva,
+                    section_name: entry.sectionName,
+                    executable_section: entry.executableSection,
+                    confidence: entry.confidence,
+                    unwind: entry.unwind
+                        ? {
+                            version: entry.unwind.version,
+                            flags: entry.unwind.flags,
+                            flag_names: entry.unwind.flagNames,
+                            prolog_size: entry.unwind.prologSize,
+                            unwind_code_count: entry.unwind.unwindCodeCount,
+                            frame_register: entry.unwind.frameRegister,
+                            frame_register_id: entry.unwind.frameRegisterId,
+                            frame_offset: entry.unwind.frameOffset,
+                            handler_rva: entry.unwind.handlerRva,
+                            chained_runtime_function: entry.unwind.chainedRuntimeFunction
+                                ? {
+                                    begin_rva: entry.unwind.chainedRuntimeFunction.beginRva,
+                                    end_rva: entry.unwind.chainedRuntimeFunction.endRva,
+                                    unwind_info_rva: entry.unwind.chainedRuntimeFunction.unwindInfoRva,
+                                }
+                                : undefined,
+                        }
+                        : null,
+                })),
+                warnings: result.warnings,
+            };
+            await cacheManager.setCachedResult(cacheKey, normalized, CACHE_TTL_MS, sample.sha256);
+            return {
+                ok: true,
+                data: normalized,
+                warnings: result.warnings.length > 0 ? result.warnings : undefined,
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errors: [error instanceof Error ? error.message : String(error)],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=pe-pdata-extract.js.map