windows-exe-decompiler-mcp-server 0.1.0

package/dist/tools/yara-scan.js

@@ -0,0 +1,313 @@
+/**
+ * yara.scan tool implementation
+ * Scans PE files using YARA rules to identify malware families and packers
+ * Requirements: 5.1, 5.2, 5.3
+ */
+import { z } from 'zod';
+import { spawn } from 'child_process';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { generateCacheKey } from '../cache-manager.js';
+import { resolvePackagePath } from '../runtime-paths.js';
+import { lookupCachedResult, formatCacheWarning } from './cache-observability.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TOOL_NAME = 'yara.scan';
+const TOOL_VERSION = '1.0.0';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// ============================================================================
+// Input/Output Schemas
+// ============================================================================
+/**
+ * Input schema for yara.scan tool
+ * Requirements: 5.1, 5.2
+ */
+export const YaraScanInputSchema = z.object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    rule_set: z.string().describe('Rule set name (e.g., malware_families, packers)'),
+    timeout_ms: z.number().int().min(1000).optional().default(30000).describe('Timeout in milliseconds'),
+    rule_tier: z
+        .enum(['production', 'experimental', 'test', 'all'])
+        .optional()
+        .default('production')
+        .describe('Rule quality tier. Default production excludes weak test rules.'),
+    force_refresh: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Bypass cache lookup and recompute from source sample'),
+});
+/**
+ * Output schema for yara.scan tool
+ * Requirements: 5.2, 5.3
+ */
+export const YaraScanOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z.object({
+        matches: z.array(z.object({
+            rule: z.string(),
+            tags: z.array(z.string()),
+            meta: z.record(z.any()),
+            strings: z.array(z.object({
+                identifier: z.string(),
+                offset: z.number(),
+                matched_data: z.string(),
+                location: z.object({
+                    section: z.string().nullable().optional(),
+                    offset_in_section: z.number().nullable().optional(),
+                    rva: z.number().nullable().optional(),
+                    distance_to_entrypoint: z.number().nullable().optional(),
+                    function_hint: z.object({
+                        name: z.string(),
+                        address: z.string(),
+                        proximity: z.string(),
+                    }).nullable().optional(),
+                }).optional(),
+            })),
+            confidence: z.object({
+                level: z.enum(['low', 'medium', 'high']),
+                score: z.number(),
+                reason: z.string(),
+            }).optional(),
+            evidence: z.object({
+                import_dll_hits: z.array(z.string()),
+                import_api_hits: z.array(z.string()),
+                section_hits: z.array(z.string()).optional(),
+                near_entrypoint_hits: z.number().optional(),
+                string_only: z.boolean(),
+            }).optional(),
+            inference: z.object({
+                classification: z.string(),
+                summary: z.string(),
+            }).optional(),
+        })),
+        ruleset_version: z.string(),
+        timed_out: z.boolean(),
+        rule_set: z.string(),
+        rule_tier: z.string().optional(),
+        rule_files: z.array(z.string()).optional(),
+        confidence_summary: z.object({
+            high: z.number(),
+            medium: z.number(),
+            low: z.number(),
+        }).optional(),
+        import_evidence: z.object({
+            dll_count: z.number(),
+            api_count: z.number(),
+        }).optional(),
+        offset_mapping: z.object({
+            parser: z.string().nullable().optional(),
+            sections_count: z.number().optional(),
+            entry_point: z.record(z.any()).optional(),
+        }).optional(),
+        quality_notes: z.array(z.string()).optional(),
+    }).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(),
+});
+// ============================================================================
+// Tool Definition
+// ============================================================================
+/**
+ * Tool definition for yara.scan
+ */
+export const yaraScanToolDefinition = {
+    name: TOOL_NAME,
+    description: '使用 YARA 规则扫描样本，识别已知的恶意软件家族和加壳器',
+    inputSchema: YaraScanInputSchema,
+    outputSchema: YaraScanOutputSchema,
+};
+/**
+ * Spawn Python Static Worker and communicate via stdin/stdout JSON protocol
+ *
+ * Requirements: Worker communication
+ *
+ * @param request - Worker request object
+ * @returns Worker response object
+ */
+async function callStaticWorker(request) {
+    return new Promise((resolve, reject) => {
+        // Get Python worker path
+        const workerPath = resolvePackagePath('workers', 'static_worker.py');
+        // Spawn Python process
+        const pythonCommand = process.platform === 'win32' ? 'python' : 'python3';
+        const pythonProcess = spawn(pythonCommand, [workerPath], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        // Collect stdout
+        pythonProcess.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        // Collect stderr
+        pythonProcess.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        // Handle process exit
+        pythonProcess.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`Python worker exited with code ${code}. stderr: ${stderr}`));
+                return;
+            }
+            // Parse response from stdout
+            try {
+                const lines = stdout.trim().split('\n');
+                const lastLine = lines[lines.length - 1];
+                const response = JSON.parse(lastLine);
+                resolve(response);
+            }
+            catch (error) {
+                reject(new Error(`Failed to parse worker response: ${error.message}. stdout: ${stdout}`));
+            }
+        });
+        // Handle process error
+        pythonProcess.on('error', (error) => {
+            reject(new Error(`Failed to spawn Python worker: ${error.message}`));
+        });
+        // Send request to worker via stdin
+        try {
+            pythonProcess.stdin.write(JSON.stringify(request) + '\n');
+            pythonProcess.stdin.end();
+        }
+        catch (error) {
+            reject(new Error(`Failed to write to worker stdin: ${error.message}`));
+        }
+    });
+}
+// ============================================================================
+// Tool Handler
+// ============================================================================
+/**
+ * Create yara.scan tool handler
+ * Requirements: 5.1, 5.2, 5.3, 5.5
+ */
+export function createYaraScanHandler(workspaceManager, database, cacheManager) {
+    return async (args) => {
+        const input = args;
+        const startTime = Date.now();
+        try {
+            // 1. Validate sample exists
+            const sample = database.findSample(input.sample_id);
+            if (!sample) {
+                return {
+                    ok: false,
+                    errors: [`Sample not found: ${input.sample_id}`],
+                };
+            }
+            // 2. Generate cache key
+            // Requirement: 5.5 - Cache key includes ruleset version
+            const cacheKey = generateCacheKey({
+                sampleSha256: sample.sha256,
+                toolName: TOOL_NAME,
+                toolVersion: TOOL_VERSION,
+                args: {
+                    rule_set: input.rule_set,
+                    timeout_ms: input.timeout_ms,
+                    rule_tier: input.rule_tier,
+                },
+            });
+            // 3. Check cache
+            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,
+                        },
+                    };
+                }
+            }
+            // 4. Get sample path from workspace
+            const workspace = await workspaceManager.getWorkspace(input.sample_id);
+            // Find the sample file in the original directory
+            const fs = await import('fs/promises');
+            const files = await fs.readdir(workspace.original);
+            if (files.length === 0) {
+                return {
+                    ok: false,
+                    errors: ['Sample file not found in workspace'],
+                };
+            }
+            const samplePath = path.join(workspace.original, files[0]);
+            // 5. Prepare worker request
+            const workerRequest = {
+                job_id: uuidv4(),
+                tool: TOOL_NAME,
+                sample: {
+                    sample_id: input.sample_id,
+                    path: samplePath,
+                },
+                args: {
+                    rule_set: input.rule_set,
+                    timeout_ms: input.timeout_ms,
+                    rule_tier: input.rule_tier,
+                },
+                context: {
+                    request_time_utc: new Date().toISOString(),
+                    policy: {
+                        allow_dynamic: false,
+                        allow_network: false,
+                    },
+                    versions: {
+                        tool_version: TOOL_VERSION,
+                    },
+                },
+            };
+            // 6. Call Static Worker
+            // Requirements: 5.1, 5.2, 5.3
+            const workerResponse = await callStaticWorker(workerRequest);
+            if (!workerResponse.ok) {
+                return {
+                    ok: false,
+                    errors: workerResponse.errors,
+                    warnings: workerResponse.warnings,
+                };
+            }
+            // 7. Cache result
+            // Requirement: 5.5 - Cache with ruleset version for invalidation
+            await cacheManager.setCachedResult(cacheKey, workerResponse.data, CACHE_TTL_MS);
+            // 8. Return result
+            return {
+                ok: true,
+                data: workerResponse.data,
+                warnings: input.force_refresh
+                    ? ['force_refresh=true; bypassed cache lookup', ...(workerResponse.warnings || [])]
+                    : workerResponse.warnings,
+                errors: workerResponse.errors,
+                artifacts: workerResponse.artifacts,
+                metrics: {
+                    ...workerResponse.metrics,
+                    elapsed_ms: Date.now() - startTime,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errors: [error.message],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=yara-scan.js.map

package/dist/types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Type definitions for the MCP Server
+ */
+import { z } from 'zod';
+/**
+ * JSON Schema type for tool input/output validation
+ */
+export type JSONSchema = z.ZodTypeAny;
+/**
+ * Tool definition following MCP protocol
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    outputSchema?: JSONSchema;
+}
+/**
+ * Prompt argument definition following MCP protocol
+ */
+export interface PromptArgumentDefinition {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/**
+ * Prompt definition following MCP protocol
+ */
+export interface PromptDefinition {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: PromptArgumentDefinition[];
+}
+/**
+ * Prompt arguments (generic string map)
+ */
+export type PromptArgs = Record<string, string>;
+/**
+ * Prompt message content
+ */
+export interface PromptMessageContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * Prompt message item
+ */
+export interface PromptMessage {
+    role: 'user' | 'assistant';
+    content: PromptMessageContent;
+}
+/**
+ * Prompt handler result
+ */
+export interface PromptResult {
+    description?: string;
+    messages: PromptMessage[];
+}
+/**
+ * Content types for MCP responses
+ */
+export type ContentType = 'text' | 'resource' | 'structuredContent';
+/**
+ * Resource content structure
+ */
+export interface ResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+}
+/**
+ * Structured content with schema
+ */
+export interface StructuredContent {
+    type: string;
+    data: unknown;
+    schema?: JSONSchema;
+}
+/**
+ * Content item in tool result
+ */
+export interface Content {
+    type: ContentType;
+    text?: string;
+    resource?: ResourceContent;
+    structuredContent?: StructuredContent;
+}
+/**
+ * Tool execution result
+ */
+export interface ToolResult {
+    content: Content[];
+    isError?: boolean;
+}
+/**
+ * Tool arguments (generic)
+ */
+export type ToolArgs = Record<string, unknown>;
+/**
+ * Tool handler function type
+ */
+export type ToolHandler = (args: unknown) => Promise<ToolResult>;
+/**
+ * Worker result from analysis workers
+ */
+export interface WorkerResult {
+    ok: boolean;
+    data?: unknown;
+    errors?: string[];
+    warnings?: string[];
+    artifacts?: ArtifactRef[];
+    metrics?: Record<string, unknown>;
+}
+export interface SampleInfo {
+    sampleId: string;
+    sha256: string;
+    md5: string;
+    size: number;
+    path: string;
+}
+export interface WorkspacePath {
+    root: string;
+    original: string;
+    cache: string;
+    ghidra: string;
+    reports: string;
+}
+export interface ArtifactRef {
+    id: string;
+    type: string;
+    path: string;
+    sha256: string;
+    mime?: string;
+}
+/**
+ * Parameters for cache key generation
+ * Requirements: 20.1, 20.2
+ */
+export interface CacheKeyParams {
+    sampleSha256: string;
+    toolName: string;
+    toolVersion: string;
+    args: Record<string, unknown>;
+    rulesetVersion?: string;
+}
+/**
+ * Cached result structure
+ * Requirements: 20.3, 20.4, 20.5
+ */
+export interface CachedResult {
+    key: string;
+    data: unknown;
+    createdAt: string;
+    expiresAt?: string;
+    sampleSha256?: string;
+}
+/**
+ * Error categories for classification
+ * Requirements: 22.1, 22.2, 22.3
+ */
+export declare enum ErrorCategory {
+    TIMEOUT = "E_TIMEOUT",
+    RESOURCE_EXHAUSTED = "E_RESOURCE_EXHAUSTED",
+    WORKER_UNAVAILABLE = "E_WORKER_UNAVAILABLE",
+    INVALID_INPUT = "E_INVALID_INPUT",
+    PARSE_ERROR = "E_PARSE_PE",
+    POLICY_DENIED = "E_POLICY_DENY",
+    NOT_FOUND = "E_NOT_FOUND",
+    PARTIAL_SUCCESS = "E_PARTIAL_SUCCESS",
+    UNKNOWN = "E_UNKNOWN"
+}
+/**
+ * Context for error handling
+ * Requirements: 22.4
+ */
+export interface ErrorContext {
+    tool: string;
+    sampleId: string;
+    attempt: number;
+    maxRetries: number;
+}
+/**
+ * Result of error handling
+ * Requirements: 22.4, 22.5, 22.6
+ */
+export interface ErrorResult {
+    shouldRetry: boolean;
+    backoffMs?: number;
+    fallbackAction?: string;
+}
+/**
+ * Job priority levels (higher number = higher priority)
+ * Requirements: 21.2
+ */
+export declare enum JobPriority {
+    LOW = 1,
+    NORMAL = 5,
+    HIGH = 10,
+    CRITICAL = 20
+}
+/**
+ * Job execution status
+ * Requirements: 21.1, 21.2
+ */
+export type JobStatusType = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Retry policy for failed jobs
+ * Requirements: 21.5
+ */
+export interface RetryPolicy {
+    maxRetries: number;
+    backoffMs: number;
+    retryableErrors: string[];
+}
+/**
+ * Job definition
+ * Requirements: 21.1
+ */
+export interface Job {
+    id: string;
+    type: 'static' | 'decompile' | 'dotnet' | 'sandbox';
+    tool: string;
+    sampleId: string;
+    args: Record<string, unknown>;
+    priority: number;
+    timeout: number;
+    retryPolicy: RetryPolicy;
+    createdAt: string;
+    attempts: number;
+}
+/**
+ * Job status information
+ * Requirements: 21.1, 21.2
+ */
+export interface JobStatus {
+    id: string;
+    status: JobStatusType;
+    progress?: number;
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+}
+/**
+ * Job execution metrics
+ * Requirements: 30.1, 30.2
+ */
+export interface JobMetrics {
+    elapsedMs: number;
+    peakRssMb: number;
+    cpuPercent?: number;
+}
+/**
+ * Job execution result
+ * Requirements: 21.4
+ */
+export interface JobResult {
+    jobId: string;
+    ok: boolean;
+    data?: unknown;
+    errors: string[];
+    warnings: string[];
+    artifacts: ArtifactRef[];
+    metrics: JobMetrics;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,41 @@
+/**
+ * Type definitions for the MCP Server
+ */
+// ============================================================================
+// Error Handling Types
+// ============================================================================
+/**
+ * Error categories for classification
+ * Requirements: 22.1, 22.2, 22.3
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    // Retryable errors
+    ErrorCategory["TIMEOUT"] = "E_TIMEOUT";
+    ErrorCategory["RESOURCE_EXHAUSTED"] = "E_RESOURCE_EXHAUSTED";
+    ErrorCategory["WORKER_UNAVAILABLE"] = "E_WORKER_UNAVAILABLE";
+    // Non-retryable errors
+    ErrorCategory["INVALID_INPUT"] = "E_INVALID_INPUT";
+    ErrorCategory["PARSE_ERROR"] = "E_PARSE_PE";
+    ErrorCategory["POLICY_DENIED"] = "E_POLICY_DENY";
+    ErrorCategory["NOT_FOUND"] = "E_NOT_FOUND";
+    // Partial failures
+    ErrorCategory["PARTIAL_SUCCESS"] = "E_PARTIAL_SUCCESS";
+    // Unknown errors
+    ErrorCategory["UNKNOWN"] = "E_UNKNOWN";
+})(ErrorCategory || (ErrorCategory = {}));
+// ============================================================================
+// Job Queue Types
+// ============================================================================
+/**
+ * Job priority levels (higher number = higher priority)
+ * Requirements: 21.2
+ */
+export var JobPriority;
+(function (JobPriority) {
+    JobPriority[JobPriority["LOW"] = 1] = "LOW";
+    JobPriority[JobPriority["NORMAL"] = 5] = "NORMAL";
+    JobPriority[JobPriority["HIGH"] = 10] = "HIGH";
+    JobPriority[JobPriority["CRITICAL"] = 20] = "CRITICAL";
+})(JobPriority || (JobPriority = {}));
+//# sourceMappingURL=types.js.map