defense-mcp-server 0.6.0

package/build/core/spawn-safe.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Low-level safe process spawning for defense-mcp-server.
+ *
+ * This module provides the foundational child process creation layer.
+ * It has NO dependencies on executor.ts, sudo-session.ts, or any module
+ * that could create circular imports.
+ *
+ * Dependencies: node:child_process, ./command-allowlist.js
+ *
+ * All child process creation outside of executor.ts should go through
+ * this module to ensure:
+ * 1. Command allowlist enforcement
+ * 2. shell: false always
+ * 3. Audit logging to stderr
+ */
+import { type SpawnOptions, type ExecFileSyncOptions, type ChildProcess } from "node:child_process";
+export interface SpawnSafeOptions extends SpawnOptions {
+}
+export interface ExecFileSafeOptions extends ExecFileSyncOptions {
+}
+/**
+ * Redact sensitive arguments from a command's argument array for safe logging.
+ *
+ * Rules:
+ * 1. If the command is "sudo", redact any argument immediately after `-S` (stdin password flag)
+ * 2. If any argument matches sensitive flag patterns (--password, --token, --key, --secret),
+ *    the NEXT argument is replaced with `[REDACTED]`
+ * 3. If a sensitive flag uses `=` syntax (e.g. `--password=foo`), the value portion is redacted
+ *
+ * @param command - The command being executed
+ * @param args - The original arguments array
+ * @returns A new array safe for logging (original is not mutated)
+ */
+export declare function redactArgs(command: string, args: readonly string[]): string[];
+/**
+ * Spawn a child process safely with allowlist enforcement and shell: false.
+ * Returns a ChildProcess (async — listen on events for output).
+ *
+ * @param command - Bare binary name (e.g. "sudo") or absolute path
+ * @param args - Arguments to pass to the command
+ * @param options - SpawnOptions (shell is always forced to false)
+ * @throws {Error} If the command is not in the allowlist
+ */
+export declare function spawnSafe(command: string, args: string[], options?: SpawnSafeOptions): ChildProcess;
+/**
+ * Execute a file synchronously with allowlist enforcement and shell: false.
+ *
+ * @param command - Bare binary name (e.g. "iptables") or absolute path
+ * @param args - Arguments to pass to the command
+ * @param options - ExecFileSyncOptions (shell is always forced to false)
+ * @returns stdout as Buffer (no encoding) or string (with encoding option)
+ * @throws {Error} If the command is not in the allowlist or the process exits non-zero
+ */
+export declare function execFileSafe(command: string, args: string[], options?: ExecFileSafeOptions): Buffer | string;
+//# sourceMappingURL=spawn-safe.d.ts.map

package/build/core/spawn-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-safe.d.ts","sourceRoot":"","sources":["../../src/core/spawn-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAK5B,MAAM,WAAW,gBAAiB,SAAQ,YAAY;CAAG;AAEzD,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;CAAG;AAUnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAgC7E;AAID;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,YAAY,CAUd;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,GAAG,MAAM,CAiCjB"}

package/build/core/spawn-safe.js

@@ -0,0 +1,146 @@
+/**
+ * Low-level safe process spawning for defense-mcp-server.
+ *
+ * This module provides the foundational child process creation layer.
+ * It has NO dependencies on executor.ts, sudo-session.ts, or any module
+ * that could create circular imports.
+ *
+ * Dependencies: node:child_process, ./command-allowlist.js
+ *
+ * All child process creation outside of executor.ts should go through
+ * this module to ensure:
+ * 1. Command allowlist enforcement
+ * 2. shell: false always
+ * 3. Audit logging to stderr
+ */
+import { spawn as nodeSpawn, execFileSync as nodeExecFileSync, } from "node:child_process";
+import { resolveCommand } from "./command-allowlist.js";
+// ── Argument Redaction ───────────────────────────────────────────────────────
+/**
+ * SECURITY (CORE-018): Patterns whose NEXT argument should be redacted in logs.
+ * Matches flags like --password, --token, --key, --secret (with = or space-separated values).
+ */
+const SENSITIVE_FLAG_RE = /^--?(password|token|key|secret|passphrase|credential|auth)$/i;
+/**
+ * Redact sensitive arguments from a command's argument array for safe logging.
+ *
+ * Rules:
+ * 1. If the command is "sudo", redact any argument immediately after `-S` (stdin password flag)
+ * 2. If any argument matches sensitive flag patterns (--password, --token, --key, --secret),
+ *    the NEXT argument is replaced with `[REDACTED]`
+ * 3. If a sensitive flag uses `=` syntax (e.g. `--password=foo`), the value portion is redacted
+ *
+ * @param command - The command being executed
+ * @param args - The original arguments array
+ * @returns A new array safe for logging (original is not mutated)
+ */
+export function redactArgs(command, args) {
+    const redacted = [...args];
+    const isSudo = command === "sudo" || command.endsWith("/sudo");
+    for (let i = 0; i < redacted.length; i++) {
+        const arg = redacted[i];
+        // Rule 1: For sudo, redact the argument after -S (stdin password)
+        if (isSudo && arg === "-S" && i + 1 < redacted.length) {
+            // Don't redact known sudo flags that follow -S
+            const next = redacted[i + 1];
+            if (next && !next.startsWith("-")) {
+                redacted[i + 1] = "[REDACTED]";
+            }
+        }
+        // Rule 2: Redact argument after sensitive flags
+        if (SENSITIVE_FLAG_RE.test(arg) && i + 1 < redacted.length) {
+            redacted[i + 1] = "[REDACTED]";
+        }
+        // Rule 3: Redact value in --flag=value style for sensitive flags
+        const eqIdx = arg.indexOf("=");
+        if (eqIdx > 0) {
+            const flagPart = arg.substring(0, eqIdx);
+            if (SENSITIVE_FLAG_RE.test(flagPart)) {
+                redacted[i] = `${flagPart}=[REDACTED]`;
+            }
+        }
+    }
+    return redacted;
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Spawn a child process safely with allowlist enforcement and shell: false.
+ * Returns a ChildProcess (async — listen on events for output).
+ *
+ * @param command - Bare binary name (e.g. "sudo") or absolute path
+ * @param args - Arguments to pass to the command
+ * @param options - SpawnOptions (shell is always forced to false)
+ * @throws {Error} If the command is not in the allowlist
+ */
+export function spawnSafe(command, args, options) {
+    const resolvedCommand = resolveCommandSafe(command);
+    const safeOptions = {
+        ...options,
+        shell: false, // ALWAYS false — non-negotiable
+    };
+    console.error(`[spawn-safe] ${resolvedCommand} ${redactArgs(command, args).join(" ")}`);
+    return nodeSpawn(resolvedCommand, args, safeOptions);
+}
+/**
+ * Execute a file synchronously with allowlist enforcement and shell: false.
+ *
+ * @param command - Bare binary name (e.g. "iptables") or absolute path
+ * @param args - Arguments to pass to the command
+ * @param options - ExecFileSyncOptions (shell is always forced to false)
+ * @returns stdout as Buffer (no encoding) or string (with encoding option)
+ * @throws {Error} If the command is not in the allowlist or the process exits non-zero
+ */
+export function execFileSafe(command, args, options) {
+    const resolvedCommand = resolveCommandSafe(command);
+    // SECURITY (CORE-011): Capture reference to any stdin input buffer for cleanup
+    const inputBuffer = options?.input && Buffer.isBuffer(options.input) ? options.input : null;
+    const safeOptions = {
+        ...options,
+        shell: false, // ALWAYS false
+        timeout: options?.timeout ?? 120_000, // 120 second default for sync operations
+    };
+    console.error(`[spawn-safe] ${resolvedCommand} ${redactArgs(command, args).join(" ")}`);
+    try {
+        return nodeExecFileSync(resolvedCommand, args, safeOptions);
+    }
+    catch (err) {
+        // Provide user-friendly timeout message
+        if (err instanceof Error && "killed" in err && err.code === "ETIMEDOUT") {
+            const timeoutSec = Math.round(safeOptions.timeout / 1000);
+            throw new Error(`Command timed out after ${timeoutSec} seconds. ` +
+                `The target may be unreachable or the operation is taking too long. ` +
+                `Consider increasing KALI_DEFENSE_COMMAND_TIMEOUT (current: ${timeoutSec}s).`);
+        }
+        throw err;
+    }
+    finally {
+        // SECURITY (CORE-011): Zero any stdin buffer that may contain sensitive data
+        // (e.g., passwords piped to commands). Guaranteed cleanup on all paths.
+        if (inputBuffer) {
+            inputBuffer.fill(0);
+        }
+    }
+}
+// ── Internal helper ──────────────────────────────────────────────────────────
+/**
+ * Resolve a command through the allowlist, or throw.
+ *
+ * Every command MUST pass through the allowlist — there is no bypass mechanism.
+ *
+ * If `resolveCommand()` throws (e.g. allowlist not yet initialized at startup),
+ * falls back to checking `isAllowlisted()` which works even before
+ * `initializeAllowlist()` has been called.
+ */
+function resolveCommandSafe(command) {
+    try {
+        return resolveCommand(command);
+    }
+    catch {
+        // SECURITY (CORE-014): Do NOT fall back to bare command name when resolution fails.
+        // Using bare names allows PATH manipulation attacks. If resolveCommand() failed,
+        // the binary either isn't on the system or the allowlist isn't initialized.
+        // In either case, refuse to proceed.
+        console.error(`[spawn-safe] Command resolution failed for "${command}" — refusing bare-name fallback`);
+        throw new Error(`[spawn-safe] Command not in allowlist or not found on system: "${command}"`);
+    }
+}

package/build/core/sudo-guard.d.ts

@@ -0,0 +1,145 @@
+/**
+ * SudoGuard — Central module for detecting permission failures and generating
+ * structured elevation prompts that instruct the AI client to ask the user
+ * for their sudo password.
+ *
+ * This module ensures that no MCP tool ever silently fails due to missing
+ * sudo privileges. Instead, failures are intercepted and converted into
+ * clear, actionable elevation prompts.
+ *
+ * ## Three Interception Layers
+ *
+ * 1. **Pre-flight** (tool-wrapper.ts): Tools with `sudo: "always"` are blocked
+ *    before execution if no session is active. SudoGuard generates the prompt.
+ *
+ * 2. **Executor** (executor.ts): After command execution, the `permissionDenied`
+ *    flag on {@link CommandResult} is set when stderr/exit code match known
+ *    permission-denied patterns.
+ *
+ * 3. **Post-execution** (tool-wrapper.ts): If a tool handler's response
+ *    indicates a permission error (detected via output text analysis),
+ *    SudoGuard wraps it with an elevation prompt.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { SudoGuard } from './sudo-guard.js';
+ *
+ * // Check if command output indicates permission denied
+ * if (SudoGuard.isPermissionError(result.stderr, result.exitCode)) {
+ *   return SudoGuard.createElevationPrompt('firewall_iptables_add');
+ * }
+ * ```
+ *
+ * @module sudo-guard
+ */
+/**
+ * Structured MCP response content for an elevation prompt.
+ * Returned when a tool cannot proceed without sudo privileges.
+ */
+export interface ElevationPromptResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+    _meta: {
+        /** Machine-readable tag for client-side detection */
+        elevationRequired: true;
+        /**
+         * Machine-readable flag that instructs the AI client to STOP its
+         * current workflow and ask the user for credentials before proceeding.
+         * The AI MUST NOT silently skip the tool or continue without elevation.
+         */
+        haltWorkflow: true;
+        /** The tool that failed */
+        failedTool: string;
+        /** Why elevation is needed */
+        reason: string;
+        /** The tool to call for elevation */
+        elevationTool: "sudo_elevate";
+    };
+}
+/**
+ * Static utility class for permission error detection and elevation prompt
+ * generation. All methods are stateless and can be called directly.
+ */
+export declare class SudoGuard {
+    /**
+     * Check whether command output (stderr and/or stdout) indicates a
+     * permission/privilege failure.
+     *
+     * Uses a combination of pattern matching against known error messages
+     * and exit code analysis. Pattern matching alone is authoritative —
+     * exit codes are used as supporting evidence only.
+     *
+     * @param output  Combined stderr + stdout text to analyze
+     * @param exitCode  The process exit code (optional, for confidence)
+     * @returns `true` if the output indicates a permission error
+     */
+    static isPermissionError(output: string, exitCode?: number): boolean;
+    /**
+     * Create a structured MCP elevation prompt response.
+     *
+     * The response includes:
+     * - A clear human-readable message explaining what happened
+     * - Instructions to call `sudo_elevate` with the user's password
+     * - Machine-readable `_meta` for client-side automation
+     *
+     * @param toolName  The tool that requires elevation
+     * @param reason    Optional specific reason (from manifest or error output)
+     * @param originalError  The original error message to include for context
+     */
+    static createElevationPrompt(toolName: string, reason?: string, originalError?: string): ElevationPromptResponse;
+    /**
+     * Check if a tool handler's MCP response content indicates a permission
+     * error that occurred at runtime (after pre-flight passed).
+     *
+     * This catches `conditional` sudo tools and tools where the pre-flight
+     * check passed but the actual command still failed due to permissions.
+     *
+     * Examines the `content` array of the tool's response for text content
+     * matching permission error patterns.
+     */
+    static isResponsePermissionError(response: Record<string, unknown> | undefined): boolean;
+    /**
+     * Extract the first text content string from an MCP response.
+     * Used to pass original error context to the elevation prompt.
+     */
+    static extractResponseText(response: Record<string, unknown> | undefined): string | undefined;
+    /**
+     * Check if the current process has an active sudo session that can
+     * be used for privileged operations.
+     */
+    static hasActiveSession(): boolean;
+    /**
+     * SECURITY (CORE-006): Validate the SUDO_ASKPASS environment variable.
+     *
+     * Before trusting the SUDO_ASKPASS path, verify:
+     * 1. The file exists and is a regular file (not a symlink)
+     * 2. Ownership is root or the current user
+     * 3. Permissions are restrictive (0o700 or 0o500 — no world/group access)
+     *
+     * @returns `{ valid: true }` if safe, or `{ valid: false, reason: string }` if not
+     */
+    static validateAskpass(): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * SECURITY (CORE-016): Validate an askpass helper path.
+     *
+     * Before trusting any askpass candidate, verify:
+     * 1. The file exists and is a regular file (not a symlink)
+     * 2. Ownership is root or the current user
+     * 3. Permissions are restrictive (no group/world access)
+     *
+     * @param askpassPath Absolute path to the askpass candidate
+     * @returns `{ valid: true }` if safe, or `{ valid: false, reason: string }` if not
+     */
+    static validateAskpassPath(askpassPath: string): {
+        valid: boolean;
+        reason?: string;
+    };
+}
+//# sourceMappingURL=sudo-guard.d.ts.map

package/build/core/sudo-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-guard.d.ts","sourceRoot":"","sources":["../../src/core/sudo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAqFH;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE;QACL,qDAAqD;QACrD,iBAAiB,EAAE,IAAI,CAAC;QACxB;;;;WAIG;QACH,YAAY,EAAE,IAAI,CAAC;QACnB,2BAA2B;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,8BAA8B;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,qCAAqC;QACrC,aAAa,EAAE,cAAc,CAAC;KAC/B,CAAC;CACH;AAID;;;GAGG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAqBpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,qBAAqB,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,uBAAuB;IAqE1B;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,OAAO;IA4BV;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS;IAoBrB;;;OAGG;IACH,MAAM,CAAC,gBAAgB,IAAI,OAAO;IAIlC;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAU7D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAiDrF"}