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

package/dist/tools/code-functions-smart-recover.js

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { generateCacheKey } from '../cache-manager.js';
+import { lookupCachedResult, formatCacheWarning } from './cache-observability.js';
+import { smartRecoverFunctionsFromPE } from '../pe-runtime-functions.js';
+import { resolvePrimarySamplePath } from '../sample-workspace.js';
+const TOOL_NAME = 'code.functions.smart_recover';
+const TOOL_VERSION = '0.1.0';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const codeFunctionsSmartRecoverInputSchema = 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 codeFunctionsSmartRecoverOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z
+        .object({
+        machine: z.number(),
+        machine_name: z.string(),
+        image_base: z.number(),
+        entry_point_rva: z.number(),
+        strategy: z.array(z.string()),
+        count: z.number(),
+        functions: z.array(z.object({
+            address: z.string(),
+            va: z.number(),
+            rva: z.number(),
+            size: z.number(),
+            name: z.string(),
+            name_source: z.enum(['entry_point', 'export', 'synthetic_sub']),
+            confidence: z.number(),
+            source: z.enum(['pdata_runtime_function', 'entry_point_only']),
+            section_name: z.string().nullable(),
+            executable_section: z.boolean(),
+            is_entry_point: z.boolean(),
+            is_exported: z.boolean(),
+            export_name: z.string().optional(),
+            evidence: z.array(z.string()),
+            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()
+                .optional(),
+        })),
+        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 codeFunctionsSmartRecoverToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Recover function candidates heuristically from PE runtime metadata such as .pdata / exception directory, exports, and entry point.',
+    inputSchema: codeFunctionsSmartRecoverInputSchema,
+    outputSchema: codeFunctionsSmartRecoverOutputSchema,
+};
+export function createCodeFunctionsSmartRecoverHandler(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 = smartRecoverFunctionsFromPE(samplePath);
+            const normalized = {
+                machine: result.machine,
+                machine_name: result.machineName,
+                image_base: result.imageBase,
+                entry_point_rva: result.entryPointRva,
+                strategy: result.strategy,
+                count: result.count,
+                functions: result.functions.map((item) => ({
+                    address: item.address,
+                    va: item.va,
+                    rva: item.rva,
+                    size: item.size,
+                    name: item.name,
+                    name_source: item.nameSource,
+                    confidence: item.confidence,
+                    source: item.source,
+                    section_name: item.sectionName,
+                    executable_section: item.executableSection,
+                    is_entry_point: item.isEntryPoint,
+                    is_exported: item.isExported,
+                    export_name: item.exportName,
+                    evidence: item.evidence,
+                    unwind: item.unwind
+                        ? {
+                            version: item.unwind.version,
+                            flags: item.unwind.flags,
+                            flag_names: item.unwind.flagNames,
+                            prolog_size: item.unwind.prologSize,
+                            unwind_code_count: item.unwind.unwindCodeCount,
+                            frame_register: item.unwind.frameRegister,
+                            frame_register_id: item.unwind.frameRegisterId,
+                            frame_offset: item.unwind.frameOffset,
+                            handler_rva: item.unwind.handlerRva,
+                            chained_runtime_function: item.unwind.chainedRuntimeFunction
+                                ? {
+                                    begin_rva: item.unwind.chainedRuntimeFunction.beginRva,
+                                    end_rva: item.unwind.chainedRuntimeFunction.endRva,
+                                    unwind_info_rva: item.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=code-functions-smart-recover.js.map

package/dist/tools/code-module-review-apply.d.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import type { ToolArgs, ToolDefinition, WorkerResult } from '../types.js';
+import type { WorkspaceManager } from '../workspace-manager.js';
+import type { DatabaseManager } from '../database.js';
+export declare const codeModuleReviewApplyInputSchema: z.ZodObject<{
+    sample_id: z.ZodString;
+    reviews: z.ZodArray<z.ZodObject<{
+        module_name: z.ZodString;
+        refined_name: z.ZodOptional<z.ZodString>;
+        summary: z.ZodString;
+        role_hint: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodNumber;
+        assumptions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        evidence_used: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        rewrite_guidance: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        focus_areas: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        priority_functions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        summary: string;
+        confidence: number;
+        module_name: string;
+        evidence_used: string[];
+        assumptions: string[];
+        focus_areas: string[];
+        priority_functions: string[];
+        role_hint?: string | undefined;
+        refined_name?: string | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+    }, {
+        summary: string;
+        confidence: number;
+        module_name: string;
+        evidence_used?: string[] | undefined;
+        role_hint?: string | undefined;
+        refined_name?: string | undefined;
+        assumptions?: string[] | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        focus_areas?: string[] | undefined;
+        priority_functions?: string[] | undefined;
+    }>, "many">;
+    client_name: z.ZodOptional<z.ZodString>;
+    model_name: z.ZodOptional<z.ZodString>;
+    prepare_artifact_id: z.ZodOptional<z.ZodString>;
+    session_tag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sample_id: string;
+    reviews: {
+        summary: string;
+        confidence: number;
+        module_name: string;
+        evidence_used: string[];
+        assumptions: string[];
+        focus_areas: string[];
+        priority_functions: string[];
+        role_hint?: string | undefined;
+        refined_name?: string | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+    }[];
+    session_tag?: string | undefined;
+    client_name?: string | undefined;
+    model_name?: string | undefined;
+    prepare_artifact_id?: string | undefined;
+}, {
+    sample_id: string;
+    reviews: {
+        summary: string;
+        confidence: number;
+        module_name: string;
+        evidence_used?: string[] | undefined;
+        role_hint?: string | undefined;
+        refined_name?: string | undefined;
+        assumptions?: string[] | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        focus_areas?: string[] | undefined;
+        priority_functions?: string[] | undefined;
+    }[];
+    session_tag?: string | undefined;
+    client_name?: string | undefined;
+    model_name?: string | undefined;
+    prepare_artifact_id?: string | undefined;
+}>;
+export declare const codeModuleReviewApplyOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodObject<{
+        sample_id: z.ZodString;
+        accepted_count: z.ZodNumber;
+        rejected_count: z.ZodNumber;
+        accepted_reviews: z.ZodArray<z.ZodObject<{
+            module_name: z.ZodString;
+            refined_name: z.ZodNullable<z.ZodString>;
+            confidence: z.ZodNumber;
+            rewrite_guidance_count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }, {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }>, "many">;
+        artifact: z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"semantic_module_reviews">;
+            path: z.ZodString;
+            sha256: z.ZodString;
+            mime: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        }, {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        }>;
+        next_steps: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        next_steps: string[];
+        accepted_count: number;
+        rejected_count: number;
+        accepted_reviews: {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }[];
+    }, {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        next_steps: string[];
+        accepted_count: number;
+        rejected_count: number;
+        accepted_reviews: {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }[];
+    }>>;
+    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;
+    data?: {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        next_steps: string[];
+        accepted_count: number;
+        rejected_count: number;
+        accepted_reviews: {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }[];
+    } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}, {
+    ok: boolean;
+    data?: {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_module_reviews";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        next_steps: string[];
+        accepted_count: number;
+        rejected_count: number;
+        accepted_reviews: {
+            confidence: number;
+            module_name: string;
+            refined_name: string | null;
+            rewrite_guidance_count: number;
+        }[];
+    } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}>;
+export declare const codeModuleReviewApplyToolDefinition: ToolDefinition;
+export declare function createCodeModuleReviewApplyHandler(workspaceManager: WorkspaceManager, database: DatabaseManager): (args: ToolArgs) => Promise<WorkerResult>;
+//# sourceMappingURL=code-module-review-apply.d.ts.map

package/dist/tools/code-module-review-apply.js

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import { persistSemanticModuleReviewsArtifact, SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE, } from '../semantic-name-suggestion-artifacts.js';
+const TOOL_NAME = 'code.module.review.apply';
+const ModuleReviewInputSchema = z.object({
+    module_name: z.string().min(1).max(120).describe('Module name as returned by code.reconstruct.export'),
+    refined_name: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe('Optional refined human-readable module display name'),
+    summary: z.string().min(1).max(1600).describe('Evidence-grounded plain-language explanation of the module'),
+    role_hint: z
+        .string()
+        .min(1)
+        .max(240)
+        .optional()
+        .describe('Optional refined module role hint, such as export dispatch or COM activation'),
+    confidence: z.number().min(0).max(1).describe('Heuristic support score for the module review'),
+    assumptions: z.array(z.string()).optional().default([]).describe('Assumptions that must hold for the review to remain valid'),
+    evidence_used: z.array(z.string()).optional().default([]).describe('Evidence sources used by the external LLM'),
+    rewrite_guidance: z
+        .union([z.string().min(1), z.array(z.string().min(1))])
+        .optional()
+        .describe('One or more rewrite-oriented guidance items derived from the evidence'),
+    focus_areas: z
+        .array(z.string().min(1))
+        .optional()
+        .default([])
+        .describe('Optional high-value focus areas inside the module'),
+    priority_functions: z
+        .array(z.string().min(1))
+        .optional()
+        .default([])
+        .describe('Optional function names or addresses that should be prioritized inside the module'),
+});
+function normalizeStringArray(input, limit = 12) {
+    if (!input) {
+        return [];
+    }
+    const values = Array.isArray(input) ? input : [input];
+    return values.map((item) => item.trim()).filter((item) => item.length > 0).slice(0, limit);
+}
+export const codeModuleReviewApplyInputSchema = z.object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    reviews: z
+        .array(ModuleReviewInputSchema)
+        .min(1)
+        .describe('Structured module review outputs returned by an external MCP client / LLM'),
+    client_name: z
+        .string()
+        .optional()
+        .describe('Optional client identifier, such as claude-desktop or codex-cli'),
+    model_name: z
+        .string()
+        .optional()
+        .describe('Optional model identifier for provenance only'),
+    prepare_artifact_id: z
+        .string()
+        .optional()
+        .describe('Optional semantic_module_review_prepare_bundle artifact ID that produced this review task'),
+    session_tag: z
+        .string()
+        .optional()
+        .describe('Optional semantic module review session tag used for artifact grouping'),
+});
+export const codeModuleReviewApplyOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z
+        .object({
+        sample_id: z.string(),
+        accepted_count: z.number().int().nonnegative(),
+        rejected_count: z.number().int().nonnegative(),
+        accepted_reviews: z.array(z.object({
+            module_name: z.string(),
+            refined_name: z.string().nullable(),
+            confidence: z.number().min(0).max(1),
+            rewrite_guidance_count: z.number().int().nonnegative(),
+        })),
+        artifact: z.object({
+            id: z.string(),
+            type: z.literal(SEMANTIC_MODULE_REVIEWS_ARTIFACT_TYPE),
+            path: z.string(),
+            sha256: z.string(),
+            mime: z.string().optional(),
+        }),
+        next_steps: z.array(z.string()),
+    })
+        .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(),
+});
+export const codeModuleReviewApplyToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Persist structured module review outputs returned by any external MCP client / LLM so export and workflow layers can consume them.',
+    inputSchema: codeModuleReviewApplyInputSchema,
+    outputSchema: codeModuleReviewApplyOutputSchema,
+};
+export function createCodeModuleReviewApplyHandler(workspaceManager, database) {
+    return async (args) => {
+        const startTime = Date.now();
+        try {
+            const input = codeModuleReviewApplyInputSchema.parse(args);
+            const sample = database.findSample(input.sample_id);
+            if (!sample) {
+                return {
+                    ok: false,
+                    errors: [`Sample not found: ${input.sample_id}`],
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
+            const acceptedReviews = [];
+            const acceptedSummary = [];
+            const warnings = [];
+            for (const review of input.reviews) {
+                const moduleName = review.module_name.trim();
+                const summary = review.summary.trim();
+                if (moduleName.length === 0 || summary.length === 0) {
+                    warnings.push('Rejected module review because module_name or summary was empty after normalization.');
+                    continue;
+                }
+                const rewriteGuidance = normalizeStringArray(review.rewrite_guidance, 10);
+                const focusAreas = normalizeStringArray(review.focus_areas, 10);
+                const priorityFunctions = normalizeStringArray(review.priority_functions, 16);
+                acceptedReviews.push({
+                    module_name: moduleName,
+                    refined_name: review.refined_name?.trim() || null,
+                    summary,
+                    role_hint: review.role_hint?.trim() || null,
+                    confidence: review.confidence,
+                    assumptions: review.assumptions || [],
+                    evidence_used: review.evidence_used || [],
+                    rewrite_guidance: rewriteGuidance,
+                    focus_areas: focusAreas,
+                    priority_functions: priorityFunctions,
+                });
+                acceptedSummary.push({
+                    module_name: moduleName,
+                    refined_name: review.refined_name?.trim() || null,
+                    confidence: review.confidence,
+                    rewrite_guidance_count: rewriteGuidance.length,
+                });
+            }
+            if (acceptedReviews.length === 0) {
+                return {
+                    ok: false,
+                    errors: ['No module reviews were accepted after normalization.'],
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
+            const payload = {
+                schema_version: 1,
+                sample_id: input.sample_id,
+                created_at: new Date().toISOString(),
+                session_tag: input.session_tag || null,
+                client_name: input.client_name || null,
+                model_name: input.model_name || null,
+                prepare_artifact_id: input.prepare_artifact_id || null,
+                reviews: acceptedReviews,
+            };
+            const artifact = await persistSemanticModuleReviewsArtifact(workspaceManager, database, payload);
+            return {
+                ok: true,
+                data: {
+                    sample_id: input.sample_id,
+                    accepted_count: acceptedReviews.length,
+                    rejected_count: input.reviews.length - acceptedReviews.length,
+                    accepted_reviews: acceptedSummary,
+                    artifact,
+                    next_steps: [
+                        'rerun code.reconstruct.export to propagate module review summaries and rewrite guidance into rewrite output',
+                        'rerun workflow.reconstruct if you want refreshed role-aware export output',
+                    ],
+                },
+                warnings: warnings.length > 0 ? warnings : undefined,
+                artifacts: [artifact],
+                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=code-module-review-apply.js.map