defense-mcp-server 0.6.0

package/build/core/sudo-session.js

@@ -0,0 +1,319 @@
+/**
+ * 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.
+ */
+import { spawnSafe } from "./spawn-safe.js";
+function runSimple(command, args, stdin, timeoutMs = 10000) {
+    return new Promise((resolve) => {
+        const controller = new AbortController();
+        let child;
+        try {
+            child = spawnSafe(command, args, {
+                signal: controller.signal,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            resolve({ stdout: "", stderr: `spawn failed for: ${command}`, exitCode: 1 });
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        child.stdout?.on("data", (c) => stdoutChunks.push(c));
+        child.stderr?.on("data", (c) => stderrChunks.push(c));
+        if (stdin && child.stdin) {
+            // Write as Buffer to avoid creating immutable V8 strings from passwords
+            child.stdin.write(Buffer.isBuffer(stdin) ? stdin : Buffer.from(stdin, "utf-8"));
+            child.stdin.end();
+        }
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+                exitCode: code ?? 1,
+            });
+        });
+        child.on("error", () => {
+            clearTimeout(timer);
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+                exitCode: 1,
+            });
+        });
+    });
+}
+// ── SudoSession singleton ────────────────────────────────────────────────────
+// SECURITY (CORE-021): Module-scoped singleton variable prevents external
+// mutation via (SudoSession as any).instance — inaccessible outside module.
+let _sudoSessionInstance = null;
+export class SudoSession {
+    /** Password stored in a Buffer so we can zero it (not interned by V8). */
+    passwordBuf = null;
+    /** Username that authenticated. */
+    username = null;
+    /**
+     * 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.
+     */
+    sessionUserId = null;
+    /** Timestamp (epoch ms) when the session expires. */
+    expiresAt = null;
+    /** Handle for the auto-expiry timer. */
+    expiryTimer = null;
+    /** Default session timeout in milliseconds (15 min). */
+    defaultTimeoutMs = 15 * 60 * 1000;
+    constructor() {
+        // Zero the password on process exit/crash
+        const cleanup = () => this.drop();
+        process.once("exit", cleanup);
+        process.once("SIGINT", cleanup);
+        process.once("SIGTERM", cleanup);
+        process.once("uncaughtException", cleanup);
+    }
+    /** Get the singleton instance. */
+    static getInstance() {
+        if (!_sudoSessionInstance) {
+            _sudoSessionInstance = new SudoSession();
+        }
+        return _sudoSessionInstance;
+    }
+    /**
+     * Reset the singleton instance (for testing only).
+     * @internal
+     */
+    static resetInstance() {
+        _sudoSessionInstance = null;
+    }
+    /**
+     * Set the session timeout in milliseconds.
+     * Only affects future `elevate()` calls.
+     */
+    setDefaultTimeout(ms) {
+        if (ms > 0) {
+            this.defaultTimeoutMs = ms;
+        }
+    }
+    /**
+     * 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.
+     */
+    async elevate(password, timeoutMs) {
+        // SECURITY (CORE-005): JavaScript strings are immutable and interned by V8,
+        // making them impossible to reliably zero from memory. Convert password to
+        // Buffer immediately to minimize credential lifetime as a V8 string.
+        // Buffer contents can be explicitly zeroed with .fill(0) after use.
+        const passwordBuf = Buffer.isBuffer(password)
+            ? Buffer.from(password) // defensive copy so caller's buffer isn't affected
+            : Buffer.from(password, "utf-8");
+        // Determine who we are first
+        const whoami = await runSimple("whoami", []);
+        const currentUser = whoami.stdout.trim() || "unknown";
+        // If already running as root, no password needed
+        if (currentUser === "root") {
+            this.username = "root";
+            this.expiresAt = null;
+            // Store an empty buffer — the executor will skip stdin piping for root
+            this.passwordBuf = Buffer.alloc(0);
+            // Zero the local buffer — not needed for root
+            passwordBuf.fill(0);
+            return { success: true };
+        }
+        // Validate the password with sudo -S -k -v
+        const validationBuf = Buffer.concat([passwordBuf, Buffer.from("\n")]);
+        const result = await runSimple("sudo", ["-S", "-k", "-v", "-p", ""], validationBuf, 10000);
+        // Zero the validation buffer immediately after use
+        validationBuf.fill(0);
+        if (result.exitCode === 0) {
+            // Password is valid — store it (storePassword makes its own defensive copy)
+            this.storePassword(passwordBuf, timeoutMs);
+            // Zero our local copy since storePassword made its own
+            passwordBuf.fill(0);
+            this.username = currentUser;
+            // SECURITY (CICD-028): Track the OS-level user ID for session isolation
+            this.sessionUserId = process.getuid?.() ?? null;
+            console.error(`[sudo-session] Elevated privileges for user '${currentUser}' (uid=${this.sessionUserId ?? "unknown"})`);
+            return { success: true };
+        }
+        // Zero password buffer on all failure paths
+        passwordBuf.fill(0);
+        // Check for common failure reasons
+        const stderr = result.stderr.toLowerCase();
+        if (stderr.includes("not in the sudoers file")) {
+            return {
+                success: false,
+                error: `User '${currentUser}' is not in the sudoers file. Cannot elevate privileges.`,
+            };
+        }
+        if (stderr.includes("incorrect password") || stderr.includes("sorry")) {
+            return {
+                success: false,
+                error: "Incorrect password. Please try again.",
+            };
+        }
+        return {
+            success: false,
+            error: `sudo validation failed (exit ${result.exitCode}): ${result.stderr.substring(0, 200)}`,
+        };
+    }
+    /**
+     * 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() {
+        if (!this.passwordBuf || this.passwordBuf.length === 0) {
+            return null;
+        }
+        if (this.isExpired()) {
+            this.drop();
+            return null;
+        }
+        // Return a COPY so original can be zeroed independently
+        const copy = Buffer.alloc(this.passwordBuf.length);
+        this.passwordBuf.copy(copy);
+        return copy;
+    }
+    /** Check whether we have an active elevated session. */
+    isElevated() {
+        if (!this.passwordBuf)
+            return false;
+        if (this.username === "root")
+            return true; // root never expires
+        if (this.isExpired()) {
+            this.drop();
+            return false;
+        }
+        return true;
+    }
+    /** Get current session status (safe to expose via MCP). */
+    getStatus() {
+        if (!this.isElevated()) {
+            return {
+                elevated: false,
+                username: null,
+                expiresAt: null,
+                remainingSeconds: null,
+            };
+        }
+        const remaining = this.expiresAt
+            ? Math.max(0, Math.round((this.expiresAt - Date.now()) / 1000))
+            : null;
+        return {
+            elevated: true,
+            username: this.username,
+            expiresAt: this.expiresAt ? new Date(this.expiresAt).toISOString() : null,
+            remainingSeconds: remaining,
+        };
+    }
+    /**
+     * Drop elevated privileges immediately.
+     * Zeroes the password buffer and clears all session state.
+     */
+    drop() {
+        if (this.passwordBuf) {
+            // Zero the buffer contents
+            this.passwordBuf.fill(0);
+            this.passwordBuf = null;
+        }
+        this.username = null;
+        this.expiresAt = null;
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+            this.expiryTimer = null;
+        }
+        // Also invalidate the system sudo cache (fire and forget)
+        try {
+            runSimple("sudo", ["-k"], undefined, 3000).catch(() => { });
+        }
+        catch {
+            // Best effort
+        }
+        console.error("[sudo-session] Privileges dropped, password zeroed");
+    }
+    /**
+     * Extend the session timeout by the given milliseconds (or the default).
+     */
+    extend(extraMs) {
+        if (!this.isElevated())
+            return false;
+        if (this.username === "root")
+            return true; // root sessions don't expire
+        const ms = extraMs ?? this.defaultTimeoutMs;
+        this.expiresAt = Date.now() + ms;
+        // Reset the timer
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+        }
+        this.expiryTimer = setTimeout(() => this.drop(), ms);
+        // Prevent the timer from keeping the process alive
+        if (this.expiryTimer && typeof this.expiryTimer === "object" && "unref" in this.expiryTimer) {
+            this.expiryTimer.unref();
+        }
+        console.error(`[sudo-session] Session extended, expires at ${new Date(this.expiresAt).toISOString()}`);
+        return true;
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    storePassword(password, timeoutMs) {
+        // Zero any existing buffer
+        if (this.passwordBuf) {
+            this.passwordBuf.fill(0);
+        }
+        // Store in a new buffer (accept both string and Buffer to avoid V8 string interning)
+        this.passwordBuf = Buffer.isBuffer(password)
+            ? Buffer.from(password) // defensive copy
+            : Buffer.from(password, "utf-8");
+        // Set expiry
+        const ms = timeoutMs ?? this.defaultTimeoutMs;
+        this.expiresAt = Date.now() + ms;
+        // Auto-drop on expiry
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+        }
+        this.expiryTimer = setTimeout(() => {
+            console.error("[sudo-session] Session expired, dropping privileges");
+            this.drop();
+        }, ms);
+        // Don't let the timer keep the process alive
+        if (this.expiryTimer && typeof this.expiryTimer === "object" && "unref" in this.expiryTimer) {
+            this.expiryTimer.unref();
+        }
+    }
+    isExpired() {
+        if (this.expiresAt === null)
+            return false; // root sessions don't expire
+        return Date.now() >= this.expiresAt;
+    }
+}

package/build/core/tool-dependencies.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool-to-dependency mapping for Defense MCP Server.
+ *
+ * Maps each registered MCP tool name to the system binaries it requires.
+ * Used by the dependency validator to ensure all required tools are
+ * installed before execution — either at server startup or on-demand.
+ *
+ * After the v0.5.0 tool consolidation (157 → 78 tools), extended to 94
+ * tools across 32 modules in v0.6.0. Each entry represents a consolidated
+ * tool whose dependencies are the UNION of all the individual tools it
+ * absorbed.  Action-specific binaries are listed as `optionalBinaries`
+ * because the tool handles missing ones gracefully based on which `action`
+ * the caller selects.
+ */
+import { type ToolRequirement } from "./installer.js";
+/**
+ * Dependency specification for an MCP tool.
+ */
+export interface ToolDependency {
+    /** The MCP tool name (e.g. "ids_rootkit_scan") */
+    toolName: string;
+    /** System binaries required for this tool to function */
+    requiredBinaries: string[];
+    /** System binaries that are optional (enhance functionality) */
+    optionalBinaries?: string[];
+    /** Whether this tool is critical (server should warn loudly if deps missing) */
+    critical?: boolean;
+}
+/**
+ * Returns the ToolRequirement for a given binary name, if known.
+ */
+export declare function getToolRequirementForBinary(binary: string): ToolRequirement | undefined;
+/**
+ * Complete mapping of MCP tool names to their system binary dependencies.
+ *
+ * 78 consolidated tools across 21 modules.  Each entry specifies:
+ * - requiredBinaries: must be present for the tool to work at all
+ * - optionalBinaries: enhance functionality but aren't strictly needed
+ * - critical: if true, missing deps trigger a startup warning
+ */
+export declare const TOOL_DEPENDENCIES: ToolDependency[];
+/**
+ * Returns the dependency specification for a given MCP tool name.
+ */
+export declare function getDependenciesForTool(toolName: string): ToolDependency | undefined;
+/**
+ * Returns all unique required binaries across all tools.
+ */
+export declare function getAllRequiredBinaries(): string[];
+/**
+ * Returns all unique binaries (required + optional) across all tools.
+ */
+export declare function getAllBinaries(): {
+    required: string[];
+    optional: string[];
+};
+/**
+ * Returns all critical tool dependencies (tools that should always work).
+ */
+export declare function getCriticalDependencies(): ToolDependency[];
+//# sourceMappingURL=tool-dependencies.d.ts.map

package/build/core/tool-dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dependencies.d.ts","sourceRoot":"","sources":["../../src/core/tool-dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAIvE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAaD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,GACb,eAAe,GAAG,SAAS,CAE7B;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAAc,EAogB7C,CAAC;AAUF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,cAAc,GAAG,SAAS,CAE5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAQjD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAiB3E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,cAAc,EAAE,CAE1D"}