defense-mcp-server 0.6.0

package/build/core/config.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Known defensive tools that support per-tool timeout overrides
+ * via KALI_DEFENSE_TIMEOUT_<TOOL> environment variables.
+ */
+export declare const KNOWN_TOOLS: readonly ["lynis", "aide", "clamav", "oscap", "snort", "suricata", "rkhunter", "chkrootkit", "tcpdump", "auditd", "nmap", "fail2ban-client", "debsums", "yara"];
+export type KnownTool = (typeof KNOWN_TOOLS)[number];
+/**
+ * Configuration interface for the Kali Defense MCP Server.
+ * All values are derived from environment variables with sensible defaults.
+ */
+export interface DefenseConfig {
+    /** Default command timeout in milliseconds */
+    defaultTimeout: number;
+    /** Maximum output buffer size in bytes */
+    maxBuffer: number;
+    /** Directories allowed for file operations */
+    allowedDirs: string[];
+    /** Logging level */
+    logLevel: "debug" | "info" | "warn" | "error";
+    /**
+     * SECURITY (CICD-014): Dry-run mode — when true, modifying operations preview
+     * commands without executing them. Defaults to `true` so the server operates
+     * in a safe, read-only mode until explicitly opted out via
+     * KALI_DEFENSE_DRY_RUN=false. This prevents accidental system modifications.
+     */
+    dryRun: boolean;
+    /** Path to the changelog JSON file */
+    changelogPath: string;
+    /** Directory for file backups */
+    backupDir: string;
+    /**
+     * SECURITY (CICD-014): Whether to create backups before modifying files.
+     * Defaults to `true` — every file modification is backed up first so that
+     * changes can be rolled back if needed. Disable only in CI/test environments
+     * via KALI_DEFENSE_BACKUP_ENABLED=false.
+     */
+    backupEnabled: boolean;
+    /** Whether to auto-install missing tools */
+    autoInstall: boolean;
+    /** Paths protected from modification */
+    protectedPaths: string[];
+    /**
+     * SECURITY (CICD-014): Whether to require confirmation for destructive
+     * actions. Defaults to `true` — the server will request explicit confirmation
+     * before executing operations that modify system state. Disable only when
+     * running automated/unattended workflows via
+     * KALI_DEFENSE_REQUIRE_CONFIRMATION=false.
+     */
+    requireConfirmation: boolean;
+    /** Directory for quarantined files */
+    quarantineDir: string;
+    /** Directory for policy files */
+    policyDir: string;
+    /** Per-tool timeout overrides in milliseconds */
+    toolTimeouts: Partial<Record<KnownTool, number>>;
+    /** Sudo session timeout in milliseconds (default: 15 minutes) */
+    sudoSessionTimeout: number;
+    /** Command execution timeout in ms (falls back to defaultTimeout; env: KALI_DEFENSE_COMMAND_TIMEOUT) */
+    commandTimeout: number;
+    /** Network operation timeout in ms (default: 30s; env: KALI_DEFENSE_NETWORK_TIMEOUT) */
+    networkTimeout: number;
+}
+/**
+ * Returns the current configuration by reading environment variables.
+ * Results are cached for 5 seconds to avoid redundant env-var parsing
+ * across the 3–5 calls per tool invocation.
+ */
+export declare function getConfig(): DefenseConfig;
+/**
+ * Invalidate the config cache, forcing the next `getConfig()` call to
+ * re-read environment variables. Useful for tests.
+ */
+export declare function invalidateConfigCache(): void;
+/**
+ * Returns the effective timeout for a given tool in milliseconds.
+ * Checks per-tool overrides first, then falls back to the default timeout.
+ */
+export declare function getToolTimeout(toolName: string, config?: DefenseConfig): number;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,WAAW,iKAed,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oBAAoB;IACpB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;OAMG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,cAAc,EAAE,MAAM,CAAC;CACxB;AAmGD;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,aAAa,CAQzC;AAwFD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAIR"}

package/build/core/config.js

@@ -0,0 +1,193 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Known defensive tools that support per-tool timeout overrides
+ * via KALI_DEFENSE_TIMEOUT_<TOOL> environment variables.
+ */
+export const KNOWN_TOOLS = [
+    "lynis",
+    "aide",
+    "clamav",
+    "oscap",
+    "snort",
+    "suricata",
+    "rkhunter",
+    "chkrootkit",
+    "tcpdump",
+    "auditd",
+    "nmap",
+    "fail2ban-client",
+    "debsums",
+    "yara",
+];
+/**
+ * Resolves `~` prefix to the user's home directory.
+ */
+function expandHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return join(homedir(), p.slice(1));
+    }
+    return p;
+}
+/**
+ * Parses a comma-separated list of paths from an environment variable.
+ */
+/**
+ * SECURITY (CORE-012): Directories that are too broad to be allowed.
+ * These grant access to the entire filesystem or critical root-level trees.
+ */
+const REJECTED_DIRS = new Set(["/"]);
+/** Directories that are very broad and deserve a warning. */
+const BROAD_DIRS = new Set(["/usr", "/var", "/etc", "/opt", "/lib", "/lib64", "/sbin", "/bin"]);
+function parsePaths(value, defaultValue) {
+    const raw = value ?? defaultValue;
+    const paths = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .map(expandHome);
+    // SECURITY (CORE-012): Validate allowedDirs to reject overly broad paths
+    return paths.filter((p) => {
+        // Reject root directory and single-character root-level paths (e.g. "/")
+        if (REJECTED_DIRS.has(p) || (p.startsWith("/") && p.length <= 2 && p !== "/" + p.slice(1).replace(/\//g, ""))) {
+            console.error(`[KALI-DEFENSE] SECURITY: Rejecting overly broad allowedDir '${p}' — ` +
+                `granting access to the entire filesystem is not permitted.`);
+            return false;
+        }
+        // Reject any single-character root-level path like "/x"
+        if (/^\/[^/]$/.test(p)) {
+            console.error(`[KALI-DEFENSE] SECURITY: Rejecting overly broad allowedDir '${p}' — ` +
+                `single-character root-level paths are not permitted.`);
+            return false;
+        }
+        // Warn about broad directories
+        if (BROAD_DIRS.has(p)) {
+            console.error(`[KALI-DEFENSE] WARNING: allowedDir '${p}' is very broad. ` +
+                `Consider using a more specific subdirectory.`);
+        }
+        return true;
+    });
+}
+/**
+ * Parses a log level string, falling back to "info" if invalid.
+ */
+function parseLogLevel(value) {
+    const valid = ["debug", "info", "warn", "error"];
+    const lower = (value ?? "info").toLowerCase();
+    return valid.includes(lower)
+        ? lower
+        : "info";
+}
+/**
+ * Reads per-tool timeout overrides from environment variables.
+ * Format: KALI_DEFENSE_TIMEOUT_<TOOL> (value in seconds, stored as ms).
+ */
+function parseToolTimeouts() {
+    const timeouts = {};
+    for (const tool of KNOWN_TOOLS) {
+        const envKey = `KALI_DEFENSE_TIMEOUT_${tool.toUpperCase()}`;
+        const value = process.env[envKey];
+        if (value !== undefined) {
+            const seconds = parseInt(value, 10);
+            if (!isNaN(seconds) && seconds > 0) {
+                timeouts[tool] = seconds * 1000;
+            }
+        }
+    }
+    return timeouts;
+}
+// ── Config cache (avoids re-parsing 15+ env vars on every call) ──────────────
+let _configCache = null;
+let _configCacheTimestamp = 0;
+const CONFIG_CACHE_TTL = 5_000; // 5 seconds
+/**
+ * Returns the current configuration by reading environment variables.
+ * Results are cached for 5 seconds to avoid redundant env-var parsing
+ * across the 3–5 calls per tool invocation.
+ */
+export function getConfig() {
+    const now = Date.now();
+    if (_configCache && (now - _configCacheTimestamp) < CONFIG_CACHE_TTL) {
+        return _configCache;
+    }
+    _configCache = buildConfigFromEnv();
+    _configCacheTimestamp = now;
+    return _configCache;
+}
+/**
+ * Build the configuration object by reading all environment variables.
+ * This is the actual parsing logic, called by the cached `getConfig()` wrapper.
+ */
+function buildConfigFromEnv() {
+    const defaultTimeoutSec = parseInt(process.env.KALI_DEFENSE_TIMEOUT_DEFAULT ?? "120", 10);
+    const maxBufferBytes = parseInt(process.env.KALI_DEFENSE_MAX_OUTPUT_SIZE ?? String(10 * 1024 * 1024), 10);
+    const config = {
+        defaultTimeout: isNaN(defaultTimeoutSec) || defaultTimeoutSec <= 0
+            ? 120_000
+            : defaultTimeoutSec * 1000,
+        maxBuffer: isNaN(maxBufferBytes) || maxBufferBytes <= 0
+            ? 10 * 1024 * 1024
+            : maxBufferBytes,
+        // SECURITY (CICD-013): /etc is excluded from default allowedDirs because it
+        // contains sensitive system configuration files (shadow, sudoers, ssh configs).
+        // Granting default read/write access to /etc is too permissive. Tools that
+        // need /etc access should require explicit configuration via
+        // KALI_DEFENSE_ALLOWED_DIRS=/tmp,/home,/var/log,/etc
+        allowedDirs: parsePaths(process.env.KALI_DEFENSE_ALLOWED_DIRS, "/tmp,/home,/var/log"),
+        logLevel: parseLogLevel(process.env.KALI_DEFENSE_LOG_LEVEL),
+        // SECURITY (CICD-014): Default to dry-run=true (safe preview mode)
+        // Set KALI_DEFENSE_DRY_RUN=false to enable live system modifications
+        dryRun: process.env.KALI_DEFENSE_DRY_RUN !== "false",
+        changelogPath: expandHome(process.env.KALI_DEFENSE_CHANGELOG_PATH ??
+            "~/.kali-defense/changelog.json"),
+        backupDir: expandHome(process.env.KALI_DEFENSE_BACKUP_DIR ?? "~/.kali-defense/backups"),
+        // SECURITY (CICD-014): Backup before modify — enabled by default
+        // Set KALI_DEFENSE_BACKUP_ENABLED=false only in CI/test environments
+        backupEnabled: process.env.KALI_DEFENSE_BACKUP_ENABLED !== "false",
+        autoInstall: process.env.KALI_DEFENSE_AUTO_INSTALL === "true",
+        protectedPaths: parsePaths(process.env.KALI_DEFENSE_PROTECTED_PATHS, "/boot,/usr/lib/systemd,/usr/bin,/usr/sbin"),
+        requireConfirmation: process.env.KALI_DEFENSE_REQUIRE_CONFIRMATION !== "false",
+        quarantineDir: expandHome(process.env.KALI_DEFENSE_QUARANTINE_DIR ?? "~/.kali-defense/quarantine"),
+        policyDir: expandHome(process.env.KALI_DEFENSE_POLICY_DIR ?? "~/.kali-defense/policies"),
+        toolTimeouts: parseToolTimeouts(),
+        sudoSessionTimeout: (() => {
+            const envVal = process.env.KALI_DEFENSE_SUDO_TIMEOUT;
+            if (envVal) {
+                const minutes = parseInt(envVal, 10);
+                if (!isNaN(minutes) && minutes > 0)
+                    return minutes * 60 * 1000;
+            }
+            return 15 * 60 * 1000; // default: 15 minutes
+        })(),
+        commandTimeout: (() => {
+            const sec = parseInt(process.env.KALI_DEFENSE_COMMAND_TIMEOUT ?? "120", 10);
+            return isNaN(sec) || sec <= 0 ? 120_000 : sec * 1000;
+        })(),
+        networkTimeout: (() => {
+            const sec = parseInt(process.env.KALI_DEFENSE_NETWORK_TIMEOUT ?? "30", 10);
+            return isNaN(sec) || sec <= 0 ? 30_000 : sec * 1000;
+        })(),
+    };
+    // Warn when dry-run is active so operators know no changes will be applied
+    if (config.dryRun) {
+        console.error("[KALI-DEFENSE] DRY_RUN mode is ACTIVE — no changes will be applied");
+    }
+    return config;
+}
+/**
+ * Invalidate the config cache, forcing the next `getConfig()` call to
+ * re-read environment variables. Useful for tests.
+ */
+export function invalidateConfigCache() {
+    _configCache = null;
+    _configCacheTimestamp = 0;
+}
+/**
+ * Returns the effective timeout for a given tool in milliseconds.
+ * Checks per-tool overrides first, then falls back to the default timeout.
+ */
+export function getToolTimeout(toolName, config) {
+    const cfg = config ?? getConfig();
+    const lowerName = toolName.toLowerCase();
+    return cfg.toolTimeouts[lowerName] ?? cfg.defaultTimeout;
+}

package/build/core/dependency-validator.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Dependency Validator for Kali Defense MCP Server.
+ *
+ * Provides three key capabilities:
+ * 1. **Startup validation** — checks all tool dependencies when the server starts
+ *    and auto-installs missing ones if KALI_DEFENSE_AUTO_INSTALL=true
+ * 2. **Runtime dependency check** — `ensureDependencies()` can be called before
+ *    any tool execution to verify (and optionally install) required binaries
+ * 3. **Dependency status cache** — avoids redundant `which` calls by caching
+ *    binary availability results with a configurable TTL
+ */
+/**
+ * Result of a startup validation run.
+ */
+export interface ValidationReport {
+    /** Total unique binaries checked */
+    totalChecked: number;
+    /** Binaries that are available */
+    available: string[];
+    /** Binaries that are missing */
+    missing: string[];
+    /** Binaries that were auto-installed */
+    installed: string[];
+    /** Binaries that failed to install */
+    installFailed: Array<{
+        binary: string;
+        error: string;
+    }>;
+    /** Critical tools with missing dependencies */
+    criticalMissing: Array<{
+        toolName: string;
+        missingBinaries: string[];
+    }>;
+    /** Duration of the validation in milliseconds */
+    durationMs: number;
+    /** Whether auto-install was enabled */
+    autoInstallEnabled: boolean;
+}
+/**
+ * Result of ensuring dependencies for a specific tool.
+ */
+export interface EnsureResult {
+    /** Whether all required dependencies are satisfied */
+    satisfied: boolean;
+    /** Missing required binaries (empty if satisfied) */
+    missingRequired: string[];
+    /** Missing optional binaries */
+    missingOptional: string[];
+    /** Binaries that were auto-installed during this check */
+    autoInstalled: string[];
+    /** Errors from auto-install attempts */
+    installErrors: Array<{
+        binary: string;
+        error: string;
+    }>;
+}
+/**
+ * Clears the entire binary cache.
+ */
+export declare function clearDependencyCache(): void;
+/**
+ * Validates all tool dependencies at server startup.
+ *
+ * This function:
+ * 1. Collects all unique binaries required across all tools
+ * 2. Checks each binary's availability
+ * 3. If autoInstall is enabled, installs missing binaries
+ * 4. Reports critical tools with missing dependencies
+ *
+ * @returns A detailed validation report
+ */
+export declare function validateAllDependencies(): Promise<ValidationReport>;
+/**
+ * Ensures all dependencies for a specific MCP tool are satisfied.
+ *
+ * Call this at the start of any tool handler to verify its binaries are present.
+ * If autoInstall is enabled, missing binaries will be installed on-the-fly.
+ *
+ * @param toolName The MCP tool name (e.g. "ids_rkhunter_scan")
+ * @returns EnsureResult with satisfaction status and details
+ *
+ * @example
+ * ```ts
+ * const deps = await ensureDependencies("ids_rkhunter_scan");
+ * if (!deps.satisfied) {
+ *   return {
+ *     content: [createErrorContent(
+ *       `Missing required tools: ${deps.missingRequired.join(", ")}. ` +
+ *       `Install with: sudo apt install ${deps.missingRequired.join(" ")}`
+ *     )],
+ *     isError: true,
+ *   };
+ * }
+ * ```
+ */
+export declare function ensureDependencies(toolName: string): Promise<EnsureResult>;
+/**
+ * Quick check if a single binary is available (cached).
+ * Does NOT auto-install. Use for lightweight pre-flight checks.
+ */
+export declare function isBinaryInstalled(binary: string): Promise<boolean>;
+/**
+ * Formats a ValidationReport into a human-readable string for logging.
+ */
+export declare function formatValidationReport(report: ValidationReport): string;
+//# sourceMappingURL=dependency-validator.d.ts.map

package/build/core/dependency-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-validator.d.ts","sourceRoot":"","sources":["../../src/core/dependency-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgCH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gCAAgC;IAChC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sCAAsC;IACtC,aAAa,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,+CAA+C;IAC/C,eAAe,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACxE,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gCAAgC;IAChC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,0DAA0D;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,wCAAwC;IACxC,aAAa,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAsCD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AA+CD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAqJzE;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CA0EvB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIxE;AAID;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAmDvE"}