security-mcp 1.0.3 → 1.0.5

package/dist/cli/update.js

@@ -0,0 +1,124 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import * as https from "node:https";
+const CACHE_DIR = join(homedir(), ".security-mcp");
+const CACHE_PATH = join(CACHE_DIR, "update-check.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const PROMPT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = "https://registry.npmjs.org/security-mcp/latest";
+function parseVersion(input) {
+    const match = input.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ?? null
+    };
+}
+function compareVersions(a, b) {
+    const parsedA = parseVersion(a);
+    const parsedB = parseVersion(b);
+    if (!parsedA || !parsedB)
+        return 0;
+    if (parsedA.major !== parsedB.major)
+        return parsedA.major < parsedB.major ? -1 : 1;
+    if (parsedA.minor !== parsedB.minor)
+        return parsedA.minor < parsedB.minor ? -1 : 1;
+    if (parsedA.patch !== parsedB.patch)
+        return parsedA.patch < parsedB.patch ? -1 : 1;
+    if (parsedA.prerelease === parsedB.prerelease)
+        return 0;
+    if (parsedA.prerelease === null)
+        return 1;
+    if (parsedB.prerelease === null)
+        return -1;
+    return parsedA.prerelease < parsedB.prerelease ? -1 : 1;
+}
+function readCache() {
+    try {
+        return JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(dirname(CACHE_PATH), { recursive: true });
+        writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2) + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal: update notifications should never block command execution.
+    }
+}
+function fetchLatestVersion(timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const req = https.get(REGISTRY_URL, {
+            headers: { "User-Agent": "security-mcp-update-checker" }
+        }, (res) => {
+            if ((res.statusCode ?? 500) >= 400) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+            });
+            res.on("end", () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    resolve(parsed.version ?? null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on("error", () => resolve(null));
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            resolve(null);
+        });
+    });
+}
+function shouldPrompt(cache, latestVersion, now) {
+    if (!cache.lastPromptedVersion || !cache.lastPromptedAt)
+        return true;
+    if (cache.lastPromptedVersion !== latestVersion)
+        return true;
+    const lastPromptedAt = Date.parse(cache.lastPromptedAt);
+    if (Number.isNaN(lastPromptedAt))
+        return true;
+    return now - lastPromptedAt >= PROMPT_INTERVAL_MS;
+}
+export async function notifyIfUpdateAvailable(currentVersion) {
+    const now = Date.now();
+    const cache = readCache();
+    const lastCheckedAt = cache.lastCheckedAt ? Date.parse(cache.lastCheckedAt) : Number.NaN;
+    const shouldRefresh = Number.isNaN(lastCheckedAt) || now - lastCheckedAt >= CHECK_INTERVAL_MS;
+    if (shouldRefresh) {
+        const latestVersion = await fetchLatestVersion();
+        if (latestVersion) {
+            cache.latestVersion = latestVersion;
+        }
+        cache.lastCheckedAt = new Date(now).toISOString();
+        writeCache(cache);
+    }
+    if (!cache.latestVersion)
+        return;
+    if (compareVersions(currentVersion, cache.latestVersion) >= 0)
+        return;
+    if (!shouldPrompt(cache, cache.latestVersion, now))
+        return;
+    process.stderr.write(`\nUpdate available: security-mcp ${currentVersion} -> ${cache.latestVersion}\n` +
+        "Update command: npm install -g security-mcp@latest\n" +
+        "Then refresh editor config: security-mcp install-global\n\n");
+    cache.lastPromptedVersion = cache.latestVersion;
+    cache.lastPromptedAt = new Date(now).toISOString();
+    writeCache(cache);
+}

package/dist/gate/catalog.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "../..");
+const ControlSchema = z.object({
+    id: z.string(),
+    description: z.string(),
+    automation: z.enum(["workflow", "evidence", "tooling", "approval"]),
+    surfaces: z.array(z.string()).default(["all"]),
+    frameworks: z.array(z.string()).default([]),
+    evidence: z.array(z.string()).optional(),
+    required_scanners: z.array(z.string()).optional(),
+    required_steps: z.array(z.string()).optional()
+});
+const CatalogSchema = z.object({
+    version: z.string(),
+    controls: z.array(ControlSchema)
+});
+async function readJsonWithFallback(relPath, fallbackName) {
+    const overrideEnvMap = {
+        ".mcp/catalog/control-catalog.json": "SECURITY_GATE_CONTROL_CATALOG"
+    };
+    const overrideEnv = overrideEnvMap[relPath];
+    if (overrideEnv && process.env[overrideEnv]) {
+        return await readFile(join(process.cwd(), process.env[overrideEnv]), "utf-8");
+    }
+    try {
+        return await readFile(join(process.cwd(), relPath), "utf-8");
+    }
+    catch {
+        return await readFile(join(PKG_ROOT, "defaults", fallbackName), "utf-8");
+    }
+}
+export async function loadControlCatalog() {
+    const raw = await readJsonWithFallback(".mcp/catalog/control-catalog.json", "control-catalog.json");
+    return CatalogSchema.parse(JSON.parse(raw));
+}
+export function controlApplies(control, surfaces) {
+    const mobile = surfaces.mobileIos || surfaces.mobileAndroid;
+    if (control.surfaces.includes("all"))
+        return true;
+    if (control.surfaces.includes("web") && surfaces.web)
+        return true;
+    if (control.surfaces.includes("api") && surfaces.api)
+        return true;
+    if (control.surfaces.includes("infra") && surfaces.infra)
+        return true;
+    if (control.surfaces.includes("ai") && surfaces.ai)
+        return true;
+    if (control.surfaces.includes("mobile") && mobile)
+        return true;
+    return false;
+}

package/dist/gate/checks/ai.js

@@ -1,34 +1,65 @@
-import { searchRepo } from "../../repo/search.js";
+import fg from "fast-glob";
+import { readFileSafe } from "../../repo/fs.js";
+const SOURCE_FILE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|json)$/i;
+const SCHEMA_RE = /zod\.object\(|outputSchema|json_schema|JSON schema/i;
+const TOOL_RE = /\bfunction_call\b|\btools?\b\s*[:=]/i;
+const INJECTION_RE = /system prompt|developer message|ignore previous|prompt injection/i;
 export async function checkAi(_) {
     const findings = [];
-    const schemaEnforcement = await searchRepo({
-        query: String.raw `zod\.object\(|outputSchema|json_schema|JSON schema`,
-        isRegex: true,
-        maxMatches: 200
+    const files = await fg(["**/*.*"], {
+        dot: true,
+        onlyFiles: true,
+        ignore: [
+            "**/node_modules/**",
+            "**/.git/**",
+            "**/dist/**",
+            "**/fixtures/**",
+            "**/.mcp/**",
+            "**/.mcp/reviews/**",
+            "**/.mcp/reports/**"
+        ]
     });
-    const toolUse = await searchRepo({ query: "tool|function_call|tools:", isRegex: true, maxMatches: 200 });
-    if (toolUse.length > 0 && schemaEnforcement.length === 0) {
+    let schemaDetected = false;
+    const toolEvidence = [];
+    const injectionEvidence = [];
+    for (const file of files) {
+        if (!SOURCE_FILE_RE.test(file))
+            continue;
+        let text = "";
+        try {
+            text = await readFileSafe(file);
+        }
+        catch {
+            continue;
+        }
+        if (SCHEMA_RE.test(text)) {
+            schemaDetected = true;
+        }
+        if (TOOL_RE.test(text)) {
+            toolEvidence.push(file);
+        }
+        if (INJECTION_RE.test(text)) {
+            injectionEvidence.push(file);
+        }
+    }
+    if (toolEvidence.length > 0 && !schemaDetected) {
         findings.push({
             id: "AI_OUTPUT_BOUNDS_MISSING",
             title: "AI/tooling present but bounded output (schema validation) not detected",
             severity: "HIGH",
+            evidence: toolEvidence,
             requiredActions: [
                 "Enforce bounded outputs via JSON schema validation for every AI response used by code.",
                 "Add prompt-injection defenses: input sanitization, tool allowlists, deny-by-default tool router, and sensitive data redaction."
             ]
         });
     }
-    const systemPromptLeaks = await searchRepo({
-        query: "system prompt|developer message|ignore previous|prompt injection",
-        isRegex: true,
-        maxMatches: 200
-    });
-    if (systemPromptLeaks.length > 0) {
+    if (injectionEvidence.length > 0) {
         findings.push({
             id: "AI_INJECTION_CUES",
             title: "Potential prompt injection cues detected. Requires explicit mitigations and tests.",
             severity: "MEDIUM",
-            evidence: systemPromptLeaks.slice(0, 10).map((m) => `${m.file}:${m.line}:${m.preview}`),
+            evidence: injectionEvidence,
             requiredActions: [
                 "Add multi-layer prompt-injection protection: instruction hierarchy enforcement, content isolation, tool gating, and output validation.",
                 "Add a red-team test harness with injection payloads and exfil attempts."

package/dist/gate/checks/dependencies.js

@@ -2,7 +2,11 @@ import fg from "fast-glob";
 import { readFileSafe } from "../../repo/fs.js";
 export async function checkDependencies(_) {
     const findings = [];
+    const manifests = await fg(["package.json"], { dot: true });
     const lockfiles = await fg(["package-lock.json", "pnpm-lock.yaml", "yarn.lock"], { dot: true });
+    if (manifests.length === 0 && lockfiles.length === 0) {
+        return findings;
+    }
     if (lockfiles.length === 0) {
         findings.push({
             id: "LOCKFILE_MISSING",

package/dist/gate/checks/scanners.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { execa } from "execa";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "../../..");
+const ScannerSchema = z.object({
+    command: z.string(),
+    args: z.array(z.string()).default(["--version"]),
+    required_for: z.array(z.string()).default(["all"])
+});
+const ScannerConfigSchema = z.object({
+    version: z.string(),
+    fail_closed: z.boolean().default(true),
+    scanners: z.record(ScannerSchema)
+});
+async function loadScannerConfig() {
+    const overridePath = process.env["SECURITY_GATE_SCANNERS"];
+    if (overridePath) {
+        const raw = await readFile(join(process.cwd(), overridePath), "utf-8");
+        return ScannerConfigSchema.parse(JSON.parse(raw));
+    }
+    try {
+        const raw = await readFile(join(process.cwd(), ".mcp", "scanners", "security-tools.json"), "utf-8");
+        return ScannerConfigSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        const raw = await readFile(join(PKG_ROOT, "defaults", "security-tools.json"), "utf-8");
+        return ScannerConfigSchema.parse(JSON.parse(raw));
+    }
+}
+function scannerApplies(requiredFor, surfaces) {
+    const mobile = surfaces.mobileIos || surfaces.mobileAndroid;
+    if (requiredFor.includes("all"))
+        return true;
+    if (requiredFor.includes("web") && surfaces.web)
+        return true;
+    if (requiredFor.includes("api") && surfaces.api)
+        return true;
+    if (requiredFor.includes("infra") && surfaces.infra)
+        return true;
+    if (requiredFor.includes("ai") && surfaces.ai)
+        return true;
+    if (requiredFor.includes("mobile") && mobile)
+        return true;
+    return false;
+}
+async function commandExists(command, args) {
+    try {
+        const result = await execa(command, args, { reject: false });
+        return result.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function checkScannerReadiness(opts) {
+    const config = await loadScannerConfig();
+    const configured = [];
+    const missing = [];
+    const findings = [];
+    for (const [scannerId, scanner] of Object.entries(config.scanners)) {
+        if (!scannerApplies(scanner.required_for, opts.surfaces))
+            continue;
+        configured.push(scannerId);
+        if (!(await commandExists(scanner.command, scanner.args))) {
+            missing.push(scannerId);
+        }
+    }
+    if (missing.length > 0 && config.fail_closed) {
+        findings.push({
+            id: "SCANNER_TOOLCHAIN_INCOMPLETE",
+            title: "Required security scanners are not installed or not runnable",
+            severity: "HIGH",
+            evidence: missing,
+            requiredActions: [
+                "Install the missing scanners or adjust the approved scanner config intentionally.",
+                "Do not rely on heuristic checks alone when fail-closed scanner enforcement is enabled."
+            ]
+        });
+    }
+    return { findings, configured, missing };
+}

package/dist/gate/checks/secrets.js

@@ -1,36 +1,63 @@
-import { execa } from "execa";
+import fg from "fast-glob";
+import { readFileSafe } from "../../repo/fs.js";
+const SECRET_PATTERNS = [
+    { name: "private_key_pem", regex: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/ },
+    { name: "aws_access_key", regex: /\bAKIA[0-9A-Z]{16}\b/ },
+    { name: "google_api_key", regex: /\bAIza[0-9A-Za-z\-_]{35}\b/ },
+    { name: "slack_bot_token", regex: /\bxoxb-[0-9A-Za-z-]{20,}\b/ },
+    { name: "llm_api_key", regex: /\bsk-[A-Za-z0-9]{20,}\b/ },
+    { name: "secret_key_assignment", regex: /\bSECRET_KEY\s*[:=]\s*["'][^"'\n]{8,}["']/ },
+    { name: "private_key_assignment", regex: /\bPRIVATE_KEY\s*[:=]\s*["'][^"'\n]{16,}["']/ }
+];
+function previewLine(text, index) {
+    const lineStart = text.lastIndexOf("\n", index);
+    const lineEnd = text.indexOf("\n", index);
+    return text.slice(lineStart === -1 ? 0 : lineStart + 1, lineEnd === -1 ? undefined : lineEnd).trim();
+}
 export async function checkSecrets(_) {
-    // CI will also run gitleaks. This is a fast local heuristic backup.
     const findings = [];
-    const patterns = [
-        "-----BEGIN PRIVATE KEY-----",
-        "AKIA", // AWS access key prefix
-        "AIza", // Google API key prefix
-        "xoxb-", // Slack bot token
-        "sk-", // common LLM key prefix (OpenAI etc.)
-        "SECRET_KEY",
-        "PRIVATE_KEY"
-    ];
-    // Each pattern must be passed as a separate -e flag.
-    // Joining with | and using a single -e flag relies on ERE alternation, but
-    // git grep defaults to BRE where | is a literal character, not alternation —
-    // causing all patterns to be silently missed (false-negative). CWE-688.
-    const eFlags = patterns.flatMap((p) => ["-e", p]);
-    const { stdout } = await execa("git", 
-    // --no-index: search working tree without git index (covers untracked files)
-    // -l: list files with matches (reduce noise); -n: show line numbers
-    // -I: skip binary files
-    ["grep", "-n", "--no-index", "-I", ...eFlags, "."], { reject: false });
-    if (stdout.trim()) {
+    const files = await fg(["**/*.*"], {
+        dot: true,
+        onlyFiles: true,
+        ignore: [
+            "**/node_modules/**",
+            "**/.git/**",
+            "**/dist/**",
+            "**/fixtures/**",
+            "**/.mcp/reviews/**",
+            "**/.mcp/reports/**"
+        ]
+    });
+    const evidence = [];
+    for (const file of files) {
+        let text = "";
+        try {
+            text = await readFileSafe(file);
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of SECRET_PATTERNS) {
+            const match = pattern.regex.exec(text);
+            if (!match || match.index === undefined)
+                continue;
+            evidence.push(`${file}:${pattern.name}:${previewLine(text, match.index)}`);
+            if (evidence.length >= 25)
+                break;
+        }
+        if (evidence.length >= 25)
+            break;
+    }
+    if (evidence.length > 0) {
         findings.push({
             id: "POSSIBLE_SECRET",
-            title: "Potential secret material detected by heuristic scan",
+            title: "Potential secret material detected by whole-repo heuristic scan",
             severity: "CRITICAL",
-            evidence: stdout.split("\n").slice(0, 50),
+            evidence,
             requiredActions: [
-                "Remove secrets from repo immediately.",
+                "Remove secrets from the affected files immediately.",
                 "Rotate any exposed credentials.",
-                "Store secrets only in GCP Secret Manager. Do not log secrets."
+                "Store secrets only in a dedicated secret manager and keep them out of logs."
             ]
         });
     }

package/dist/gate/diff.js

@@ -1,10 +1,10 @@
 import { execa } from "execa";
 // Allowlist for git ref strings. Blocks option injection (e.g. --upload-pack=…)
 // and git pathspec magic characters. CWE-88 / MITRE ATT&CK T1059.
-const SAFE_REF_RE = /^[a-zA-Z0-9_.\-/]+$/;
+const SAFE_REF_RE = /^[a-zA-Z0-9_./~^-]+$/;
 function validateRef(name, value) {
     if (!value || !SAFE_REF_RE.test(value)) {
-        throw new Error(`Invalid git ref for ${name}: must contain only alphanumerics, _, ., -, /`);
+        throw new Error(`Invalid git ref for ${name}: must contain only alphanumerics, _, ., -, /, ~, ^`);
     }
 }
 export async function getChangedFiles(opts) {

package/dist/gate/evidence.js

@@ -0,0 +1,116 @@
+import { readFile } from "node:fs/promises";
+import fg from "fast-glob";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadControlCatalog, controlApplies } from "./catalog.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "../..");
+async function loadEvidenceMap() {
+    const overridePath = process.env["SECURITY_GATE_EVIDENCE_MAP"];
+    if (overridePath) {
+        const raw = await readFile(join(process.cwd(), overridePath), "utf-8");
+        return JSON.parse(raw);
+    }
+    try {
+        const raw = await readFile(join(process.cwd(), ".mcp", "mappings", "evidence-map.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        const raw = await readFile(join(PKG_ROOT, "defaults", "evidence-map.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+}
+function getPolicyControl(policy, control) {
+    return policy.requirements.find((requirement) => requirement.id === control.id);
+}
+export async function evaluateEvidenceCoverage(opts) {
+    const evidenceMap = await loadEvidenceMap();
+    const catalog = await loadControlCatalog();
+    const findings = [];
+    const controls = [];
+    for (const control of catalog.controls) {
+        if (!controlApplies(control, opts.surfaces)) {
+            controls.push({
+                id: control.id,
+                description: control.description,
+                automation: control.automation,
+                frameworks: control.frameworks,
+                status: "not_applicable",
+                details: ["Surface not in scope for this review."]
+            });
+            continue;
+        }
+        if (control.automation !== "evidence") {
+            controls.push({
+                id: control.id,
+                description: control.description,
+                automation: control.automation,
+                frameworks: control.frameworks,
+                status: "not_applicable",
+                details: ["Resolved outside evidence coverage evaluation."]
+            });
+            continue;
+        }
+        const policyControl = getPolicyControl(opts.policy, control);
+        const evidenceIds = policyControl?.evidence ?? control.evidence ?? [];
+        const missingMappings = evidenceIds.filter((evidenceId) => !evidenceMap[evidenceId]);
+        if (missingMappings.length > 0) {
+            findings.push({
+                id: "EVIDENCE_MAPPING_MISSING",
+                title: `Evidence mapping missing for control ${control.id}`,
+                severity: "HIGH",
+                evidence: missingMappings,
+                requiredActions: [
+                    "Add the missing evidence IDs to .mcp/mappings/evidence-map.json.",
+                    "Map each control to file globs that prove the control exists."
+                ]
+            });
+        }
+        const matchedEvidence = [];
+        const missingEvidence = [];
+        for (const evidenceId of evidenceIds) {
+            const globs = evidenceMap[evidenceId] ?? [];
+            const matches = await fg(globs, {
+                dot: true,
+                onlyFiles: true,
+                ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
+            });
+            if (matches.length === 0) {
+                missingEvidence.push(evidenceId);
+            }
+            else {
+                matchedEvidence.push(`${evidenceId}: ${matches[0]}`);
+            }
+        }
+        if (missingEvidence.length > 0) {
+            findings.push({
+                id: "CONTROL_EVIDENCE_MISSING",
+                title: `Required evidence missing for control ${control.id}`,
+                severity: "HIGH",
+                evidence: missingEvidence,
+                requiredActions: [
+                    `Implement or surface evidence for control ${control.id}.`,
+                    "Add or update code, tests, or config so the evidence globs resolve."
+                ]
+            });
+            controls.push({
+                id: control.id,
+                description: control.description,
+                automation: control.automation,
+                frameworks: control.frameworks,
+                status: "missing",
+                details: missingEvidence
+            });
+            continue;
+        }
+        controls.push({
+            id: control.id,
+            description: control.description,
+            automation: control.automation,
+            frameworks: control.frameworks,
+            status: "satisfied",
+            details: matchedEvidence
+        });
+    }
+    return { findings, controls };
+}

package/dist/gate/exceptions.js

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "../..");
+const ExceptionSchema = z.object({
+    id: z.string(),
+    finding_ids: z.array(z.string()).default([]),
+    control_ids: z.array(z.string()).default([]),
+    justification: z.string(),
+    ticket: z.string().optional(),
+    owner: z.string(),
+    approver: z.string(),
+    approval_role: z.string(),
+    expires_on: z.string()
+});
+const ExceptionFileSchema = z.object({
+    version: z.string(),
+    exceptions: z.array(ExceptionSchema).default([])
+});
+async function readExceptionsJson() {
+    const overridePath = process.env["SECURITY_GATE_EXCEPTIONS"];
+    if (overridePath) {
+        return await readFile(join(process.cwd(), overridePath), "utf-8");
+    }
+    try {
+        return await readFile(join(process.cwd(), ".mcp", "exceptions", "security-exceptions.json"), "utf-8");
+    }
+    catch {
+        return await readFile(join(PKG_ROOT, "defaults", "security-exceptions.json"), "utf-8");
+    }
+}
+export async function loadSecurityExceptions() {
+    const raw = await readExceptionsJson();
+    return ExceptionFileSchema.parse(JSON.parse(raw)).exceptions;
+}
+export async function applySecurityExceptions(findings) {
+    const exceptions = await loadSecurityExceptions();
+    const active = [];
+    const suppressed = [];
+    const exceptionFindings = [];
+    const activeControlExceptionIds = new Set();
+    for (const entry of exceptions) {
+        const expiresAt = new Date(entry.expires_on);
+        if (!Number.isNaN(expiresAt.getTime()) && expiresAt.getTime() >= Date.now()) {
+            for (const controlId of entry.control_ids) {
+                activeControlExceptionIds.add(controlId);
+            }
+        }
+    }
+    for (const finding of findings) {
+        const match = exceptions.find((entry) => entry.finding_ids.includes(finding.id));
+        if (!match) {
+            active.push(finding);
+            continue;
+        }
+        const expiresAt = new Date(match.expires_on);
+        if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() < Date.now()) {
+            active.push(finding);
+            exceptionFindings.push({
+                id: "SECURITY_EXCEPTION_EXPIRED",
+                title: `Security exception ${match.id} is expired or invalid`,
+                severity: "HIGH",
+                evidence: [`Finding: ${finding.id}`, `Owner: ${match.owner}`, `Expires: ${match.expires_on}`],
+                requiredActions: [
+                    "Renew or remove the expired exception.",
+                    "Resolve the underlying finding or obtain a new approved exception."
+                ]
+            });
+            continue;
+        }
+        suppressed.push({
+            finding,
+            exceptionId: match.id,
+            expiresOn: match.expires_on
+        });
+    }
+    return {
+        findings: active,
+        suppressed,
+        exceptionFindings,
+        activeControlExceptionIds: Array.from(activeControlExceptionIds)
+    };
+}