defense-mcp-server 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -6,6 +6,43 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [0.7.1] — 2026-03-14
+
+### v0.7.1 — Critical PAM Hardening Fix
+
+#### Security Fix
+- **CRITICAL**: Fixed `pam_configure` action corrupting `/etc/pam.d/common-auth` — sed commands stripped whitespace separators between PAM fields, breaking ALL authentication system-wide (required GRUB recovery to fix)
+- **CRITICAL**: Fixed `[success=N]` jump count not being updated after faillock rule insertion — would cause authentication denial on Debian/Ubuntu systems
+
+#### New Module: `src/core/pam-utils.ts`
+- Safe in-memory PAM config parser/serializer replacing fragile sed-based manipulation
+- `parsePamConfig()` — Lossless parser handling comments, blanks, `@include`, bracket-style controls
+- `serializePamConfig()` — Serializer with proper formatting (matching `pam-auth-update` canonical format)
+- `validatePamConfig()` — Triple validation: field formatting, module existence, and `[success=N]` jump count correctness
+- `adjustJumpCounts()` — Automatically updates bracket-control jump counts when rules are inserted/removed
+- Manipulation helpers: `removeModuleRules()`, `insertBeforeModule()`, `insertAfterModule()` with pamType filter
+- Sudo-aware I/O: `readPamFile()`, `writePamFile()` (atomic via `sudo install`), `backupPamFile()`, `restorePamFile()`
+
+#### Safety Layers (Defense-in-Depth)
+- Mandatory backup before any PAM file modification
+- In-memory validation before writing (catches corrupted fields, missing pam_unix.so, wrong jump counts)
+- Atomic file write using `sudo install -m 644 -o root -g root` (no partial state)
+- Post-write re-read validation
+- Auto-rollback on ANY failure (restores from backup automatically)
+
+#### Security Review Remediations
+- Fixed partial write state on chmod/chown failure (atomic `sudo install`)
+- Fixed temp file symlink race (secure `mkdtempSync`)
+- Fixed insert helpers matching by module only (added pamType filter)
+- Fixed `backupPamFile` mutating BackupEntry internal state
+- Fixed `restorePamFile` leaking PAM content to stdout via `tee`
+- Added PAM modification warning to SafeguardRegistry
+
+#### Testing
+- 63 new tests in `tests/core/pam-utils.test.ts` covering parser, serializer, validator, jump count adjustment, manipulation helpers, and full faillock integration flow
+- 7 new tests in `tests/tools/access-control.test.ts` for pam_configure regression testing
+- Critical regression test: verifies concatenated PAM fields (the original lockout bug) can never be produced
+
 ## [0.7.0] — 2026-03-12
 
 ### v0.7.0 — Tool Consolidation & Sudo Hardening Overhaul

package/README.md

@@ -2,11 +2,14 @@
 
 A Model Context Protocol (MCP) server that gives AI assistants access to **94 defensive security tools** on Linux. Connect it to Claude Desktop, Cursor, or any MCP-compatible client to harden systems, manage firewalls, scan for vulnerabilities, and enforce compliance — all through natural language conversation.
 
-## What It Does
+## Why I Made This
+Basically I'm a total noob when it comes to really serious system hardening so I thought I'd test the latest LLM models and see how far I could get. Turns out they're pretty helpful! I got tired of hardening my new systems by hand every time I spun up a new one so I made this MCP server to make it pretty easy. I jam packed as many security tools as I could into this thing so be prepared to burn tokens using it. Hopefully it helps you about half as much as its helped me. 
 
-This server exposes Linux security tools as MCP tools that an AI assistant can invoke on your behalf. Instead of memorizing command syntax for dozens of security utilities, you describe what you want in plain English and the assistant calls the right tool with the right parameters.
+## So What It Does
 
-The 94 tools are organized into 32 modules:
+This server exposes Linux security tools as MCP tools that an AI assistant can invoke on your behalf. Instead of memorizing command syntax for dozens of security utilities, you describe what you want in plain English and the assistant calls the right tool with the right parameters. Sounds pretty good right!
+
+Here are the tools:
 
 | Module | What It Does |
 |--------|-------------|

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

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAqEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAgFD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAmNxB"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAkFA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AA0FD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAmNxB"}

package/build/core/executor.js

@@ -1,5 +1,7 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as pathJoin } from "node:path";
 import { getConfig, getToolTimeout } from "./config.js";
 import { SudoSession } from "./sudo-session.js";
 import { SudoGuard } from "./sudo-guard.js";
@@ -8,14 +10,25 @@ import { resolveCommand, resolveSudoCommand } from "./command-allowlist.js";
 /**
  * Ordered list of known graphical sudo/SSH askpass helpers.
  * The first one found on the system will be used as the SUDO_ASKPASS program.
+ *
+ * NOTE: The user-local MCP askpass helper is checked first (highest priority)
+ * since it is installed as part of the native deployment setup and is the
+ * preferred path for desktop environments running the server natively.
+ * It is placed at ~/.local/bin/mcp-askpass with mode 0700 (owner-only).
  */
-const ASKPASS_CANDIDATES = [
-    "/usr/bin/ssh-askpass", // Generic (often symlinked to ksshaskpass/gnome)
-    "/usr/bin/ksshaskpass", // KDE Plasma
-    "/usr/lib/ssh/x11-ssh-askpass", // X11 classic
-    "/usr/libexec/openssh/gnome-ssh-askpass", // GNOME
-    "/usr/bin/lxqt-sudo", // LXQt
-];
+function getAskpassCandidates() {
+    return [
+        // User-local MCP askpass wrapper (zenity/pinentry, installed by setup)
+        pathJoin(homedir(), ".local", "bin", "mcp-askpass"),
+        // System-level alternatives
+        "/usr/local/bin/mcp-askpass", // System-wide MCP askpass (if installed by admin)
+        "/usr/bin/ssh-askpass", // Generic (often symlinked to ksshaskpass/gnome)
+        "/usr/bin/ksshaskpass", // KDE Plasma
+        "/usr/lib/ssh/x11-ssh-askpass", // X11 classic
+        "/usr/libexec/openssh/gnome-ssh-askpass", // GNOME
+        "/usr/bin/lxqt-sudo", // LXQt
+    ];
+}
 /** Cached result of askpass detection (null = not yet checked, undefined = not found) */
 let cachedAskpass = null;
 /**
@@ -43,14 +56,14 @@ function findAskpassHelper() {
         cachedAskpass = undefined;
         return undefined;
     }
-    for (const candidate of ASKPASS_CANDIDATES) {
+    for (const candidate of getAskpassCandidates()) {
         if (existsSync(candidate)) {
             // SECURITY (CORE-016): Validate each candidate's ownership, permissions, and integrity
             const validation = SudoGuard.validateAskpassPath(candidate);
             if (validation.valid) {
                 cachedAskpass = candidate;
                 console.error(`[executor] Found verified askpass helper: ${candidate}`);
-                return cachedAskpass;
+                return candidate;
             }
             console.error(`[executor] Skipping askpass candidate ${candidate}: ${validation.reason}`);
         }
@@ -77,8 +90,16 @@ function findAskpassHelper() {
  * `command: "sudo", args: ["iptables", ...]`.
  */
 function prepareSudoOptions(options) {
-    // Only transform calls where the command is "sudo"
-    if (options.command !== "sudo")
+    // FIX (ordering bug): By the time this function is called, the allowlist block
+    // in executeCommand() has already resolved "sudo" → "/usr/bin/sudo" (absolute
+    // path). The original guard `if (options.command !== "sudo")` would therefore
+    // always return early, permanently bypassing credential injection.
+    //
+    // Fix: accept both the bare name "sudo" (pre-allowlist, from tests or direct
+    // callers) and any absolute path ending in "/sudo" (post-allowlist resolution,
+    // the normal runtime path) so that injection works in both cases.
+    const isSudoCommand = options.command === "sudo" || options.command.endsWith("/sudo");
+    if (!isSudoCommand)
         return options;
     // Skip if the caller explicitly opted out (e.g. sudo-session.ts itself)
     if (options.skipSudoInjection)

package/build/core/installer.d.ts

@@ -60,7 +60,10 @@ export interface InstallResult {
 export declare const DEFENSIVE_TOOLS: ToolRequirement[];
 /**
  * Checks whether a tool binary is available on the system.
- * Uses `which` to find the binary, then attempts `--version` for version info.
+ * Uses the command allowlist (which already resolved paths via existsSync at
+ * startup) or falls back to probing standard binary directories with
+ * existsSync. This avoids shelling out to `which`, which is blocked by the
+ * command allowlist.
  */
 export declare function checkTool(binary: string): Promise<{
     installed: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/core/installer.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,SAAS,GACT,WAAW,GACX,WAAW,GACX,YAAY,GACZ,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,eAAe,EAk6B5C,CAAC;AAEF;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsClE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC,CAkB5B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,aAAa,CAAC,CAwDxB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,YAAY,EACvB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,EAAE,CAAC,CAgC1B"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/core/installer.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,SAAS,GACT,WAAW,GACX,WAAW,GACX,YAAY,GACZ,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,eAAe,EAk6B5C,CAAC;AAYF;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8ClE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC,CAkB5B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,aAAa,CAAC,CAwDxB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,YAAY,EACvB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,EAAE,CAAC,CAgC1B"}

package/build/core/installer.js

@@ -1,6 +1,8 @@
+import { existsSync } from "node:fs";
 import { executeCommand } from "./executor.js";
 import { detectDistro, getInstallCommand, getUpdateCommand, } from "./distro.js";
 import { getConfig } from "./config.js";
+import { resolveCommand } from "./command-allowlist.js";
 /**
  * Comprehensive list of defensive security tools across categories.
  */
@@ -922,21 +924,43 @@ export const DEFENSIVE_TOOLS = [
         required: false,
     },
 ];
+/** Standard binary directories to probe when a binary is not in the command allowlist. */
+const STANDARD_BINARY_DIRS = [
+    "/usr/bin",
+    "/usr/sbin",
+    "/bin",
+    "/sbin",
+    "/usr/local/bin",
+    "/usr/local/sbin",
+];
 /**
  * Checks whether a tool binary is available on the system.
- * Uses `which` to find the binary, then attempts `--version` for version info.
+ * Uses the command allowlist (which already resolved paths via existsSync at
+ * startup) or falls back to probing standard binary directories with
+ * existsSync. This avoids shelling out to `which`, which is blocked by the
+ * command allowlist.
  */
 export async function checkTool(binary) {
-    // Check if binary exists
-    const whichResult = await executeCommand({
-        command: "which",
-        args: [binary],
-        timeout: 5000,
-    });
-    if (whichResult.exitCode !== 0) {
+    // Attempt to resolve via the command allowlist first (O(1) lookup, already
+    // verified with existsSync at startup).
+    let binaryPath;
+    try {
+        binaryPath = resolveCommand(binary);
+    }
+    catch {
+        // Binary not in the allowlist or not yet resolved; fall back to probing
+        // standard directories with existsSync.
+        for (const dir of STANDARD_BINARY_DIRS) {
+            const candidate = `${dir}/${binary}`;
+            if (existsSync(candidate)) {
+                binaryPath = candidate;
+                break;
+            }
+        }
+    }
+    if (!binaryPath) {
         return { installed: false };
     }
-    const binaryPath = whichResult.stdout.trim();
     // Try to get version
     let version;
     const versionResult = await executeCommand({

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

@@ -0,0 +1,233 @@
+/**
+ * PAM configuration parser, serializer, validator, and file I/O manager.
+ *
+ * Replaces fragile sed-based PAM manipulation with safe in-memory operations:
+ *   1. Parse PAM config into structured records
+ *   2. Manipulate records (insert, remove, reorder)
+ *   3. Serialize back with correct formatting
+ *   4. Validate before writing
+ *   5. Write atomically with mandatory backup and auto-rollback
+ *
+ * @see docs/PAM-HARDENING-FIX.md for architecture details
+ */
+import { type BackupEntry } from "./backup-manager.js";
+/** A PAM rule line: type control module [args...] */
+export interface PamRule {
+    kind: "rule";
+    /** PAM type: auth, account, password, session (optionally prefixed with -) */
+    pamType: string;
+    /** Control flag: required, requisite, sufficient, optional, or [value=action ...] */
+    control: string;
+    /** Module path/name: pam_unix.so, pam_faillock.so, etc. */
+    module: string;
+    /** Module arguments: nullok, silent, deny=5, etc. */
+    args: string[];
+    /** Original raw text (preserved for round-trip fidelity). */
+    rawLine: string;
+}
+/** A comment line (starts with #). */
+export interface PamComment {
+    kind: "comment";
+    text: string;
+}
+/** A blank/empty line. */
+export interface PamBlank {
+    kind: "blank";
+}
+/** An @include directive. */
+export interface PamInclude {
+    kind: "include";
+    target: string;
+    rawLine: string;
+}
+/** Union of all PAM line types. */
+export type PamLine = PamRule | PamComment | PamBlank | PamInclude;
+/** Thrown when PAM config validation fails. */
+export declare class PamValidationError extends Error {
+    readonly errors: string[];
+    readonly filePath?: string | undefined;
+    constructor(errors: string[], filePath?: string | undefined);
+}
+/** Thrown when PAM file write fails or post-write validation fails. */
+export declare class PamWriteError extends Error {
+    readonly filePath: string;
+    readonly backupId?: string | undefined;
+    constructor(message: string, filePath: string, backupId?: string | undefined);
+}
+/**
+ * Parse PAM config file content into structured records.
+ *
+ * Handles:
+ * - Standard rules: auth required pam_unix.so nullok
+ * - Complex controls: auth [success=1 default=ignore] pam_unix.so
+ * - Comments: # This is a comment
+ * - Blank lines: (preserved for formatting fidelity)
+ * - Include directives: @include common-auth
+ *
+ * **Critical**: The parser is **lossless**. Every line in the input appears
+ * in the output array. Unknown/unparseable lines are preserved as comments
+ * to prevent silent data loss.
+ *
+ * @param content - Raw PAM config file text
+ * @returns Array of PamLine records in file order
+ */
+export declare function parsePamConfig(content: string): PamLine[];
+/**
+ * Serialize structured PAM records back to file content.
+ *
+ * For PamRule records, generates lines with consistent formatting:
+ *   - Fields separated by 4-space padding
+ *   - Module args separated by single spaces
+ *
+ * For PamComment, PamBlank, and PamInclude records, the original
+ * raw text is emitted unchanged (round-trip preservation).
+ *
+ * @param lines - Array of PamLine records
+ * @returns PAM config file content string (with trailing newline)
+ */
+export declare function serializePamConfig(lines: PamLine[]): string;
+/**
+ * Validate PAM config for syntactic correctness.
+ *
+ * Checks:
+ * 1. Every PamRule has a valid pamType, non-empty control, and module ending in .so
+ * 2. At least one pam_unix.so rule exists (sanity check — PAM needs it)
+ * 3. No lines have concatenated fields (the bug that caused the lockout)
+ *
+ * Does NOT check:
+ * - Whether .so files exist on disk
+ * - Semantic correctness of control flags
+ *
+ * @param lines - Parsed PamLine array
+ * @returns Validation result with error details
+ */
+export declare function validatePamConfig(lines: PamLine[]): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validate raw PAM config content string.
+ *
+ * Convenience wrapper that parses then validates.
+ *
+ * @param content - Raw PAM config file text
+ * @returns Validation result
+ */
+export declare function validatePamConfigContent(content: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Create a new PamRule record.
+ *
+ * @param pamType - PAM type (auth, account, password, session)
+ * @param control - Control flag (required, requisite, [success=1 default=ignore], etc.)
+ * @param module - Module name (pam_faillock.so, pam_unix.so, etc.)
+ * @param args - Module arguments
+ * @returns New PamRule with generated rawLine
+ */
+export declare function createPamRule(pamType: string, control: string, module: string, args: string[]): PamRule;
+/**
+ * Remove all rules referencing a specific module.
+ *
+ * @param lines - Current PamLine array
+ * @param moduleName - Module to remove (e.g., "pam_faillock.so")
+ * @returns New array with matching rules removed
+ */
+export declare function removeModuleRules(lines: PamLine[], moduleName: string): PamLine[];
+/**
+ * Insert a new rule BEFORE the first rule matching targetModule.
+ * If targetModule is not found, appends at the end.
+ *
+ * @param lines - Current PamLine array
+ * @param targetModule - Module to insert before (e.g., "pam_unix.so")
+ * @param newRule - The rule to insert
+ * @param options - Optional filters: pamType restricts match to specific PAM type
+ * @returns New array with the rule inserted
+ */
+export declare function insertBeforeModule(lines: PamLine[], targetModule: string, newRule: PamRule, options?: {
+    pamType?: string;
+}): PamLine[];
+/**
+ * Insert a new rule AFTER the first rule matching targetModule.
+ * If targetModule is not found, appends at the end.
+ *
+ * @param lines - Current PamLine array
+ * @param targetModule - Module to insert after (e.g., "pam_unix.so")
+ * @param newRule - The rule to insert
+ * @param options - Optional filters: pamType restricts match to specific PAM type
+ * @returns New array with the rule inserted
+ */
+export declare function insertAfterModule(lines: PamLine[], targetModule: string, newRule: PamRule, options?: {
+    pamType?: string;
+}): PamLine[];
+/**
+ * Find all rules referencing a specific module.
+ *
+ * @param lines - PamLine array to search
+ * @param moduleName - Module to find (e.g., "pam_faillock.so")
+ * @returns Array of matching PamRule records
+ */
+export declare function findModuleRules(lines: PamLine[], moduleName: string): PamRule[];
+/**
+ * After inserting rules, adjust [success=N] jump counts on any rule
+ * that uses bracket-style controls with a success=N pattern.
+ *
+ * For each rule with [success=N ...], count how many rules now exist
+ * between that rule and pam_deny.so (requisite), and update N so that
+ * success still jumps PAST pam_deny.so.
+ *
+ * @param lines - PamLine array (typically after insertions)
+ * @returns New array with corrected jump counts
+ */
+export declare function adjustJumpCounts(lines: PamLine[]): PamLine[];
+/**
+ * Read a PAM config file via sudo.
+ *
+ * @param filePath - Absolute path (e.g., /etc/pam.d/common-auth)
+ * @returns File content string
+ * @throws If sudo cat fails
+ */
+export declare function readPamFile(filePath: string): Promise<string>;
+/**
+ * Write a PAM config file via sudo, with mandatory pre-write validation.
+ *
+ * Steps:
+ * 1. Parse the content with parsePamConfig()
+ * 2. Validate with validatePamConfig() — if invalid, throw (never write bad content)
+ * 3. Write to a secure temp directory (mkdtempSync — eliminates symlink race)
+ * 4. Use `sudo install -m 644 -o root -g root` for atomic write (eliminates partial-write state)
+ * 5. Post-write verification
+ *
+ * @param filePath - Absolute path
+ * @param content - PAM config content to write
+ * @throws PamValidationError if pre-write validation fails
+ * @throws PamWriteError if write or permission setting fails
+ */
+export declare function writePamFile(filePath: string, content: string): Promise<void>;
+/**
+ * Backup a PAM file using the project BackupManager.
+ *
+ * Since PAM files are root-owned, this:
+ * 1. Reads content via sudo cat
+ * 2. Writes to a secure temp directory (eliminates symlink race)
+ * 3. Uses BackupManager.backupSync() to create a tracked backup
+ * 4. Returns a new object (does NOT mutate BackupManager's internal entry)
+ * 5. Cleans up the temp file/directory
+ *
+ * @param filePath - PAM file to backup
+ * @returns BackupEntry for later restore (with corrected originalPath)
+ */
+export declare function backupPamFile(filePath: string): Promise<BackupEntry>;
+/**
+ * Restore a PAM file from backup.
+ *
+ * 1. Reads backup content from BackupManager's directory
+ * 2. Validates the backup content (refuse to restore garbage)
+ * 3. Writes to a secure temp file, then uses `sudo install` (eliminates tee stdout leak)
+ *
+ * @param backupEntry - The BackupEntry from backupPamFile()
+ * @throws If backup file is missing, invalid, or restore fails
+ */
+export declare function restorePamFile(backupEntry: BackupEntry): Promise<void>;
+//# sourceMappingURL=pam-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pam-utils.d.ts","sourceRoot":"","sources":["../../src/core/pam-utils.ts"],"names":[],"mappings":"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"}