defense-mcp-server 0.6.0

package/build/tools/malware.js

@@ -0,0 +1,532 @@
+/**
+ * Malware detection and quarantine tools for Kali Defense MCP Server.
+ *
+ * Registers 4 tools: malware_clamav (actions: scan, update),
+ * malware_yara_scan, malware_file_scan (actions: suspicious, webshell),
+ * malware_quarantine_manage.
+ */
+import { z } from "zod";
+import * as path from "node:path";
+import { executeCommand } from "../core/executor.js";
+import { getConfig, getToolTimeout } from "../core/config.js";
+import { createTextContent, createErrorContent, parseClamavOutput, formatToolOutput, } from "../core/parsers.js";
+import { logChange, createChangeEntry, } from "../core/changelog.js";
+import { validateFilePath, validateYaraRule, sanitizeArgs, } from "../core/sanitizer.js";
+// ── TOOL-006 remediation: quarantine file_id validation ────────────────────
+/** Strict pattern for quarantine file IDs — simple identifiers only */
+const FILE_ID_REGEX = /^[a-zA-Z0-9._-]+$/;
+/**
+ * Validate a quarantine file_id to prevent path traversal.
+ * Rejects any id containing `..`, `/`, or `\`.
+ * After validation, resolves the full path and verifies it stays within the quarantine directory.
+ */
+function validateQuarantineFileId(fileId, quarantineDir) {
+    // Reject any file_id containing path separators or traversal sequences
+    if (fileId.includes("..") || fileId.includes("/") || fileId.includes("\\")) {
+        throw new Error(`Invalid file_id: path traversal sequences are not allowed`);
+    }
+    if (!FILE_ID_REGEX.test(fileId)) {
+        throw new Error(`Invalid file_id: '${fileId}'. Only [a-zA-Z0-9._-] characters are allowed.`);
+    }
+    // Resolve full path and verify it's within the quarantine directory
+    const resolvedPath = path.resolve(quarantineDir, fileId);
+    const resolvedBase = path.resolve(quarantineDir);
+    if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
+        throw new Error(`Invalid file_id: resolved path escapes quarantine directory`);
+    }
+    return fileId;
+}
+// ── Registration entry point ───────────────────────────────────────────────
+export function registerMalwareTools(server) {
+    // ── 1. malware_clamav (merged: scan + update) ─────────────────────────
+    server.tool("malware_clamav", "ClamAV antivirus: scan files/directories or update virus definitions.", {
+        action: z.enum(["scan", "update"]).describe("Action: scan=scan files, update=update virus definitions"),
+        // scan params
+        path: z.string().optional().describe("File or directory path to scan (scan action)"),
+        recursive: z.boolean().optional().default(true).describe("Recursively scan directories (scan action)"),
+        remove_infected: z.boolean().optional().default(false).describe("Remove infected files (scan action)"),
+        move_to_quarantine: z.boolean().optional().default(false).describe("Move infected files to quarantine (scan action)"),
+        max_filesize: z.string().optional().default("100M").describe("Maximum file size to scan (scan action)"),
+        // shared
+        dry_run: z.boolean().optional().describe("Preview without executing (defaults to KALI_DEFENSE_DRY_RUN env var)"),
+    }, async (params) => {
+        const { action } = params;
+        switch (action) {
+            case "scan": {
+                const { path: scanPath, recursive, remove_infected, move_to_quarantine, max_filesize, dry_run } = params;
+                try {
+                    if (!scanPath) {
+                        return { content: [createErrorContent("path is required for scan action")], isError: true };
+                    }
+                    const validatedPath = validateFilePath(scanPath);
+                    const config = getConfig();
+                    const args = [];
+                    if (recursive)
+                        args.push("--recursive");
+                    if (!dry_run && remove_infected)
+                        args.push("--remove");
+                    if (!dry_run && move_to_quarantine)
+                        args.push(`--move=${config.quarantineDir}`);
+                    args.push(`--max-filesize=${max_filesize}`);
+                    args.push(validatedPath);
+                    sanitizeArgs(args);
+                    const fullCmd = `clamscan ${args.join(" ")}`;
+                    if (dry_run && (remove_infected || move_to_quarantine)) {
+                        const scanArgs = args.filter((a) => !a.startsWith("--remove") && !a.startsWith("--move="));
+                        const result = await executeCommand({
+                            command: "clamscan",
+                            args: scanArgs,
+                            toolName: "malware_clamav",
+                            timeout: getToolTimeout("clamav"),
+                        });
+                        const parsed = parseClamavOutput(result.stdout);
+                        const infected = parsed.filter((r) => r.status === "FOUND");
+                        logChange(createChangeEntry({
+                            tool: "malware_clamav",
+                            action: `[DRY-RUN] ClamAV scan`,
+                            target: validatedPath,
+                            after: `Would execute: ${fullCmd}`,
+                            dryRun: true,
+                            success: true,
+                        }));
+                        return { content: [formatToolOutput({
+                                    mode: "dry_run",
+                                    wouldExecute: fullCmd,
+                                    scannedFiles: parsed.length,
+                                    infectedFiles: infected.length,
+                                    findings: infected,
+                                    raw: result.stdout,
+                                })] };
+                    }
+                    const result = await executeCommand({
+                        command: "clamscan",
+                        args,
+                        toolName: "malware_clamav",
+                        timeout: getToolTimeout("clamav"),
+                    });
+                    const parsed = parseClamavOutput(result.stdout);
+                    const infected = parsed.filter((r) => r.status === "FOUND");
+                    logChange(createChangeEntry({
+                        tool: "malware_clamav",
+                        action: `ClamAV scan${remove_infected ? " (remove)" : ""}${move_to_quarantine ? " (quarantine)" : ""}`,
+                        target: validatedPath,
+                        after: `Scanned: ${parsed.length}, Infected: ${infected.length}`,
+                        dryRun: false,
+                        success: true,
+                    }));
+                    return { content: [formatToolOutput({
+                                scannedFiles: parsed.length,
+                                infectedFiles: infected.length,
+                                findings: infected,
+                                actionsApplied: { removed: remove_infected, quarantined: move_to_quarantine },
+                                raw: result.stdout,
+                            })] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { content: [createErrorContent(msg)], isError: true };
+                }
+            }
+            case "update": {
+                const { dry_run } = params;
+                try {
+                    const fullCmd = "sudo freshclam";
+                    if (dry_run ?? getConfig().dryRun) {
+                        logChange(createChangeEntry({
+                            tool: "malware_clamav",
+                            action: `[DRY-RUN] Update ClamAV virus definitions`,
+                            target: "freshclam",
+                            after: fullCmd,
+                            dryRun: true,
+                            success: true,
+                        }));
+                        return {
+                            content: [createTextContent(`[DRY-RUN] Would execute:\n  ${fullCmd}\n\nThis would update ClamAV virus definitions.`)],
+                        };
+                    }
+                    const result = await executeCommand({
+                        command: "sudo",
+                        args: ["freshclam"],
+                        toolName: "malware_clamav",
+                        timeout: getToolTimeout("clamav"),
+                    });
+                    const success = result.exitCode === 0;
+                    logChange(createChangeEntry({
+                        tool: "malware_clamav",
+                        action: "Update ClamAV virus definitions",
+                        target: "freshclam",
+                        after: result.stdout,
+                        dryRun: false,
+                        success,
+                        error: success ? undefined : result.stderr,
+                    }));
+                    if (!success) {
+                        return { content: [createErrorContent(`freshclam failed (exit ${result.exitCode}): ${result.stderr}`)], isError: true };
+                    }
+                    return { content: [createTextContent(`ClamAV definitions updated successfully.\n\n${result.stdout}`)] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { content: [createErrorContent(msg)], isError: true };
+                }
+            }
+            default:
+                return { content: [createErrorContent(`Unknown action: ${action}`)], isError: true };
+        }
+    });
+    // ── 2. malware_yara_scan (kept as-is) ─────────────────────────────────
+    server.tool("malware_yara_scan", "Scan files with YARA rules for pattern-based malware detection", {
+        rules_path: z
+            .string()
+            .describe("Path to YARA rules file (.yar/.yara)"),
+        target_path: z.string().describe("File or directory to scan"),
+        recursive: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Recursively scan directories (default: false)"),
+        timeout_per_file: z
+            .number()
+            .optional()
+            .default(60)
+            .describe("Timeout in seconds per file (default: 60)"),
+    }, async ({ rules_path, target_path, recursive, timeout_per_file }) => {
+        try {
+            const validatedRules = validateYaraRule(rules_path);
+            const validatedTarget = validateFilePath(target_path);
+            const args = [];
+            if (recursive) {
+                args.push("-r");
+            }
+            args.push("-t", String(timeout_per_file));
+            args.push(validatedRules);
+            args.push(validatedTarget);
+            sanitizeArgs(args);
+            const result = await executeCommand({
+                command: "yara",
+                args,
+                toolName: "malware_yara_scan",
+                timeout: getToolTimeout("malware_yara_scan"),
+            });
+            // Parse YARA output: each line is "RuleName MatchedFile"
+            const findings = [];
+            for (const line of result.stdout.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const spaceIdx = trimmed.indexOf(" ");
+                if (spaceIdx > 0) {
+                    findings.push({
+                        rule: trimmed.substring(0, spaceIdx),
+                        file: trimmed.substring(spaceIdx + 1),
+                    });
+                }
+            }
+            const entry = createChangeEntry({
+                tool: "malware_yara_scan",
+                action: "YARA scan",
+                target: validatedTarget,
+                after: `Rules: ${validatedRules}, Matches: ${findings.length}`,
+                dryRun: false,
+                success: true,
+            });
+            logChange(entry);
+            const output = {
+                rulesFile: validatedRules,
+                targetPath: validatedTarget,
+                recursive,
+                matchCount: findings.length,
+                findings,
+                raw: result.stdout,
+            };
+            return { content: [formatToolOutput(output)] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [createErrorContent(msg)], isError: true };
+        }
+    });
+    // ── 3. malware_file_scan (merged: suspicious_files + webshell_detect) ──
+    server.tool("malware_file_scan", "File scanning: find suspicious files (SUID, SGID, world-writable, hidden executables, recently modified) or detect web shells.", {
+        action: z.enum(["suspicious", "webshell"]).describe("Action: suspicious=find suspicious files, webshell=detect web shells"),
+        // suspicious params
+        search_path: z.string().optional().default("/tmp").describe("Root path to search (suspicious action, default: /tmp)"),
+        check_type: z.enum(["suid", "sgid", "world_writable", "hidden_executables", "recently_modified", "all"]).optional().default("all").describe("Type of suspicious file check (suspicious action)"),
+        days: z.number().optional().default(7).describe("Days for recently_modified check (suspicious action)"),
+        // webshell params
+        path: z.string().optional().default("/var/www").describe("Web root directory to scan (webshell action)"),
+        max_depth: z.number().optional().default(5).describe("Max directory depth (webshell action)"),
+    }, async (params) => {
+        const { action } = params;
+        switch (action) {
+            case "suspicious": {
+                const { search_path, check_type, days } = params;
+                try {
+                    const validatedPath = validateFilePath(search_path);
+                    const checks = {
+                        suid: { cmd: "find", args: [validatedPath, "-perm", "-4000", "-type", "f"] },
+                        sgid: { cmd: "find", args: [validatedPath, "-perm", "-2000", "-type", "f"] },
+                        world_writable: { cmd: "find", args: [validatedPath, "-perm", "-0002", "-type", "f", "-not", "-path", "*/proc/*"] },
+                        hidden_executables: { cmd: "find", args: [validatedPath, "-name", ".*", "-executable", "-type", "f"] },
+                        recently_modified: { cmd: "find", args: [validatedPath, "-mtime", `-${days}`, "-type", "f"] },
+                    };
+                    const typesToCheck = check_type === "all" ? Object.keys(checks) : [check_type];
+                    const results = {};
+                    for (const checkName of typesToCheck) {
+                        const check = checks[checkName];
+                        if (!check)
+                            continue;
+                        const result = await executeCommand({
+                            command: check.cmd,
+                            args: check.args,
+                            toolName: "malware_file_scan",
+                            timeout: getToolTimeout("malware_suspicious_files"),
+                        });
+                        results[checkName] = result.stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+                    }
+                    const totalFindings = Object.values(results).reduce((sum, files) => sum + files.length, 0);
+                    logChange(createChangeEntry({
+                        tool: "malware_file_scan",
+                        action: `Suspicious file scan (${check_type})`,
+                        target: validatedPath,
+                        after: `Total findings: ${totalFindings}`,
+                        dryRun: false,
+                        success: true,
+                    }));
+                    return { content: [formatToolOutput({ searchPath: validatedPath, checkType: check_type, totalFindings, categories: results })] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { content: [createErrorContent(msg)], isError: true };
+                }
+            }
+            case "webshell": {
+                const { path: webPath, max_depth } = params;
+                try {
+                    const patterns = [
+                        "eval\\s*\\(\\s*\\$_(POST|GET|REQUEST)",
+                        "base64_decode\\s*\\(\\s*\\$_(POST|GET|REQUEST)",
+                        "system\\s*\\(\\s*\\$_(POST|GET|REQUEST)",
+                        "exec\\s*\\(\\s*\\$_(POST|GET|REQUEST)",
+                        "passthru\\s*\\(",
+                        "shell_exec\\s*\\(",
+                        "proc_open\\s*\\(",
+                        "assert\\s*\\(\\s*\\$_",
+                        "preg_replace.*\\/e",
+                        "\\$\\{.*\\$_(POST|GET|REQUEST)",
+                        "Runtime\\.getRuntime\\(\\)\\.exec",
+                        "ProcessBuilder",
+                        "cmd\\.exe",
+                        "powershell",
+                    ];
+                    const grepPattern = patterns.join("|");
+                    const result = await executeCommand({
+                        command: "grep",
+                        args: ["-rnl", "--include=*.php", "--include=*.jsp", "--include=*.asp", "--include=*.aspx", "--include=*.cgi", "--include=*.py", "-E", grepPattern, webPath, `--max-depth=${max_depth}`],
+                        timeout: 60000,
+                        toolName: "malware_file_scan",
+                    });
+                    const suspiciousFiles = result.stdout.trim().split("\n").filter((f) => f.trim());
+                    const details = [];
+                    for (const file of suspiciousFiles.slice(0, 20)) {
+                        const statResult = await executeCommand({ command: "stat", args: ["-c", "%a %U:%G %Y %s", file], timeout: 5000, toolName: "malware_file_scan" });
+                        const matchResult = await executeCommand({ command: "grep", args: ["-c", "-E", grepPattern, file], timeout: 5000, toolName: "malware_file_scan" });
+                        details.push({ file, stat: statResult.stdout.trim(), patternMatches: parseInt(matchResult.stdout.trim()) || 0 });
+                    }
+                    return { content: [createTextContent(JSON.stringify({ scanPath: webPath, totalSuspicious: suspiciousFiles.length, details, note: suspiciousFiles.length > 0 ? "Review these files manually — pattern matches may include legitimate code" : "No webshell patterns detected" }, null, 2))] };
+                }
+                catch (error) {
+                    const errMsg = error instanceof Error ? error.message : String(error);
+                    if (errMsg.includes("exit code 1")) {
+                        return { content: [createTextContent(JSON.stringify({ scanPath: params.path, totalSuspicious: 0, note: "No webshell patterns detected" }, null, 2))] };
+                    }
+                    return { content: [createErrorContent(errMsg)], isError: true };
+                }
+            }
+            default:
+                return { content: [createErrorContent(`Unknown action: ${action}`)], isError: true };
+        }
+    });
+    // ── 4. malware_quarantine_manage (kept as-is) ─────────────────────────
+    server.tool("malware_quarantine_manage", "Manage quarantined files (list, restore, delete, info)", {
+        action: z
+            .enum(["list", "restore", "delete", "info"])
+            .describe("Action to perform on quarantine"),
+        file_id: z
+            .string()
+            .optional()
+            .describe("Filename in quarantine directory (required for restore, delete, info)"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Preview destructive actions without executing (defaults to KALI_DEFENSE_DRY_RUN env var)"),
+    }, async ({ action, file_id, dry_run }) => {
+        try {
+            const config = getConfig();
+            const quarantineDir = config.quarantineDir;
+            if ((action === "restore" || action === "delete" || action === "info") && !file_id) {
+                return {
+                    content: [
+                        createErrorContent(`file_id is required for '${action}' action`),
+                    ],
+                    isError: true,
+                };
+            }
+            // TOOL-006: Validate file_id against path traversal
+            if (file_id) {
+                validateQuarantineFileId(file_id, quarantineDir);
+            }
+            switch (action) {
+                case "list": {
+                    const result = await executeCommand({
+                        command: "ls",
+                        args: ["-la", quarantineDir],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    return {
+                        content: [
+                            createTextContent(`Quarantine directory: ${quarantineDir}\n\n${result.stdout || "No files in quarantine."}`),
+                        ],
+                    };
+                }
+                case "info": {
+                    const filePath = `${quarantineDir}/${file_id}`;
+                    const fileResult = await executeCommand({
+                        command: "file",
+                        args: [filePath],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    const hashResult = await executeCommand({
+                        command: "sha256sum",
+                        args: [filePath],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    const statResult = await executeCommand({
+                        command: "stat",
+                        args: [filePath],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    const output = {
+                        file: file_id,
+                        fileType: fileResult.stdout.trim(),
+                        sha256: hashResult.stdout.trim().split(/\s+/)[0] ?? "",
+                        stat: statResult.stdout,
+                    };
+                    return { content: [formatToolOutput(output)] };
+                }
+                case "restore": {
+                    const filePath = `${quarantineDir}/${file_id}`;
+                    const fullCmd = `cp ${filePath} /tmp/${file_id}`;
+                    if (dry_run ?? getConfig().dryRun) {
+                        const entry = createChangeEntry({
+                            tool: "malware_quarantine_manage",
+                            action: `[DRY-RUN] Restore quarantined file`,
+                            target: filePath,
+                            after: `Would restore to /tmp/${file_id}`,
+                            dryRun: true,
+                            success: true,
+                        });
+                        logChange(entry);
+                        return {
+                            content: [
+                                createTextContent(`[DRY-RUN] Would execute:\n  ${fullCmd}\n\nNote: File would be restored to /tmp/ for safety.`),
+                            ],
+                        };
+                    }
+                    const result = await executeCommand({
+                        command: "cp",
+                        args: [filePath, `/tmp/${file_id}`],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    const success = result.exitCode === 0;
+                    const entry = createChangeEntry({
+                        tool: "malware_quarantine_manage",
+                        action: "Restore quarantined file",
+                        target: filePath,
+                        after: `/tmp/${file_id}`,
+                        dryRun: false,
+                        success,
+                        error: success ? undefined : result.stderr,
+                        rollbackCommand: `rm /tmp/${file_id}`,
+                    });
+                    logChange(entry);
+                    if (!success) {
+                        return {
+                            content: [
+                                createErrorContent(`Restore failed (exit ${result.exitCode}): ${result.stderr}`),
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [
+                            createTextContent(`File restored to /tmp/${file_id}\nReview the file before moving to its original location.`),
+                        ],
+                    };
+                }
+                case "delete": {
+                    const filePath = `${quarantineDir}/${file_id}`;
+                    const fullCmd = `rm ${filePath}`;
+                    if (dry_run ?? getConfig().dryRun) {
+                        const entry = createChangeEntry({
+                            tool: "malware_quarantine_manage",
+                            action: `[DRY-RUN] Delete quarantined file`,
+                            target: filePath,
+                            dryRun: true,
+                            success: true,
+                        });
+                        logChange(entry);
+                        return {
+                            content: [
+                                createTextContent(`[DRY-RUN] Would execute:\n  ${fullCmd}\n\nThis would permanently delete the quarantined file.`),
+                            ],
+                        };
+                    }
+                    const result = await executeCommand({
+                        command: "rm",
+                        args: [filePath],
+                        toolName: "malware_quarantine_manage",
+                        timeout: getToolTimeout("malware_quarantine_manage"),
+                    });
+                    const success = result.exitCode === 0;
+                    const entry = createChangeEntry({
+                        tool: "malware_quarantine_manage",
+                        action: "Delete quarantined file",
+                        target: filePath,
+                        dryRun: false,
+                        success,
+                        error: success ? undefined : result.stderr,
+                    });
+                    logChange(entry);
+                    if (!success) {
+                        return {
+                            content: [
+                                createErrorContent(`Delete failed (exit ${result.exitCode}): ${result.stderr}`),
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [
+                            createTextContent(`Quarantined file ${file_id} deleted permanently.`),
+                        ],
+                    };
+                }
+                default:
+                    return {
+                        content: [createErrorContent(`Unknown action: ${action}`)],
+                        isError: true,
+                    };
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [createErrorContent(msg)], isError: true };
+        }
+    });
+}

package/build/tools/meta.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Meta/utility tools for Defense MCP Server.
+ *
+ * Registers 6 tools: defense_check_tools, defense_workflow (actions: suggest, run),
+ * defense_change_history, security_posture (actions: score, trend, dashboard),
+ * scheduled_audit (actions: create, list, remove, history),
+ * auto_remediate (actions: plan, apply, rollback_session, status).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMetaTools(server: McpServer): void;
+//# sourceMappingURL=meta.d.ts.map

package/build/tools/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/tools/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwrCpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAk0CzD"}