defense-mcp-server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [0.7.0] — 2026-03-12
+
+### v0.7.0 — Tool Consolidation & Sudo Hardening Overhaul
+
+#### Tool Consolidation (94 → 31 tools, −67%, zero capability loss)
+- Merged all 94 granular MCP tools into 31 domain-grouped tools using action discriminators
+- Every previous capability preserved via `action` parameters within each consolidated tool
+- Reduces MCP registration overhead by 67% while maintaining full security coverage
+- All 1,802 tests passing across 62 test files
+
+#### Sudo Hardening
+- **Removed `NOPASSWD: ALL`** sudoers grant — eliminated overly-broad privilege escalation
+- **Scoped allowlist** (`etc/sudoers.d/mcpuser`): 94-command explicit allowlist covering only required security binaries (iptables, ufw, aide, rkhunter, clamav, auditd, etc.)
+- **NOPASSWD regression detection**: `SudoGuard.checkNopasswdConfiguration()` runs at server startup to detect any re-introduction of broad sudo grants
+- **Rate limiting** on sudo elevation: `RateLimiter` wired into `SudoSession.elevate()` (5 attempts per 5-minute window)
+- **Structured audit trail**: `logger.security()` emits JSON audit events for all elevation, drop, extension, and timeout events
+
+#### Docker Entrypoint
+- New `docker-entrypoint.sh`: sets `mcpuser` password from Docker secret (`/run/secrets/mcpuser_password`) or `MCPUSER_PASSWORD` env var at container startup
+- Credentials zeroed from environment after use, privileges dropped before handing off to the MCP server process
+- Prevents hardcoded or empty passwords in container images
+
+#### New Modules
+- `src/tools/integrity.ts` — Absorbs and supersedes `ids.ts` + `drift-detection.ts`; unified integrity checking with IDS baseline management, drift detection, and file integrity verification
+- `etc/sudoers.d/mcpuser` — Scoped sudoers allowlist (94 commands, no wildcards)
+- `docker-entrypoint.sh` — Secure container password bootstrap script
+
+#### Infrastructure
+- `src/core/sudo-session.ts` — Integrated `RateLimiter` for elevation throttling
+- `src/core/sudo-guard.ts` — Added `checkNopasswdConfiguration()` startup regression check
+- `src/core/rate-limiter.ts` — Extended to support sudo-specific rate limiting context
+- Updated `TOOLS-REFERENCE.md` and `TOOL-CONSOLIDATION-PLAN.md` to reflect 31-tool architecture
+
+---
+
 ## [0.6.0] — 2026-03-09
 
 ### v0.6.0 — 16 New Security Tools

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

@@ -48,6 +48,40 @@ export declare class RateLimiter {
     static instance(): RateLimiter;
     /** Reset the singleton (for testing). */
     static resetInstance(): void;
+    /**
+     * Inspect current rate limit state for `key` WITHOUT recording an invocation.
+     *
+     * Use this to check whether a call would be allowed before deciding to
+     * proceed. Unlike `check()`, this does NOT consume an attempt slot.
+     *
+     * @param key - Identifier to inspect (e.g., a tool name or auth key)
+     * @returns Current limit state: allowed, remaining attempts, and optional
+     *          retryAfterMs (ms until the oldest timestamp expires and a slot opens)
+     */
+    peek(key: string): {
+        allowed: boolean;
+        remaining: number;
+        retryAfterMs?: number;
+    };
+    /**
+     * Record a failure for `key` without performing a limit check.
+     *
+     * Use this to register a failed attempt (e.g., wrong password) after the
+     * fact. Unlike `check()`, this does NOT gate on the current limit state —
+     * it unconditionally adds a timestamp to the bucket.
+     *
+     * @param key - Identifier to record against
+     */
+    record(key: string): void;
+    /**
+     * Reset the rate limit counter for a specific `key`.
+     *
+     * Use after a confirmed successful authentication to clear the failed-attempt
+     * counter so a subsequent failure starts from zero.
+     *
+     * @param key - Identifier whose bucket should be cleared
+     */
+    resetKey(key: string): void;
     /**
      * Check whether an invocation of `toolName` is allowed, and if so,
      * record it. Returns a {@link RateLimitResult} indicating whether the

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

@@ -1 +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"}
+{"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;;;;;;;;;OASG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAkBjF;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI3B;;;;;;;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

@@ -49,6 +49,56 @@ export class RateLimiter {
     static resetInstance() {
         RateLimiter._instance = null;
     }
+    /**
+     * Inspect current rate limit state for `key` WITHOUT recording an invocation.
+     *
+     * Use this to check whether a call would be allowed before deciding to
+     * proceed. Unlike `check()`, this does NOT consume an attempt slot.
+     *
+     * @param key - Identifier to inspect (e.g., a tool name or auth key)
+     * @returns Current limit state: allowed, remaining attempts, and optional
+     *          retryAfterMs (ms until the oldest timestamp expires and a slot opens)
+     */
+    peek(key) {
+        const now = Date.now();
+        this.pruneTool(key, now);
+        const bucket = this.getToolBucket(key);
+        const count = bucket.timestamps.length;
+        if (this.maxPerTool > 0 && count >= this.maxPerTool) {
+            const oldest = bucket.timestamps[0] ?? now;
+            const retryAfterMs = Math.max(0, oldest + this.windowMs - now);
+            return { allowed: false, remaining: 0, retryAfterMs };
+        }
+        return {
+            allowed: true,
+            remaining: this.maxPerTool > 0 ? this.maxPerTool - count : Infinity,
+        };
+    }
+    /**
+     * Record a failure for `key` without performing a limit check.
+     *
+     * Use this to register a failed attempt (e.g., wrong password) after the
+     * fact. Unlike `check()`, this does NOT gate on the current limit state —
+     * it unconditionally adds a timestamp to the bucket.
+     *
+     * @param key - Identifier to record against
+     */
+    record(key) {
+        const now = Date.now();
+        this.pruneTool(key, now);
+        this.getToolBucket(key).timestamps.push(now);
+    }
+    /**
+     * Reset the rate limit counter for a specific `key`.
+     *
+     * Use after a confirmed successful authentication to clear the failed-attempt
+     * counter so a subsequent failure starts from zero.
+     *
+     * @param key - Identifier whose bucket should be cleared
+     */
+    resetKey(key) {
+        this.toolBuckets.delete(key);
+    }
     /**
      * Check whether an invocation of `toolName` is allowed, and if so,
      * record it. Returns a {@link RateLimitResult} indicating whether the

package/build/core/sudo-guard.d.ts

@@ -65,6 +65,23 @@ export interface ElevationPromptResponse {
  * generation. All methods are stateless and can be called directly.
  */
 export declare class SudoGuard {
+    /**
+     * Check whether passwordless sudo (`NOPASSWD: ALL`) is still active.
+     *
+     * Reads `/etc/sudoers` and `/etc/sudoers.d/mcpuser` (non-root readable
+     * paths only) and searches for the `NOPASSWD:.*ALL` pattern. If found,
+     * logs a CRITICAL security warning — the credential validation in
+     * `SudoSession.elevate()` is hollow while this grant exists.
+     *
+     * This check is intended to be called during server startup so operators
+     * are alerted immediately if the Docker image was not rebuilt correctly.
+     *
+     * @returns `{ nopasswdDetected: boolean, location?: string }`
+     */
+    static checkNopasswdConfiguration(): {
+        nopasswdDetected: boolean;
+        location?: string;
+    };
     /**
      * Check whether command output (stderr and/or stdout) indicates a
      * permission/privilege failure.

package/build/core/sudo-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sudo-guard.d.ts","sourceRoot":"","sources":["../../src/core/sudo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAqFH;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE;QACL,qDAAqD;QACrD,iBAAiB,EAAE,IAAI,CAAC;QACxB;;;;WAIG;QACH,YAAY,EAAE,IAAI,CAAC;QACnB,2BAA2B;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,8BAA8B;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,qCAAqC;QACrC,aAAa,EAAE,cAAc,CAAC;KAC/B,CAAC;CACH;AAID;;;GAGG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAqBpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,qBAAqB,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,uBAAuB;IAqE1B;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,OAAO;IA4BV;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS;IAoBrB;;;OAGG;IACH,MAAM,CAAC,gBAAgB,IAAI,OAAO;IAIlC;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAU7D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAiDrF"}
+{"version":3,"file":"sudo-guard.d.ts","sourceRoot":"","sources":["../../src/core/sudo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsFH;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE;QACL,qDAAqD;QACrD,iBAAiB,EAAE,IAAI,CAAC;QACxB;;;;WAIG;QACH,YAAY,EAAE,IAAI,CAAC;QACnB,2BAA2B;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,8BAA8B;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,qCAAqC;QACrC,aAAa,EAAE,cAAc,CAAC;KAC/B,CAAC;CACH;AAID;;;GAGG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,0BAA0B,IAAI;QAAE,gBAAgB,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IA2CrF;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAqBpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,qBAAqB,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,uBAAuB;IAqE1B;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,OAAO;IA4BV;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS;IAoBrB;;;OAGG;IACH,MAAM,CAAC,gBAAgB,IAAI,OAAO;IAIlC;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAU7D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAiDrF"}

package/build/core/sudo-guard.js

@@ -34,7 +34,8 @@
  * @module sudo-guard
  */
 import { SudoSession } from "./sudo-session.js";
-import { lstatSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
+import { logger } from "./logger.js";
 // ── Permission Error Detection ───────────────────────────────────────────────
 /**
  * Patterns in stderr/stdout that indicate a permission/privilege failure.
@@ -108,6 +109,49 @@ const PERMISSION_EXIT_CODES = new Set([
  * generation. All methods are stateless and can be called directly.
  */
 export class SudoGuard {
+    /**
+     * Check whether passwordless sudo (`NOPASSWD: ALL`) is still active.
+     *
+     * Reads `/etc/sudoers` and `/etc/sudoers.d/mcpuser` (non-root readable
+     * paths only) and searches for the `NOPASSWD:.*ALL` pattern. If found,
+     * logs a CRITICAL security warning — the credential validation in
+     * `SudoSession.elevate()` is hollow while this grant exists.
+     *
+     * This check is intended to be called during server startup so operators
+     * are alerted immediately if the Docker image was not rebuilt correctly.
+     *
+     * @returns `{ nopasswdDetected: boolean, location?: string }`
+     */
+    static checkNopasswdConfiguration() {
+        const candidatePaths = [
+            "/etc/sudoers",
+            "/etc/sudoers.d/mcpuser",
+            "/etc/sudoers.d/",
+        ];
+        const nopasswdPattern = /NOPASSWD\s*:\s*ALL/i;
+        for (const filePath of candidatePaths) {
+            try {
+                const content = readFileSync(filePath, "utf-8");
+                if (nopasswdPattern.test(content)) {
+                    logger.security("sudo-guard", "nopasswd_detected", "SECURITY CRITICAL: NOPASSWD:ALL detected in sudoers configuration. " +
+                        "Authentication via sudo_elevate is NON-FUNCTIONAL — any password will be accepted. " +
+                        "Remove NOPASSWD from the sudoers file and set a real password for mcpuser. " +
+                        "See docs/SUDO-SESSION-DESIGN.md for remediation steps.", {
+                        severity: "CRITICAL",
+                        location: filePath,
+                        remediation: "Rebuild the Docker image with the updated Dockerfile that uses " +
+                            "etc/sudoers.d/mcpuser (scoped allowlist, no NOPASSWD).",
+                    });
+                    return { nopasswdDetected: true, location: filePath };
+                }
+            }
+            catch {
+                // File may not exist or may not be readable — that's fine
+            }
+        }
+        logger.info("sudo-guard", "nopasswd_check_passed", "Sudoers NOPASSWD:ALL check passed — passwordless sudo not detected");
+        return { nopasswdDetected: false };
+    }
     /**
      * Check whether command output (stderr and/or stdout) indicates a
      * permission/privilege failure.

package/build/core/sudo-session.d.ts

@@ -12,8 +12,11 @@
  *   - Auto-expires after a configurable timeout (default 15 minutes)
  *   - Explicit `drop()` zeroes the buffer immediately
  *   - Process exit handler zeroes the buffer on shutdown
- *   - Validates credentials before storing (test with `sudo -S -v`)
+ *   - Validates credentials before storing (test with `sudo -S -k -v`)
  *   - Never logs or exposes the password in any output
+ *   - Rate limits failed authentication attempts (5 per 5 minutes)
+ *   - Session UID guard: drops session if OS UID changes mid-session
+ *   - Emits structured audit events for all state transitions
  *
  * Child process spawning goes through spawn-safe.ts which enforces the
  * command allowlist and shell: false without creating circular dependencies.
@@ -23,6 +26,21 @@ export interface SudoSessionStatus {
     username: string | null;
     expiresAt: string | null;
     remainingSeconds: number | null;
+    /** Rate-limit info (safe to surface to MCP callers). */
+    rateLimit: {
+        limited: boolean;
+        attemptsRemaining: number;
+        resetAt?: string;
+    };
+}
+/** Structured result from {@link SudoSession.elevate}. */
+export interface ElevateResult {
+    success: boolean;
+    error?: string;
+    /** Present when the elevation was blocked by rate limiting. */
+    rateLimited?: boolean;
+    /** Present when rate-limited: ms until the lockout window resets. */
+    retryAfterMs?: number;
 }
 export declare class SudoSession {
     /** Password stored in a Buffer so we can zero it (not interned by V8). */
@@ -41,10 +59,18 @@ export declare class SudoSession {
     private sessionUserId;
     /** Timestamp (epoch ms) when the session expires. */
     private expiresAt;
+    /** Epoch ms when the current session was established (for drop duration calc). */
+    private elevatedAt;
     /** Handle for the auto-expiry timer. */
     private expiryTimer;
     /** Default session timeout in milliseconds (15 min). */
     private defaultTimeoutMs;
+    /**
+     * Per-session rate limiter for authentication attempts.
+     * Configured with a sliding 5-minute window and 5-attempt cap.
+     * Uses per-key tracking via `peek()` / `record()` / `resetKey()`.
+     */
+    private authRateLimiter;
     private constructor();
     /** Get the singleton instance. */
     static getInstance(): SudoSession;
@@ -67,16 +93,22 @@ export declare class SudoSession {
      * `-S` reads password from stdin.
      * `-p ""` suppresses the password prompt text.
      *
-     * @returns result indicating success or failure with error message.
+     * Phase 2: Checks the auth rate limiter before attempting. Records failures.
+     * Resets the counter on success.
+     *
+     * Phase 3: Emits structured audit events for all outcomes.
+     *
+     * @returns Structured result indicating success, failure, or rate-limit block.
      */
-    elevate(password: string | Buffer, timeoutMs?: number): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    elevate(password: string | Buffer, timeoutMs?: number): Promise<ElevateResult>;
     /**
      * Returns a **copy** of the password Buffer for piping to sudo -S,
      * or null if not elevated.
      *
+     * SECURITY (CICD-028): Validates that the calling process UID matches the
+     * UID that established the session. If the UID has changed (e.g., due to
+     * a UID-switching attack), the session is dropped and null is returned.
+     *
      * The caller MUST zero the returned Buffer with `.fill(0)` after use.
      * A copy is returned so the original can be zeroed independently via `drop()`.
      */
@@ -85,6 +117,15 @@ export declare class SudoSession {
     isElevated(): boolean;
     /** Get current session status (safe to expose via MCP). */
     getStatus(): SudoSessionStatus;
+    /**
+     * Get the current rate-limit status for the auth key.
+     * Safe to surface to MCP callers (contains no credentials).
+     */
+    getRateLimitStatus(): {
+        limited: boolean;
+        attemptsRemaining: number;
+        resetAt?: string;
+    };
     /**
      * Drop elevated privileges immediately.
      * Zeroes the password buffer and clears all session state.
@@ -94,6 +135,8 @@ export declare class SudoSession {
      * Extend the session timeout by the given milliseconds (or the default).
      */
     extend(extraMs?: number): boolean;
+    /** Called when the TTL timer fires. Emits audit event then drops. */
+    private _onSessionExpired;
     private storePassword;
     private isExpired;
 }

package/build/core/sudo-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sudo-session.d.ts","sourceRoot":"","sources":["../../src/core/sudo-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAsED,qBAAa,WAAW;IACtB,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAuB;IAE1C,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAuB;IAEvC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa,CAAuB;IAE5C,qDAAqD;IACrD,OAAO,CAAC,SAAS,CAAuB;IAExC,wCAAwC;IACxC,OAAO,CAAC,WAAW,CAA8C;IAEjE,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAkB;IAE1C,OAAO;IASP,kCAAkC;IAClC,MAAM,CAAC,WAAW,IAAI,WAAW;IAOjC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMnC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAuE3G;;;;;;OAMG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAc5B,wDAAwD;IACxD,UAAU,IAAI,OAAO;IAUrB,2DAA2D;IAC3D,SAAS,IAAI,iBAAiB;IAsB9B;;;OAGG;IACH,IAAI,IAAI,IAAI;IAwBZ;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAyBjC,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,SAAS;CAIlB"}
+{"version":3,"file":"sudo-session.d.ts","sourceRoot":"","sources":["../../src/core/sudo-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wDAAwD;IACxD,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuFD,qBAAa,WAAW;IACtB,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAuB;IAE1C,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAuB;IAEvC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa,CAAuB;IAE5C,qDAAqD;IACrD,OAAO,CAAC,SAAS,CAAuB;IAExC,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAuB;IAEzC,wCAAwC;IACxC,OAAO,CAAC,WAAW,CAA8C;IAEjE,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAkB;IAE1C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAc;IAErC,OAAO;IAiBP,kCAAkC;IAClC,MAAM,CAAC,WAAW,IAAI,WAAW;IAOjC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMnC;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA+JpF;;;;;;;;;;OAUG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IA2B5B,wDAAwD;IACxD,UAAU,IAAI,OAAO;IAUrB,2DAA2D;IAC3D,SAAS,IAAI,iBAAiB;IAmC9B;;;OAGG;IACH,kBAAkB,IAAI;QACpB,OAAO,EAAE,OAAO,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;IAWD;;;OAGG;IACH,IAAI,IAAI,IAAI;IAuCZ;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAiCjC,qEAAqE;IACrE,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,SAAS;CAIlB"}