@mxf-dev/core 1.0.0

package/dist/protocols/mcp/tools/shell/ShellExecuteHandler.js

@@ -0,0 +1,314 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * ShellExecuteHandler.ts
+ *
+ * Enhanced shell command execution handler that integrates command semantics,
+ * destructive warnings, command classification, large output handling, and
+ * event emission. Replaces the inline handler in InfrastructureTools.ts.
+ *
+ * Key improvements over the original inline handler:
+ * - Uses spawn() instead of exec() — streams output, no maxBuffer limit
+ * - Interprets exit codes semantically (e.g., grep returning 1 = no matches, not error)
+ * - Classifies commands (read-only, silent, category) for downstream decision-making
+ * - Emits lifecycle events (started, completed, failed, destructive warning)
+ * - Processes large output through LargeOutputHandler (truncation + MongoDB persistence)
+ * - Surfaces destructive command warnings as informational events
+ */
+import { spawn } from 'child_process';
+import crypto from 'crypto';
+import { Events } from '../../../../events/EventNames.js';
+import { EventBus } from '../../../../events/EventBus.js';
+import { createShellExecutionStartedPayload, createShellExecutionCompletedPayload, createShellExecutionFailedPayload, createShellDestructiveWarningPayload } from '../../../../schemas/ShellExecutionEventPayloads.js';
+import { getSecurityGuard } from '../../security/McpSecurityGuard.js';
+import { getConfirmationManager } from '../../security/McpConfirmationManager.js';
+import { Logger } from '../../../../utils/Logger.js';
+import { createStrictValidator } from '../../../../utils/validation.js';
+import { classifyCommand } from './CommandClassification.js';
+import { getDestructiveWarnings } from './DestructiveCommandWarnings.js';
+import { interpretExitCode } from './CommandSemantics.js';
+import { processOutput } from './LargeOutputHandler.js';
+import { extractEffectiveCommands } from './ShellCommandParser.js';
+const logger = new Logger('info', 'ShellExecuteHandler', 'server');
+const validator = createStrictValidator('ShellExecuteHandler');
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute a short SHA-256 hash of a command string for event correlation
+ * and large output handler context.
+ */
+function computeCommandHash(command) {
+    return crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
+}
+/**
+ * Shell-escape an argument by wrapping in single quotes and escaping
+ * embedded single quotes. Matches the escaping logic from InfrastructureTools.
+ */
+function shellEscapeArg(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Build the full command string from base command and optional arguments.
+ */
+function buildFullCommand(command, args) {
+    if (!args || args.length === 0) {
+        return command;
+    }
+    const escapedArgs = args.map(shellEscapeArg).join(' ');
+    return `${command} ${escapedArgs}`;
+}
+/**
+ * Execute a command using spawn() wrapped in a Promise.
+ * Returns stdout, stderr, and exit code once the process closes.
+ */
+function spawnCommand(fullCommand, cwd, env, timeout) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(fullCommand, [], {
+            shell: true,
+            cwd,
+            env,
+            timeout
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on('data', (chunk) => {
+            stdoutChunks.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrChunks.push(chunk);
+        });
+        child.on('error', (err) => {
+            // Spawn-level error (e.g., command not found, ENOENT)
+            reject(err);
+        });
+        child.on('close', (exitCode) => {
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+                exitCode: exitCode ?? 1
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Main execute function
+// ---------------------------------------------------------------------------
+/**
+ * Execute a shell command with enhanced semantics, classification, warnings,
+ * large output handling, and event emission.
+ *
+ * This function replaces the inline handler from InfrastructureTools.shellExecTool.
+ * It integrates with the Phase 1+2 modules (CommandSemantics, CommandClassification,
+ * DestructiveCommandWarnings, LargeOutputHandler) and emits shell execution lifecycle
+ * events via EventBus.
+ *
+ * @param input - Command and execution parameters
+ * @param context - Agent/channel/request context for events and security
+ * @returns Enhanced execution result with semantic exit codes and classification
+ */
+export async function execute(input, context) {
+    try {
+        // ── 1. Validate input ──────────────────────────────────────────────
+        validator.assertIsString(input.command, 'command');
+        // ── 2. Classify the command ────────────────────────────────────────
+        const classification = classifyCommand(input.command);
+        // ── 3. Check for destructive warnings (informational only) ─────────
+        const destructiveWarnings = getDestructiveWarnings(input.command);
+        const warningMessages = destructiveWarnings.map(w => w.warning);
+        // ── 4. Security validation ─────────────────────────────────────────
+        const securityGuard = getSecurityGuard();
+        const confirmationManager = getConfirmationManager();
+        const securityContext = {
+            agentId: context.agentId,
+            channelId: context.channelId,
+            requestId: context.requestId
+        };
+        const commandValidation = securityGuard.validateCommand(input.command, securityContext);
+        if (!commandValidation.allowed) {
+            throw new Error(commandValidation.reason || 'Command not allowed');
+        }
+        // Request confirmation if the security guard requires it
+        if (commandValidation.requiresConfirmation) {
+            const confirmed = await confirmationManager.requestConfirmation('command', 'Execute shell command', {
+                command: input.command,
+                riskLevel: commandValidation.riskLevel || 'medium',
+                reason: commandValidation.reason || 'Command requires confirmation'
+            }, securityContext, input.timeout || 30000);
+            if (!confirmed) {
+                throw new Error('Command execution denied by user');
+            }
+        }
+        // ── 5. Emit destructive warning event if applicable ────────────────
+        if (destructiveWarnings.length > 0) {
+            logger.warn(`Destructive command warnings for "${input.command}": ${warningMessages.join('; ')}`);
+            EventBus.server.emit(Events.Shell.SHELL_DESTRUCTIVE_WARNING, createShellDestructiveWarningPayload(context.agentId, context.channelId, {
+                requestId: context.requestId,
+                command: input.command,
+                warnings: destructiveWarnings.map(w => ({
+                    warning: w.warning,
+                    severity: w.severity
+                }))
+            }));
+        }
+        // ── 6. Check allowed commands whitelist ────────────────────────────
+        if (input.allowedCommands) {
+            // Use the parser to extract the effective command, handling env
+            // prefixes (FOO=bar cmd) and wrappers (sudo cmd, timeout 5 cmd)
+            const effectiveCommands = extractEffectiveCommands(input.command);
+            for (const effectiveCmd of effectiveCommands) {
+                if (!input.allowedCommands.includes(effectiveCmd)) {
+                    throw new Error(`Command '${effectiveCmd}' not in allowed commands list`);
+                }
+            }
+        }
+        // ── 7. Build command string and compute hash ───────────────────────
+        const fullCommand = buildFullCommand(input.command, input.args);
+        const commandHash = computeCommandHash(input.command);
+        const timeout = input.timeout || 30000;
+        const captureOutput = input.captureOutput !== false; // default true
+        // ── 8. Emit SHELL_EXECUTION_STARTED event ──────────────────────────
+        EventBus.server.emit(Events.Shell.SHELL_EXECUTION_STARTED, createShellExecutionStartedPayload(context.agentId, context.channelId, {
+            requestId: context.requestId,
+            command: fullCommand,
+            description: input.description,
+            commandHash,
+            timeout,
+            classification: {
+                category: classification.category,
+                isReadOnly: classification.isReadOnly
+            },
+            warnings: warningMessages
+        }));
+        // ── 9. Execute the command using spawn() ───────────────────────────
+        const startTime = Date.now();
+        let stdout = '';
+        let stderr = '';
+        let exitCode = 0;
+        try {
+            const result = await spawnCommand(fullCommand, input.workingDirectory || process.cwd(), { ...process.env, ...input.environment }, timeout);
+            stdout = result.stdout;
+            stderr = result.stderr;
+            exitCode = result.exitCode;
+        }
+        catch (spawnError) {
+            // Spawn-level error (ENOENT = command not found, etc.)
+            const executionTime = Date.now() - startTime;
+            const errorMessage = spawnError.message || String(spawnError);
+            logger.error(`Spawn error for "${fullCommand}": ${errorMessage}`);
+            // Emit failed event for spawn errors
+            EventBus.server.emit(Events.Shell.SHELL_EXECUTION_FAILED, createShellExecutionFailedPayload(context.agentId, context.channelId, {
+                requestId: context.requestId,
+                command: fullCommand,
+                error: errorMessage,
+                exitCode: 127,
+                executionTime
+            }));
+            return {
+                command: fullCommand,
+                description: input.description,
+                exitCode: 127,
+                exitCodeMeaning: 'Command not found or spawn error',
+                isError: true,
+                stderr: captureOutput ? errorMessage : undefined,
+                classification: {
+                    category: classification.category,
+                    isReadOnly: classification.isReadOnly,
+                    isSilent: classification.isSilent
+                },
+                warnings: warningMessages.length > 0 ? warningMessages : undefined,
+                executionTime,
+                executedAt: Date.now()
+            };
+        }
+        const executionTime = Date.now() - startTime;
+        // ── 10. Interpret exit code semantically ───────────────────────────
+        const semanticResult = interpretExitCode(input.command, exitCode, stdout, stderr);
+        // ── 11. Process output through large output handler ────────────────
+        let outputTruncated = false;
+        let persistedOutputId;
+        let totalOutputBytes = 0;
+        let totalOutputLines = 0;
+        let processedStdout = stdout;
+        if (captureOutput && stdout) {
+            const processed = await processOutput(stdout, {
+                agentId: context.agentId,
+                channelId: context.channelId,
+                commandHash
+            });
+            processedStdout = processed.inline;
+            outputTruncated = processed.isTruncated;
+            totalOutputBytes = processed.totalBytes;
+            totalOutputLines = processed.totalLines;
+            persistedOutputId = processed.persistedOutputId;
+        }
+        // ── 12. Emit completion or failure event ───────────────────────────
+        const outputSize = totalOutputBytes || Buffer.byteLength(stdout, 'utf-8');
+        if (semanticResult.isError) {
+            EventBus.server.emit(Events.Shell.SHELL_EXECUTION_FAILED, createShellExecutionFailedPayload(context.agentId, context.channelId, {
+                requestId: context.requestId,
+                command: fullCommand,
+                error: stderr || semanticResult.meaning,
+                exitCode,
+                executionTime
+            }));
+        }
+        else {
+            EventBus.server.emit(Events.Shell.SHELL_EXECUTION_COMPLETED, createShellExecutionCompletedPayload(context.agentId, context.channelId, {
+                requestId: context.requestId,
+                command: fullCommand,
+                exitCode,
+                exitCodeMeaning: semanticResult.meaning,
+                isError: false,
+                executionTime,
+                outputSize,
+                outputTruncated,
+                persistedOutputId
+            }));
+        }
+        // ── 13. Return enhanced result ─────────────────────────────────────
+        return {
+            command: fullCommand,
+            description: input.description,
+            exitCode,
+            exitCodeMeaning: semanticResult.meaning,
+            isError: semanticResult.isError,
+            stdout: captureOutput ? processedStdout : undefined,
+            stderr: captureOutput ? stderr : undefined,
+            classification: {
+                category: classification.category,
+                isReadOnly: classification.isReadOnly,
+                isSilent: classification.isSilent
+            },
+            warnings: warningMessages.length > 0 ? warningMessages : undefined,
+            executionTime,
+            executedAt: Date.now(),
+            outputTruncated: outputTruncated || undefined,
+            persistedOutputId,
+            totalOutputBytes: totalOutputBytes || undefined,
+            totalOutputLines: totalOutputLines || undefined
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to execute command: ${error}`);
+        throw new Error(`Failed to execute command: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=ShellExecuteHandler.js.map

package/dist/protocols/mcp/tools/shell/ShellExecuteHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellExecuteHandler.js","sourceRoot":"","sources":["../../../../../src/protocols/mcp/tools/shell/ShellExecuteHandler.ts"],"names":[],"mappings":"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"}

package/dist/protocols/mcp/tools/shell/ShellSandbox.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Configuration for the shell sandbox.
+ * Controls Docker container behavior for sandboxed shell execution.
+ */
+export interface ShellSandboxConfig {
+    /** Whether sandbox mode is enabled. Default: false (opt-in) */
+    enabled: boolean;
+    /** Whether the sandboxed container has network access. Default: false */
+    networkAccess: boolean;
+    /** Paths to mount as read-write inside the container */
+    writablePaths: string[];
+    /** Custom mount configurations */
+    mountPaths: Array<{
+        host: string;
+        container: string;
+        readOnly: boolean;
+    }>;
+    /** Memory limit in MB for the container. Default: 256 */
+    memoryLimit: number;
+    /** CPU limit (fractional cores). Default: 1.0 */
+    cpuLimit: number;
+}
+/**
+ * Result from sandboxed shell command execution.
+ */
+export interface SandboxedShellResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    executionTime: number;
+    sandboxed: true;
+}
+/**
+ * Default shell sandbox configuration.
+ * Sandbox is opt-in (enabled: false) to maintain backward compatibility.
+ * All security constraints are maximally restrictive by default.
+ */
+export declare const DEFAULT_SHELL_SANDBOX_CONFIG: ShellSandboxConfig;
+/**
+ * Check if the shell sandbox is available (Docker is accessible and image exists).
+ *
+ * Attempts to initialize the ContainerExecutionManager if it has not already
+ * been initialized, then verifies that Docker is reachable.
+ *
+ * @returns true if Docker is available and the shell-executor image can be used
+ */
+export declare function isSandboxAvailable(): Promise<boolean>;
+/**
+ * Execute a shell command inside a Docker sandbox container.
+ * Uses an Alpine-based container with common CLI tools.
+ *
+ * The container:
+ * - Has no network access by default
+ * - Runs as non-root user (1000:1000)
+ * - Has a read-only root filesystem
+ * - Has /tmp mounted as writable tmpfs
+ * - Drops all Linux capabilities
+ * - Has resource limits (memory, CPU)
+ *
+ * @param command - The shell command to execute
+ * @param config - Partial sandbox configuration (merged with defaults)
+ * @param options - Execution options (timeout, working directory, environment)
+ * @returns The execution result including stdout, stderr, exit code, and timing
+ * @throws Error if Docker is not available or the shell-executor image is missing
+ */
+export declare function executeInSandbox(command: string, config: Partial<ShellSandboxConfig>, options?: {
+    timeout?: number;
+    workingDirectory?: string;
+    environment?: Record<string, string>;
+}): Promise<SandboxedShellResult>;
+//# sourceMappingURL=ShellSandbox.d.ts.map

package/dist/protocols/mcp/tools/shell/ShellSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellSandbox.d.ts","sourceRoot":"","sources":["../../../../../src/protocols/mcp/tools/shell/ShellSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiCH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kCAAkC;IAClC,UAAU,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACrB,CAAC,CAAC;IACH,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAO1C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CAc3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,EACnC,OAAO,GAAE;IACL,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,GACP,OAAO,CAAC,oBAAoB,CAAC,CA0K/B"}