windows-exe-decompiler-mcp-server 0.1.0

package/dist/analysis-provenance.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export const ArtifactSelectionProvenanceSchema = z.object({
+    scope: z.enum(['all', 'latest', 'session']),
+    session_selector: z.string().nullable(),
+    artifact_count: z.number().int().nonnegative(),
+    artifact_ids: z.array(z.string()),
+    session_tags: z.array(z.string()),
+    earliest_artifact_at: z.string().nullable(),
+    latest_artifact_at: z.string().nullable(),
+    scope_note: z.string(),
+});
+export const AnalysisProvenanceSchema = z.object({
+    runtime: ArtifactSelectionProvenanceSchema,
+    semantic_names: ArtifactSelectionProvenanceSchema.optional(),
+    semantic_explanations: ArtifactSelectionProvenanceSchema.optional(),
+});
+function emptyScopeNote(label, scope, sessionTag) {
+    if (scope === 'session' && sessionTag?.trim()) {
+        return `No ${label} matched session selector "${sessionTag.trim()}".`;
+    }
+    if (scope === 'latest') {
+        return `No ${label} matched the latest selection window.`;
+    }
+    return `No ${label} were selected.`;
+}
+export function buildRuntimeArtifactProvenance(dynamicEvidence, scope, sessionTag) {
+    if (!dynamicEvidence) {
+        return {
+            scope,
+            session_selector: sessionTag?.trim() || null,
+            artifact_count: 0,
+            artifact_ids: [],
+            session_tags: [],
+            earliest_artifact_at: null,
+            latest_artifact_at: null,
+            scope_note: emptyScopeNote('runtime evidence artifacts', scope, sessionTag),
+        };
+    }
+    return {
+        scope,
+        session_selector: dynamicEvidence.session_selector || sessionTag?.trim() || null,
+        artifact_count: dynamicEvidence.artifact_count,
+        artifact_ids: dynamicEvidence.artifact_ids || [],
+        session_tags: dynamicEvidence.session_tags || [],
+        earliest_artifact_at: dynamicEvidence.earliest_imported_at || null,
+        latest_artifact_at: dynamicEvidence.latest_imported_at || null,
+        scope_note: dynamicEvidence.scope_note || emptyScopeNote('runtime evidence artifacts', scope, sessionTag),
+    };
+}
+export function buildSemanticArtifactProvenance(label, index, scope, sessionTag) {
+    if (!index) {
+        return {
+            scope,
+            session_selector: sessionTag?.trim() || null,
+            artifact_count: 0,
+            artifact_ids: [],
+            session_tags: [],
+            earliest_artifact_at: null,
+            latest_artifact_at: null,
+            scope_note: emptyScopeNote(label, scope, sessionTag),
+        };
+    }
+    return {
+        scope,
+        session_selector: sessionTag?.trim() || null,
+        artifact_count: index.artifact_ids.length,
+        artifact_ids: index.artifact_ids,
+        session_tags: index.session_tags,
+        earliest_artifact_at: index.earliest_created_at,
+        latest_artifact_at: index.latest_created_at,
+        scope_note: index.scope_note || emptyScopeNote(label, scope, sessionTag),
+    };
+}
+//# sourceMappingURL=analysis-provenance.js.map

package/dist/analysis-task-runner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Background runner for queued analysis jobs.
+ * Current scope: execute ghidra.analyze jobs with cancellation/timeouts and stale-job reaping.
+ */
+import type { DatabaseManager } from './database.js';
+import type { WorkspaceManager } from './workspace-manager.js';
+import type { JobQueue } from './job-queue.js';
+import type { CacheManager } from './cache-manager.js';
+export interface AnalysisTaskRunnerOptions {
+    pollIntervalMs?: number;
+    staleRunningMs?: number | null;
+}
+export declare class AnalysisTaskRunner {
+    private readonly jobQueue;
+    private readonly decompilerWorker;
+    private readonly pollIntervalMs;
+    private readonly staleRunningMs?;
+    private readonly database;
+    private readonly workspaceManager;
+    private readonly cacheManager?;
+    private timer?;
+    private processing;
+    private activeControllers;
+    constructor(jobQueue: JobQueue, database: DatabaseManager, workspaceManager: WorkspaceManager, cacheManager?: CacheManager, options?: AnalysisTaskRunnerOptions);
+    start(): void;
+    stop(): void;
+    private reapStaleRunning;
+    private processNext;
+    private executeJob;
+}
+//# sourceMappingURL=analysis-task-runner.d.ts.map

package/dist/analysis-task-runner.js

@@ -0,0 +1,160 @@
+/**
+ * Background runner for queued analysis jobs.
+ * Current scope: execute ghidra.analyze jobs with cancellation/timeouts and stale-job reaping.
+ */
+import { DecompilerWorker, GhidraProcessError } from './decompiler-worker.js';
+import { logger } from './logger.js';
+import { deepStaticWorkflow } from './workflows/deep-static.js';
+export class AnalysisTaskRunner {
+    jobQueue;
+    decompilerWorker;
+    pollIntervalMs;
+    staleRunningMs;
+    database;
+    workspaceManager;
+    cacheManager;
+    timer;
+    processing = false;
+    activeControllers = new Map();
+    constructor(jobQueue, database, workspaceManager, cacheManager, options = {}) {
+        this.jobQueue = jobQueue;
+        this.database = database;
+        this.workspaceManager = workspaceManager;
+        this.cacheManager = cacheManager;
+        this.decompilerWorker = new DecompilerWorker(database, workspaceManager);
+        this.pollIntervalMs = options.pollIntervalMs ?? 500;
+        this.staleRunningMs = options.staleRunningMs;
+        this.jobQueue.on('job:cancelled', (jobId) => {
+            const controller = this.activeControllers.get(jobId);
+            if (controller) {
+                controller.abort();
+            }
+        });
+    }
+    start() {
+        if (this.timer) {
+            return;
+        }
+        this.timer = setInterval(() => {
+            this.reapStaleRunning();
+            void this.processNext();
+        }, this.pollIntervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        for (const controller of this.activeControllers.values()) {
+            controller.abort();
+        }
+        this.activeControllers.clear();
+    }
+    reapStaleRunning() {
+        if (typeof this.staleRunningMs !== 'number' ||
+            !Number.isFinite(this.staleRunningMs) ||
+            this.staleRunningMs <= 0) {
+            return;
+        }
+        const queue = this.jobQueue;
+        if (typeof queue.reapStaleRunningJobs !== 'function') {
+            return;
+        }
+        const reaped = queue.reapStaleRunningJobs(this.staleRunningMs);
+        for (const jobId of reaped) {
+            const controller = this.activeControllers.get(jobId);
+            if (controller) {
+                controller.abort();
+            }
+        }
+        if (reaped.length > 0) {
+            logger.warn({
+                reaped_count: reaped.length,
+                stale_running_ms: this.staleRunningMs,
+                jobs: reaped,
+            }, 'Reaped stale running analysis jobs');
+        }
+    }
+    async processNext() {
+        if (this.processing) {
+            return;
+        }
+        const job = this.jobQueue.dequeue();
+        if (!job) {
+            return;
+        }
+        this.processing = true;
+        const startTime = Date.now();
+        const controller = new AbortController();
+        this.activeControllers.set(job.id, controller);
+        try {
+            const result = await this.executeJob(job, controller.signal);
+            if (typeof result.metrics.elapsedMs !== 'number' || result.metrics.elapsedMs <= 0) {
+                result.metrics.elapsedMs = Date.now() - startTime;
+            }
+            this.jobQueue.complete(job.id, result);
+        }
+        catch (error) {
+            const elapsedMs = Date.now() - startTime;
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({
+                job_id: job.id,
+                tool: job.tool,
+                sample_id: job.sampleId,
+                error: message,
+            }, 'Analysis task failed');
+            const normalizedError = error instanceof Error ? error : new Error(message);
+            this.jobQueue.complete(job.id, this.decompilerWorker.createErrorJobResult(job.id, normalizedError, elapsedMs));
+        }
+        finally {
+            this.activeControllers.delete(job.id);
+            this.processing = false;
+        }
+    }
+    async executeJob(job, abortSignal) {
+        if (job.tool === 'ghidra.analyze') {
+            const options = (job.args?.options || {});
+            try {
+                const analysisResult = await this.decompilerWorker.analyze(job.sampleId, {
+                    analysisId: job.id,
+                    timeout: job.timeout,
+                    maxCpu: options.max_cpu || '4',
+                    projectKey: options.project_key,
+                    abortSignal,
+                });
+                return this.decompilerWorker.createJobResult(analysisResult, 0);
+            }
+            catch (error) {
+                if (error instanceof GhidraProcessError && error.errorCode === 'E_CANCELLED') {
+                    throw new Error('E_CANCELLED: analysis task cancelled');
+                }
+                throw error;
+            }
+        }
+        if (job.tool === 'workflow.deep_static') {
+            if (!this.cacheManager) {
+                throw new Error('workflow.deep_static requires cache manager for queued execution');
+            }
+            const options = (job.args?.options || {});
+            const result = await deepStaticWorkflow(job.sampleId, this.workspaceManager, this.database, this.cacheManager, options, {
+                onProgress: (progress) => {
+                    this.jobQueue.updateProgress(job.id, progress);
+                },
+            });
+            return {
+                jobId: job.id,
+                ok: result.ok,
+                data: result.data,
+                errors: result.errors || [],
+                warnings: result.warnings || [],
+                artifacts: [],
+                metrics: {
+                    elapsedMs: 0,
+                    peakRssMb: 0,
+                },
+            };
+        }
+        throw new Error(`Unsupported queued tool: ${job.tool}`);
+    }
+}
+//# sourceMappingURL=analysis-task-runner.js.map

package/dist/artifact-inventory.d.ts

@@ -0,0 +1,23 @@
+import type { WorkspaceManager } from './workspace-manager.js';
+import type { DatabaseManager, Artifact } from './database.js';
+export interface ArtifactInventoryItem extends Artifact {
+    exists: boolean;
+    size_bytes: number | null;
+    modified_at: string | null;
+    tracked: boolean;
+    session_tag: string | null;
+    retention_bucket: 'active' | 'recent' | 'archive';
+    age_days: number;
+}
+export interface ArtifactInventoryOptions {
+    artifactTypes?: Iterable<string>;
+    includeMissing?: boolean;
+    includeUntrackedFiles?: boolean;
+    recursive?: boolean;
+    scanRoots?: string[];
+}
+export declare function normalizeRelativeArtifactPath(p: string): string;
+export declare function inferUntrackedArtifactType(relativePath: string): string;
+export declare function deriveArtifactSessionTag(relativePath: string): string | null;
+export declare function listArtifactInventory(workspaceManager: WorkspaceManager, database: DatabaseManager, sampleId: string, options?: ArtifactInventoryOptions): Promise<ArtifactInventoryItem[]>;
+//# sourceMappingURL=artifact-inventory.d.ts.map

package/dist/artifact-inventory.js

@@ -0,0 +1,175 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { createHash } from 'crypto';
+export function normalizeRelativeArtifactPath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.?\//, '');
+}
+export function inferUntrackedArtifactType(relativePath) {
+    const normalized = relativePath.toLowerCase();
+    if (normalized.endsWith('.pseudo.c') || normalized.includes('pseudo')) {
+        return 'ghidra_pseudocode';
+    }
+    if (normalized.includes('manifest')) {
+        return 'manifest';
+    }
+    if (normalized.includes('gaps')) {
+        return 'gaps';
+    }
+    if (normalized.includes('report')) {
+        return 'report';
+    }
+    if (normalized.includes('ioc_export')) {
+        return 'ioc_export';
+    }
+    return 'filesystem_untracked';
+}
+export function deriveArtifactSessionTag(relativePath) {
+    const normalized = normalizeRelativeArtifactPath(relativePath);
+    const segments = normalized.split('/').filter((item) => item.length > 0);
+    if (segments.length < 2) {
+        return null;
+    }
+    if (segments[0] === 'reports' && segments.length >= 4) {
+        return `${segments[0]}/${segments[1]}/${segments[2]}`;
+    }
+    if (segments[0] === 'reports' && segments.length >= 2) {
+        return `${segments[0]}/${segments[1]}`;
+    }
+    return `${segments[0]}/${segments[1]}`;
+}
+function deriveArtifactAgeDays(referenceIso) {
+    const timestamp = referenceIso ? new Date(referenceIso).getTime() : Number.NaN;
+    if (!Number.isFinite(timestamp)) {
+        return 0;
+    }
+    return Math.max(0, Math.floor((Date.now() - timestamp) / (24 * 60 * 60 * 1000)));
+}
+function deriveRetentionBucket(ageDays) {
+    if (ageDays <= 3) {
+        return 'active';
+    }
+    if (ageDays <= 14) {
+        return 'recent';
+    }
+    return 'archive';
+}
+async function collectFiles(rootPath, recursive) {
+    const items = [];
+    let entries = [];
+    try {
+        entries = (await fs.readdir(rootPath, {
+            withFileTypes: true,
+            encoding: 'utf8',
+        }));
+    }
+    catch {
+        return items;
+    }
+    for (const entry of entries) {
+        const absolute = path.join(rootPath, String(entry.name));
+        if (entry.isFile()) {
+            try {
+                const stat = await fs.stat(absolute);
+                items.push({ absolute, stat: { size: stat.size, mtime: stat.mtime } });
+            }
+            catch {
+                // Ignore transient file errors.
+            }
+            continue;
+        }
+        if (recursive && entry.isDirectory()) {
+            const nested = await collectFiles(absolute, recursive);
+            items.push(...nested);
+        }
+    }
+    return items;
+}
+async function enrichTrackedArtifact(workspaceManager, workspaceRoot, artifact) {
+    const absolutePath = workspaceManager.normalizePath(workspaceRoot, artifact.path);
+    const sessionTag = deriveArtifactSessionTag(artifact.path);
+    try {
+        const stat = await fs.stat(absolutePath);
+        const ageDays = deriveArtifactAgeDays(artifact.created_at || stat.mtime.toISOString());
+        return {
+            ...artifact,
+            exists: true,
+            size_bytes: stat.size,
+            modified_at: stat.mtime.toISOString(),
+            tracked: true,
+            session_tag: sessionTag,
+            retention_bucket: deriveRetentionBucket(ageDays),
+            age_days: ageDays,
+        };
+    }
+    catch {
+        const ageDays = deriveArtifactAgeDays(artifact.created_at);
+        return {
+            ...artifact,
+            exists: false,
+            size_bytes: null,
+            modified_at: null,
+            tracked: true,
+            session_tag: sessionTag,
+            retention_bucket: deriveRetentionBucket(ageDays),
+            age_days: ageDays,
+        };
+    }
+}
+export async function listArtifactInventory(workspaceManager, database, sampleId, options = {}) {
+    const includeMissing = options.includeMissing !== false;
+    const includeUntrackedFiles = options.includeUntrackedFiles !== false;
+    const recursive = options.recursive !== false;
+    const scanRoots = options.scanRoots || ['reports', 'ghidra', 'dotnet'];
+    const typeFilter = new Set();
+    for (const item of options.artifactTypes || []) {
+        if (typeof item === 'string' && item.length > 0) {
+            typeFilter.add(item);
+        }
+    }
+    const trackedArtifacts = database.findArtifacts(sampleId);
+    const filteredTracked = typeFilter.size > 0
+        ? trackedArtifacts.filter((item) => typeFilter.has(item.type))
+        : trackedArtifacts;
+    const workspace = await workspaceManager.getWorkspace(sampleId);
+    const tracked = await Promise.all(filteredTracked.map((artifact) => enrichTrackedArtifact(workspaceManager, workspace.root, artifact)));
+    const trackedPathSet = new Set(tracked.map((item) => normalizeRelativeArtifactPath(item.path).toLowerCase()));
+    const untracked = [];
+    if (includeUntrackedFiles) {
+        for (const scanRoot of scanRoots) {
+            const rootAbsolute = path.join(workspace.root, scanRoot);
+            const files = await collectFiles(rootAbsolute, recursive);
+            for (const file of files) {
+                const relative = normalizeRelativeArtifactPath(path.relative(workspace.root, file.absolute));
+                const key = relative.toLowerCase();
+                if (trackedPathSet.has(key)) {
+                    continue;
+                }
+                trackedPathSet.add(key);
+                const inferredType = inferUntrackedArtifactType(relative);
+                const ageDays = deriveArtifactAgeDays(file.stat.mtime.toISOString());
+                if (typeFilter.size > 0 && !typeFilter.has(inferredType)) {
+                    continue;
+                }
+                untracked.push({
+                    id: `fs:${createHash('sha1').update(relative).digest('hex')}`,
+                    sample_id: sampleId,
+                    type: inferredType,
+                    path: relative,
+                    sha256: '',
+                    mime: null,
+                    created_at: file.stat.mtime.toISOString(),
+                    exists: true,
+                    size_bytes: file.stat.size,
+                    modified_at: file.stat.mtime.toISOString(),
+                    tracked: false,
+                    session_tag: deriveArtifactSessionTag(relative),
+                    retention_bucket: deriveRetentionBucket(ageDays),
+                    age_days: ageDays,
+                });
+            }
+        }
+    }
+    const merged = [...tracked, ...untracked];
+    return includeMissing ? merged : merged.filter((item) => item.exists);
+}
+//# sourceMappingURL=artifact-inventory.js.map

package/dist/cache-manager.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Cache Manager
+ * Implements cache key generation and three-tier caching architecture
+ * Requirements: 20.1, 20.2, 20.3, 20.4, 20.5
+ */
+import type { CacheKeyParams } from './types.js';
+import type { DatabaseManager } from './database.js';
+export type CacheTier = 'memory' | 'filesystem' | 'database' | 'unknown';
+export interface CacheHitMetadata {
+    key: string;
+    tier: CacheTier;
+    createdAt?: string;
+    expiresAt?: string;
+    fetchedAt: string;
+    sampleSha256?: string;
+}
+export interface CacheHitLookup {
+    data: unknown;
+    metadata: CacheHitMetadata;
+}
+/**
+ * Cache Manager with three-tier architecture
+ *
+ * Requirements: 20.3, 20.4, 20.5, 26.1 (cache prewarming)
+ *
+ * Architecture:
+ * - L1: Memory cache (LRU, 5 minutes TTL)
+ * - L2: File system cache (30 days TTL)
+ * - L3: Database cache
+ */
+export declare class CacheManager {
+    private memoryCache;
+    private fsCache;
+    private db;
+    private prewarmInProgress;
+    constructor(cacheDir: string, db?: DatabaseManager);
+    /**
+     * Get cached result from three-tier cache
+     *
+     * Requirements: 20.3
+     *
+     * Algorithm:
+     * 1. Check L1 (memory cache)
+     * 2. If miss, check L2 (file system cache) and populate L1
+     * 3. If miss, check L3 (database cache) and populate L1 and L2
+     * 4. Return null if not found in any layer
+     *
+     * @param key - Cache key
+     * @returns Cached data or null if not found
+     */
+    getCachedResult(key: string): Promise<unknown | null>;
+    /**
+     * Get cached result with hit metadata for observability.
+     */
+    getCachedResultWithMetadata(key: string): Promise<CacheHitLookup | null>;
+    /**
+     * Set cached result in all three tiers
+     *
+     * Requirements: 20.4
+     *
+     * Algorithm:
+     * 1. Store in L1 (memory cache)
+     * 2. Store in L2 (file system cache)
+     * 3. Store in L3 (database cache) if available
+     *
+     * @param key - Cache key
+     * @param data - Data to cache
+     * @param ttl - Time to live in milliseconds (optional)
+     */
+    setCachedResult(key: string, data: unknown, ttl?: number, sampleSha256?: string): Promise<void>;
+    /**
+     * Clear all caches
+     */
+    clearAll(): void;
+    /**
+     * Prewarm cache by loading frequently accessed data into memory
+     *
+     * Requirements: 26.1 (cache prewarming)
+     *
+     * Strategy:
+     * 1. Load recent cache entries from database
+     * 2. Populate L1 (memory) and L2 (filesystem) caches
+     * 3. Prioritize entries with high access frequency
+     *
+     * @param maxEntries - Maximum number of entries to prewarm (default: 100)
+     */
+    prewarmCache(maxEntries?: number): Promise<number>;
+    /**
+     * Prewarm cache for a specific sample
+     * Loads all cached results for a sample into memory
+     *
+     * Requirements: 26.1 (cache prewarming)
+     *
+     * @param sampleSha256 - SHA256 hash of the sample
+     * @returns Number of entries prewarmed
+     */
+    prewarmSampleCache(sampleSha256: string): Promise<number>;
+}
+/**
+ * Generate deterministic cache key from parameters
+ *
+ * Requirements: 20.1, 20.2
+ *
+ * Algorithm:
+ * 1. Normalize arguments (sort keys, remove defaults)
+ * 2. Create canonical representation
+ * 3. Generate SHA256 hash
+ *
+ * @param params - Cache key parameters
+ * @returns Cache key string in format "cache:<sha256>"
+ */
+export declare function generateCacheKey(params: CacheKeyParams): string;
+/**
+ * Normalize arguments for cache key generation
+ *
+ * Requirements: 20.2
+ *
+ * Normalization rules:
+ * 1. Sort object keys recursively
+ * 2. Remove null and undefined values
+ * 3. Recursively normalize nested objects
+ * 4. Preserve arrays as-is (order matters)
+ *
+ * @param args - Arguments object to normalize
+ * @returns Normalized arguments object
+ */
+export declare function normalizeArgs(args: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=cache-manager.d.ts.map