defense-mcp-server 0.6.0

package/build/core/encrypted-state.js

@@ -0,0 +1,209 @@
+/**
+ * encrypted-state.ts — Encrypted storage for sensitive state data.
+ *
+ * Provides AES-256-GCM encrypted at-rest storage for rollback data,
+ * policy files, sudo session tokens, and other sensitive state.
+ *
+ * Key derivation uses PBKDF2 from a configurable secret via the
+ * `KALI_DEFENSE_STATE_KEY` environment variable. If no key is
+ * configured, falls back to unencrypted mode with a warning.
+ *
+ * @module encrypted-state
+ */
+import { randomBytes, createCipheriv, createDecipheriv, pbkdf2Sync, } from "node:crypto";
+import { readFileSync, unlinkSync, existsSync, mkdirSync, chmodSync, } from "node:fs";
+import { join } from "node:path";
+import { logger } from "./logger.js";
+import { atomicWriteFileSync } from "./secure-fs.js";
+// ── Constants ────────────────────────────────────────────────────────────────
+/** AES-256-GCM algorithm identifier. */
+const ALGORITHM = "aes-256-gcm";
+/** Key length in bytes (256 bits). */
+const KEY_LENGTH = 32;
+/** IV length in bytes (96 bits recommended for GCM). */
+const IV_LENGTH = 12;
+/** Auth tag length in bytes. */
+const AUTH_TAG_LENGTH = 16;
+/** PBKDF2 iteration count. */
+const PBKDF2_ITERATIONS = 100_000;
+/** PBKDF2 digest algorithm. */
+const PBKDF2_DIGEST = "sha512";
+/** Salt length in bytes. */
+const SALT_LENGTH = 16;
+/** Default state directory. */
+const DEFAULT_STATE_DIR = "/tmp/kali-defense/state/";
+/** File permission: owner read/write only. */
+const SECURE_FILE_MODE = 0o600;
+/** Directory permission: owner read/write/execute only. */
+const SECURE_DIR_MODE = 0o700;
+/** Environment variable name for the encryption key. */
+const ENV_KEY_NAME = "KALI_DEFENSE_STATE_KEY";
+// ── Encrypted file format ────────────────────────────────────────────────────
+// Binary layout: [salt (16)] [iv (12)] [authTag (16)] [ciphertext (...)]
+// JSON fallback (unencrypted): plain JSON text
+// ── SecureStateStore ─────────────────────────────────────────────────────────
+/**
+ * Encrypted state storage for sensitive data at rest.
+ *
+ * Uses AES-256-GCM with PBKDF2-derived keys when `KALI_DEFENSE_STATE_KEY`
+ * is set. Falls back to plaintext JSON when no key is configured.
+ */
+export class SecureStateStore {
+    stateDir;
+    secret;
+    /**
+     * @param stateDir - Directory for state files (default: `/tmp/kali-defense/state/`)
+     * @param secret - Encryption secret. If omitted, reads from `KALI_DEFENSE_STATE_KEY` env var.
+     *                 Pass empty string or omit to use unencrypted fallback.
+     */
+    constructor(stateDir, secret) {
+        this.stateDir = stateDir ?? DEFAULT_STATE_DIR;
+        // Determine secret: explicit parameter > env var > null (unencrypted)
+        if (secret !== undefined) {
+            this.secret = secret.length > 0 ? secret : null;
+        }
+        else {
+            const envKey = process.env[ENV_KEY_NAME];
+            this.secret = envKey && envKey.length > 0 ? envKey : null;
+        }
+        if (this.secret === null) {
+            logger.warn("encrypted-state", "init", "No encryption key configured — state files will be stored unencrypted. " +
+                `Set ${ENV_KEY_NAME} environment variable for encrypted storage.`);
+        }
+        // Ensure state directory exists with secure permissions
+        this.ensureStateDir();
+    }
+    /**
+     * Whether the store is operating in encrypted mode.
+     */
+    get encrypted() {
+        return this.secret !== null;
+    }
+    /**
+     * Save a state object to disk.
+     *
+     * @param id - Unique identifier for the state (used as filename stem)
+     * @param data - JSON-serializable object to persist
+     */
+    save(id, data) {
+        const filePath = this.filePath(id);
+        const json = JSON.stringify(data);
+        if (this.secret !== null) {
+            const encrypted = this.encrypt(json);
+            atomicWriteFileSync(filePath, encrypted, { mode: SECURE_FILE_MODE });
+        }
+        else {
+            atomicWriteFileSync(filePath, json, { mode: SECURE_FILE_MODE });
+        }
+        logger.debug("encrypted-state", "save", `State saved: ${id}`, { encrypted: this.encrypted });
+    }
+    /**
+     * Load a state object from disk.
+     *
+     * @param id - Unique identifier for the state
+     * @returns The deserialized object, or `null` if the state file doesn't exist
+     */
+    load(id) {
+        const filePath = this.filePath(id);
+        if (!existsSync(filePath)) {
+            return null;
+        }
+        const raw = readFileSync(filePath);
+        if (this.secret !== null) {
+            const json = this.decrypt(raw);
+            return JSON.parse(json);
+        }
+        else {
+            return JSON.parse(raw.toString("utf-8"));
+        }
+    }
+    /**
+     * Delete a state file from disk.
+     *
+     * @param id - Unique identifier for the state to delete
+     */
+    delete(id) {
+        const filePath = this.filePath(id);
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+            logger.debug("encrypted-state", "delete", `State deleted: ${id}`);
+        }
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    /** Build the full file path for a state ID. */
+    filePath(id) {
+        // Sanitize id to prevent path traversal
+        const safeId = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+        return join(this.stateDir, `${safeId}.state`);
+    }
+    /** Ensure the state directory exists with secure permissions. */
+    ensureStateDir() {
+        if (!existsSync(this.stateDir)) {
+            mkdirSync(this.stateDir, { recursive: true, mode: SECURE_DIR_MODE });
+        }
+        chmodSync(this.stateDir, SECURE_DIR_MODE);
+    }
+    /** Derive an AES-256 key from the secret and a salt. */
+    deriveKey(salt) {
+        if (!this.secret) {
+            throw new Error("Cannot derive key: no secret configured");
+        }
+        return pbkdf2Sync(this.secret, salt, PBKDF2_ITERATIONS, KEY_LENGTH, PBKDF2_DIGEST);
+    }
+    /**
+     * Encrypt plaintext JSON using AES-256-GCM.
+     * Returns a Buffer: [salt (16)] [iv (12)] [authTag (16)] [ciphertext]
+     */
+    encrypt(plaintext) {
+        const salt = randomBytes(SALT_LENGTH);
+        const key = this.deriveKey(salt);
+        const iv = randomBytes(IV_LENGTH);
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const encrypted = Buffer.concat([
+            cipher.update(plaintext, "utf-8"),
+            cipher.final(),
+        ]);
+        const authTag = cipher.getAuthTag();
+        // Combine: salt + iv + authTag + ciphertext
+        return Buffer.concat([salt, iv, authTag, encrypted]);
+    }
+    /**
+     * Decrypt an AES-256-GCM encrypted buffer.
+     * Expects format: [salt (16)] [iv (12)] [authTag (16)] [ciphertext]
+     */
+    decrypt(data) {
+        const minLength = SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH;
+        if (data.length < minLength) {
+            throw new Error("Corrupted state file: data too short to contain encryption headers");
+        }
+        let offset = 0;
+        const salt = data.subarray(offset, offset + SALT_LENGTH);
+        offset += SALT_LENGTH;
+        const iv = data.subarray(offset, offset + IV_LENGTH);
+        offset += IV_LENGTH;
+        const authTag = data.subarray(offset, offset + AUTH_TAG_LENGTH);
+        offset += AUTH_TAG_LENGTH;
+        const ciphertext = data.subarray(offset);
+        const key = this.deriveKey(salt);
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(authTag);
+        try {
+            const decrypted = Buffer.concat([
+                decipher.update(ciphertext),
+                decipher.final(),
+            ]);
+            return decrypted.toString("utf-8");
+        }
+        catch {
+            throw new Error("Failed to decrypt state file: invalid key or corrupted data");
+        }
+    }
+}
+// ── Singleton Export ─────────────────────────────────────────────────────────
+/**
+ * Default singleton SecureStateStore instance.
+ *
+ * Uses the default state directory and reads the encryption key from
+ * the `KALI_DEFENSE_STATE_KEY` environment variable.
+ */
+export const secureState = new SecureStateStore();

package/build/core/executor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Options for executing a command.
+ */
+export interface ExecuteOptions {
+    /** The command binary to execute */
+    command: string;
+    /** Arguments to pass to the command */
+    args: string[];
+    /** Timeout in milliseconds (overrides default) */
+    timeout?: number;
+    /** Working directory for the command */
+    cwd?: string;
+    /** Additional environment variables */
+    env?: Record<string, string>;
+    /** Data to pipe to stdin (Buffer preferred for sensitive data like passwords) */
+    stdin?: string | Buffer;
+    /** Maximum output buffer size in bytes */
+    maxBuffer?: number;
+    /** Tool name for timeout lookup */
+    toolName?: string;
+    /** Skip automatic sudo credential injection (used internally) */
+    skipSudoInjection?: boolean;
+}
+/**
+ * Result of a command execution.
+ */
+export interface CommandResult {
+    /** Standard output content */
+    stdout: string;
+    /** Standard error content */
+    stderr: string;
+    /** Process exit code (124 on timeout) */
+    exitCode: number;
+    /** Whether the command was killed due to timeout */
+    timedOut: boolean;
+    /** Wall-clock duration in milliseconds */
+    duration: number;
+    /**
+     * Whether the command failed due to insufficient privileges.
+     * Detected by analyzing stderr/stdout against known permission error patterns.
+     * When `true`, the caller should prompt the user to call `sudo_elevate`.
+     */
+    permissionDenied: boolean;
+}
+/**
+ * Executes a command safely using spawn with shell: false.
+ *
+ * - Transparently injects sudo credentials from SudoSession when available
+ * - Uses AbortController for timeout enforcement
+ * - Caps stdout/stderr buffers to maxBuffer
+ * - Tracks execution duration
+ * - Handles stdin piping
+ * - Catches spawn errors gracefully
+ */
+export declare function executeCommand(options: ExecuteOptions): Promise<CommandResult>;
+//# sourceMappingURL=executor.d.ts.map

package/build/core/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAqEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAgFD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAmNxB"}

package/build/core/executor.js

@@ -0,0 +1,350 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { getConfig, getToolTimeout } from "./config.js";
+import { SudoSession } from "./sudo-session.js";
+import { SudoGuard } from "./sudo-guard.js";
+import { resolveCommand, resolveSudoCommand } from "./command-allowlist.js";
+// ── Askpass helper detection ─────────────────────────────────────────────────
+/**
+ * Ordered list of known graphical sudo/SSH askpass helpers.
+ * The first one found on the system will be used as the SUDO_ASKPASS program.
+ */
+const ASKPASS_CANDIDATES = [
+    "/usr/bin/ssh-askpass", // Generic (often symlinked to ksshaskpass/gnome)
+    "/usr/bin/ksshaskpass", // KDE Plasma
+    "/usr/lib/ssh/x11-ssh-askpass", // X11 classic
+    "/usr/libexec/openssh/gnome-ssh-askpass", // GNOME
+    "/usr/bin/lxqt-sudo", // LXQt
+];
+/** Cached result of askpass detection (null = not yet checked, undefined = not found) */
+let cachedAskpass = null;
+/**
+ * Find the first available graphical askpass helper on the system.
+ * Returns the absolute path or `undefined` if none found.
+ * Result is cached for the process lifetime.
+ */
+function findAskpassHelper() {
+    if (cachedAskpass !== null)
+        return cachedAskpass;
+    // Check environment variable first — user may have set it explicitly
+    const envAskpass = process.env.SUDO_ASKPASS;
+    if (envAskpass && existsSync(envAskpass)) {
+        // SECURITY (CORE-016): Validate the env-specified askpass helper
+        const envValidation = SudoGuard.validateAskpassPath(envAskpass);
+        if (envValidation.valid) {
+            cachedAskpass = envAskpass;
+            return cachedAskpass;
+        }
+        console.error(`[executor] Rejecting SUDO_ASKPASS: ${envValidation.reason}`);
+    }
+    // Must have a display server to show a GUI dialog
+    const hasDisplay = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+    if (!hasDisplay) {
+        cachedAskpass = undefined;
+        return undefined;
+    }
+    for (const candidate of ASKPASS_CANDIDATES) {
+        if (existsSync(candidate)) {
+            // SECURITY (CORE-016): Validate each candidate's ownership, permissions, and integrity
+            const validation = SudoGuard.validateAskpassPath(candidate);
+            if (validation.valid) {
+                cachedAskpass = candidate;
+                console.error(`[executor] Found verified askpass helper: ${candidate}`);
+                return cachedAskpass;
+            }
+            console.error(`[executor] Skipping askpass candidate ${candidate}: ${validation.reason}`);
+        }
+    }
+    console.error(`[executor] No verified askpass helper found`);
+    cachedAskpass = undefined;
+    return undefined;
+}
+/**
+ * Prepares sudo command options by injecting credentials so that sudo
+ * works in non-interactive (no-TTY) environments like MCP servers.
+ *
+ * **Strategy (in priority order):**
+ * 1. If a {@link SudoSession} is active with a cached password, inject
+ *    `-S -p ""` and pipe the password via stdin (fastest, no UI).
+ * 2. If no session but a graphical askpass helper is available (e.g.
+ *    `ssh-askpass`, `ksshaskpass`), inject `-A` and set `SUDO_ASKPASS`
+ *    env var. This pops a **secure native GUI dialog** for the password
+ *    — the password never enters the chat or any log.
+ * 3. If neither is available, let sudo run as-is (will fail without TTY,
+ *    but the error will be caught and an elevation prompt returned).
+ *
+ * This is transparent to callers — tool code continues to use
+ * `command: "sudo", args: ["iptables", ...]`.
+ */
+function prepareSudoOptions(options) {
+    // Only transform calls where the command is "sudo"
+    if (options.command !== "sudo")
+        return options;
+    // Skip if the caller explicitly opted out (e.g. sudo-session.ts itself)
+    if (options.skipSudoInjection)
+        return options;
+    // Skip if the caller already supplied `-S` or `-A` (manual control)
+    if (options.args.includes("-S") || options.args.includes("-A"))
+        return options;
+    const session = SudoSession.getInstance();
+    const passwordBuf = session.getPassword(); // Returns Buffer | null (a copy)
+    if (passwordBuf) {
+        // ── Strategy 1: SudoSession has a cached password → pipe via stdin ──
+        const newArgs = ["-S", "-p", "", ...options.args];
+        const newline = Buffer.from("\n");
+        const stdinPayload = options.stdin
+            ? Buffer.concat([
+                passwordBuf,
+                newline,
+                Buffer.isBuffer(options.stdin) ? options.stdin : Buffer.from(options.stdin),
+            ])
+            : Buffer.concat([passwordBuf, newline]);
+        // Zero the password copy immediately after concatenation
+        passwordBuf.fill(0);
+        return {
+            ...options,
+            args: newArgs,
+            stdin: stdinPayload,
+        };
+    }
+    // ── Strategy 2: No cached password → try graphical askpass helper ──
+    const askpassPath = findAskpassHelper();
+    if (askpassPath) {
+        console.error(`[executor] No sudo session — falling back to askpass GUI: ${askpassPath}`);
+        const newArgs = ["-A", ...options.args];
+        return {
+            ...options,
+            args: newArgs,
+            env: {
+                ...options.env,
+                SUDO_ASKPASS: askpassPath,
+                // Ensure DISPLAY is forwarded for GUI dialog
+                ...(process.env.DISPLAY ? { DISPLAY: process.env.DISPLAY } : {}),
+                ...(process.env.WAYLAND_DISPLAY
+                    ? { WAYLAND_DISPLAY: process.env.WAYLAND_DISPLAY }
+                    : {}),
+            },
+        };
+    }
+    // ── Strategy 3: No session, no askpass → let sudo fail naturally ──
+    // The error will be caught by SudoGuard and an elevation prompt returned.
+    return options;
+}
+/**
+ * Executes a command safely using spawn with shell: false.
+ *
+ * - Transparently injects sudo credentials from SudoSession when available
+ * - Uses AbortController for timeout enforcement
+ * - Caps stdout/stderr buffers to maxBuffer
+ * - Tracks execution duration
+ * - Handles stdin piping
+ * - Catches spawn errors gracefully
+ */
+export async function executeCommand(options) {
+    const config = getConfig();
+    const timeout = options.timeout ??
+        (options.toolName
+            ? getToolTimeout(options.toolName, config)
+            : config.commandTimeout);
+    const maxBuffer = options.maxBuffer ?? config.maxBuffer;
+    // ── Command allowlist validation ─────────────────────────────────────
+    // Resolve bare command names to absolute paths and reject anything
+    // not in the allowlist. For sudo, also validate the target binary.
+    try {
+        if (options.command === "sudo") {
+            const { sudoPath, targetIndex, targetPath } = resolveSudoCommand(options.args);
+            options = {
+                ...options,
+                command: sudoPath,
+                args: targetIndex >= 0
+                    ? [
+                        ...options.args.slice(0, targetIndex),
+                        targetPath,
+                        ...options.args.slice(targetIndex + 1),
+                    ]
+                    : options.args,
+            };
+        }
+        else {
+            options = {
+                ...options,
+                command: resolveCommand(options.command),
+            };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            stdout: "",
+            stderr: `Allowlist validation failed: ${message}`,
+            exitCode: 1,
+            timedOut: false,
+            duration: 0,
+            permissionDenied: false,
+        };
+    }
+    // ── Transparent sudo credential injection ────────────────────────────
+    const effectiveOptions = prepareSudoOptions(options);
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        let timedOut = false;
+        const controller = new AbortController();
+        const { signal } = controller;
+        let spawnEnv;
+        if (effectiveOptions.env) {
+            spawnEnv = { ...process.env, ...effectiveOptions.env };
+        }
+        let child;
+        try {
+            child = spawn(effectiveOptions.command, effectiveOptions.args, {
+                shell: false,
+                cwd: effectiveOptions.cwd,
+                env: spawnEnv,
+                signal,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - startTime;
+            const message = err instanceof Error ? err.message : String(err);
+            const stderrMsg = `Spawn error: ${message}`;
+            resolve({
+                stdout: "",
+                stderr: stderrMsg,
+                exitCode: 1,
+                timedOut: false,
+                duration,
+                permissionDenied: SudoGuard.isPermissionError(stderrMsg, 1),
+            });
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutLen = 0;
+        let stderrLen = 0;
+        let stdoutCapped = false;
+        let stderrCapped = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            // Close stdin first to unblock any process waiting for input (e.g. sudo -S waiting for password)
+            try {
+                if (child.stdin && !child.stdin.destroyed)
+                    child.stdin.end();
+            }
+            catch { /* ignore */ }
+            // Graceful SIGTERM first
+            try {
+                child.kill("SIGTERM");
+            }
+            catch { /* ignore */ }
+            // Escalate to SIGKILL after 5 seconds if still running
+            setTimeout(() => {
+                try {
+                    if (!child.killed)
+                        child.kill("SIGKILL");
+                }
+                catch { /* ignore */ }
+            }, 5000);
+        }, timeout);
+        child.stdout?.on("data", (chunk) => {
+            if (stdoutCapped)
+                return;
+            stdoutLen += chunk.length;
+            if (stdoutLen > maxBuffer) {
+                stdoutCapped = true;
+                const remaining = maxBuffer - (stdoutLen - chunk.length);
+                if (remaining > 0) {
+                    stdoutChunks.push(chunk.subarray(0, remaining));
+                }
+            }
+            else {
+                stdoutChunks.push(chunk);
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderrCapped)
+                return;
+            stderrLen += chunk.length;
+            if (stderrLen > maxBuffer) {
+                stderrCapped = true;
+                const remaining = maxBuffer - (stderrLen - chunk.length);
+                if (remaining > 0) {
+                    stderrChunks.push(chunk.subarray(0, remaining));
+                }
+            }
+            else {
+                stderrChunks.push(chunk);
+            }
+        });
+        if (effectiveOptions.stdin && child.stdin) {
+            const stdinBuf = Buffer.isBuffer(effectiveOptions.stdin)
+                ? effectiveOptions.stdin
+                : Buffer.from(effectiveOptions.stdin);
+            child.stdin.write(stdinBuf);
+            child.stdin.end();
+            // Zero the buffer after writing (may contain sudo password)
+            stdinBuf.fill(0);
+        }
+        child.on("close", (code) => {
+            clearTimeout(timeoutId);
+            const duration = Date.now() - startTime;
+            const exitCode = timedOut ? 124 : (code ?? 1);
+            let stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+            let stderr = Buffer.concat(stderrChunks).toString("utf-8");
+            if (stdoutCapped) {
+                stdout += "\n[OUTPUT TRUNCATED - exceeded max buffer]";
+            }
+            if (stderrCapped) {
+                stderr += "\n[STDERR TRUNCATED - exceeded max buffer]";
+            }
+            if (timedOut) {
+                const timeoutSec = Math.round(timeout / 1000);
+                stderr += `\nCommand 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).`;
+            }
+            // Detect permission errors from combined output
+            const combinedOutput = stdout + "\n" + stderr;
+            const permissionDenied = !timedOut &&
+                exitCode !== 0 &&
+                SudoGuard.isPermissionError(combinedOutput, exitCode);
+            resolve({
+                stdout,
+                stderr,
+                exitCode,
+                timedOut,
+                duration,
+                permissionDenied,
+            });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timeoutId);
+            const duration = Date.now() - startTime;
+            // If it was an abort error from our timeout, handle as timeout
+            if (timedOut) {
+                const timeoutSec = Math.round(timeout / 1000);
+                const timeoutMsg = `\nCommand 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).`;
+                resolve({
+                    stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                    stderr: Buffer.concat(stderrChunks).toString("utf-8") + timeoutMsg,
+                    exitCode: 124,
+                    timedOut: true,
+                    duration,
+                    permissionDenied: false,
+                });
+                return;
+            }
+            const stderrMsg = `Process error: ${err.message}`;
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                stderr: stderrMsg,
+                exitCode: 1,
+                timedOut: false,
+                duration,
+                permissionDenied: SudoGuard.isPermissionError(stderrMsg, 1),
+            });
+        });
+    });
+}