windows-exe-decompiler-mcp-server 0.1.0

package/dist/decompiler-worker.d.ts

@@ -0,0 +1,441 @@
+/**
+ * Decompiler Worker - Ghidra Headless integration
+ *
+ * Implements requirements 8.1-8.6:
+ * - Creates isolated Ghidra project spaces
+ * - Executes Ghidra Headless analysis
+ * - Extracts function lists
+ * - Stores results in database
+ * - Handles timeouts and failures
+ */
+import { type GhidraCapabilityStatus } from './ghidra-analysis-status.js';
+import type { DatabaseManager } from './database.js';
+import type { WorkspaceManager } from './workspace-manager.js';
+import type { JobResult } from './types.js';
+/**
+ * Options for Ghidra analysis
+ * Requirements: 8.1
+ */
+export interface GhidraOptions {
+    analysisId?: string;
+    projectKey?: string;
+    analysisOptions?: Record<string, unknown>;
+    timeout?: number;
+    maxCpu?: string;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result of Ghidra analysis
+ * Requirements: 8.2, 8.3, 8.4
+ */
+export interface AnalysisResult {
+    analysisId: string;
+    backend: 'ghidra';
+    functionCount: number;
+    projectPath: string;
+    status: 'done' | 'partial_success';
+    warnings?: string[];
+    readiness?: {
+        function_index: GhidraCapabilityStatus;
+        decompile: GhidraCapabilityStatus;
+        cfg: GhidraCapabilityStatus;
+    };
+}
+/**
+ * Function information extracted from Ghidra
+ * Requirements: 8.3
+ */
+export interface GhidraFunction {
+    address: string;
+    name: string;
+    size: number;
+    is_thunk: boolean;
+    is_external: boolean;
+    calling_convention: string;
+    signature: string;
+    callers: Array<{
+        address: string;
+        name: string;
+    }>;
+    caller_count: number;
+    callees: Array<{
+        address: string;
+        name: string;
+    }>;
+    callee_count: number;
+    caller_relationships?: FunctionRelationship[];
+    callee_relationships?: FunctionRelationship[];
+    is_entry_point: boolean;
+    is_exported: boolean;
+}
+/**
+ * Ghidra analysis output format
+ */
+export interface GhidraAnalysisOutput {
+    program_name: string;
+    program_path: string;
+    function_count: number;
+    functions: GhidraFunction[];
+}
+/**
+ * Function information for listing
+ * Requirements: 9.1
+ */
+export interface FunctionInfo {
+    name: string;
+    address: string;
+    size: number;
+    callers: number;
+    callees: number;
+}
+/**
+ * Ranked function with score and reasons
+ * Requirements: 9.2, 9.8
+ */
+export interface RankedFunction {
+    address: string;
+    name: string;
+    score: number;
+    reasons: string[];
+    xref_summary?: FunctionXrefSummary[];
+}
+export interface FunctionXrefSummary {
+    api: string;
+    provenance: 'static_named_call' | 'dynamic_resolution_api' | 'dynamic_resolution_helper' | 'global_string_hint' | 'unknown';
+    confidence: number;
+    evidence: string[];
+}
+export interface FunctionRelationship {
+    address: string;
+    name: string;
+    relation_types: string[];
+    reference_types: string[];
+    reference_addresses: string[];
+    target_addresses?: string[];
+    resolved_by?: string;
+    is_exact?: boolean;
+}
+export interface FunctionSearchStringMatch {
+    value: string;
+    data_address?: string;
+    referenced_from?: string;
+}
+export interface FunctionSearchMatch {
+    function: string;
+    address: string;
+    caller_count: number;
+    callee_count: number;
+    api_matches?: string[];
+    string_matches?: FunctionSearchStringMatch[];
+    match_types: Array<'api_call' | 'string_reference' | 'api_call_index'>;
+}
+export interface FunctionSearchResult {
+    query: {
+        api?: string;
+        string?: string;
+        limit: number;
+    };
+    matches: FunctionSearchMatch[];
+    count: number;
+}
+/**
+ * Cross-reference information
+ * Requirements: 10.4
+ */
+export interface CrossReference {
+    from_address: string;
+    type: string;
+    is_call: boolean;
+    is_data: boolean;
+    from_function?: string;
+}
+/**
+ * Decompiled function result
+ * Requirements: 10.1, 10.2, 10.3, 10.4
+ */
+export interface DecompiledFunction {
+    function: string;
+    address: string;
+    pseudocode: string;
+    callers: Array<{
+        address: string;
+        name: string;
+    }>;
+    callees: Array<{
+        address: string;
+        name: string;
+    }>;
+    caller_relationships?: FunctionRelationship[];
+    callee_relationships?: FunctionRelationship[];
+    xrefs?: CrossReference[];
+}
+/**
+ * CFG Node
+ * Requirements: 11.2, 11.3
+ */
+export interface CFGNode {
+    id: string;
+    address: string;
+    instructions: string[];
+    type: 'entry' | 'exit' | 'basic' | 'call' | 'return';
+}
+/**
+ * CFG Edge
+ * Requirements: 11.4
+ */
+export interface CFGEdge {
+    from: string;
+    to: string;
+    type: 'fallthrough' | 'jump' | 'call' | 'return';
+}
+/**
+ * Control Flow Graph
+ * Requirements: 11.1, 11.5
+ */
+export interface ControlFlowGraph {
+    function: string;
+    address: string;
+    nodes: CFGNode[];
+    edges: CFGEdge[];
+}
+export interface GhidraProcessDiagnostics {
+    raw_cmd: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    exit_code: number | null;
+    signal: NodeJS.Signals | null;
+    timed_out: boolean;
+    cancelled: boolean;
+    stdout: string;
+    stderr: string;
+    stdout_encoding: string;
+    stderr_encoding: string;
+    spawn_error?: string;
+}
+export interface NormalizedGhidraError {
+    code: 'timeout' | 'cancelled' | 'project_lock' | 'spawn_einval' | 'spawn_failure' | 'pyghidra_unavailable' | 'script_runtime_require_undefined' | 'missing_json_output' | 'ghidra_process_failure' | 'unknown';
+    category: 'transient' | 'environment' | 'configuration' | 'script_output' | 'process' | 'user';
+    summary: string;
+    remediation_hints: string[];
+    evidence: string[];
+    stage?: string;
+}
+export declare class GhidraProcessError extends Error {
+    readonly errorCode: 'E_TIMEOUT' | 'E_SPAWN' | 'E_GHIDRA_PROCESS' | 'E_CANCELLED';
+    readonly diagnostics: GhidraProcessDiagnostics;
+    constructor(message: string, diagnostics: GhidraProcessDiagnostics, errorCode: 'E_TIMEOUT' | 'E_SPAWN' | 'E_GHIDRA_PROCESS' | 'E_CANCELLED');
+}
+export declare class GhidraOutputParseError extends Error {
+    readonly diagnostics: GhidraProcessDiagnostics;
+    constructor(message: string, diagnostics: GhidraProcessDiagnostics);
+}
+export declare function getGhidraDiagnostics(error: unknown): GhidraProcessDiagnostics | undefined;
+export declare function normalizeGhidraError(error: unknown, stage?: string): NormalizedGhidraError | undefined;
+/**
+ * Decompiler Worker class
+ * Manages Ghidra Headless execution and result processing
+ */
+export declare class DecompilerWorker {
+    private database;
+    private workspaceManager;
+    constructor(database: DatabaseManager, workspaceManager: WorkspaceManager);
+    private delay;
+    private isProjectLockFailure;
+    private runWithProjectLockRetry;
+    /**
+     * Resolve sample file path in workspace/original.
+     * Prefer legacy "sample.exe" name, then fall back to first regular file.
+     */
+    private resolveSamplePath;
+    /**
+     * Spawn Ghidra process with Windows batch-script compatibility.
+     * On Windows, spawning .bat/.cmd directly can throw EINVAL; route through
+     * buildProcessInvocation() so batch scripts run via explicit cmd.exe quoting.
+     */
+    private spawnGhidraProcess;
+    private buildProcessDiagnostics;
+    private runGhidraCommand;
+    private buildAnalyzeBaseArgs;
+    private buildAnalysisArgs;
+    private buildExtractFunctionsArgs;
+    private executeMainAnalysis;
+    private executeFunctionExtractionScript;
+    private tryExtractFunctionsWithFallback;
+    private selectProbeTarget;
+    private buildCapabilityReadyStatus;
+    private buildCapabilityFailureStatus;
+    private probeCapability;
+    private resolveAnalysisProject;
+    private resolveGhidraAnalysisForCapability;
+    /**
+     * Analyze a sample with Ghidra Headless
+     *
+     * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
+     *
+     * @param sampleId - Sample identifier
+     * @param options - Ghidra analysis options
+     * @returns Analysis result with function count and project path
+     */
+    analyze(sampleId: string, options?: GhidraOptions): Promise<AnalysisResult>;
+    /**
+     * List functions from the functions table
+     *
+     * Requirements: 9.1
+     *
+     * @param sampleId - Sample identifier
+     * @param limit - Optional limit on number of functions to return
+     * @returns Array of function information
+     */
+    listFunctions(sampleId: string, limit?: number): Promise<FunctionInfo[]>;
+    /**
+     * Rank functions by interest score
+     *
+     * Requirements: 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8
+     *
+     * Scoring rules:
+     * - Large functions (> 1000 bytes): +10 points (Requirement 9.3)
+     * - High caller count (> 10): +5 * log(callers) points (Requirement 9.4)
+     * - Calls sensitive APIs: +15 points (Requirement 9.5)
+     * - Entry point or exported: +20 points (Requirement 9.6)
+     *
+     * @param sampleId - Sample identifier
+     * @param topK - Number of top functions to return (default: 20)
+     * @returns Array of ranked functions with scores and reasons
+     */
+    rankFunctions(sampleId: string, topK?: number): Promise<RankedFunction[]>;
+    searchFunctions(sampleId: string, options: {
+        apiQuery?: string;
+        stringQuery?: string;
+        limit?: number;
+        timeout?: number;
+    }): Promise<FunctionSearchResult>;
+    /**
+     * Decompile a specific function
+     *
+     * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6
+     *
+     * @param sampleId - Sample identifier
+     * @param addressOrSymbol - Function address (hex string) or symbol name
+     * @param includeXrefs - Whether to include cross-references (default: false)
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Decompiled function with pseudocode, callers, callees, and optional xrefs
+     */
+    decompileFunction(sampleId: string, addressOrSymbol: string, includeXrefs?: boolean, timeout?: number): Promise<DecompiledFunction>;
+    private buildOutputSnippet;
+    private buildSyntheticDiagnostics;
+    private buildNoJsonOutputMessage;
+    private normalizeNamedAddressList;
+    private normalizeStringArray;
+    private normalizeFunctionRelationships;
+    private normalizeCrossReferences;
+    private normalizeGhidraFunction;
+    private normalizeDecompiledFunction;
+    /**
+     * Parse Ghidra output JSON
+     *
+     * Requirements: 8.3
+     *
+     * @param output - Ghidra stdout output
+     * @returns Parsed analysis output
+     */
+    private parseGhidraOutput;
+    /**
+     * Execute DecompileFunction.py script
+     *
+     * Requirements: 10.1, 10.2, 10.6 (timeout handling)
+     *
+     * @param projectPath - Ghidra project directory path
+     * @param projectKey - Unique project key
+     * @param samplePath - Path to sample file
+     * @param addressOrSymbol - Function address or symbol name
+     * @param includeXrefs - Whether to include cross-references
+     * @param timeout - Timeout in milliseconds
+     * @returns Ghidra output (stdout)
+     */
+    private executeDecompileScript;
+    /**
+     * Parse decompile script output
+     *
+     * Requirements: 10.3, 10.4, 10.5
+     *
+     * @param output - Script stdout output
+     * @returns Parsed decompiled function or error
+     */
+    private parseDecompileOutput;
+    /**
+     * Get control flow graph for a function
+     *
+     * Requirements: 11.1, 11.2, 11.3, 11.4, 11.5
+     *
+     * @param sampleId - Sample identifier
+     * @param addressOrSymbol - Function address (hex string) or symbol name
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Control flow graph with nodes and edges
+     */
+    getFunctionCFG(sampleId: string, addressOrSymbol: string, timeout?: number): Promise<ControlFlowGraph>;
+    /**
+     * Execute ExtractCFG.py script
+     *
+     * Requirements: 11.1
+     *
+     * @param projectPath - Ghidra project directory path
+     * @param projectKey - Unique project key
+     * @param samplePath - Path to sample file
+     * @param addressOrSymbol - Function address or symbol name
+     * @param timeout - Timeout in milliseconds
+     * @returns Ghidra output (stdout)
+     */
+    private executeCFGScript;
+    private searchFunctionsWithGhidra;
+    private searchFunctionsFromIndex;
+    private parseFunctionCallees;
+    private executeSearchScript;
+    private parseSearchOutput;
+    /**
+     * Parse CFG script output
+     *
+     * Requirements: 11.2, 11.3, 11.4, 11.5
+     *
+     * @param output - Script stdout output
+     * @returns Parsed control flow graph or error
+     */
+    private parseCFGOutput;
+    /**
+     * Store functions to database
+     *
+     * Requirements: 8.4
+     *
+     * @param sampleId - Sample identifier
+     * @param functions - Array of functions from Ghidra
+     */
+    private storeFunctions;
+    /**
+     * Create a job result from analysis result
+     * Helper method for job queue integration
+     *
+     * @param analysisResult - Analysis result
+     * @param elapsedMs - Elapsed time in milliseconds
+     * @returns Job result
+     */
+    createJobResult(analysisResult: AnalysisResult, elapsedMs: number): JobResult;
+    /**
+     * Create a job result from error
+     * Helper method for job queue integration
+     *
+     * @param jobId - Job identifier
+     * @param error - Error that occurred
+     * @param elapsedMs - Elapsed time in milliseconds
+     * @returns Job result
+     */
+    createErrorJobResult(jobId: string, error: Error, elapsedMs: number): JobResult;
+}
+/**
+ * Create a decompiler worker instance
+ *
+ * @param database - Database manager
+ * @param workspaceManager - Workspace manager
+ * @returns Decompiler worker instance
+ */
+export declare function createDecompilerWorker(database: DatabaseManager, workspaceManager: WorkspaceManager): DecompilerWorker;
+//# sourceMappingURL=decompiler-worker.d.ts.map