windows-exe-decompiler-mcp-server 0.1.0

package/dist/policy-guard.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Policy Guard Component
+ * Enforces authorization rules for dangerous operations
+ * Requirements: 18.1, 18.2, 18.3, 18.4
+ */
+/**
+ * Operation types that can be checked by Policy Guard
+ */
+export type OperationType = 'static_analysis' | 'decompile' | 'dynamic_execution' | 'network_access' | 'external_upload' | 'bulk_decompile';
+/**
+ * Operation to be checked
+ */
+export interface Operation {
+    type: OperationType;
+    tool: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Context for policy decision
+ */
+export interface PolicyContext {
+    user?: string;
+    sampleId?: string;
+    timestamp?: string;
+}
+/**
+ * Policy decision result
+ */
+export interface PolicyDecision {
+    allowed: boolean;
+    reason?: string;
+    requiresApproval?: boolean;
+}
+/**
+ * Dangerous operation requiring approval
+ */
+export interface DangerousOperation {
+    type: string;
+    description: string;
+    risks: string[];
+    sampleId: string;
+}
+/**
+ * Audit event for logging
+ */
+export interface AuditEvent {
+    timestamp: string;
+    operation: string;
+    user?: string;
+    sampleId: string;
+    decision: 'allow' | 'deny';
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Policy rule configuration
+ */
+export interface PolicyRule {
+    defaultAllow: boolean;
+    requiresApproval: boolean;
+    requiresIsolation?: boolean;
+    auditLevel: 'info' | 'warning' | 'critical';
+    maxLimit?: number;
+}
+/**
+ * Policy rules for different operation types
+ * Requirements: 18.1, 18.2, 18.3, 18.4
+ */
+export declare const POLICY_RULES: Record<string, PolicyRule>;
+/**
+ * Policy Guard class for enforcing authorization rules
+ */
+export declare class PolicyGuard {
+    private auditLogPath;
+    constructor(auditLogPath?: string);
+    /**
+     * Ensure audit log file exists
+     */
+    private ensureAuditLogExists;
+    /**
+     * Check permission for an operation
+     * Requirements: 18.1, 18.2
+     */
+    checkPermission(operation: Operation, _context: PolicyContext): Promise<PolicyDecision>;
+    /**
+     * Detect if operation is dangerous based on tool and arguments
+     * Requirements: 18.1, 18.3, 18.4
+     */
+    private detectDangerousOperation;
+    /**
+     * Check if approval was provided in operation arguments
+     */
+    private checkApprovalProvided;
+    /**
+     * Check if operation exceeds limit
+     */
+    private checkLimitExceeded;
+    /**
+     * Require user approval for dangerous operation (placeholder)
+     * Requirements: 18.1
+     * Note: This is a placeholder for V0.5 when human-in-the-loop is implemented
+     */
+    requireUserApproval(_operation: DangerousOperation): Promise<boolean>;
+    /**
+     * Record audit log event
+     * Requirements: 18.5, 18.6, 23.1, 23.2, 23.4, 23.5
+     */
+    auditLog(event: AuditEvent): Promise<void>;
+    /**
+     * Get audit log path
+     */
+    getAuditLogPath(): string;
+}
+export default PolicyGuard;
+//# sourceMappingURL=policy-guard.d.ts.map

package/dist/policy-guard.js

@@ -0,0 +1,243 @@
+/**
+ * Policy Guard Component
+ * Enforces authorization rules for dangerous operations
+ * Requirements: 18.1, 18.2, 18.3, 18.4
+ */
+import fs from 'fs';
+import path from 'path';
+// ============================================================================
+// Policy Rules Configuration
+// ============================================================================
+/**
+ * Policy rules for different operation types
+ * Requirements: 18.1, 18.2, 18.3, 18.4
+ */
+export const POLICY_RULES = {
+    // Requirement 18.1: Dynamic execution requires approval
+    dynamic_execution: {
+        defaultAllow: false,
+        requiresApproval: true,
+        requiresIsolation: true,
+        auditLevel: 'critical',
+    },
+    // Requirement 18.3: External upload requires approval
+    external_upload: {
+        defaultAllow: false,
+        requiresApproval: true,
+        auditLevel: 'critical',
+    },
+    // Requirement 18.4: Bulk decompilation requires approval
+    bulk_decompile: {
+        defaultAllow: false,
+        requiresApproval: true,
+        auditLevel: 'warning',
+        maxLimit: 100,
+    },
+    // Static analysis is generally allowed
+    static_analysis: {
+        defaultAllow: true,
+        requiresApproval: false,
+        auditLevel: 'info',
+    },
+    // Regular decompilation is allowed
+    decompile: {
+        defaultAllow: true,
+        requiresApproval: false,
+        auditLevel: 'info',
+    },
+    // Network access requires approval
+    network_access: {
+        defaultAllow: false,
+        requiresApproval: true,
+        requiresIsolation: true,
+        auditLevel: 'critical',
+    },
+};
+// ============================================================================
+// Policy Guard Implementation
+// ============================================================================
+/**
+ * Policy Guard class for enforcing authorization rules
+ */
+export class PolicyGuard {
+    auditLogPath;
+    constructor(auditLogPath = './audit.log') {
+        this.auditLogPath = auditLogPath;
+        this.ensureAuditLogExists();
+    }
+    /**
+     * Ensure audit log file exists
+     */
+    ensureAuditLogExists() {
+        const dir = path.dirname(this.auditLogPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        if (!fs.existsSync(this.auditLogPath)) {
+            fs.writeFileSync(this.auditLogPath, '', 'utf-8');
+        }
+    }
+    /**
+     * Check permission for an operation
+     * Requirements: 18.1, 18.2
+     */
+    async checkPermission(operation, _context) {
+        // Detect dangerous operations
+        const dangerousType = this.detectDangerousOperation(operation);
+        // Get policy rule for the operation type
+        const rule = POLICY_RULES[dangerousType] || POLICY_RULES[operation.type];
+        if (!rule) {
+            // Unknown operation type - deny by default
+            return {
+                allowed: false,
+                reason: `Unknown operation type: ${operation.type}`,
+            };
+        }
+        // Check specific limits FIRST (e.g., bulk decompile limit)
+        if (rule.maxLimit !== undefined) {
+            const limitExceeded = this.checkLimitExceeded(operation, rule.maxLimit);
+            if (limitExceeded) {
+                return {
+                    allowed: false,
+                    reason: `Operation exceeds maximum limit of ${rule.maxLimit}`,
+                    requiresApproval: true,
+                };
+            }
+        }
+        // Check if operation requires approval
+        if (rule.requiresApproval) {
+            // Check if approval was explicitly provided
+            const hasApproval = this.checkApprovalProvided(operation);
+            if (!hasApproval) {
+                return {
+                    allowed: false,
+                    reason: `Operation '${operation.type}' requires explicit approval`,
+                    requiresApproval: true,
+                };
+            }
+        }
+        // Operation is allowed
+        return {
+            allowed: rule.defaultAllow || this.checkApprovalProvided(operation),
+            reason: rule.defaultAllow ? undefined : 'Approved by user',
+        };
+    }
+    /**
+     * Detect if operation is dangerous based on tool and arguments
+     * Requirements: 18.1, 18.3, 18.4
+     */
+    detectDangerousOperation(operation) {
+        // Check for dynamic execution
+        if (operation.tool === 'sandbox.execute' ||
+            operation.type === 'dynamic_execution') {
+            return 'dynamic_execution';
+        }
+        // Check for external upload
+        if (operation.tool.includes('upload') ||
+            operation.args.backend === 'online_sandbox' ||
+            operation.args.external === true) {
+            return 'external_upload';
+        }
+        // Check for bulk decompilation - check multiple parameters
+        if (operation.type === 'decompile') {
+            // Check count parameter
+            if (typeof operation.args.count === 'number' && operation.args.count > 100) {
+                return 'bulk_decompile';
+            }
+            // Check topk parameter
+            if (typeof operation.args.topk === 'number' && operation.args.topk > 100) {
+                return 'bulk_decompile';
+            }
+            // Check addresses array
+            if (Array.isArray(operation.args.addresses) && operation.args.addresses.length > 100) {
+                return 'bulk_decompile';
+            }
+            // Check functions array
+            if (Array.isArray(operation.args.functions) && operation.args.functions.length > 100) {
+                return 'bulk_decompile';
+            }
+        }
+        // Check for network access
+        if (operation.args.network === 'enabled' ||
+            operation.args.network === 'fake') {
+            return 'network_access';
+        }
+        return operation.type;
+    }
+    /**
+     * Check if approval was provided in operation arguments
+     */
+    checkApprovalProvided(operation) {
+        // Check for explicit approval flag
+        if (operation.args.require_user_approval === true) {
+            return true;
+        }
+        if (operation.args.approved === true) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if operation exceeds limit
+     */
+    checkLimitExceeded(operation, maxLimit) {
+        // Check count parameter
+        if (typeof operation.args.count === 'number') {
+            return operation.args.count > maxLimit;
+        }
+        // Check topk parameter (for bulk operations)
+        if (typeof operation.args.topk === 'number') {
+            return operation.args.topk > maxLimit;
+        }
+        // Check array length parameters
+        if (Array.isArray(operation.args.addresses)) {
+            return operation.args.addresses.length > maxLimit;
+        }
+        if (Array.isArray(operation.args.functions)) {
+            return operation.args.functions.length > maxLimit;
+        }
+        return false;
+    }
+    /**
+     * Require user approval for dangerous operation (placeholder)
+     * Requirements: 18.1
+     * Note: This is a placeholder for V0.5 when human-in-the-loop is implemented
+     */
+    async requireUserApproval(_operation) {
+        // Placeholder implementation - always returns false
+        // In V0.5, this will implement actual human approval mechanism
+        return false;
+    }
+    /**
+     * Record audit log event
+     * Requirements: 18.5, 18.6, 23.1, 23.2, 23.4, 23.5
+     */
+    async auditLog(event) {
+        // Ensure timestamp is set
+        if (!event.timestamp) {
+            event.timestamp = new Date().toISOString();
+        }
+        // Format as JSON Lines (one JSON object per line)
+        const logLine = JSON.stringify(event) + '\n';
+        // Append to audit log file
+        try {
+            fs.appendFileSync(this.auditLogPath, logLine, 'utf-8');
+        }
+        catch (error) {
+            // Log to console if file write fails
+            console.error('Failed to write audit log:', error);
+            console.error('Audit event:', event);
+        }
+    }
+    /**
+     * Get audit log path
+     */
+    getAuditLogPath() {
+        return this.auditLogPath;
+    }
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default PolicyGuard;
+//# sourceMappingURL=policy-guard.js.map

package/dist/process-output.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helpers for decoding process output and rendering raw command lines.
+ */
+export interface DecodedProcessText {
+    text: string;
+    encoding: string;
+}
+export interface DecodedProcessStreams {
+    stdout: DecodedProcessText;
+    stderr: DecodedProcessText;
+}
+export declare function decodeProcessText(input: Buffer | string | null | undefined, platform?: NodeJS.Platform): DecodedProcessText;
+export declare function decodeProcessStreams(stdout: Buffer | string | null | undefined, stderr: Buffer | string | null | undefined, platform?: NodeJS.Platform): DecodedProcessStreams;
+export declare function buildRawCommandLine(command: string, args: string[]): string;
+//# sourceMappingURL=process-output.d.ts.map

package/dist/process-output.js

@@ -0,0 +1,90 @@
+/**
+ * Helpers for decoding process output and rendering raw command lines.
+ */
+const WINDOWS_CANDIDATE_ENCODINGS = ['utf-8', 'gb18030', 'gbk', 'cp936', 'utf-16le', 'latin1'];
+const DEFAULT_CANDIDATE_ENCODINGS = ['utf-8', 'utf-16le', 'latin1'];
+function toBuffer(input) {
+    if (input === undefined || input === null) {
+        return Buffer.alloc(0);
+    }
+    if (Buffer.isBuffer(input)) {
+        return input;
+    }
+    return Buffer.from(input);
+}
+function scoreDecodedText(text) {
+    if (!text) {
+        return 0;
+    }
+    let replacementCount = 0;
+    let controlCount = 0;
+    for (const char of text) {
+        const code = char.charCodeAt(0);
+        if (code === 0xfffd) {
+            replacementCount += 1;
+            continue;
+        }
+        if (code < 32 && char !== '\r' && char !== '\n' && char !== '\t') {
+            controlCount += 1;
+        }
+    }
+    return text.length - replacementCount * 8 - controlCount * 2;
+}
+function tryDecode(buffer, encoding) {
+    try {
+        const decoder = new TextDecoder(encoding);
+        return decoder.decode(buffer);
+    }
+    catch {
+        return null;
+    }
+}
+export function decodeProcessText(input, platform = process.platform) {
+    if (typeof input === 'string') {
+        return {
+            text: input,
+            encoding: 'utf-8',
+        };
+    }
+    const buffer = toBuffer(input);
+    if (buffer.length === 0) {
+        return {
+            text: '',
+            encoding: 'utf-8',
+        };
+    }
+    const candidateEncodings = platform === 'win32' ? WINDOWS_CANDIDATE_ENCODINGS : DEFAULT_CANDIDATE_ENCODINGS;
+    let best = null;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (const encoding of candidateEncodings) {
+        const decoded = tryDecode(buffer, encoding);
+        if (decoded === null) {
+            continue;
+        }
+        const score = scoreDecodedText(decoded);
+        if (score > bestScore) {
+            bestScore = score;
+            best = {
+                text: decoded,
+                encoding,
+            };
+        }
+    }
+    if (best) {
+        return best;
+    }
+    return {
+        text: buffer.toString('utf8'),
+        encoding: 'utf-8',
+    };
+}
+export function decodeProcessStreams(stdout, stderr, platform = process.platform) {
+    return {
+        stdout: decodeProcessText(stdout, platform),
+        stderr: decodeProcessText(stderr, platform),
+    };
+}
+export function buildRawCommandLine(command, args) {
+    return [command, ...args].join(' ').trim();
+}
+//# sourceMappingURL=process-output.js.map

package/dist/prompts/function-explanation-review.d.ts

@@ -0,0 +1,5 @@
+import type { PromptArgs, PromptDefinition, PromptResult } from '../types.js';
+export declare const functionExplanationReviewPromptDefinition: PromptDefinition;
+export declare function buildFunctionExplanationReviewPromptText(preparedBundleJson: string, analysisGoal?: string): string;
+export declare function createFunctionExplanationReviewPromptHandler(): (args: PromptArgs) => Promise<PromptResult>;
+//# sourceMappingURL=function-explanation-review.d.ts.map

package/dist/prompts/function-explanation-review.js

@@ -0,0 +1,64 @@
+export const functionExplanationReviewPromptDefinition = {
+    name: 'reverse.function_explanation_review',
+    title: 'Function Explanation Review',
+    description: 'Guide an external LLM to explain structured reverse-engineering evidence and return strict JSON explanations grounded in MCP evidence.',
+    arguments: [
+        {
+            name: 'prepared_bundle_json',
+            description: 'JSON bundle produced by code.function.explain.prepare',
+            required: true,
+        },
+        {
+            name: 'analysis_goal',
+            description: 'Optional analysis goal to bias the explanation toward malware, tooling, or library semantics',
+            required: false,
+        },
+    ],
+};
+export function buildFunctionExplanationReviewPromptText(preparedBundleJson, analysisGoal) {
+    const goal = analysisGoal?.trim() ||
+        'Explain the supplied functions in plain language and propose evidence-grounded rewrite guidance.';
+    return [
+        goal,
+        '',
+        'You are reviewing structured reverse-engineering evidence from an MCP server.',
+        'Use only the supplied evidence bundle. Do not invent APIs, data structures, or behaviors that do not appear in the evidence.',
+        '',
+        'Explanation policy:',
+        '- Prefer behavior-first summaries such as "resolves dynamic imports", "dispatches exported commands", or "checks service control state".',
+        '- Treat all confidence values as heuristic evidence strength, not calibrated probability.',
+        '- Explicitly preserve uncertainty. If a behavior depends on an assumption, state the assumption rather than overstating certainty.',
+        '- Keep rewrite guidance implementation-oriented but evidence-grounded. Avoid pretending you recovered the original source code.',
+        '',
+        'Output contract:',
+        'Return strict JSON only, with the shape {"explanations":[...]}',
+        'Each explanation item must contain:',
+        '- address_or_function, or separate address / function fields',
+        '- summary',
+        '- behavior',
+        '- confidence',
+        '- assumptions',
+        '- evidence_used',
+        '- rewrite_guidance',
+        '',
+        'The client can use your JSON output as a post-processing explanation layer over reconstruct/export results.',
+        '',
+        'Prepared bundle JSON:',
+        preparedBundleJson,
+    ].join('\n');
+}
+export function createFunctionExplanationReviewPromptHandler() {
+    return async (args) => ({
+        description: 'Prompt template for evidence-grounded function explanation and rewrite guidance.',
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: buildFunctionExplanationReviewPromptText(args.prepared_bundle_json || '', args.analysis_goal),
+                },
+            },
+        ],
+    });
+}
+//# sourceMappingURL=function-explanation-review.js.map

package/dist/prompts/semantic-name-review.d.ts

@@ -0,0 +1,5 @@
+import type { PromptArgs, PromptDefinition, PromptResult } from '../types.js';
+export declare const semanticNameReviewPromptDefinition: PromptDefinition;
+export declare function buildSemanticNameReviewPromptText(preparedBundleJson: string, analysisGoal?: string): string;
+export declare function createSemanticNameReviewPromptHandler(): (args: PromptArgs) => Promise<PromptResult>;
+//# sourceMappingURL=semantic-name-review.d.ts.map

package/dist/prompts/semantic-name-review.js

@@ -0,0 +1,63 @@
+export const semanticNameReviewPromptDefinition = {
+    name: 'reverse.semantic_name_review',
+    title: 'Semantic Name Review',
+    description: 'Guide an external LLM to review structured reverse-engineering evidence and return JSON name suggestions.',
+    arguments: [
+        {
+            name: 'prepared_bundle_json',
+            description: 'JSON bundle produced by code.function.rename.prepare',
+            required: true,
+        },
+        {
+            name: 'analysis_goal',
+            description: 'Optional analysis goal to bias the review toward a malware/operator-tooling objective',
+            required: false,
+        },
+    ],
+};
+export function buildSemanticNameReviewPromptText(preparedBundleJson, analysisGoal) {
+    const goal = analysisGoal?.trim() ||
+        'Review the supplied function evidence bundle and propose precise, human-readable semantic names.';
+    return [
+        goal,
+        '',
+        'You are reviewing structured reverse-engineering evidence from an MCP server.',
+        'Use only the supplied evidence. Do not invent APIs, data structures, or behaviors that are not present in the bundle.',
+        '',
+        'Naming policy:',
+        '- Preserve any existing rule_based_name unless the bundle explicitly marks the function unresolved.',
+        '- Prefer snake_case names that describe observable behavior, such as read_remote_memory, write_remote_memory, or parse_pe_sections.',
+        '- Return no suggestion when evidence is too weak. Weak evidence is better represented as a lower confidence candidate than as a hallucinated precise name.',
+        '- Keep suggestions implementation-agnostic. Avoid compiler, thunk, or framework noise unless it is the dominant behavior.',
+        '',
+        'Output contract:',
+        'Return strict JSON only, with the shape {"suggestions":[...]}',
+        'Each suggestion item must contain:',
+        '- address_or_function, or separate address / function fields',
+        '- candidate_name',
+        '- confidence',
+        '- why',
+        '- required_assumptions',
+        '- evidence_used',
+        '',
+        'The client should pass your JSON result to code.function.rename.apply.',
+        '',
+        'Prepared bundle JSON:',
+        preparedBundleJson,
+    ].join('\n');
+}
+export function createSemanticNameReviewPromptHandler() {
+    return async (args) => ({
+        description: 'Prompt template for evidence-grounded semantic renaming of reconstructed functions.',
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: buildSemanticNameReviewPromptText(args.prepared_bundle_json || '', args.analysis_goal),
+                },
+            },
+        ],
+    });
+}
+//# sourceMappingURL=semantic-name-review.js.map

package/dist/runtime-correlation.d.ts

@@ -0,0 +1,34 @@
+import type { DynamicTraceSummary } from './dynamic-trace.js';
+export interface RuntimeCorrelationInput {
+    functionName?: string;
+    moduleName?: string;
+    behaviorTags?: string[];
+    xrefApis?: string[];
+    rankReasons?: string[];
+    semanticSummary?: string;
+    stringHints?: string[];
+    callTargets?: string[];
+}
+export interface RuntimeCorrelation {
+    corroborated_apis: string[];
+    corroborated_stages: string[];
+    notes: string[];
+    confidence: number;
+    executed?: boolean;
+    evidence_sources?: string[];
+    source_names?: string[];
+    artifact_count?: number;
+    executed_artifact_count?: number;
+    matched_memory_regions?: string[];
+    suggested_modules?: string[];
+    matched_by?: string[];
+    provenance_layers?: string[];
+    latest_artifact_at?: string | null;
+    scope_note?: string;
+}
+export declare function normalizeRuntimeApiName(value: string): string;
+export declare function extractSensitiveApisFromReasons(rankReasons?: string[]): string[];
+export declare function deriveRuntimeStageCandidates(input: RuntimeCorrelationInput): string[];
+export declare function correlateFunctionWithRuntimeEvidence(input: RuntimeCorrelationInput, dynamicEvidence: DynamicTraceSummary | null | undefined): RuntimeCorrelation | undefined;
+export declare function modulesSuggestedByRuntimeStages(stages?: string[]): string[];
+//# sourceMappingURL=runtime-correlation.d.ts.map