defense-mcp-server 0.6.0

package/build/core/sudo-guard.js

@@ -0,0 +1,349 @@
+/**
+ * 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
+ */
+import { SudoSession } from "./sudo-session.js";
+import { lstatSync } from "node:fs";
+// ── Permission Error Detection ───────────────────────────────────────────────
+/**
+ * Patterns in stderr/stdout that indicate a permission/privilege failure.
+ * These are matched case-insensitively against combined output.
+ *
+ * Covers sudo, polkit, systemd, Docker, iptables, and general POSIX errors.
+ */
+const PERMISSION_ERROR_PATTERNS = [
+    // sudo-specific
+    /sudo[:\s].*password/i,
+    /sudo[:\s].*required/i,
+    /a password is required/i,
+    /sorry,?\s+try again/i,
+    /\bsudo\b.*\bnot allowed\b/i,
+    /no password.*and.*not.*(sudoers|allowed)/i,
+    // General POSIX permission errors
+    /permission denied/i,
+    /operation not permitted/i,
+    /EACCES/,
+    /EPERM/,
+    /access denied/i,
+    // Specific binary errors
+    /must be run as root/i,
+    /must be root/i,
+    /requires? root/i,
+    /requires? superuser/i,
+    /run.*as.*root/i,
+    /need to be root/i,
+    /insufficient privileges?/i,
+    /not enough privileges?/i,
+    /only root can/i,
+    /you must be root/i,
+    // iptables / nftables
+    /can't initialize iptables/i,
+    /iptables.*Permission denied/i,
+    /nft.*Operation not permitted/i,
+    // systemd / service management
+    /polkit.*authorization/i,
+    /interactive authentication required/i,
+    /access denied by.*policy/i,
+    /not privileged/i,
+    // Docker
+    /docker.*permission denied/i,
+    /connect: permission denied/i,
+    /dial.*permission denied/i,
+    // Package management
+    /are you root\?/i,
+    /unable to lock/i,
+    /could not get lock/i,
+    // auditd
+    /audit.*permission/i,
+    // File system
+    /cannot open.*permission denied/i,
+    /cannot write.*permission denied/i,
+    /read-only file system/i,
+];
+/**
+ * Exit codes that commonly indicate permission failures.
+ * Note: exit code alone is not sufficient — must be combined with pattern
+ * matching for reliable detection.
+ */
+const PERMISSION_EXIT_CODES = new Set([
+    1, // General error (common for sudo failures)
+    126, // Command invoked cannot execute (permission issue)
+    4, // iptables: resource problem (often permission)
+    77, // BSD/systemd: noperm
+]);
+// ── SudoGuard ────────────────────────────────────────────────────────────────
+/**
+ * Static utility class for permission error detection and elevation prompt
+ * generation. All methods are stateless and can be called directly.
+ */
+export 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, exitCode) {
+        if (!output || output.length === 0) {
+            return false;
+        }
+        // Check patterns against combined output
+        for (const pattern of PERMISSION_ERROR_PATTERNS) {
+            if (pattern.test(output)) {
+                return true;
+            }
+        }
+        // Exit code alone is not sufficient (too many false positives),
+        // but exit code 126 is very specific to permission issues
+        if (exitCode === 126) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 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, reason, originalError) {
+        const session = SudoSession.getInstance();
+        const status = session.getStatus();
+        const reasonText = reason ?? "This tool requires elevated (root) privileges to function.";
+        // Build the prompt message — designed to be assertive enough that
+        // AI clients will HALT their workflow and ask the user for credentials.
+        const lines = [];
+        lines.push("🛑 WORKFLOW HALTED — ELEVATED PRIVILEGES REQUIRED");
+        lines.push("═".repeat(50));
+        lines.push("");
+        lines.push(`Tool: ${toolName}`);
+        lines.push(`Reason: ${reasonText}`);
+        lines.push("");
+        if (status.elevated && status.remainingSeconds !== null && status.remainingSeconds <= 0) {
+            // Session expired
+            lines.push("⚠️  Your sudo session has expired.");
+            lines.push("");
+        }
+        lines.push("⚠️  DO NOT SKIP THIS TOOL OR CONTINUE WITHOUT ELEVATION.");
+        lines.push("⚠️  You MUST ask the user for their sudo password NOW.");
+        lines.push("");
+        lines.push("ACTION REQUIRED — BEFORE PROCEEDING:");
+        lines.push("─".repeat(50));
+        lines.push("");
+        lines.push("1. ASK the user for their sudo password");
+        lines.push("2. CALL sudo_elevate with the password");
+        lines.push("3. RETRY this tool (and any other tools that failed)");
+        lines.push("");
+        lines.push("  Tool: sudo_elevate");
+        lines.push("  Parameter: password = <user's sudo password>");
+        lines.push("");
+        lines.push("Once elevated, ALL privileged tools will work automatically");
+        lines.push("for the session duration (default: 15 minutes).");
+        lines.push("");
+        lines.push("Security guarantees for the user's password:");
+        lines.push("  • Stored securely in a zeroable memory buffer");
+        lines.push("  • Never logged or exposed in any output");
+        lines.push("  • Auto-expires after the configured timeout");
+        lines.push("  • Can be dropped at any time with sudo_drop");
+        if (originalError) {
+            lines.push("");
+            lines.push("─".repeat(50));
+            lines.push("Original error:");
+            lines.push(originalError.substring(0, 500));
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: lines.join("\n"),
+                },
+            ],
+            isError: true,
+            _meta: {
+                elevationRequired: true,
+                haltWorkflow: true,
+                failedTool: toolName,
+                reason: reasonText,
+                elevationTool: "sudo_elevate",
+            },
+        };
+    }
+    /**
+     * 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) {
+        if (!response)
+            return false;
+        // Only check error responses
+        if (!response.isError)
+            return false;
+        const content = response.content;
+        if (!Array.isArray(content))
+            return false;
+        for (const item of content) {
+            if (typeof item === "object" &&
+                item !== null &&
+                "type" in item &&
+                item.type === "text" &&
+                "text" in item &&
+                typeof item.text === "string") {
+                const text = item.text;
+                if (SudoGuard.isPermissionError(text)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Extract the first text content string from an MCP response.
+     * Used to pass original error context to the elevation prompt.
+     */
+    static extractResponseText(response) {
+        if (!response)
+            return undefined;
+        const content = response.content;
+        if (!Array.isArray(content))
+            return undefined;
+        for (const item of content) {
+            if (typeof item === "object" &&
+                item !== null &&
+                "type" in item &&
+                item.type === "text" &&
+                "text" in item) {
+                return item.text;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if the current process has an active sudo session that can
+     * be used for privileged operations.
+     */
+    static hasActiveSession() {
+        return SudoSession.getInstance().isElevated();
+    }
+    /**
+     * 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() {
+        const askpassPath = process.env.SUDO_ASKPASS;
+        if (!askpassPath) {
+            return { valid: true }; // Not set — nothing to validate
+        }
+        return SudoGuard.validateAskpassPath(askpassPath);
+    }
+    /**
+     * 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) {
+        try {
+            // 1. Check with lstat (does NOT follow symlinks)
+            const lstats = lstatSync(askpassPath);
+            if (lstats.isSymbolicLink()) {
+                return {
+                    valid: false,
+                    reason: `Askpass path '${askpassPath}' is a symlink. Refusing to trust it.`,
+                };
+            }
+            if (!lstats.isFile()) {
+                return {
+                    valid: false,
+                    reason: `Askpass path '${askpassPath}' is not a regular file.`,
+                };
+            }
+            // 2. Verify ownership: must be root (uid 0) or the current user
+            const currentUid = process.getuid?.() ?? -1;
+            if (lstats.uid !== 0 && lstats.uid !== currentUid) {
+                return {
+                    valid: false,
+                    reason: `Askpass '${askpassPath}' is owned by uid ${lstats.uid}, expected root (0) or current user (${currentUid}).`,
+                };
+            }
+            // 3. Verify permissions: no group or world access (must be 0o700 or 0o500)
+            // Extract the permission bits (lower 9 bits of mode)
+            const perms = lstats.mode & 0o777;
+            const groupWorldBits = perms & 0o077;
+            if (groupWorldBits !== 0) {
+                return {
+                    valid: false,
+                    reason: `Askpass '${askpassPath}' has overly permissive mode 0o${perms.toString(8)}. ` +
+                        `Expected no group/world access (e.g., 0700 or 0500).`,
+                };
+            }
+            return { valid: true };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                valid: false,
+                reason: `Failed to verify askpass '${askpassPath}': ${msg}`,
+            };
+        }
+    }
+}

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

@@ -0,0 +1,100 @@
+/**
+ * SudoSession — singleton that manages elevated privilege credentials.
+ *
+ * The MCP server runs non-interactively via stdio transport, so `sudo`
+ * cannot prompt for a password through a TTY. This module stores the
+ * user's password in a zeroable Buffer and transparently provides it
+ * to `sudo -S` via stdin piping in the executor.
+ *
+ * Security features:
+ *   - Password stored in a Buffer and remains as Buffer through the entire
+ *     stdin pipeline (never converted to a V8 string, can be zeroed)
+ *   - Auto-expires after a configurable timeout (default 15 minutes)
+ *   - Explicit `drop()` zeroes the buffer immediately
+ *   - Process exit handler zeroes the buffer on shutdown
+ *   - Validates credentials before storing (test with `sudo -S -v`)
+ *   - Never logs or exposes the password in any output
+ *
+ * Child process spawning goes through spawn-safe.ts which enforces the
+ * command allowlist and shell: false without creating circular dependencies.
+ */
+export interface SudoSessionStatus {
+    elevated: boolean;
+    username: string | null;
+    expiresAt: string | null;
+    remainingSeconds: number | null;
+}
+export declare class SudoSession {
+    /** Password stored in a Buffer so we can zero it (not interned by V8). */
+    private passwordBuf;
+    /** Username that authenticated. */
+    private username;
+    /**
+     * SECURITY (CICD-028): OS-level user ID that created this session.
+     * Used for session isolation tracking. Defaults to process.getuid().
+     *
+     * NOTE: Concurrent multi-user sessions are NOT currently supported.
+     * This server should not be used in multi-tenant environments where
+     * multiple users share the same process. Each user should run their
+     * own server instance.
+     */
+    private sessionUserId;
+    /** Timestamp (epoch ms) when the session expires. */
+    private expiresAt;
+    /** Handle for the auto-expiry timer. */
+    private expiryTimer;
+    /** Default session timeout in milliseconds (15 min). */
+    private defaultTimeoutMs;
+    private constructor();
+    /** Get the singleton instance. */
+    static getInstance(): SudoSession;
+    /**
+     * Reset the singleton instance (for testing only).
+     * @internal
+     */
+    static resetInstance(): void;
+    /**
+     * Set the session timeout in milliseconds.
+     * Only affects future `elevate()` calls.
+     */
+    setDefaultTimeout(ms: number): void;
+    /**
+     * Attempt to elevate privileges by validating the given password.
+     *
+     * Runs `sudo -S -k -v` with the password piped on stdin.
+     * `-k` invalidates cached credentials so we always test our password.
+     * `-v` validates without running a command.
+     * `-S` reads password from stdin.
+     * `-p ""` suppresses the password prompt text.
+     *
+     * @returns result indicating success or failure with error message.
+     */
+    elevate(password: string | Buffer, timeoutMs?: number): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Returns a **copy** of the password Buffer for piping to sudo -S,
+     * or null if not elevated.
+     *
+     * The caller MUST zero the returned Buffer with `.fill(0)` after use.
+     * A copy is returned so the original can be zeroed independently via `drop()`.
+     */
+    getPassword(): Buffer | null;
+    /** Check whether we have an active elevated session. */
+    isElevated(): boolean;
+    /** Get current session status (safe to expose via MCP). */
+    getStatus(): SudoSessionStatus;
+    /**
+     * Drop elevated privileges immediately.
+     * Zeroes the password buffer and clears all session state.
+     */
+    drop(): void;
+    /**
+     * Extend the session timeout by the given milliseconds (or the default).
+     */
+    extend(extraMs?: number): boolean;
+    private storePassword;
+    private isExpired;
+}
+//# sourceMappingURL=sudo-session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-session.d.ts","sourceRoot":"","sources":["../../src/core/sudo-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAsED,qBAAa,WAAW;IACtB,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAuB;IAE1C,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAuB;IAEvC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa,CAAuB;IAE5C,qDAAqD;IACrD,OAAO,CAAC,SAAS,CAAuB;IAExC,wCAAwC;IACxC,OAAO,CAAC,WAAW,CAA8C;IAEjE,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAkB;IAE1C,OAAO;IASP,kCAAkC;IAClC,MAAM,CAAC,WAAW,IAAI,WAAW;IAOjC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMnC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAuE3G;;;;;;OAMG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAc5B,wDAAwD;IACxD,UAAU,IAAI,OAAO;IAUrB,2DAA2D;IAC3D,SAAS,IAAI,iBAAiB;IAsB9B;;;OAGG;IACH,IAAI,IAAI,IAAI;IAwBZ;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAyBjC,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,SAAS;CAIlB"}