@jshookmcp/jshook 0.1.5 → 0.1.6

package/dist/server/domains/maintenance/handlers.extensions.js

@@ -233,28 +233,38 @@ async function rewriteLocalExtensionSdkDependency(installDir) {
     }
 }
 async function findRegistryEntryBySlug(registryBase, slug) {
-    let workflowFetchError;
-    try {
-        const workflowIndex = await fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' });
-        const workflowEntry = workflowIndex.data.workflows.find((item) => item.slug === slug);
+    const [workflowResult, pluginResult] = await Promise.allSettled([
+        fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' }),
+        fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' }),
+    ]);
+    if (workflowResult.status === 'fulfilled') {
+        const workflows = Array.isArray(workflowResult.value.data.workflows)
+            ? workflowResult.value.data.workflows
+            : [];
+        const workflowEntry = workflows.find((item) => item.slug === slug);
         if (workflowEntry) {
             return { entry: workflowEntry, kind: 'workflow' };
         }
     }
-    catch (error) {
-        workflowFetchError = error instanceof Error ? error : new Error(String(error));
-    }
-    let pluginFetchError;
-    try {
-        const pluginIndex = await fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' });
-        const pluginEntry = pluginIndex.data.plugins.find((item) => item.slug === slug);
+    if (pluginResult.status === 'fulfilled') {
+        const plugins = Array.isArray(pluginResult.value.data.plugins)
+            ? pluginResult.value.data.plugins
+            : [];
+        const pluginEntry = plugins.find((item) => item.slug === slug);
         if (pluginEntry) {
             return { entry: pluginEntry, kind: 'plugin' };
         }
     }
-    catch (error) {
-        pluginFetchError = error instanceof Error ? error : new Error(String(error));
-    }
+    const workflowFetchError = workflowResult.status === 'rejected'
+        ? workflowResult.reason instanceof Error
+            ? workflowResult.reason
+            : new Error(String(workflowResult.reason))
+        : undefined;
+    const pluginFetchError = pluginResult.status === 'rejected'
+        ? pluginResult.reason instanceof Error
+            ? pluginResult.reason
+            : new Error(String(pluginResult.reason))
+        : undefined;
     if (workflowFetchError && pluginFetchError) {
         throw new Error(`Failed to resolve extension slug "${slug}": workflow registry error: ${workflowFetchError.message}; plugin registry error: ${pluginFetchError.message}`);
     }
@@ -298,9 +308,19 @@ export class ExtensionManagementHandlers {
             const showWorkflows = kind === 'all' || kind === 'workflow';
             const result = { success: true };
             let stale = false;
-            if (showPlugins) {
-                const index = await fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' });
-                result.plugins = index.data.plugins.map((p) => ({
+            const pluginPromise = showPlugins
+                ? fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: 'plugins' })
+                : undefined;
+            const workflowPromise = showWorkflows
+                ? fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' })
+                : undefined;
+            const [pluginIndex, workflowIndex] = await Promise.all([
+                pluginPromise ?? Promise.resolve(undefined),
+                workflowPromise ?? Promise.resolve(undefined),
+            ]);
+            if (pluginIndex) {
+                const plugins = Array.isArray(pluginIndex.data.plugins) ? pluginIndex.data.plugins : [];
+                result.plugins = plugins.map((p) => ({
                     slug: p.slug,
                     id: p.id,
                     name: p.meta.name,
@@ -310,13 +330,13 @@ export class ExtensionManagementHandlers {
                     commit: p.source.commit,
                     entry: p.source.entry,
                 }));
-                result.pluginCount = index.data.plugins.length;
-                result.pluginSource = index.source;
-                stale = stale || index.stale;
+                result.pluginCount = plugins.length;
+                result.pluginSource = pluginIndex.source;
+                stale = stale || pluginIndex.stale;
             }
-            if (showWorkflows) {
-                const index = await fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: 'workflows' });
-                result.workflows = index.data.workflows.map((w) => ({
+            if (workflowIndex) {
+                const workflows = Array.isArray(workflowIndex.data.workflows) ? workflowIndex.data.workflows : [];
+                result.workflows = workflows.map((w) => ({
                     slug: w.slug,
                     id: w.id,
                     name: w.meta.name,
@@ -326,9 +346,9 @@ export class ExtensionManagementHandlers {
                     commit: w.source.commit,
                     entry: w.source.entry,
                 }));
-                result.workflowCount = index.data.workflows.length;
-                result.workflowSource = index.source;
-                stale = stale || index.stale;
+                result.workflowCount = workflows.length;
+                result.workflowSource = workflowIndex.source;
+                stale = stale || workflowIndex.stale;
             }
             if (stale) {
                 result.stale = true;

package/dist/server/domains/process/definitions.js

@@ -121,7 +121,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'memory_read',
-        description: 'Read memory from a process at a specific address. Requires process to be attached.',
+        description: 'Read memory from a process at a specific address. Failures include structured diagnostics for permissions, region checks, and ASLR guidance.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -143,7 +143,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'memory_write',
-        description: 'Write data to process memory at a specific address. Requires process to be attached.',
+        description: 'Write data to process memory at a specific address. Failures include structured diagnostics for permissions, region checks, and ASLR guidance.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -171,7 +171,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'memory_scan',
-        description: 'Scan process memory for a pattern or value. Useful for finding game values.',
+        description: 'Scan process memory for a pattern or value. Failures include structured diagnostics for permissions, region checks, and ASLR guidance.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -325,9 +325,22 @@ export const processToolDefinitions = [
             required: ['pid'],
         },
     },
+    {
+        name: 'memory_audit_export',
+        description: 'Export the in-memory audit trail for memory operations as JSON. Supports clear=true to flush the buffer after export.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                clear: {
+                    type: 'boolean',
+                    description: 'Clear audit trail after export',
+                },
+            },
+        },
+    },
     {
         name: 'inject_dll',
-        description: 'Inject a DLL into a target process using CreateRemoteThread + LoadLibraryA. Requires administrator privileges.',
+        description: 'Inject a DLL into a target process using CreateRemoteThread + LoadLibraryA. Disabled by default; set ENABLE_INJECTION_TOOLS=true to enable. Requires administrator privileges.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -345,7 +358,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'module_inject_dll',
-        description: 'Alias of inject_dll. Inject a DLL into a target process.',
+        description: 'Alias of inject_dll. Disabled by default; set ENABLE_INJECTION_TOOLS=true to enable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -363,7 +376,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'inject_shellcode',
-        description: 'Inject and execute shellcode in a target process. Uses VirtualAllocEx + WriteProcessMemory + CreateRemoteThread.',
+        description: 'Inject and execute shellcode in a target process. Accepts hex or base64. Disabled by default; set ENABLE_INJECTION_TOOLS=true to enable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -387,7 +400,7 @@ export const processToolDefinitions = [
     },
     {
         name: 'module_inject_shellcode',
-        description: 'Alias of inject_shellcode. Inject and execute shellcode in a target process.',
+        description: 'Alias of inject_shellcode. Disabled by default; set ENABLE_INJECTION_TOOLS=true to enable.',
         inputSchema: {
             type: 'object',
             properties: {

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,3 +84,4 @@ export declare class ProcessToolHandlersBase {
         }[];
     }>;
 }
+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: [
                     {

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),
                     },
                 ],
             };

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;