defense-mcp-server 0.6.0

package/build/core/privilege-manager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * PrivilegeManager — detects the current privilege level and checks whether
+ * a tool's privilege requirements are satisfied.
+ *
+ * This module is part of the pre-flight validation system. It queries:
+ *   - UID / EUID via `process.getuid()` / `process.geteuid()`
+ *   - Linux capabilities via `/proc/self/status` CapEff bitmask
+ *   - Passwordless sudo via `sudo -n true`
+ *   - Active sudo session via `SudoSession.getInstance().isElevated()`
+ *   - User groups via `id -Gn`
+ *
+ * Child process spawning goes through spawn-safe.ts which enforces the
+ * command allowlist and shell: false without creating circular dependencies.
+ *
+ * @module privilege-manager
+ */
+import type { ToolManifest } from "./tool-registry.js";
+export interface PrivilegeStatus {
+    /** Current real user ID */
+    uid: number;
+    /** Current effective user ID */
+    euid: number;
+    /** Whether running as root (euid === 0) */
+    isRoot: boolean;
+    /** Whether `sudo` binary is available on PATH */
+    sudoAvailable: boolean;
+    /** Whether passwordless sudo works (`sudo -n true`) */
+    passwordlessSudo: boolean;
+    /** Whether SudoSession has cached credentials */
+    sudoSessionActive: boolean;
+    /** Currently held Linux capabilities (from CapEff) */
+    capabilities: Set<string>;
+    /** User's group memberships */
+    groups: string[];
+}
+export interface PrivilegeCheckResult {
+    /** All privilege requirements met */
+    satisfied: boolean;
+    /** Problems found */
+    issues: PrivilegeIssue[];
+    /** How to fix any issues */
+    recommendations: string[];
+}
+export interface PrivilegeIssue {
+    type: "sudo-required" | "capability-missing" | "sudo-unavailable" | "session-expired";
+    /** Human-readable description of the issue */
+    description: string;
+    /** Which tool/operation needs this privilege */
+    operation: string;
+    /** How to resolve the issue */
+    resolution: string;
+}
+export declare class PrivilegeManager {
+    private cachedStatus;
+    private cacheExpiry;
+    private static readonly CACHE_TTL;
+    private static _instance;
+    private constructor();
+    /** Get or create the singleton instance. */
+    static instance(): PrivilegeManager;
+    /**
+     * Detect current privilege level.
+     * Results are cached for {@link CACHE_TTL} ms to avoid repeated
+     * subprocess spawns on rapid sequential tool calls.
+     */
+    getStatus(): Promise<PrivilegeStatus>;
+    /**
+     * Check whether a specific tool's privilege requirements are met.
+     *
+     * Evaluates the tool's `sudo` level and `capabilities` list against
+     * the current {@link PrivilegeStatus} and returns actionable issues.
+     */
+    checkForTool(manifest: ToolManifest): Promise<PrivilegeCheckResult>;
+    /**
+     * Check if a specific Linux capability is in the current effective set.
+     */
+    hasCapability(cap: string): Promise<boolean>;
+    /**
+     * Parse the effective capability set from `/proc/self/status`.
+     *
+     * Reads the `CapEff` line which contains a hex-encoded bitmask,
+     * then maps set bits to capability names using the kernel-defined
+     * bit positions.
+     */
+    getCurrentCapabilities(): Promise<Set<string>>;
+    /**
+     * Test whether passwordless sudo works by running `sudo -n true`.
+     * The `-n` (non-interactive) flag causes sudo to fail immediately
+     * rather than prompting if a password is required.
+     */
+    testPasswordlessSudo(): Promise<boolean>;
+    /**
+     * Check whether the `sudo` binary exists on PATH.
+     */
+    isSudoAvailable(): Promise<boolean>;
+    /**
+     * Invalidate the cached status.
+     * Should be called after events that change privilege state,
+     * e.g., after `sudo_elevate` or `sudo_drop`.
+     */
+    clearCache(): void;
+    /**
+     * Get user group memberships via `id -Gn`.
+     * Returns an empty array on failure.
+     */
+    private getGroups;
+}
+//# sourceMappingURL=privilege-manager.d.ts.map

package/build/core/privilege-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privilege-manager.d.ts","sourceRoot":"","sources":["../../src/core/privilege-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAoEvD,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,aAAa,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sDAAsD;IACtD,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,4BAA4B;IAC5B,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EACA,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,iBAAiB,CAAC;IACtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;CACpB;AA+ED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAU;IAE3C,OAAO,CAAC,MAAM,CAAC,SAAS,CAAiC;IAEzD,OAAO;IAIP,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,IAAI,gBAAgB;IASnC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAoC3C;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkGzE;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlD;;;;;;OAMG;IACG,sBAAsB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAkCpD;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAM9C;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAKzC;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAOlB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAUlB"}

package/build/core/privilege-manager.js

@@ -0,0 +1,363 @@
+/**
+ * PrivilegeManager — detects the current privilege level and checks whether
+ * a tool's privilege requirements are satisfied.
+ *
+ * This module is part of the pre-flight validation system. It queries:
+ *   - UID / EUID via `process.getuid()` / `process.geteuid()`
+ *   - Linux capabilities via `/proc/self/status` CapEff bitmask
+ *   - Passwordless sudo via `sudo -n true`
+ *   - Active sudo session via `SudoSession.getInstance().isElevated()`
+ *   - User groups via `id -Gn`
+ *
+ * Child process spawning goes through spawn-safe.ts which enforces the
+ * command allowlist and shell: false without creating circular dependencies.
+ *
+ * @module privilege-manager
+ */
+import { readFileSync, existsSync, lstatSync } from "node:fs";
+import { execFileSafe } from "./spawn-safe.js";
+import { SudoSession } from "./sudo-session.js";
+// ── Askpass helper detection (mirrors executor.ts) ───────────────────────────
+const ASKPASS_CANDIDATES = [
+    "/usr/bin/ssh-askpass",
+    "/usr/bin/ksshaskpass",
+    "/usr/lib/ssh/x11-ssh-askpass",
+    "/usr/libexec/openssh/gnome-ssh-askpass",
+    "/usr/bin/lxqt-sudo",
+];
+let cachedAskpassAvailable = null;
+/**
+ * Check whether a graphical askpass helper is available on the system.
+ * When available, `sudo -A` can pop a secure GUI dialog for the password,
+ * so tools should NOT be blocked at pre-flight for missing sudo sessions.
+ */
+/**
+ * SECURITY (CORE-016): Validate an askpass candidate's ownership and permissions.
+ * This is a local implementation to avoid circular dependency with sudo-guard.ts.
+ * Mirrors SudoGuard.validateAskpassPath() logic.
+ */
+function isAskpassCandidateValid(candidatePath) {
+    try {
+        const lstats = lstatSync(candidatePath);
+        if (lstats.isSymbolicLink() || !lstats.isFile())
+            return false;
+        const currentUid = process.getuid?.() ?? -1;
+        if (lstats.uid !== 0 && lstats.uid !== currentUid)
+            return false;
+        const perms = lstats.mode & 0o777;
+        if ((perms & 0o077) !== 0)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isAskpassAvailable() {
+    if (cachedAskpassAvailable !== null)
+        return cachedAskpassAvailable;
+    const hasDisplay = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+    if (!hasDisplay) {
+        cachedAskpassAvailable = false;
+        return false;
+    }
+    // SECURITY (CORE-016): Validate env-specified askpass helper
+    const envAskpass = process.env.SUDO_ASKPASS;
+    if (envAskpass && existsSync(envAskpass) && isAskpassCandidateValid(envAskpass)) {
+        cachedAskpassAvailable = true;
+        return true;
+    }
+    // SECURITY (CORE-016): Validate each candidate before accepting
+    for (const candidate of ASKPASS_CANDIDATES) {
+        if (existsSync(candidate) && isAskpassCandidateValid(candidate)) {
+            cachedAskpassAvailable = true;
+            return true;
+        }
+    }
+    cachedAskpassAvailable = false;
+    return false;
+}
+// ── Linux Capability Bit → Name Mapping ──────────────────────────────────────
+/**
+ * Maps bit position to Linux capability name.
+ * Derived from the kernel's `include/uapi/linux/capability.h`.
+ */
+const CAPABILITY_NAMES = [
+    "CAP_CHOWN", // 0
+    "CAP_DAC_OVERRIDE", // 1
+    "CAP_DAC_READ_SEARCH", // 2
+    "CAP_FOWNER", // 3
+    "CAP_FSETID", // 4
+    "CAP_KILL", // 5
+    "CAP_SETGID", // 6
+    "CAP_SETUID", // 7
+    "CAP_SETPCAP", // 8
+    "CAP_LINUX_IMMUTABLE", // 9
+    "CAP_NET_BIND_SERVICE", // 10
+    "CAP_NET_BROADCAST", // 11
+    "CAP_NET_ADMIN", // 12
+    "CAP_NET_RAW", // 13
+    "CAP_IPC_LOCK", // 14
+    "CAP_IPC_OWNER", // 15
+    "CAP_SYS_MODULE", // 16
+    "CAP_SYS_RAWIO", // 17
+    "CAP_SYS_CHROOT", // 18
+    "CAP_SYS_PTRACE", // 19
+    "CAP_SYS_PACCT", // 20
+    "CAP_SYS_ADMIN", // 21
+    "CAP_SYS_BOOT", // 22
+    "CAP_SYS_NICE", // 23
+    "CAP_SYS_RESOURCE", // 24
+    "CAP_SYS_TIME", // 25
+    "CAP_SYS_TTY_CONFIG", // 26
+    "CAP_MKNOD", // 27
+    "CAP_LEASE", // 28
+    "CAP_AUDIT_WRITE", // 29
+    "CAP_AUDIT_CONTROL", // 30
+    "CAP_SETFCAP", // 31
+    "CAP_MAC_OVERRIDE", // 32
+    "CAP_MAC_ADMIN", // 33
+    "CAP_SYSLOG", // 34
+    "CAP_WAKE_ALARM", // 35
+    "CAP_BLOCK_SUSPEND", // 36
+    "CAP_AUDIT_READ", // 37
+    "CAP_PERFMON", // 38
+    "CAP_BPF", // 39
+    "CAP_CHECKPOINT_RESTORE", // 40
+];
+// ── Helper: safe execFileSync wrapper ────────────────────────────────────────
+/**
+ * Run a command synchronously with a timeout, returning stdout on success
+ * or `null` on any failure. Never throws.
+ *
+ * Uses execFileSafe which handles allowlist resolution and shell: false.
+ */
+function execSafe(file, args, timeoutMs = 5_000) {
+    try {
+        const result = execFileSafe(file, args, {
+            encoding: "utf-8",
+            timeout: timeoutMs,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+// ── PrivilegeManager ─────────────────────────────────────────────────────────
+export class PrivilegeManager {
+    cachedStatus = null;
+    cacheExpiry = 0;
+    static CACHE_TTL = 30_000; // 30 seconds
+    static _instance = null;
+    constructor() {
+        // Singleton — use PrivilegeManager.instance()
+    }
+    /** Get or create the singleton instance. */
+    static instance() {
+        if (!PrivilegeManager._instance) {
+            PrivilegeManager._instance = new PrivilegeManager();
+        }
+        return PrivilegeManager._instance;
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /**
+     * Detect current privilege level.
+     * Results are cached for {@link CACHE_TTL} ms to avoid repeated
+     * subprocess spawns on rapid sequential tool calls.
+     */
+    async getStatus() {
+        const now = Date.now();
+        if (this.cachedStatus && now < this.cacheExpiry) {
+            return this.cachedStatus;
+        }
+        const uid = typeof process.getuid === "function" ? process.getuid() : -1;
+        const euid = typeof process.geteuid === "function" ? process.geteuid() : -1;
+        const isRoot = euid === 0;
+        const groups = this.getGroups();
+        const sudoAvailable = await this.isSudoAvailable();
+        const passwordlessSudo = sudoAvailable
+            ? await this.testPasswordlessSudo()
+            : false;
+        const sudoSessionActive = SudoSession.getInstance().isElevated();
+        const capabilities = await this.getCurrentCapabilities();
+        const status = {
+            uid,
+            euid,
+            isRoot,
+            sudoAvailable,
+            passwordlessSudo,
+            sudoSessionActive,
+            capabilities,
+            groups,
+        };
+        this.cachedStatus = status;
+        this.cacheExpiry = now + PrivilegeManager.CACHE_TTL;
+        return status;
+    }
+    /**
+     * Check whether a specific tool's privilege requirements are met.
+     *
+     * Evaluates the tool's `sudo` level and `capabilities` list against
+     * the current {@link PrivilegeStatus} and returns actionable issues.
+     */
+    async checkForTool(manifest) {
+        const issues = [];
+        const recommendations = [];
+        // ── sudo: 'never' → always satisfied ───────────────────────────────
+        if (manifest.sudo === "never") {
+            return { satisfied: true, issues, recommendations };
+        }
+        const status = await this.getStatus();
+        // ── sudo: 'always' → must have root, session, passwordless sudo, or askpass ─
+        if (manifest.sudo === "always") {
+            const hasAskpass = isAskpassAvailable();
+            if (!status.isRoot && !status.sudoSessionActive && !status.passwordlessSudo && !hasAskpass) {
+                if (!status.sudoAvailable) {
+                    issues.push({
+                        type: "sudo-unavailable",
+                        description: `Tool '${manifest.toolName}' requires elevated privileges but ` +
+                            `the 'sudo' binary is not available on this system.`,
+                        operation: manifest.toolName,
+                        resolution: "Install sudo (e.g., 'apt install sudo') or run the server as root.",
+                    });
+                    recommendations.push("Install the 'sudo' package or run the MCP server as root.");
+                }
+                else {
+                    const reason = manifest.sudoReason
+                        ? ` to ${manifest.sudoReason.charAt(0).toLowerCase()}${manifest.sudoReason.slice(1)}`
+                        : "";
+                    issues.push({
+                        type: "sudo-required",
+                        description: `Tool '${manifest.toolName}' requires elevated privileges${reason}. ` +
+                            `No active sudo session or passwordless sudo detected.`,
+                        operation: manifest.toolName,
+                        resolution: "Call the 'sudo_elevate' tool first to provide your credentials for this session.",
+                    });
+                    recommendations.push(`Run the 'sudo_elevate' tool to provide credentials before using '${manifest.toolName}'.`);
+                }
+            }
+        }
+        // ── sudo: 'conditional' → don't block, but advise ──────────────────
+        if (manifest.sudo === "conditional") {
+            if (!status.isRoot &&
+                !status.sudoSessionActive &&
+                !status.passwordlessSudo &&
+                status.sudoAvailable) {
+                recommendations.push(`Tool '${manifest.toolName}' may show limited results without elevated privileges. ` +
+                    `Consider running 'sudo_elevate' first for complete output.`);
+            }
+        }
+        // ── Capability checks ──────────────────────────────────────────────
+        if (manifest.capabilities && manifest.capabilities.length > 0) {
+            for (const requiredCap of manifest.capabilities) {
+                const hasCap = status.capabilities.has(requiredCap);
+                // If running as root, have an active sudo session, passwordless sudo,
+                // or an askpass helper, capabilities will be available when the command
+                // runs under sudo, so don't flag.
+                const hasAskpassForCaps = isAskpassAvailable();
+                if (!hasCap && !status.isRoot && !status.sudoSessionActive && !status.passwordlessSudo && !hasAskpassForCaps) {
+                    issues.push({
+                        type: "capability-missing",
+                        description: `Tool '${manifest.toolName}' requires Linux capability '${requiredCap}' ` +
+                            `which is not in the current effective capability set.`,
+                        operation: manifest.toolName,
+                        resolution: `Either run 'sudo_elevate' to gain full privileges, or grant '${requiredCap}' ` +
+                            `to the Node.js binary with: sudo setcap '${requiredCap.toLowerCase()}+ep' $(which node)`,
+                    });
+                    recommendations.push(`Capability '${requiredCap}' is required for '${manifest.toolName}'. ` +
+                        `Use 'sudo_elevate' or grant the capability directly to the node binary.`);
+                }
+            }
+        }
+        return {
+            satisfied: issues.length === 0,
+            issues,
+            recommendations,
+        };
+    }
+    /**
+     * Check if a specific Linux capability is in the current effective set.
+     */
+    async hasCapability(cap) {
+        const caps = await this.getCurrentCapabilities();
+        return caps.has(cap);
+    }
+    /**
+     * Parse the effective capability set from `/proc/self/status`.
+     *
+     * Reads the `CapEff` line which contains a hex-encoded bitmask,
+     * then maps set bits to capability names using the kernel-defined
+     * bit positions.
+     */
+    async getCurrentCapabilities() {
+        const caps = new Set();
+        try {
+            const statusContent = readFileSync("/proc/self/status", "utf-8");
+            const capEffLine = statusContent
+                .split("\n")
+                .find((line) => line.startsWith("CapEff:"));
+            if (!capEffLine) {
+                return caps;
+            }
+            const hexStr = capEffLine.split(":")[1]?.trim();
+            if (!hexStr) {
+                return caps;
+            }
+            // Parse the hex string as a BigInt to handle the full 64-bit bitmask
+            const bitmask = BigInt("0x" + hexStr);
+            for (let bit = 0; bit < CAPABILITY_NAMES.length; bit++) {
+                if (bitmask & (1n << BigInt(bit))) {
+                    caps.add(CAPABILITY_NAMES[bit]);
+                }
+            }
+        }
+        catch {
+            // /proc/self/status may not exist on non-Linux systems;
+            // return empty set rather than crashing.
+        }
+        return caps;
+    }
+    /**
+     * Test whether passwordless sudo works by running `sudo -n true`.
+     * The `-n` (non-interactive) flag causes sudo to fail immediately
+     * rather than prompting if a password is required.
+     */
+    async testPasswordlessSudo() {
+        const result = execSafe("sudo", ["-n", "true"], 5_000);
+        // execFileSync throws on non-zero exit, so if result is non-null it succeeded
+        return result !== null;
+    }
+    /**
+     * Check whether the `sudo` binary exists on PATH.
+     */
+    async isSudoAvailable() {
+        const result = execSafe("which", ["sudo"], 3_000);
+        return result !== null && result.trim().length > 0;
+    }
+    /**
+     * Invalidate the cached status.
+     * Should be called after events that change privilege state,
+     * e.g., after `sudo_elevate` or `sudo_drop`.
+     */
+    clearCache() {
+        this.cachedStatus = null;
+        this.cacheExpiry = 0;
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    /**
+     * Get user group memberships via `id -Gn`.
+     * Returns an empty array on failure.
+     */
+    getGroups() {
+        const output = execSafe("id", ["-Gn"], 3_000);
+        if (!output) {
+            return [];
+        }
+        return output
+            .trim()
+            .split(/\s+/)
+            .filter((g) => g.length > 0);
+    }
+}

package/build/core/rate-limiter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * rate-limiter.ts — Token-bucket rate limiter for MCP tool invocations.
+ *
+ * Provides per-tool and global rate limiting to prevent abuse and resource
+ * exhaustion. Limits are configurable via environment variables.
+ *
+ * @module rate-limiter
+ * @see CICD-024
+ */
+/** Result of a rate limit check. */
+export interface RateLimitResult {
+    /** Whether the invocation is allowed */
+    allowed: boolean;
+    /** If rejected, the reason message */
+    reason?: string;
+    /** Remaining invocations in the current window (per-tool) */
+    remainingPerTool: number;
+    /** Remaining invocations in the current window (global) */
+    remainingGlobal: number;
+}
+/**
+ * Simple sliding-window rate limiter for tool invocations.
+ *
+ * Tracks invocations per tool and globally using timestamp arrays.
+ * Old entries outside the time window are pruned on each check.
+ *
+ * Configuration via environment variables:
+ * - `KALI_DEFENSE_RATE_LIMIT_PER_TOOL` — Max invocations per tool per window (default: 30)
+ * - `KALI_DEFENSE_RATE_LIMIT_GLOBAL`   — Max total invocations per window (default: 100)
+ * - `KALI_DEFENSE_RATE_LIMIT_WINDOW`   — Window size in seconds (default: 60)
+ *
+ * Set any limit to `0` to disable that particular limit.
+ */
+export declare class RateLimiter {
+    /** Per-tool invocation buckets */
+    private toolBuckets;
+    /** Global invocation bucket */
+    private globalBucket;
+    /** Max invocations per tool per window */
+    readonly maxPerTool: number;
+    /** Max total invocations per window */
+    readonly maxGlobal: number;
+    /** Window size in milliseconds */
+    readonly windowMs: number;
+    private static _instance;
+    constructor(maxPerTool?: number, maxGlobal?: number, windowMs?: number);
+    /** Get or create the singleton instance. */
+    static instance(): RateLimiter;
+    /** Reset the singleton (for testing). */
+    static resetInstance(): void;
+    /**
+     * Check whether an invocation of `toolName` is allowed, and if so,
+     * record it. Returns a {@link RateLimitResult} indicating whether the
+     * call is permitted.
+     *
+     * @param toolName - The MCP tool name being invoked
+     * @returns Rate limit check result
+     */
+    check(toolName: string): RateLimitResult;
+    /** Clear all rate limit state (for testing). */
+    reset(): void;
+    private getToolBucket;
+    private pruneGlobal;
+    private pruneTool;
+    private parseEnvInt;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/build/core/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/core/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,kCAAkC;IAClC,OAAO,CAAC,WAAW,CAAkC;IACrD,+BAA+B;IAC/B,OAAO,CAAC,YAAY,CAA8B;IAElD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;gBAExC,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAMtE,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,IAAI,WAAW;IAO9B,yCAAyC;IACzC,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IA8CxC,gDAAgD;IAChD,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,WAAW;CAMpB"}

package/build/core/rate-limiter.js

@@ -0,0 +1,129 @@
+/**
+ * rate-limiter.ts — Token-bucket rate limiter for MCP tool invocations.
+ *
+ * Provides per-tool and global rate limiting to prevent abuse and resource
+ * exhaustion. Limits are configurable via environment variables.
+ *
+ * @module rate-limiter
+ * @see CICD-024
+ */
+// ── Rate Limiter Class ───────────────────────────────────────────────────────
+/**
+ * Simple sliding-window rate limiter for tool invocations.
+ *
+ * Tracks invocations per tool and globally using timestamp arrays.
+ * Old entries outside the time window are pruned on each check.
+ *
+ * Configuration via environment variables:
+ * - `KALI_DEFENSE_RATE_LIMIT_PER_TOOL` — Max invocations per tool per window (default: 30)
+ * - `KALI_DEFENSE_RATE_LIMIT_GLOBAL`   — Max total invocations per window (default: 100)
+ * - `KALI_DEFENSE_RATE_LIMIT_WINDOW`   — Window size in seconds (default: 60)
+ *
+ * Set any limit to `0` to disable that particular limit.
+ */
+export class RateLimiter {
+    /** Per-tool invocation buckets */
+    toolBuckets = new Map();
+    /** Global invocation bucket */
+    globalBucket = { timestamps: [] };
+    /** Max invocations per tool per window */
+    maxPerTool;
+    /** Max total invocations per window */
+    maxGlobal;
+    /** Window size in milliseconds */
+    windowMs;
+    static _instance = null;
+    constructor(maxPerTool, maxGlobal, windowMs) {
+        this.maxPerTool = maxPerTool ?? this.parseEnvInt("KALI_DEFENSE_RATE_LIMIT_PER_TOOL", 30);
+        this.maxGlobal = maxGlobal ?? this.parseEnvInt("KALI_DEFENSE_RATE_LIMIT_GLOBAL", 100);
+        this.windowMs = (windowMs ?? this.parseEnvInt("KALI_DEFENSE_RATE_LIMIT_WINDOW", 60)) * 1000;
+    }
+    /** Get or create the singleton instance. */
+    static instance() {
+        if (!RateLimiter._instance) {
+            RateLimiter._instance = new RateLimiter();
+        }
+        return RateLimiter._instance;
+    }
+    /** Reset the singleton (for testing). */
+    static resetInstance() {
+        RateLimiter._instance = null;
+    }
+    /**
+     * Check whether an invocation of `toolName` is allowed, and if so,
+     * record it. Returns a {@link RateLimitResult} indicating whether the
+     * call is permitted.
+     *
+     * @param toolName - The MCP tool name being invoked
+     * @returns Rate limit check result
+     */
+    check(toolName) {
+        const now = Date.now();
+        // Prune expired entries
+        this.pruneGlobal(now);
+        this.pruneTool(toolName, now);
+        const toolBucket = this.getToolBucket(toolName);
+        const globalCount = this.globalBucket.timestamps.length;
+        const toolCount = toolBucket.timestamps.length;
+        // Check global limit (0 = disabled)
+        if (this.maxGlobal > 0 && globalCount >= this.maxGlobal) {
+            return {
+                allowed: false,
+                reason: `Global rate limit exceeded: ${globalCount}/${this.maxGlobal} invocations ` +
+                    `in the last ${this.windowMs / 1000}s. Please wait before retrying.`,
+                remainingPerTool: Math.max(0, this.maxPerTool - toolCount),
+                remainingGlobal: 0,
+            };
+        }
+        // Check per-tool limit (0 = disabled)
+        if (this.maxPerTool > 0 && toolCount >= this.maxPerTool) {
+            return {
+                allowed: false,
+                reason: `Per-tool rate limit exceeded for '${toolName}': ${toolCount}/${this.maxPerTool} ` +
+                    `invocations in the last ${this.windowMs / 1000}s. Please wait before retrying.`,
+                remainingPerTool: 0,
+                remainingGlobal: Math.max(0, this.maxGlobal - globalCount),
+            };
+        }
+        // Allowed — record the invocation
+        toolBucket.timestamps.push(now);
+        this.globalBucket.timestamps.push(now);
+        return {
+            allowed: true,
+            remainingPerTool: this.maxPerTool > 0 ? this.maxPerTool - toolCount - 1 : Infinity,
+            remainingGlobal: this.maxGlobal > 0 ? this.maxGlobal - globalCount - 1 : Infinity,
+        };
+    }
+    /** Clear all rate limit state (for testing). */
+    reset() {
+        this.toolBuckets.clear();
+        this.globalBucket = { timestamps: [] };
+    }
+    // ── Internal helpers ─────────────────────────────────────────────────────
+    getToolBucket(toolName) {
+        let bucket = this.toolBuckets.get(toolName);
+        if (!bucket) {
+            bucket = { timestamps: [] };
+            this.toolBuckets.set(toolName, bucket);
+        }
+        return bucket;
+    }
+    pruneGlobal(now) {
+        const cutoff = now - this.windowMs;
+        this.globalBucket.timestamps = this.globalBucket.timestamps.filter((t) => t > cutoff);
+    }
+    pruneTool(toolName, now) {
+        const bucket = this.toolBuckets.get(toolName);
+        if (bucket) {
+            const cutoff = now - this.windowMs;
+            bucket.timestamps = bucket.timestamps.filter((t) => t > cutoff);
+        }
+    }
+    parseEnvInt(envVar, defaultValue) {
+        const raw = process.env[envVar];
+        if (raw === undefined)
+            return defaultValue;
+        const parsed = parseInt(raw, 10);
+        return isNaN(parsed) || parsed < 0 ? defaultValue : parsed;
+    }
+}