defense-mcp-server 0.8.0 → 0.8.1

package/build/core/pam-utils.d.ts

@@ -230,4 +230,127 @@ export declare function backupPamFile(filePath: string): Promise<BackupEntry>;
  * @throws If backup file is missing, invalid, or restore fails
  */
 export declare function restorePamFile(backupEntry: BackupEntry): Promise<void>;
+/** A single finding from PAM policy sanity validation. */
+export interface PamSanityFinding {
+    /** warning = proceed with caution; critical = blocks operation unless forced */
+    severity: "warning" | "critical";
+    /** Which module the finding relates to */
+    module: "pam_faillock.so" | "pam_pwquality.so" | "general";
+    /** The specific parameter that triggered the finding, if applicable */
+    parameter?: string;
+    /** The problematic value */
+    value?: string | number;
+    /** Human-readable description of the problem */
+    message: string;
+    /** What the user should do instead */
+    recommendation: string;
+}
+/** Result of PAM policy sanity validation. */
+export interface PamSanityResult {
+    /** true if no critical findings exist */
+    safe: boolean;
+    /** All findings, ordered by severity then module */
+    findings: PamSanityFinding[];
+    /** Count of critical-severity findings */
+    criticalCount: number;
+    /** Count of warning-severity findings */
+    warningCount: number;
+}
+/**
+ * Thresholds for PAM policy sanity checks.
+ * These define what constitutes "sane" vs "dangerous" PAM policy values.
+ * Tuned to prevent lockouts while allowing reasonable security hardening.
+ */
+export declare const PAM_SANITY_THRESHOLDS: {
+    readonly faillock: {
+        /** deny below this triggers critical — too few attempts before lockout */
+        readonly minDeny: 3;
+        /** unlock_time above this triggers warning — extended lockout */
+        readonly maxUnlockTimeWarn: 1800;
+        /** unlock_time above this triggers critical — extreme lockout */
+        readonly maxUnlockTimeCritical: 86400;
+        /** fail_interval below this triggers warning — unusually short window */
+        readonly minFailInterval: 60;
+    };
+    readonly pwquality: {
+        /** minlen above this triggers warning — unusually long */
+        readonly maxMinlenWarn: 24;
+        /** minlen above this triggers critical — unreasonably long */
+        readonly maxMinlenCritical: 64;
+        /** retry below this triggers critical — no second chance */
+        readonly minRetry: 2;
+        /** Combined credit threshold: all credits at this or below with high minlen */
+        readonly restrictiveCreditThreshold: -2;
+    };
+};
+/**
+ * Validate faillock parameters for policy sanity.
+ *
+ * Checks for overly restrictive settings that could cause lockouts:
+ * - deny too low (typos cause lockout)
+ * - unlock_time too high or zero (extended/permanent lockout)
+ * - deny + unlock_time=0 combination (permanent lock on typos)
+ * - fail_interval too short
+ *
+ * @param params - Faillock parameters to validate
+ * @returns Array of sanity findings (empty = all sane)
+ */
+export declare function validateFaillockParams(params: {
+    deny?: number;
+    unlock_time?: number;
+    fail_interval?: number;
+}): PamSanityFinding[];
+/**
+ * Validate pwquality parameters for policy sanity.
+ *
+ * Checks for overly restrictive settings that prevent password creation:
+ * - minlen too high
+ * - retry too low (no second chance)
+ * - All character class requirements simultaneously very strict
+ *
+ * @param params - Pwquality parameters to validate
+ * @returns Array of sanity findings (empty = all sane)
+ */
+export declare function validatePwqualityParams(params: {
+    minlen?: number;
+    dcredit?: number;
+    ucredit?: number;
+    lcredit?: number;
+    ocredit?: number;
+    minclass?: number;
+    maxrepeat?: number;
+    retry?: number;
+}): PamSanityFinding[];
+/**
+ * Validate a PAM config structure for dangerous patterns.
+ *
+ * Checks the resulting PamLine[] after manipulation for patterns
+ * that would break authentication:
+ * - pam_deny.so as first auth rule (blocks all auth)
+ * - Missing pam_unix.so in auth stack
+ * - Incomplete faillock setup (preauth without authfail or vice versa)
+ * - Missing pam_permit.so in session stack
+ *
+ * @param lines - Parsed PAM config lines (after manipulation)
+ * @returns Array of sanity findings
+ */
+export declare function validatePamConfigSanity(lines: PamLine[]): PamSanityFinding[];
+/**
+ * Validate PAM policy sanity — combined parameter + config check.
+ *
+ * This is the main entry point for sanity validation. It runs:
+ * 1. Module-specific parameter checks (if module + params provided)
+ * 2. Config structure checks (if lines provided)
+ *
+ * @param options - What to validate
+ * @returns Combined sanity result with safe flag and all findings
+ */
+export declare function validatePamPolicySanity(options: {
+    /** Which PAM module is being configured */
+    module?: "faillock" | "pwquality";
+    /** Module parameters being applied */
+    params?: Record<string, unknown>;
+    /** Resulting PAM config lines (after manipulation) */
+    lines?: PamLine[];
+}): PamSanityResult;
 //# sourceMappingURL=pam-utils.d.ts.map

package/build/core/pam-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pam-utils.d.ts","sourceRoot":"","sources":["../../src/core/pam-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pam-utils.d.ts","sourceRoot":"","sources":["../../src/core/pam-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKtE,qDAAqD;AACrD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0BAA0B;AAC1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAInE,+CAA+C;AAC/C,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,MAAM,EAAE,MAAM,EAAE;aAChB,QAAQ,CAAC,EAAE,MAAM;gBADjB,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,MAAM,YAAA;CAOpC;AAED,uEAAuE;AACvE,qBAAa,aAAc,SAAQ,KAAK;aAGpB,QAAQ,EAAE,MAAM;aAChB,QAAQ,CAAC,EAAE,MAAM;gBAFjC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,YAAA;CAKpC;AA+BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CA2CzD;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAyB3D;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EAAE,GACf;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA0FtC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,GACd;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAGtC;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAWT;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EAAE,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,EAAE,CAIX;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EAAE,EAChB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,EAAE,CAgBX;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EAAE,EAChB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,EAAE,CAgBX;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EAAE,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,EAAE,CAKX;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CA2D5D;AAID;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC,CAyCtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAqDf;AAID,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;IACjC,0CAA0C;IAC1C,MAAM,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,SAAS,CAAC;IAC3D,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAID;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;QAE9B,0EAA0E;;QAE1E,iEAAiE;;QAEjE,iEAAiE;;QAEjE,yEAAyE;;;;QAIzE,0DAA0D;;QAE1D,8DAA8D;;QAE9D,4DAA4D;;QAE5D,+EAA+E;;;CAGzE,CAAC;AAIX;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,gBAAgB,EAAE,CAgErB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,gBAAgB,EAAE,CA2ErB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,gBAAgB,EAAE,CAoE5E;AAID;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,2CAA2C;IAC3C,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IAClC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB,GAAG,eAAe,CAmDlB"}

package/build/core/pam-utils.js

@@ -624,3 +624,312 @@ export async function restorePamFile(backupEntry) {
     }
     console.error(`[pam-utils] Restored ${backupEntry.backupPath} → ${backupEntry.originalPath}`);
 }
+// ── PAM Sanity Thresholds ───────────────────────────────────────────────────
+/**
+ * Thresholds for PAM policy sanity checks.
+ * These define what constitutes "sane" vs "dangerous" PAM policy values.
+ * Tuned to prevent lockouts while allowing reasonable security hardening.
+ */
+export const PAM_SANITY_THRESHOLDS = {
+    faillock: {
+        /** deny below this triggers critical — too few attempts before lockout */
+        minDeny: 3,
+        /** unlock_time above this triggers warning — extended lockout */
+        maxUnlockTimeWarn: 1800, // 30 minutes
+        /** unlock_time above this triggers critical — extreme lockout */
+        maxUnlockTimeCritical: 86400, // 24 hours
+        /** fail_interval below this triggers warning — unusually short window */
+        minFailInterval: 60, // 1 minute
+    },
+    pwquality: {
+        /** minlen above this triggers warning — unusually long */
+        maxMinlenWarn: 24,
+        /** minlen above this triggers critical — unreasonably long */
+        maxMinlenCritical: 64,
+        /** retry below this triggers critical — no second chance */
+        minRetry: 2,
+        /** Combined credit threshold: all credits at this or below with high minlen */
+        restrictiveCreditThreshold: -2,
+    },
+};
+// ── Faillock Parameter Validation ───────────────────────────────────────────
+/**
+ * Validate faillock parameters for policy sanity.
+ *
+ * Checks for overly restrictive settings that could cause lockouts:
+ * - deny too low (typos cause lockout)
+ * - unlock_time too high or zero (extended/permanent lockout)
+ * - deny + unlock_time=0 combination (permanent lock on typos)
+ * - fail_interval too short
+ *
+ * @param params - Faillock parameters to validate
+ * @returns Array of sanity findings (empty = all sane)
+ */
+export function validateFaillockParams(params) {
+    const findings = [];
+    const T = PAM_SANITY_THRESHOLDS.faillock;
+    // Check deny
+    if (params.deny !== undefined && params.deny < T.minDeny) {
+        findings.push({
+            severity: "critical",
+            module: "pam_faillock.so",
+            parameter: "deny",
+            value: params.deny,
+            message: params.deny === 1
+                ? `deny=${params.deny}: A single failed attempt locks the account — typos cause immediate lockout`
+                : `deny=${params.deny}: Only ${params.deny} attempts before lockout — insufficient margin for typos`,
+            recommendation: `Set deny >= ${T.minDeny} (CIS Benchmark recommends 3-5)`,
+        });
+    }
+    // Check unlock_time
+    if (params.unlock_time !== undefined) {
+        if (params.unlock_time === 0) {
+            findings.push({
+                severity: "critical",
+                module: "pam_faillock.so",
+                parameter: "unlock_time",
+                value: 0,
+                message: "unlock_time=0: Permanent lock until admin runs 'faillock --reset' — no automatic recovery",
+                recommendation: "Set unlock_time to a positive value (e.g., 900 for 15 minutes)",
+            });
+        }
+        else if (params.unlock_time > T.maxUnlockTimeCritical) {
+            findings.push({
+                severity: "critical",
+                module: "pam_faillock.so",
+                parameter: "unlock_time",
+                value: params.unlock_time,
+                message: `unlock_time=${params.unlock_time}: Lockout exceeds 24 hours — effectively permanent for most users`,
+                recommendation: `Set unlock_time <= ${T.maxUnlockTimeWarn} (30 minutes, per CIS Benchmark)`,
+            });
+        }
+        else if (params.unlock_time > T.maxUnlockTimeWarn) {
+            findings.push({
+                severity: "warning",
+                module: "pam_faillock.so",
+                parameter: "unlock_time",
+                value: params.unlock_time,
+                message: `unlock_time=${params.unlock_time}: Lockout exceeds 30 minutes — consider a shorter unlock time`,
+                recommendation: `Set unlock_time <= ${T.maxUnlockTimeWarn} (30 minutes, per CIS Benchmark)`,
+            });
+        }
+    }
+    // Check fail_interval
+    if (params.fail_interval !== undefined && params.fail_interval < T.minFailInterval) {
+        findings.push({
+            severity: "warning",
+            module: "pam_faillock.so",
+            parameter: "fail_interval",
+            value: params.fail_interval,
+            message: `fail_interval=${params.fail_interval}: Very short failure tracking window (< 60s)`,
+            recommendation: `Set fail_interval >= ${T.minFailInterval} (60 seconds or more)`,
+        });
+    }
+    return findings;
+}
+// ── Pwquality Parameter Validation ──────────────────────────────────────────
+/**
+ * Validate pwquality parameters for policy sanity.
+ *
+ * Checks for overly restrictive settings that prevent password creation:
+ * - minlen too high
+ * - retry too low (no second chance)
+ * - All character class requirements simultaneously very strict
+ *
+ * @param params - Pwquality parameters to validate
+ * @returns Array of sanity findings (empty = all sane)
+ */
+export function validatePwqualityParams(params) {
+    const findings = [];
+    const T = PAM_SANITY_THRESHOLDS.pwquality;
+    // Check minlen
+    if (params.minlen !== undefined) {
+        if (params.minlen > T.maxMinlenCritical) {
+            findings.push({
+                severity: "critical",
+                module: "pam_pwquality.so",
+                parameter: "minlen",
+                value: params.minlen,
+                message: `minlen=${params.minlen}: Minimum password length exceeds ${T.maxMinlenCritical} — users cannot create compliant passwords`,
+                recommendation: `Set minlen <= ${T.maxMinlenWarn} (NIST SP 800-63B recommends 8-64 characters)`,
+            });
+        }
+        else if (params.minlen > T.maxMinlenWarn) {
+            findings.push({
+                severity: "warning",
+                module: "pam_pwquality.so",
+                parameter: "minlen",
+                value: params.minlen,
+                message: `minlen=${params.minlen}: Minimum password length exceeds ${T.maxMinlenWarn} — may be difficult for users`,
+                recommendation: `Set minlen <= ${T.maxMinlenWarn} for usability (14-16 is a good balance)`,
+            });
+        }
+    }
+    // Check retry
+    if (params.retry !== undefined && params.retry < T.minRetry) {
+        findings.push({
+            severity: "critical",
+            module: "pam_pwquality.so",
+            parameter: "retry",
+            value: params.retry,
+            message: params.retry === 0
+                ? "retry=0: Zero retries — password rejected on first attempt with no recovery"
+                : `retry=${params.retry}: Only ${params.retry} retry — insufficient for correcting typos`,
+            recommendation: `Set retry >= ${T.minRetry}`,
+        });
+    }
+    // Check combined restrictive credit requirements with high minlen
+    const minlen = params.minlen ?? 0;
+    const credits = [params.dcredit, params.ucredit, params.lcredit, params.ocredit];
+    const definedCredits = credits.filter((c) => c !== undefined);
+    if (definedCredits.length === 4 && minlen > 16) {
+        const allVeryRestrictive = definedCredits.every((c) => c <= T.restrictiveCreditThreshold);
+        if (allVeryRestrictive) {
+            findings.push({
+                severity: "warning",
+                module: "pam_pwquality.so",
+                parameter: "dcredit+ucredit+lcredit+ocredit",
+                message: `All character classes require ${Math.abs(T.restrictiveCreditThreshold)}+ characters with minlen=${minlen} — very restrictive combined requirements`,
+                recommendation: "Relax either the character class requirements or the minimum length",
+            });
+        }
+    }
+    // Check minclass=4 with high minlen
+    if (params.minclass !== undefined && params.minclass >= 4 && minlen > 16) {
+        findings.push({
+            severity: "warning",
+            module: "pam_pwquality.so",
+            parameter: "minclass",
+            value: params.minclass,
+            message: `minclass=${params.minclass} with minlen=${minlen}: All ${params.minclass} character classes required with long minimum — very restrictive`,
+            recommendation: "Consider minclass=3 or reducing minlen when requiring all character classes",
+        });
+    }
+    return findings;
+}
+// ── PAM Config Structure Validation ─────────────────────────────────────────
+/**
+ * Validate a PAM config structure for dangerous patterns.
+ *
+ * Checks the resulting PamLine[] after manipulation for patterns
+ * that would break authentication:
+ * - pam_deny.so as first auth rule (blocks all auth)
+ * - Missing pam_unix.so in auth stack
+ * - Incomplete faillock setup (preauth without authfail or vice versa)
+ * - Missing pam_permit.so in session stack
+ *
+ * @param lines - Parsed PAM config lines (after manipulation)
+ * @returns Array of sanity findings
+ */
+export function validatePamConfigSanity(lines) {
+    const findings = [];
+    const authRules = lines.filter((l) => l.kind === "rule" && (l.pamType === "auth" || l.pamType === "-auth"));
+    const sessionRules = lines.filter((l) => l.kind === "rule" && (l.pamType === "session" || l.pamType === "-session"));
+    // Check: pam_deny.so as first auth rule
+    if (authRules.length > 0 && authRules[0].module === "pam_deny.so") {
+        findings.push({
+            severity: "critical",
+            module: "general",
+            message: "pam_deny.so is the first auth rule — this blocks ALL authentication",
+            recommendation: "Ensure pam_deny.so is not the first rule in the auth stack",
+        });
+    }
+    // Check: no pam_unix.so in auth stack
+    const hasUnixAuth = authRules.some((r) => r.module === "pam_unix.so");
+    if (authRules.length > 0 && !hasUnixAuth) {
+        findings.push({
+            severity: "critical",
+            module: "general",
+            message: "No pam_unix.so in auth stack — basic password authentication is broken",
+            recommendation: "Ensure pam_unix.so is present in the auth stack",
+        });
+    }
+    // Check: incomplete faillock setup
+    const faillockRules = authRules.filter((r) => r.module === "pam_faillock.so");
+    if (faillockRules.length > 0) {
+        const hasPreauth = faillockRules.some((r) => r.args.includes("preauth"));
+        const hasAuthfail = faillockRules.some((r) => r.args.includes("authfail"));
+        if (hasPreauth && !hasAuthfail) {
+            findings.push({
+                severity: "warning",
+                module: "pam_faillock.so",
+                message: "Incomplete faillock setup: preauth rule present but authfail rule missing — failed attempts may not be tracked",
+                recommendation: "Add a pam_faillock.so authfail rule after pam_unix.so",
+            });
+        }
+        if (hasAuthfail && !hasPreauth) {
+            findings.push({
+                severity: "warning",
+                module: "pam_faillock.so",
+                message: "Incomplete faillock setup: authfail rule present but preauth rule missing — locked accounts may not be checked before authentication",
+                recommendation: "Add a pam_faillock.so preauth rule before pam_unix.so",
+            });
+        }
+    }
+    // Check: missing pam_permit.so in session stack
+    const hasPermitSession = sessionRules.some((r) => r.module === "pam_permit.so");
+    if (sessionRules.length > 0 && !hasPermitSession) {
+        findings.push({
+            severity: "warning",
+            module: "general",
+            message: "No pam_permit.so in session stack — sessions may fail to initialize",
+            recommendation: "Add 'session required pam_permit.so' to the session stack",
+        });
+    }
+    return findings;
+}
+// ── Combined Entry Point ────────────────────────────────────────────────────
+/**
+ * Validate PAM policy sanity — combined parameter + config check.
+ *
+ * This is the main entry point for sanity validation. It runs:
+ * 1. Module-specific parameter checks (if module + params provided)
+ * 2. Config structure checks (if lines provided)
+ *
+ * @param options - What to validate
+ * @returns Combined sanity result with safe flag and all findings
+ */
+export function validatePamPolicySanity(options) {
+    const findings = [];
+    // 1. Module-specific parameter checks
+    if (options.module && options.params) {
+        if (options.module === "faillock") {
+            findings.push(...validateFaillockParams({
+                deny: typeof options.params.deny === "number" ? options.params.deny : undefined,
+                unlock_time: typeof options.params.unlock_time === "number" ? options.params.unlock_time : undefined,
+                fail_interval: typeof options.params.fail_interval === "number" ? options.params.fail_interval : undefined,
+            }));
+        }
+        else if (options.module === "pwquality") {
+            findings.push(...validatePwqualityParams({
+                minlen: typeof options.params.minlen === "number" ? options.params.minlen : undefined,
+                dcredit: typeof options.params.dcredit === "number" ? options.params.dcredit : undefined,
+                ucredit: typeof options.params.ucredit === "number" ? options.params.ucredit : undefined,
+                lcredit: typeof options.params.lcredit === "number" ? options.params.lcredit : undefined,
+                ocredit: typeof options.params.ocredit === "number" ? options.params.ocredit : undefined,
+                minclass: typeof options.params.minclass === "number" ? options.params.minclass : undefined,
+                maxrepeat: typeof options.params.maxrepeat === "number" ? options.params.maxrepeat : undefined,
+                retry: typeof options.params.retry === "number" ? options.params.retry : undefined,
+            }));
+        }
+    }
+    // 2. Config structure checks
+    if (options.lines) {
+        findings.push(...validatePamConfigSanity(options.lines));
+    }
+    // Sort: critical first, then warning; within same severity, by module
+    findings.sort((a, b) => {
+        if (a.severity !== b.severity) {
+            return a.severity === "critical" ? -1 : 1;
+        }
+        return a.module.localeCompare(b.module);
+    });
+    const criticalCount = findings.filter((f) => f.severity === "critical").length;
+    const warningCount = findings.filter((f) => f.severity === "warning").length;
+    return {
+        safe: criticalCount === 0,
+        findings,
+        criticalCount,
+        warningCount,
+    };
+}

package/build/tools/access-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/tools/access-control.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA0MpE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAu4DlE"}
+{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/tools/access-control.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6PpE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0jElE"}

package/build/tools/access-control.js

@@ -12,7 +12,40 @@ import { getConfig, getToolTimeout } from "../core/config.js";
 import { getDistroAdapter } from "../core/distro-adapter.js";
 import { createTextContent, createErrorContent, formatToolOutput, } from "../core/parsers.js";
 import { logChange, createChangeEntry, backupFile, } from "../core/changelog.js";
-import { parsePamConfig, serializePamConfig, validatePamConfig, createPamRule, removeModuleRules, insertBeforeModule, insertAfterModule, adjustJumpCounts, readPamFile, writePamFile, backupPamFile, restorePamFile, PamWriteError, } from "../core/pam-utils.js";
+import { parsePamConfig, serializePamConfig, validatePamConfig, createPamRule, removeModuleRules, insertBeforeModule, insertAfterModule, adjustJumpCounts, readPamFile, writePamFile, backupPamFile, restorePamFile, PamWriteError, validatePamPolicySanity, } from "../core/pam-utils.js";
+/**
+ * Downgrade a severity level by one step.
+ * critical → high, high → medium, medium → low, low → low
+ */
+function downgradeSeverity(severity) {
+    switch (severity) {
+        case "critical": return "high";
+        case "high": return "medium";
+        case "medium": return "low";
+        default: return severity;
+    }
+}
+/**
+ * Adjust finding severity and description based on SSH service state.
+ */
+function adjustFindingForServiceState(finding, serviceState) {
+    switch (serviceState) {
+        case "active":
+            return finding;
+        case "installed_inactive":
+            return {
+                severity: downgradeSeverity(finding.severity),
+                description: `[SERVICE STOPPED] ${finding.description}`,
+            };
+        case "removed_residual":
+            return {
+                severity: "info",
+                description: `[RESIDUAL CONFIG] ${finding.description}`,
+            };
+        case "not_installed":
+            return finding; // Should not reach here — not_installed short-circuits
+    }
+}
 const SSH_HARDENING_CHECKS = [
     {
         key: "PermitRootLogin",
@@ -285,6 +318,12 @@ export function registerAccessControlTools(server) {
             .default("/usr/sbin/nologin")
             .describe("Shell to set (restrict_shell, default: /usr/sbin/nologin)"),
         // ── shared ──
+        force: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Force operation even if sanity checks report critical findings (pam_configure). " +
+            "Use with extreme caution — may cause lockouts."),
         dry_run: z
             .boolean()
             .optional()
@@ -296,13 +335,90 @@ export function registerAccessControlTools(server) {
             case "ssh_audit": {
                 try {
                     const config_path = params.config_path ?? "/etc/ssh/sshd_config";
+                    // ── Step 1: Detect SSH service state ──────────────────────
+                    const whichResult = await executeCommand({
+                        command: "which",
+                        args: ["sshd"],
+                        toolName: "access_control",
+                        timeout: 5000,
+                    });
+                    const sshdBinaryExists = whichResult.exitCode === 0;
+                    const serviceResult = await executeCommand({
+                        command: "systemctl",
+                        args: ["is-active", "ssh", "sshd"],
+                        toolName: "access_control",
+                        timeout: 5000,
+                    });
+                    const serviceRunning = serviceResult.exitCode === 0;
+                    // ── Step 2: Try to read the config file ──────────────────
                     const result = await executeCommand({
                         command: "sudo",
                         args: ["cat", config_path],
                         toolName: "access_control",
                         timeout: getToolTimeout("access_control"),
                     });
-                    if (result.exitCode !== 0) {
+                    const configExists = result.exitCode === 0;
+                    // ── Step 3: Classify service state ───────────────────────
+                    let serviceStatus;
+                    if (sshdBinaryExists && serviceRunning) {
+                        serviceStatus = {
+                            state: "active",
+                            label: "ACTIVE (sshd running, accepting connections)",
+                            sshdBinaryExists: true,
+                            serviceRunning: true,
+                            configExists,
+                        };
+                    }
+                    else if (sshdBinaryExists && !serviceRunning) {
+                        serviceStatus = {
+                            state: "installed_inactive",
+                            label: "INSTALLED BUT INACTIVE (sshd binary found, service not running)",
+                            sshdBinaryExists: true,
+                            serviceRunning: false,
+                            configExists,
+                        };
+                    }
+                    else if (!sshdBinaryExists && configExists) {
+                        serviceStatus = {
+                            state: "removed_residual",
+                            label: "NOT INSTALLED (residual config file detected)",
+                            sshdBinaryExists: false,
+                            serviceRunning: false,
+                            configExists: true,
+                        };
+                    }
+                    else {
+                        serviceStatus = {
+                            state: "not_installed",
+                            label: "NOT INSTALLED",
+                            sshdBinaryExists: false,
+                            serviceRunning: false,
+                            configExists: false,
+                        };
+                    }
+                    // ── Step 4: Short-circuit for not_installed ──────────────
+                    if (serviceStatus.state === "not_installed") {
+                        const entry = createChangeEntry({
+                            tool: "access_control",
+                            action: "SSH configuration audit",
+                            target: config_path,
+                            after: "SSH server not installed — audit skipped",
+                            dryRun: false,
+                            success: true,
+                        });
+                        logChange(entry);
+                        const output = {
+                            configPath: config_path,
+                            serviceStatus: serviceStatus.label,
+                            serviceState: serviceStatus.state,
+                            summary: { passed: 0, failed: 0, warned: 0, total: 0 },
+                            findings: [],
+                            note: "SSH server is not installed on this system. No audit required.",
+                        };
+                        return { content: [formatToolOutput(output)] };
+                    }
+                    // ── Step 5: Config read failed but binary exists → error ─
+                    if (!configExists) {
                         return {
                             content: [
                                 createErrorContent(`Cannot read SSH config (exit ${result.exitCode}): ${result.stderr}`),
@@ -362,13 +478,15 @@ export function registerAccessControlTools(server) {
                         else {
                             status = currentValue.toLowerCase() === check.recommended.toLowerCase() ? "pass" : "fail";
                         }
+                        // ── Step 6: Adjust severity based on service state ─────
+                        const adjusted = adjustFindingForServiceState({ severity: check.severity, description: check.description }, serviceStatus.state);
                         findings.push({
                             setting: check.key,
                             currentValue,
                             recommendedValue: check.recommended,
                             status,
-                            severity: check.severity,
-                            description: check.description,
+                            severity: adjusted.severity,
+                            description: adjusted.description,
                         });
                     }
                     const passed = findings.filter((f) => f.status === "pass").length;
@@ -378,16 +496,31 @@ export function registerAccessControlTools(server) {
                         tool: "access_control",
                         action: "SSH configuration audit",
                         target: config_path,
-                        after: `Pass: ${passed}, Fail: ${failed}, Warn: ${warned}`,
+                        after: `Pass: ${passed}, Fail: ${failed}, Warn: ${warned}, Service: ${serviceStatus.state}`,
                         dryRun: false,
                         success: true,
                     });
                     logChange(entry);
+                    // ── Step 7: Build output with service status context ─────
                     const output = {
                         configPath: config_path,
+                        serviceStatus: serviceStatus.label,
+                        serviceState: serviceStatus.state,
                         summary: { passed, failed, warned, total: findings.length },
                         findings,
                     };
+                    // Add contextual notes for non-active states
+                    if (serviceStatus.state === "removed_residual") {
+                        output.note =
+                            "openssh-server has been removed but " + config_path + " remains. " +
+                                "All findings below are INFORMATIONAL — no SSH server is running. " +
+                                "Recommendation: sudo dpkg --purge openssh-server";
+                    }
+                    else if (serviceStatus.state === "installed_inactive") {
+                        output.note =
+                            "sshd is installed but the service is not currently running. " +
+                                "Findings have been downgraded by one severity level.";
+                    }
                     return { content: [formatToolOutput(output)] };
                 }
                 catch (err) {
@@ -954,6 +1087,27 @@ export function registerAccessControlTools(server) {
                             maxrepeat: params.pam_settings?.maxrepeat ?? defaults.maxrepeat,
                             reject_username: params.pam_settings?.reject_username ?? defaults.reject_username,
                         };
+                        // ── Sanity check: detect dangerous pwquality parameters ──
+                        const pwqSanityResult = validatePamPolicySanity({
+                            module: "pwquality",
+                            params: merged,
+                        });
+                        if (pwqSanityResult.criticalCount > 0 && !(params.force)) {
+                            const findingsText = pwqSanityResult.findings
+                                .map(f => `  [${f.severity.toUpperCase()}] ${f.message}\n    → ${f.recommendation}`)
+                                .join("\n");
+                            return {
+                                content: [
+                                    createErrorContent(`PAM policy sanity check FAILED — ${pwqSanityResult.criticalCount} critical finding(s):\n\n` +
+                                        findingsText +
+                                        `\n\nTo override, set force=true. This may cause lockouts.`),
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const pwqSanityWarnings = pwqSanityResult.findings
+                            .map(f => `[${f.severity.toUpperCase()}] ${f.message}`)
+                            .join("\n");
                         const targetFile = "/etc/security/pwquality.conf";
                         const configLines = [
                             `minlen = ${merged.minlen}`,
@@ -978,7 +1132,8 @@ export function registerAccessControlTools(server) {
                             return {
                                 content: [
                                     createTextContent(`[DRY-RUN] Would write the following to ${targetFile}:\n\n` +
-                                        configLines.map((l) => `  ${l}`).join("\n")),
+                                        configLines.map((l) => `  ${l}`).join("\n") +
+                                        (pwqSanityWarnings ? `\n\n⚠️ Sanity warnings:\n${pwqSanityWarnings}` : "")),
                                 ],
                             };
                         }
@@ -1023,7 +1178,8 @@ export function registerAccessControlTools(server) {
                             return {
                                 content: [
                                     createTextContent(`pam_pwquality configured in ${targetFile}:\n\n` +
-                                        configLines.map((l) => `  ${l}`).join("\n")),
+                                        configLines.map((l) => `  ${l}`).join("\n") +
+                                        (pwqSanityWarnings ? `\n\n⚠️ Sanity warnings:\n${pwqSanityWarnings}` : "")),
                                 ],
                             };
                         }
@@ -1054,6 +1210,27 @@ export function registerAccessControlTools(server) {
                         unlock_time: params.pam_settings?.unlock_time ?? defaults.unlock_time,
                         fail_interval: params.pam_settings?.fail_interval ?? defaults.fail_interval,
                     };
+                    // ── Sanity check: detect dangerous faillock parameters ──
+                    const flSanityResult = validatePamPolicySanity({
+                        module: "faillock",
+                        params: merged,
+                    });
+                    if (flSanityResult.criticalCount > 0 && !(params.force)) {
+                        const findingsText = flSanityResult.findings
+                            .map(f => `  [${f.severity.toUpperCase()}] ${f.message}\n    → ${f.recommendation}`)
+                            .join("\n");
+                        return {
+                            content: [
+                                createErrorContent(`PAM policy sanity check FAILED — ${flSanityResult.criticalCount} critical finding(s):\n\n` +
+                                    findingsText +
+                                    `\n\nTo override, set force=true. This may cause lockouts.`),
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const flSanityWarnings = flSanityResult.findings
+                        .map(f => `[${f.severity.toUpperCase()}] ${f.message}`)
+                        .join("\n");
                     const targetFile = (await getDistroAdapter()).paths.pamAuth;
                     const failArgsList = [
                         `deny=${merged.deny}`,
@@ -1077,7 +1254,8 @@ export function registerAccessControlTools(server) {
                             content: [
                                 createTextContent(`[DRY-RUN] Would add/update pam_faillock.so in ${targetFile}:\n\n` +
                                     `  ${preLine}\n  ${authLine}\n\n` +
-                                    `Settings: ${JSON.stringify(merged)}`),
+                                    `Settings: ${JSON.stringify(merged)}` +
+                                    (flSanityWarnings ? `\n\n⚠️ Sanity warnings:\n${flSanityWarnings}` : "")),
                             ],
                         };
                     }
@@ -1110,6 +1288,11 @@ export function registerAccessControlTools(server) {
                         if (!recheckValidation.valid) {
                             throw new PamWriteError(`Generated PAM config failed validation: ${recheckValidation.errors.join("; ")}`, targetFile, backupEntry.id);
                         }
+                        // 7b. Config-level sanity check on the resulting PAM structure
+                        const configSanity = validatePamPolicySanity({ lines: recheckLines });
+                        if (configSanity.criticalCount > 0 && !(params.force)) {
+                            throw new PamWriteError(`PAM config sanity check failed: ${configSanity.findings.map(f => f.message).join("; ")}`, targetFile, backupEntry.id);
+                        }
                         // 8. Write (validates pre and post-write internally)
                         await writePamFile(targetFile, newContent);
                         const entry = createChangeEntry({
@@ -1127,7 +1310,8 @@ export function registerAccessControlTools(server) {
                                 createTextContent(`pam_faillock configured in ${targetFile}:\n\n` +
                                     `  ${preLine}\n  ${authLine}\n\n` +
                                     `Settings: ${JSON.stringify(merged)}\n` +
-                                    `Backup: ${backupEntry.backupPath}`),
+                                    `Backup: ${backupEntry.backupPath}` +
+                                    (flSanityWarnings ? `\n\n⚠️ Sanity warnings:\n${flSanityWarnings}` : "")),
                             ],
                         };
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "defense-mcp-server",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Defense MCP Server — 31 defensive security tools across 29 modules for system hardening and threat detection",
   "type": "module",
   "main": "build/index.js",