windows-exe-decompiler-mcp-server 0.1.0

package/dist/env-validator.js

@@ -0,0 +1,249 @@
+/**
+ * Environment validation for MCP Server
+ * Validates that required dependencies and paths exist
+ */
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+/**
+ * Check if a file or directory exists
+ */
+function pathExists(path) {
+    try {
+        fs.accessSync(path, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a command is available in PATH
+ */
+function commandExists(command) {
+    try {
+        execSync(`which ${command}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate Node.js version
+ */
+function validateNodeVersion() {
+    const version = process.version;
+    const major = parseInt(version.slice(1).split('.')[0], 10);
+    if (major < 18) {
+        return {
+            valid: false,
+            error: `Node.js version ${version} is not supported. Minimum required version is 18.0.0`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate workspace directory
+ */
+function validateWorkspace(workspaceRoot) {
+    if (!pathExists(workspaceRoot)) {
+        try {
+            fs.mkdirSync(workspaceRoot, { recursive: true });
+            return { valid: true, warning: `Created workspace directory: ${workspaceRoot}` };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: `Failed to create workspace directory ${workspaceRoot}: ${error.message}`,
+            };
+        }
+    }
+    // Check if directory is writable
+    try {
+        fs.accessSync(workspaceRoot, fs.constants.W_OK);
+        return { valid: true };
+    }
+    catch {
+        return {
+            valid: false,
+            error: `Workspace directory ${workspaceRoot} is not writable`,
+        };
+    }
+}
+/**
+ * Validate database configuration
+ */
+function validateDatabase(dbConfig) {
+    if (dbConfig.type === 'sqlite') {
+        if (dbConfig.path) {
+            const dir = path.dirname(dbConfig.path);
+            if (dir && dir !== '.' && !pathExists(dir)) {
+                try {
+                    fs.mkdirSync(dir, { recursive: true });
+                    return { valid: true, warning: `Created database directory: ${dir}` };
+                }
+                catch (error) {
+                    return {
+                        valid: false,
+                        error: `Failed to create database directory ${dir}: ${error.message}`,
+                    };
+                }
+            }
+        }
+        return { valid: true };
+    }
+    if (dbConfig.type === 'postgresql') {
+        if (!dbConfig.host || !dbConfig.database) {
+            return {
+                valid: false,
+                error: 'PostgreSQL configuration requires host and database name',
+            };
+        }
+        return { valid: true };
+    }
+    return { valid: true };
+}
+/**
+ * Validate Ghidra worker configuration
+ */
+function validateGhidraWorker(ghidraConfig) {
+    if (!ghidraConfig.enabled) {
+        return { valid: true };
+    }
+    if (!ghidraConfig.path) {
+        return {
+            valid: false,
+            error: 'Ghidra worker is enabled but GHIDRA_PATH is not configured',
+        };
+    }
+    if (!pathExists(ghidraConfig.path)) {
+        return {
+            valid: false,
+            error: `Ghidra path does not exist: ${ghidraConfig.path}`,
+        };
+    }
+    // Check for analyzeHeadless script
+    const analyzeHeadless = `${ghidraConfig.path}/support/analyzeHeadless`;
+    if (!pathExists(analyzeHeadless) && !pathExists(`${analyzeHeadless}.bat`)) {
+        return {
+            valid: false,
+            error: `Ghidra analyzeHeadless script not found at ${analyzeHeadless}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate Python worker configuration
+ */
+function validatePythonWorker(staticConfig) {
+    if (!staticConfig.enabled) {
+        return { valid: true };
+    }
+    const pythonCmd = staticConfig.pythonPath || 'python3';
+    if (!commandExists(pythonCmd)) {
+        return {
+            valid: false,
+            error: `Python command not found: ${pythonCmd}`,
+        };
+    }
+    // Check Python version
+    try {
+        const version = execSync(`${pythonCmd} --version`, { encoding: 'utf-8' });
+        const match = version.match(/Python (\d+)\.(\d+)/);
+        if (match) {
+            const major = parseInt(match[1], 10);
+            const minor = parseInt(match[2], 10);
+            if (major < 3 || (major === 3 && minor < 9)) {
+                return {
+                    valid: false,
+                    error: `Python version ${version.trim()} is not supported. Minimum required version is 3.9`,
+                };
+            }
+        }
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Failed to check Python version: ${error.message}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate .NET worker configuration
+ */
+function validateDotNetWorker(dotnetConfig) {
+    if (!dotnetConfig.enabled) {
+        return { valid: true };
+    }
+    if (!dotnetConfig.ilspyPath) {
+        return {
+            valid: false,
+            error: '.NET worker is enabled but ilspyPath is not configured',
+        };
+    }
+    if (!pathExists(dotnetConfig.ilspyPath)) {
+        return {
+            valid: false,
+            error: `ILSpy path does not exist: ${dotnetConfig.ilspyPath}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate the entire environment based on configuration
+ */
+export function validateEnvironment(config) {
+    const errors = [];
+    const warnings = [];
+    // Validate Node.js version
+    const nodeValidation = validateNodeVersion();
+    if (!nodeValidation.valid && nodeValidation.error) {
+        errors.push(nodeValidation.error);
+    }
+    // Validate workspace
+    const workspaceValidation = validateWorkspace(config.workspace.root);
+    if (!workspaceValidation.valid && workspaceValidation.error) {
+        errors.push(workspaceValidation.error);
+    }
+    if (workspaceValidation.warning) {
+        warnings.push(workspaceValidation.warning);
+    }
+    // Validate database
+    const dbValidation = validateDatabase(config.database);
+    if (!dbValidation.valid && dbValidation.error) {
+        errors.push(dbValidation.error);
+    }
+    if (dbValidation.warning) {
+        warnings.push(dbValidation.warning);
+    }
+    // Validate workers
+    const ghidraValidation = validateGhidraWorker(config.workers.ghidra);
+    if (!ghidraValidation.valid && ghidraValidation.error) {
+        errors.push(ghidraValidation.error);
+    }
+    if (ghidraValidation.warning) {
+        warnings.push(ghidraValidation.warning);
+    }
+    const pythonValidation = validatePythonWorker(config.workers.static);
+    if (!pythonValidation.valid && pythonValidation.error) {
+        errors.push(pythonValidation.error);
+    }
+    if (pythonValidation.warning) {
+        warnings.push(pythonValidation.warning);
+    }
+    const dotnetValidation = validateDotNetWorker(config.workers.dotnet);
+    if (!dotnetValidation.valid && dotnetValidation.error) {
+        errors.push(dotnetValidation.error);
+    }
+    if (dotnetValidation.warning) {
+        warnings.push(dotnetValidation.warning);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=env-validator.js.map

package/dist/error-handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Error handling and classification module
+ * Requirements: 22.1, 22.2, 22.3, 22.4, 22.5, 22.6
+ */
+import { ErrorCategory, ErrorContext, ErrorResult } from './types.js';
+/**
+ * Classify an error into a category
+ * Requirements: 22.1, 22.2, 22.3
+ */
+export declare function classifyError(error: Error): ErrorCategory;
+/**
+ * Calculate exponential backoff delay
+ * Requirements: 22.4
+ *
+ * Formula: min(baseMs * 2^attempt, maxMs) + jitter
+ */
+export declare function exponentialBackoff(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Handle an error and determine retry strategy
+ * Requirements: 22.1, 22.2, 22.3, 22.4, 22.5, 22.6
+ */
+export declare function handleError(error: Error, context: ErrorContext): ErrorResult;
+/**
+ * Create a standardized error message
+ */
+export declare function formatErrorMessage(category: ErrorCategory, originalError: Error, context: ErrorContext): string;
+export { ErrorCategory, ErrorContext, ErrorResult } from './types.js';
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.example.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Example usage of the error handler module
+ * This file demonstrates how to integrate error handling into tools and workers
+ */
+/**
+ * Example: Retry logic for a tool with exponential backoff
+ */
+declare function executeToolWithRetry<T>(toolName: string, sampleId: string, operation: () => Promise<T>, maxRetries?: number): Promise<T>;
+/**
+ * Example: PE fingerprint tool with fallback parser
+ */
+declare function peFingerprint(sampleId: string, useLief?: boolean): Promise<any>;
+/**
+ * Example: Ghidra analysis with timeout handling
+ */
+declare function ghidraAnalyze(sampleId: string): Promise<any>;
+/**
+ * Example: Policy-denied error (non-retryable)
+ */
+declare function sandboxExecute(sampleId: string, requireApproval: boolean): Promise<any>;
+export { executeToolWithRetry, peFingerprint, ghidraAnalyze, sandboxExecute };
+//# sourceMappingURL=error-handler.example.d.ts.map

package/dist/error-handler.example.js

@@ -0,0 +1,141 @@
+/**
+ * Example usage of the error handler module
+ * This file demonstrates how to integrate error handling into tools and workers
+ */
+import { handleError, classifyError, formatErrorMessage, ErrorCategory } from './error-handler.js';
+/**
+ * Example: Retry logic for a tool with exponential backoff
+ */
+async function executeToolWithRetry(toolName, sampleId, operation, maxRetries = 3) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            const context = {
+                tool: toolName,
+                sampleId,
+                attempt,
+                maxRetries
+            };
+            const result = handleError(lastError, context);
+            // Log the error with formatted message
+            const category = classifyError(lastError);
+            const message = formatErrorMessage(category, lastError, context);
+            console.error(message);
+            if (!result.shouldRetry) {
+                // Handle fallback actions
+                if (result.fallbackAction === 'use_lief_instead_of_pefile') {
+                    console.log('Attempting fallback parser...');
+                    // Implement fallback logic here
+                }
+                else if (result.fallbackAction === 'log_warning') {
+                    console.warn('Partial success, continuing...');
+                }
+                else if (result.fallbackAction === 'notify_admin') {
+                    console.error('Max retries exceeded, admin notification required');
+                }
+                throw lastError;
+            }
+            // Wait before retrying
+            if (result.backoffMs) {
+                console.log(`Retrying in ${result.backoffMs}ms...`);
+                await sleep(result.backoffMs);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Example: PE fingerprint tool with fallback parser
+ */
+async function peFingerprint(sampleId, useLief = false) {
+    const context = {
+        tool: 'pe.fingerprint',
+        sampleId,
+        attempt: 0,
+        maxRetries: 1
+    };
+    try {
+        if (useLief) {
+            // Use LIEF parser
+            return await parsePEWithLief(sampleId);
+        }
+        else {
+            // Use pefile parser
+            return await parsePEWithPefile(sampleId);
+        }
+    }
+    catch (error) {
+        const result = handleError(error, context);
+        if (result.fallbackAction === 'use_lief_instead_of_pefile') {
+            console.log('Primary parser failed, trying LIEF...');
+            return await peFingerprint(sampleId, true);
+        }
+        throw error;
+    }
+}
+/**
+ * Example: Ghidra analysis with timeout handling
+ */
+async function ghidraAnalyze(sampleId) {
+    return executeToolWithRetry('ghidra.analyze', sampleId, async () => {
+        // Simulate Ghidra analysis
+        const result = await runGhidraHeadless(sampleId);
+        return result;
+    }, 3 // Max 3 retries for timeout errors
+    );
+}
+/**
+ * Example: Policy-denied error (non-retryable)
+ */
+async function sandboxExecute(sampleId, requireApproval) {
+    const context = {
+        tool: 'sandbox.execute',
+        sampleId,
+        attempt: 0,
+        maxRetries: 0 // No retries for policy errors
+    };
+    try {
+        if (!requireApproval) {
+            throw new Error('Policy denied: approval required for dynamic execution');
+        }
+        return await executeSandbox(sampleId);
+    }
+    catch (error) {
+        const result = handleError(error, context);
+        if (!result.shouldRetry) {
+            const category = classifyError(error);
+            if (category === ErrorCategory.POLICY_DENIED) {
+                console.error('Operation denied by policy guard');
+                // Log to audit log
+            }
+        }
+        throw error;
+    }
+}
+// Helper functions (stubs for demonstration)
+async function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function parsePEWithPefile(_sampleId) {
+    // Stub implementation
+    throw new Error('Parse error: malformed PE header');
+}
+async function parsePEWithLief(_sampleId) {
+    // Stub implementation
+    return { success: true, parser: 'lief' };
+}
+async function runGhidraHeadless(_sampleId) {
+    // Stub implementation
+    return { functions: [] };
+}
+async function executeSandbox(_sampleId) {
+    // Stub implementation
+    return { traces: [] };
+}
+// Export examples for documentation
+export { executeToolWithRetry, peFingerprint, ghidraAnalyze, sandboxExecute };
+//# sourceMappingURL=error-handler.example.js.map

package/dist/error-handler.js

@@ -0,0 +1,139 @@
+/**
+ * Error handling and classification module
+ * Requirements: 22.1, 22.2, 22.3, 22.4, 22.5, 22.6
+ */
+import { ErrorCategory } from './types.js';
+/**
+ * Classify an error into a category
+ * Requirements: 22.1, 22.2, 22.3
+ */
+export function classifyError(error) {
+    const message = error.message.toLowerCase();
+    // Timeout errors
+    if (message.includes('timeout') || message.includes('timed out')) {
+        return ErrorCategory.TIMEOUT;
+    }
+    // Resource exhaustion
+    if (message.includes('out of memory') ||
+        message.includes('resource exhausted') ||
+        message.includes('enomem') ||
+        message.includes('enospc')) {
+        return ErrorCategory.RESOURCE_EXHAUSTED;
+    }
+    // Worker unavailable
+    if (message.includes('worker unavailable') ||
+        message.includes('connection refused') ||
+        message.includes('econnrefused')) {
+        return ErrorCategory.WORKER_UNAVAILABLE;
+    }
+    // Invalid input
+    if (message.includes('invalid input') ||
+        message.includes('validation failed') ||
+        message.includes('invalid argument')) {
+        return ErrorCategory.INVALID_INPUT;
+    }
+    // Parse errors
+    if (message.includes('parse error') ||
+        message.includes('malformed') ||
+        message.includes('invalid pe')) {
+        return ErrorCategory.PARSE_ERROR;
+    }
+    // Policy denied
+    if (message.includes('policy denied') ||
+        message.includes('permission denied') ||
+        message.includes('unauthorized')) {
+        return ErrorCategory.POLICY_DENIED;
+    }
+    // Not found
+    if (message.includes('not found') || message.includes('enoent')) {
+        return ErrorCategory.NOT_FOUND;
+    }
+    // Partial success
+    if (message.includes('partial')) {
+        return ErrorCategory.PARTIAL_SUCCESS;
+    }
+    return ErrorCategory.UNKNOWN;
+}
+/**
+ * Calculate exponential backoff delay
+ * Requirements: 22.4
+ *
+ * Formula: min(baseMs * 2^attempt, maxMs) + jitter
+ */
+export function exponentialBackoff(attempt, baseMs = 1000, maxMs = 30000) {
+    const exponentialDelay = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    // Add jitter (0-20% of delay) to prevent thundering herd
+    const jitter = Math.random() * 0.2 * exponentialDelay;
+    return Math.floor(exponentialDelay + jitter);
+}
+/**
+ * Handle an error and determine retry strategy
+ * Requirements: 22.1, 22.2, 22.3, 22.4, 22.5, 22.6
+ */
+export function handleError(error, context) {
+    const category = classifyError(error);
+    switch (category) {
+        case ErrorCategory.TIMEOUT:
+        case ErrorCategory.RESOURCE_EXHAUSTED:
+        case ErrorCategory.WORKER_UNAVAILABLE:
+            // Retryable errors with exponential backoff
+            if (context.attempt < context.maxRetries) {
+                return {
+                    shouldRetry: true,
+                    backoffMs: exponentialBackoff(context.attempt)
+                };
+            }
+            else {
+                return {
+                    shouldRetry: false,
+                    fallbackAction: 'notify_admin'
+                };
+            }
+        case ErrorCategory.INVALID_INPUT:
+        case ErrorCategory.POLICY_DENIED:
+            // Non-retryable errors - log and fail immediately
+            return {
+                shouldRetry: false
+            };
+        case ErrorCategory.PARSE_ERROR:
+            // Try fallback parser for PE parsing errors
+            if (context.tool === 'pe.fingerprint') {
+                return {
+                    shouldRetry: true,
+                    fallbackAction: 'use_lief_instead_of_pefile'
+                };
+            }
+            else {
+                return {
+                    shouldRetry: false
+                };
+            }
+        case ErrorCategory.PARTIAL_SUCCESS:
+            // Log warning but don't retry
+            return {
+                shouldRetry: false,
+                fallbackAction: 'log_warning'
+            };
+        case ErrorCategory.NOT_FOUND:
+            // Don't retry for not found errors
+            return {
+                shouldRetry: false
+            };
+        case ErrorCategory.UNKNOWN:
+        default:
+            // Unknown errors - don't retry by default
+            return {
+                shouldRetry: false,
+                fallbackAction: 'log_error'
+            };
+    }
+}
+/**
+ * Create a standardized error message
+ */
+export function formatErrorMessage(category, originalError, context) {
+    return `[${category}] ${context.tool} failed for sample ${context.sampleId} (attempt ${context.attempt}/${context.maxRetries}): ${originalError.message}`;
+}
+// Re-export types for convenience
+export { ErrorCategory } from './types.js';
+//# sourceMappingURL=error-handler.js.map

package/dist/ghidra-analysis-status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared helpers for interpreting persisted Ghidra analysis states.
+ */
+import type { Analysis } from './database.js';
+export declare const GHIDRA_READY_STATUSES: Set<string>;
+export declare const GHIDRA_STRICT_READY_STATUSES: Set<string>;
+export type GhidraCapability = 'function_index' | 'decompile' | 'cfg';
+export type GhidraCapabilityState = 'ready' | 'degraded' | 'missing';
+export interface GhidraCapabilityStatus {
+    available: boolean;
+    status: GhidraCapabilityState;
+    reason?: string;
+    warnings?: string[];
+    checked_at?: string;
+    target?: string;
+    details?: Record<string, unknown>;
+}
+export interface GhidraAnalysisMetadata {
+    function_count?: number;
+    project_path?: string;
+    project_key?: string;
+    function_extraction?: {
+        status?: string;
+        script_used?: string;
+        warnings?: string[];
+        attempts?: unknown[];
+    };
+    readiness?: Partial<Record<GhidraCapability, GhidraCapabilityStatus>>;
+    end_to_end_probe?: {
+        target?: string;
+        decompile?: GhidraCapabilityStatus;
+        cfg?: GhidraCapabilityStatus;
+        checked_at?: string;
+    };
+    [key: string]: unknown;
+}
+export interface GhidraReadinessMatrix {
+    function_index: GhidraCapabilityStatus;
+    decompile: GhidraCapabilityStatus;
+    cfg: GhidraCapabilityStatus;
+}
+export declare function parseGhidraAnalysisMetadata(outputJson: string | null | undefined): GhidraAnalysisMetadata;
+export declare function isGhidraReadyStatus(status: string | null | undefined): boolean;
+export declare function isStrictGhidraReadyStatus(status: string | null | undefined): boolean;
+export declare function getGhidraReadiness(analysis: Pick<Analysis, 'status' | 'output_json'>): GhidraReadinessMatrix;
+export declare function getGhidraCapabilityStatus(analysis: Pick<Analysis, 'status' | 'output_json'>, capability: GhidraCapability): GhidraCapabilityStatus;
+export declare function isGhidraCapabilityReady(analysis: Pick<Analysis, 'status' | 'output_json'>, capability: GhidraCapability): boolean;
+export declare function findBestGhidraAnalysis(analyses: Analysis[], capability?: GhidraCapability): Analysis | undefined;
+//# sourceMappingURL=ghidra-analysis-status.d.ts.map