@jshookmcp/jshook 0.1.4 → 0.1.6

package/dist/server/domains/process/handlers.impl.core.runtime.base.d.ts

@@ -1,4 +1,36 @@
 import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
+import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
+interface MemoryDiagnosticsInput {
+    pid?: number;
+    address?: string;
+    size?: number;
+    operation: string;
+    error?: string;
+}
+interface MemoryDiagnostics {
+    permission: {
+        available: boolean;
+        reason?: string;
+        platform: string;
+    };
+    process: {
+        exists: boolean | null;
+        pid: number | null;
+        name: string | null;
+    };
+    address: {
+        queried: boolean;
+        valid: boolean | null;
+        protection: string | null;
+        regionStart: string | null;
+        regionSize: number | null;
+    };
+    aslr: {
+        heuristic: true;
+        note: string;
+    };
+    recommendedActions: string[];
+}
 export declare function validatePid(value: unknown): number;
 export declare function requireString(value: unknown, name: string): string;
 export declare function requirePositiveNumber(value: unknown, name: string): number;
@@ -6,7 +38,9 @@ export declare class ProcessToolHandlersBase {
     protected processManager: UnifiedProcessManager;
     protected memoryManager: MemoryManager;
     protected platform: string;
+    protected auditTrail: MemoryAuditTrail;
     constructor();
+    protected buildMemoryDiagnostics(input: MemoryDiagnosticsInput): Promise<MemoryDiagnostics>;
     handleProcessFind(args: Record<string, unknown>): Promise<{
         content: {
             type: string;
@@ -50,4 +84,4 @@ export declare class ProcessToolHandlersBase {
         }[];
     }>;
 }
-//# sourceMappingURL=handlers.impl.core.runtime.base.d.ts.map
+export {};

package/dist/server/domains/process/handlers.impl.core.runtime.base.js

@@ -1,4 +1,5 @@
 import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
+import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
 import { logger } from '../../../utils/logger.js';
 export function validatePid(value) {
     const n = Number(value);
@@ -22,12 +23,115 @@ export class ProcessToolHandlersBase {
     processManager;
     memoryManager;
     platform;
+    auditTrail = new MemoryAuditTrail();
     constructor() {
         this.processManager = new UnifiedProcessManager();
         this.memoryManager = new MemoryManager();
         this.platform = this.processManager.getPlatform();
         logger.info(`ProcessToolHandlers initialized for platform: ${this.platform}`);
     }
+    async buildMemoryDiagnostics(input) {
+        const recommendedActions = new Set();
+        const permission = await this.memoryManager.checkAvailability();
+        if (!permission.available) {
+            recommendedActions.add('Run as administrator');
+        }
+        let processInfo = null;
+        if (input.pid != null) {
+            try {
+                const resolvedProcess = await this.processManager.getProcessByPid(input.pid);
+                processInfo = resolvedProcess
+                    ? {
+                        pid: resolvedProcess.pid,
+                        name: resolvedProcess.name,
+                        executablePath: resolvedProcess.executablePath,
+                        windowTitle: resolvedProcess.windowTitle,
+                        windowHandle: resolvedProcess.windowHandle,
+                        memoryUsage: resolvedProcess.memoryUsage,
+                    }
+                    : null;
+            }
+            catch {
+                processInfo = null;
+            }
+            if (!processInfo) {
+                recommendedActions.add('Check if process is still running');
+            }
+        }
+        let protectionInfo = null;
+        let protectionQueryFailed = false;
+        if (input.pid != null && input.address) {
+            try {
+                protectionInfo = await this.memoryManager.checkMemoryProtection(input.pid, input.address);
+            }
+            catch {
+                protectionQueryFailed = true;
+            }
+            if (protectionQueryFailed || protectionInfo?.success === false) {
+                recommendedActions.add('Verify address is within valid memory region');
+            }
+        }
+        if (input.size != null && protectionInfo?.regionSize != null && input.size > protectionInfo.regionSize) {
+            recommendedActions.add('Reduce the requested size to fit the target memory region');
+        }
+        if (input.operation === 'memory_read' && protectionInfo?.success && protectionInfo.isReadable === false) {
+            recommendedActions.add('Ensure target memory region is readable');
+        }
+        if (input.operation === 'memory_write' && protectionInfo?.success && protectionInfo.isWritable === false) {
+            recommendedActions.add('Ensure target memory region is writable');
+        }
+        let modulesEnumerated = false;
+        let moduleCount = null;
+        if (input.pid != null) {
+            try {
+                const modulesResult = await this.memoryManager.enumerateModules(input.pid);
+                modulesEnumerated = modulesResult.success;
+                moduleCount = modulesResult.modules?.length ?? null;
+            }
+            catch {
+                modulesEnumerated = false;
+            }
+        }
+        if (input.pid != null && input.address) {
+            recommendedActions.add('Re-resolve the address after the process restarts because ASLR can shift module addresses');
+        }
+        const normalizedError = input.error?.toLowerCase() ?? '';
+        if (normalizedError.includes('access denied') ||
+            normalizedError.includes('permission') ||
+            normalizedError.includes('privilege') ||
+            normalizedError.includes('administrator')) {
+            recommendedActions.add('Run as administrator');
+        }
+        const aslrNote = modulesEnumerated
+            ? moduleCount && moduleCount > 0
+                ? `Enumerated ${moduleCount} module(s). Treat absolute addresses as session-specific because ASLR can shift module bases between launches.`
+                : 'Module enumeration succeeded but returned no modules. Absolute addresses may still change across process launches because of ASLR.'
+            : 'Module enumeration was unavailable. Assume ASLR may shift absolute addresses between launches and re-resolve addresses after restarts.';
+        return {
+            permission: {
+                available: permission.available,
+                reason: permission.reason,
+                platform: this.platform,
+            },
+            process: {
+                exists: input.pid != null ? Boolean(processInfo) : null,
+                pid: input.pid ?? null,
+                name: processInfo?.name ?? null,
+            },
+            address: {
+                queried: input.pid != null && Boolean(input.address),
+                valid: input.pid != null && input.address ? protectionInfo?.success ?? null : null,
+                protection: protectionInfo?.protection ?? null,
+                regionStart: protectionInfo?.regionStart ?? null,
+                regionSize: protectionInfo?.regionSize ?? null,
+            },
+            aslr: {
+                heuristic: true,
+                note: aslrNote,
+            },
+            recommendedActions: Array.from(recommendedActions),
+        };
+    }
     async handleProcessFind(args) {
         try {
             const pattern = requireString(args.pattern, 'pattern');
@@ -86,7 +190,9 @@ export class ProcessToolHandlersBase {
                 };
             }
             const cmdLine = await this.processManager.getProcessCommandLine(pid);
-            const debugPort = await this.processManager.checkDebugPort(pid);
+            const debugPort = await this.processManager.checkDebugPort(pid, {
+                commandLine: cmdLine.commandLine,
+            });
             return {
                 content: [
                     {
@@ -296,4 +402,3 @@ export class ProcessToolHandlersBase {
         }
     }
 }
-//# sourceMappingURL=handlers.impl.core.runtime.base.js.map

package/dist/server/domains/process/handlers.impl.core.runtime.d.ts

@@ -1,2 +1 @@
 export { ProcessToolHandlersRuntime as ProcessToolHandlers } from '../../domains/process/handlers.impl.core.runtime.inject.js';
-//# sourceMappingURL=handlers.impl.core.runtime.d.ts.map

package/dist/server/domains/process/handlers.impl.core.runtime.inject.d.ts

@@ -31,4 +31,3 @@ export declare class ProcessToolHandlersRuntime extends ProcessToolHandlersMemor
         }[];
     }>;
 }
-//# sourceMappingURL=handlers.impl.core.runtime.inject.d.ts.map

package/dist/server/domains/process/handlers.impl.core.runtime.inject.js

@@ -1,12 +1,67 @@
 import { logger } from '../../../utils/logger.js';
+import { ENABLE_INJECTION_TOOLS } from '../../../constants.js';
 import { ProcessToolHandlersMemory } from '../../domains/process/handlers.impl.core.runtime.memory.js';
 import { requireString, validatePid } from '../../domains/process/handlers.impl.core.runtime.base.js';
+const INJECTION_TOOLS_DISABLED_ERROR = 'Injection tools are disabled by default for safety. Set ENABLE_INJECTION_TOOLS=true before starting the server to enable DLL and shellcode injection.';
+const INJECTION_TOOLS_ENABLE_GUIDANCE = 'Set ENABLE_INJECTION_TOOLS=true before starting the server.';
+const INJECTION_TOOLS_SECURITY_NOTICE = 'Only enable injection tools in an authorized debugging, lab, or CTF environment.';
+function buildInjectionDisabledPayload() {
+    return {
+        success: false,
+        error: INJECTION_TOOLS_DISABLED_ERROR,
+        howToEnable: INJECTION_TOOLS_ENABLE_GUIDANCE,
+        securityNotice: INJECTION_TOOLS_SECURITY_NOTICE,
+    };
+}
+function getOptionalPid(value) {
+    const pid = Number(value);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function getOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function getShellcodeSize(shellcode, encoding) {
+    if (encoding === 'hex') {
+        const normalized = shellcode.replace(/\s+/g, '');
+        return Math.ceil(normalized.length / 2);
+    }
+    return Buffer.from(shellcode, 'base64').length;
+}
 export class ProcessToolHandlersRuntime extends ProcessToolHandlersMemory {
     async handleInjectDll(args) {
+        const startedAt = Date.now();
+        if (!ENABLE_INJECTION_TOOLS) {
+            this.recordMemoryAudit({
+                operation: 'inject_dll',
+                pid: getOptionalPid(args.pid),
+                address: getOptionalString(args.dllPath),
+                size: null,
+                result: 'failure',
+                error: INJECTION_TOOLS_DISABLED_ERROR,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(buildInjectionDisabledPayload(), null, 2),
+                    },
+                ],
+            };
+        }
         try {
             const pid = validatePid(args.pid);
             const dllPath = requireString(args.dllPath, 'dllPath');
             const result = await this.memoryManager.injectDll(pid, dllPath);
+            this.recordMemoryAudit({
+                operation: 'inject_dll',
+                pid,
+                address: dllPath,
+                size: null,
+                result: result.success ? 'success' : 'failure',
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            });
             return {
                 content: [
                     {
@@ -18,22 +73,64 @@ export class ProcessToolHandlersRuntime extends ProcessToolHandlersMemory {
         }
         catch (error) {
             logger.error('DLL injection failed:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.recordMemoryAudit({
+                operation: 'inject_dll',
+                pid: getOptionalPid(args.pid),
+                address: getOptionalString(args.dllPath),
+                size: null,
+                result: 'failure',
+                error: errorMessage,
+                durationMs: Date.now() - startedAt,
+            });
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                        text: JSON.stringify({ success: false, error: errorMessage }, null, 2),
                     },
                 ],
             };
         }
     }
     async handleInjectShellcode(args) {
+        const startedAt = Date.now();
+        if (!ENABLE_INJECTION_TOOLS) {
+            const shellcode = getOptionalString(args.shellcode);
+            const encoding = args.encoding || 'hex';
+            this.recordMemoryAudit({
+                operation: 'inject_shellcode',
+                pid: getOptionalPid(args.pid),
+                address: null,
+                size: shellcode ? getShellcodeSize(shellcode, encoding) : null,
+                result: 'failure',
+                error: INJECTION_TOOLS_DISABLED_ERROR,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(buildInjectionDisabledPayload(), null, 2),
+                    },
+                ],
+            };
+        }
         try {
             const pid = validatePid(args.pid);
             const shellcode = requireString(args.shellcode, 'shellcode');
             const encoding = args.encoding || 'hex';
+            const size = getShellcodeSize(shellcode, encoding);
             const result = await this.memoryManager.injectShellcode(pid, shellcode, encoding);
+            this.recordMemoryAudit({
+                operation: 'inject_shellcode',
+                pid,
+                address: null,
+                size,
+                result: result.success ? 'success' : 'failure',
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            });
             return {
                 content: [
                     {
@@ -45,11 +142,23 @@ export class ProcessToolHandlersRuntime extends ProcessToolHandlersMemory {
         }
         catch (error) {
             logger.error('Shellcode injection failed:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const shellcode = getOptionalString(args.shellcode);
+            const encoding = args.encoding || 'hex';
+            this.recordMemoryAudit({
+                operation: 'inject_shellcode',
+                pid: getOptionalPid(args.pid),
+                address: null,
+                size: shellcode ? getShellcodeSize(shellcode, encoding) : null,
+                result: 'failure',
+                error: errorMessage,
+                durationMs: Date.now() - startedAt,
+            });
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                        text: JSON.stringify({ success: false, error: errorMessage }, null, 2),
                     },
                 ],
             };
@@ -299,4 +408,3 @@ export class ProcessToolHandlersRuntime extends ProcessToolHandlersMemory {
         }
     }
 }
-//# sourceMappingURL=handlers.impl.core.runtime.inject.js.map

package/dist/server/domains/process/handlers.impl.core.runtime.js

@@ -1,2 +1 @@
 export { ProcessToolHandlersRuntime as ProcessToolHandlers } from '../../domains/process/handlers.impl.core.runtime.inject.js';
-//# sourceMappingURL=handlers.impl.core.runtime.js.map

package/dist/server/domains/process/handlers.impl.core.runtime.memory.d.ts

@@ -1,5 +1,8 @@
+import type { AuditEntry } from '../../../modules/process/memory/AuditTrail.js';
 import { ProcessToolHandlersBase } from '../../domains/process/handlers.impl.core.runtime.base.js';
 export declare class ProcessToolHandlersMemory extends ProcessToolHandlersBase {
+    private safeBuildMemoryDiagnostics;
+    protected recordMemoryAudit(entry: Omit<AuditEntry, 'timestamp' | 'user'>): void;
     handleMemoryRead(args: Record<string, unknown>): Promise<{
         content: {
             type: string;
@@ -18,6 +21,12 @@ export declare class ProcessToolHandlersMemory extends ProcessToolHandlersBase {
             text: string;
         }[];
     }>;
+    handleMemoryAuditExport(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
     handleMemoryCheckProtection(args: Record<string, unknown>): Promise<{
         content: {
             type: string;
@@ -49,4 +58,3 @@ export declare class ProcessToolHandlersMemory extends ProcessToolHandlersBase {
         }[];
     }>;
 }
-//# sourceMappingURL=handlers.impl.core.runtime.memory.d.ts.map