@avi770/testteam 3.0.0 → 3.2.0

package/dist/core/security-audit/sentinel.js

@@ -0,0 +1,725 @@
+import { ENGINE_MODULE, } from './types.js';
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+const AGENT_ID = 8;
+/** Approximate cost units per scan tier. Used by the frugal governor. */
+const SCAN_COST = {
+    passive: 1,
+    headerCheck: 2,
+    cveReachability: 3,
+    iacCheck: 3,
+    activeEndpoint: 5,
+    sandboxExploit: 10,
+    deepDast: 20,
+};
+/** Severity weights for priority scoring (show-the-math). */
+const SEVERITY_WEIGHT = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0.5,
+};
+/** Blast-radius multiplier per data-sensitivity tier. */
+const BLAST_RADIUS_WEIGHT = {
+    public: 0.5,
+    internal: 1.0,
+    pii: 2.0,
+    phi: 3.0,
+    payment: 3.0,
+};
+/**
+ * Compliance tags by engine module name.
+ * Uses ENGINE_MODULE constants so renames cause compile errors here, not silent mismatches.
+ */
+const COMPLIANCE_TAGS_BY_MODULE = {
+    [ENGINE_MODULE.SECURITY_HEADERS]: ['SOC2-CC6.1', 'OWASP-ASVS-14.4'],
+    [ENGINE_MODULE.AUTH_FUZZER]: ['SOC2-CC6.6', 'OWASP-ASVS-2.1', 'CWE-287'],
+    [ENGINE_MODULE.CSRF_TESTER]: ['OWASP-ASVS-4.2', 'CWE-352'],
+    [ENGINE_MODULE.XSS_SCANNER]: ['OWASP-ASVS-5.3', 'CWE-79'],
+    [ENGINE_MODULE.DEPENDENCY_SCANNER]: ['SOC2-CC7.1', 'PCI-6.3'],
+    [ENGINE_MODULE.SECRETS_SCANNER]: ['SOC2-CC6.7', 'CWE-798', 'GDPR-Art5'],
+    'iac': ['SOC2-CC6.3', 'CWE-732'],
+};
+// ---------------------------------------------------------------------------
+// Utility helpers
+// ---------------------------------------------------------------------------
+/** Generate a deterministic scan ID from timestamp (no random — reproducible in tests). */
+function makeScanId(nowMs) {
+    return `sentinel-scan-${nowMs}`;
+}
+/** Severity order for comparison (higher index = higher severity). */
+const SEVERITY_ORDER = ['info', 'low', 'medium', 'high', 'critical'];
+function maxSeverity(a, b) {
+    return SEVERITY_ORDER.indexOf(a) >= SEVERITY_ORDER.indexOf(b) ? a : b;
+}
+/**
+ * Truncate to 2 decimals WITHOUT rounding up (Avi's QA standard). Used for the posture
+ * score so strictly-increasing harmonic penalties stay strictly distinct at 2dp precision
+ * (integer Math.floor tied scores once the marginal penalty dropped below 1 — MF-4).
+ */
+function truncate2(n) {
+    return Math.trunc(n * 100) / 100;
+}
+/**
+ * Combine severity for an attack path.
+ * Path severity = worst-step severity. We never invent a severity higher than what's present.
+ * Show-the-math: the description explains the derivation.
+ */
+function computePathSeverity(steps) {
+    return steps.reduce((acc, s) => maxSeverity(acc, s.finding.severity), 'info');
+}
+/** Stable, deterministic sort key — no ties break randomly. */
+function priorityScore(finding, epss, blastRadiusWeight) {
+    const sw = SEVERITY_WEIGHT[finding.severity] ?? 1;
+    // Multiply, not add — each dimension is a gate, not a fallback.
+    return sw * epss * blastRadiusWeight;
+}
+/** Compliance tags for a finding (best-effort; extensible). */
+function complianceTags(finding) {
+    return COMPLIANCE_TAGS_BY_MODULE[finding.module] ?? [];
+}
+/** Deduplicate findings by id; last-write wins. */
+function dedup(findings) {
+    const map = new Map();
+    for (const f of findings) {
+        map.set(f.id, f);
+    }
+    return [...map.values()];
+}
+/** Remove findings whose id is in the accepted baseline (known-risk suppression). */
+function applyBaseline(findings, baseline) {
+    if (!baseline || baseline.size === 0)
+        return [...findings];
+    return findings.filter((f) => !baseline.has(f.id));
+}
+/** Determine which endpoints to skip (contentHash unchanged since last scan). */
+function computeSkippedEndpoints(target, scanBaseline) {
+    if (!scanBaseline)
+        return new Set();
+    const skipped = new Set();
+    for (const ep of target.endpoints) {
+        if (scanBaseline[ep.id] === ep.contentHash) {
+            skipped.add(ep.id);
+        }
+    }
+    return skipped;
+}
+// ---------------------------------------------------------------------------
+// Frugal governor
+// ---------------------------------------------------------------------------
+/**
+ * FrugalGovernor tracks units consumed and enforces the budget.
+ * Cheapest-highest-value checks are registered first; the governor halts
+ * before queuing expensive work when the budget is exhausted.
+ *
+ * FAIL-CLOSED: tryConsume() returning false NEVER means "proceed as if clean".
+ * Callers MUST record the skipped phase in skippedChecks and mark the scan
+ * budgetTruncated=true. Skipped phases are explicitly surfaced to the caller.
+ */
+export class FrugalGovernor {
+    consumed = 0;
+    total;
+    halted = false;
+    constructor(totalUnits) {
+        if (!Number.isFinite(totalUnits) || totalUnits < 0) {
+            throw new Error(`[Sentinel] FrugalGovernor: invalid totalUnits ${String(totalUnits)}`);
+        }
+        this.total = totalUnits;
+    }
+    /**
+     * Try to consume `units`.
+     * Returns true if within budget and units were consumed; false if budget exceeded.
+     * On false: the CALLER must record the skipped check name in skippedChecks[].
+     */
+    tryConsume(units) {
+        if (this.consumed + units > this.total) {
+            this.halted = true;
+            return false;
+        }
+        this.consumed += units;
+        return true;
+    }
+    result(reason) {
+        const unitsRemaining = Math.max(0, this.total - this.consumed);
+        return {
+            decision: this.halted ? 'halt' : 'proceed',
+            unitsConsumed: this.consumed,
+            unitsRemaining,
+            reason,
+        };
+    }
+    get remaining() {
+        return Math.max(0, this.total - this.consumed);
+    }
+    get wasHalted() {
+        return this.halted;
+    }
+}
+// ---------------------------------------------------------------------------
+// CVE reachability gate
+// ---------------------------------------------------------------------------
+/**
+ * Filter CVE entries by reachability.
+ * Returns { alertable, suppressed }.
+ * Spec: "Reachability-gated CVE triage — only alert on dependency CVEs whose vulnerable
+ * function is actually reachable in the call graph."
+ */
+export function partitionCvesByReachability(cves) {
+    const alertable = [];
+    const suppressed = [];
+    for (const cve of cves) {
+        if (cve.reachable) {
+            alertable.push(cve);
+        }
+        else {
+            suppressed.push(cve);
+        }
+    }
+    return { alertable, suppressed };
+}
+/** Convert a reachable CVE into a Finding (type code-bug-security). */
+export function cveToFinding(cve) {
+    let severity;
+    if (cve.cvssScore >= 9.0)
+        severity = 'critical';
+    else if (cve.cvssScore >= 7.0)
+        severity = 'high';
+    else if (cve.cvssScore >= 4.0)
+        severity = 'medium';
+    else
+        severity = 'low';
+    // Structured id embeds both packageName and cveId for unambiguous correlation.
+    return {
+        id: `${AGENT_ID}-cve-${cve.cveId}-${cve.packageName}`,
+        type: 'code-bug-security',
+        severity,
+        agentId: AGENT_ID,
+        module: ENGINE_MODULE.DEPENDENCY_SCANNER,
+        description: `[Sentinel] Reachable CVE ${cve.cveId} in ${cve.packageName} — CVSS ${cve.cvssScore}, EPSS ${cve.epss}${cve.inKev ? ', in CISA KEV' : ''}`,
+        // Structured fields so rankFindings can correlate on packageName without substring matching.
+        // file is reused as the package identifier (colon-separated for clarity).
+        file: `pkg:${cve.packageName}@${cve.packageVersion ?? 'unknown'}`,
+        confidence: cve.epss,
+        provenance: 'CVE/KEV/EPSS feed',
+        trustClass: 'untrusted', // derived from external feed; never auto-actuates
+    };
+}
+// ---------------------------------------------------------------------------
+// Canary token check
+// ---------------------------------------------------------------------------
+/**
+ * Check if any canary token values appear in the provided content string.
+ * Used in passive analysis of telemetry/logs without triggering real network calls.
+ */
+export function detectCanaryUse(tokens, observedContent, source, nowMs) {
+    const alerts = [];
+    for (const token of tokens) {
+        if (observedContent.includes(token.value)) {
+            alerts.push({
+                tokenId: token.tokenId,
+                label: token.label,
+                triggeredAt: nowMs,
+                source,
+            });
+        }
+    }
+    return alerts;
+}
+// ---------------------------------------------------------------------------
+// Exploit-chain analysis
+// ---------------------------------------------------------------------------
+/**
+ * Chain ≥2 low/medium findings into attack paths.
+ * Spec: "Chains ≥2 seeded low findings into a correct attack path."
+ *
+ * Strategy: pair any finding that represents an information-leak / enumeration
+ * risk (missing auth, missing header, info-disclosure) with any finding that
+ * represents a direct access path (IDOR, auth bypass, injection) — their
+ * combination forms a kill-chain. We generate at most one path per pair to
+ * avoid exponential blowup.
+ *
+ * Each path is assigned the max severity of its constituent findings.
+ */
+export function buildAttackPaths(findings) {
+    // Classify findings by role: enablers vs exploits.
+    // Uses ENGINE_MODULE constants so engine-agent renames surface here.
+    const enablers = findings.filter((f) => f.module === ENGINE_MODULE.SECURITY_HEADERS ||
+        f.description.toLowerCase().includes('missing') ||
+        f.description.toLowerCase().includes('header') ||
+        f.description.toLowerCase().includes('rate') ||
+        f.description.toLowerCase().includes('lockout'));
+    const exploits = findings.filter((f) => f.module === ENGINE_MODULE.AUTH_FUZZER ||
+        f.module === ENGINE_MODULE.CSRF_TESTER ||
+        f.module === ENGINE_MODULE.XSS_SCANNER ||
+        f.description.toLowerCase().includes('bypass') ||
+        f.description.toLowerCase().includes('injection') ||
+        f.description.toLowerCase().includes('xss') ||
+        f.description.toLowerCase().includes('idor'));
+    const paths = [];
+    let pathSeq = 0;
+    for (const enabler of enablers) {
+        for (const exploit of exploits) {
+            // Avoid pairing a finding with itself
+            if (enabler.id === exploit.id)
+                continue;
+            // Surface-correlation gate: when BOTH findings carry a target surface (file/endpoint)
+            // they must SHARE it — an enabler on /login does not chain with an exploit on an
+            // unrelated /public page (which would fabricate a kill-chain and inflate the score
+            // deduction). When surface info is absent (engine findings without a file), fall back
+            // to the role classification above (best-effort).
+            if (enabler.file !== undefined &&
+                exploit.file !== undefined &&
+                enabler.file !== exploit.file) {
+                continue;
+            }
+            const steps = [
+                { finding: enabler, role: 'enabler' },
+                { finding: exploit, role: 'exploit' },
+            ];
+            const combinedSeverity = computePathSeverity(steps);
+            paths.push({
+                id: `path-${pathSeq++}-${enabler.id}-${exploit.id}`,
+                steps,
+                combinedSeverity,
+                description: `Chain: "${enabler.description.slice(0, 60)}" + ` +
+                    `"${exploit.description.slice(0, 60)}" → ${combinedSeverity.toUpperCase()} kill-chain`,
+            });
+        }
+    }
+    return paths;
+}
+// ---------------------------------------------------------------------------
+// IaC / posture check (pure, fixture-driven)
+// ---------------------------------------------------------------------------
+/**
+ * Check IaC config blobs for known misconfigurations.
+ * Each blob is analysed by keyword pattern matching against community rule
+ * patterns (Checkov/tfsec rule names, not re-implemented here).
+ * Real integration plugs in the Checkov/tfsec JSON output; this layer models
+ * the decision logic that consumes that output.
+ */
+export function checkIacBlobs(iacBlobs) {
+    const findings = [];
+    let seq = 0;
+    const isS3 = (b) => b.includes('aws_s3_bucket');
+    const isSecurityGroup = (b) => b.includes('aws_security_group') || b.includes('ingress') || b.includes('cidr_blocks');
+    const isDockerfile = (b) => /(^|\n)\s*FROM\s/i.test(b);
+    const isK8sManifest = (b) => b.includes('apiVersion:') || b.includes('kind:');
+    const isTerraformModule = (b) => b.includes('required_providers') || /terraform\s*\{/.test(b) || /provider\s+"/.test(b);
+    const rules = [
+        { rule: 'CKV_AWS_18', description: 'S3 bucket access logging is not enabled', severity: 'medium', keyword: 'access_logs', mode: 'absence', appliesTo: isS3 },
+        { rule: 'CKV_AWS_19', description: 'S3 bucket encryption is not enabled', severity: 'high', keyword: 'server_side_encryption', mode: 'absence', appliesTo: isS3 },
+        { rule: 'CKV_AWS_23', description: 'Security group allows unrestricted ingress from 0.0.0.0/0', severity: 'critical', keyword: '0.0.0.0/0', mode: 'presence', appliesTo: isSecurityGroup },
+        { rule: 'CKV_DOCKER_2', description: 'Dockerfile does not use non-root USER', severity: 'medium', keyword: 'USER', mode: 'absence', appliesTo: isDockerfile },
+        { rule: 'CKV_K8S_8', description: 'Containers run as root', severity: 'high', keyword: 'runAsNonRoot', mode: 'absence', appliesTo: isK8sManifest },
+        { rule: 'CKV_TF_1', description: 'Terraform module does not enforce version pinning', severity: 'low', keyword: 'version =', mode: 'absence', appliesTo: isTerraformModule },
+    ];
+    for (const [resourceName, blobContent] of Object.entries(iacBlobs)) {
+        for (const r of rules) {
+            if (!r.appliesTo(blobContent))
+                continue; // scope the rule to the right resource type
+            const hit = r.mode === 'absence' ? !blobContent.includes(r.keyword) : blobContent.includes(r.keyword);
+            if (hit) {
+                findings.push({
+                    id: `${AGENT_ID}-iac-${r.rule}-${seq++}`,
+                    resource: resourceName,
+                    rule: r.rule,
+                    description: `[Sentinel/IaC] ${r.description} in "${resourceName}"`,
+                    severity: r.severity,
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Safe proof-of-exploit (staging only) — MF-2 FIX
+// ---------------------------------------------------------------------------
+/**
+ * Simulate a proof-of-exploit record for a finding AGAINST STAGING ONLY.
+ *
+ * SAFETY — RUNTIME GUARD (MF-2):
+ *  1. prodBaseUrl and stagingBaseUrl must NOT be equal strings — if they are,
+ *     we cannot tell them apart and refusing to proceed is the only safe choice.
+ *  2. The requestDetail always embeds stagingBaseUrl, never prodBaseUrl.
+ *  3. The return type's environment field is typed as 'staging' (literal),
+ *     guaranteeing the caller cannot pass a prod URL undetected at the type level.
+ *
+ * In production integration, this would invoke ZAP/Nuclei against staging.
+ * Here it models the outcome of that test deterministically from the finding.
+ *
+ * @throws Error if prodBaseUrl === stagingBaseUrl (fail-closed safety rule).
+ */
+export function buildProofOfExploit(finding, stagingBaseUrl, nowMs, prodBaseUrl) {
+    // RUNTIME guard: if the caller can supply prodBaseUrl, reject equality.
+    // This is the hard fence that makes "staging only" enforceable at runtime.
+    if (prodBaseUrl !== undefined && prodBaseUrl !== '' && prodBaseUrl === stagingBaseUrl) {
+        throw new Error(`[Sentinel] SAFETY VIOLATION: prodBaseUrl and stagingBaseUrl are identical ("${stagingBaseUrl}"). ` +
+            `Proof-of-exploit cannot safely target this URL — it may be production. Aborting.`);
+    }
+    return {
+        findingId: finding.id,
+        environment: 'staging',
+        requestDetail: `[Sentinel/PoE] Reproduce "${finding.description}" against ${stagingBaseUrl} — non-destructive probe`,
+        observedResult: `Finding confirmed in sandbox (${finding.severity.toUpperCase()})`,
+        confirmed: true,
+        ranAtMs: nowMs,
+    };
+}
+// ---------------------------------------------------------------------------
+// Virtual patch drafts
+// ---------------------------------------------------------------------------
+/** Draft a WAF rule / mitigation for a finding. For human apply only; never auto-applied. */
+export function draftVirtualPatch(finding) {
+    let patchContent;
+    if (finding.module === ENGINE_MODULE.SECURITY_HEADERS) {
+        const header = finding.description.match(/Missing security header: (.+)/)?.[1] ?? 'unknown-header';
+        patchContent = `# WAF header-injection rule (NGINX/Caddy/CloudFront)\nadd_header ${header} "ENABLE" always;`;
+    }
+    else if (finding.module === ENGINE_MODULE.AUTH_FUZZER) {
+        patchContent = `# WAF rate-limit rule — block auth brute-force\nlimit_req_zone $binary_remote_addr zone=auth:10m rate=5r/m;\nlimit_req zone=auth burst=5;`;
+    }
+    else if (finding.module === ENGINE_MODULE.CSRF_TESTER) {
+        patchContent = `# Middleware: enforce CSRF token on all state-mutating requests\n# Require X-CSRF-Token header; reject without 403.`;
+    }
+    else if (finding.module === ENGINE_MODULE.XSS_SCANNER) {
+        patchContent = `# WAF: block reflective XSS patterns\nSecRule ARGS "@rx <script|onerror=" "deny,log,id:1001"`;
+    }
+    else {
+        patchContent = `# Virtual patch for "${finding.id}" — see description for manual remediation guidance`;
+    }
+    return {
+        findingId: finding.id,
+        patchContent,
+        rationale: `Mitigates "${finding.description.slice(0, 80)}" while the real fix is built. DRAFT — apply manually after review.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Secret rotation runbook
+// ---------------------------------------------------------------------------
+/** Draft a secret-rotation runbook for a secrets-scanner finding. For human apply only. */
+export function draftRotationRunbook(finding, keyStillActive) {
+    return {
+        secretLabel: finding.description.slice(0, 80),
+        steps: [
+            '1. Verify the secret is still active (check auth against the issuing service).',
+            '2. Revoke / rotate the secret at the issuing service.',
+            '3. Update all secrets managers and environment configs to the new value.',
+            '4. Deploy the new config and confirm the service is functional.',
+            '5. Confirm the old secret no longer authenticates (attempt and expect 401).',
+            '6. Audit VCS history to confirm the secret is not present in earlier commits; rotate if so.',
+            `7. Finding reference: ${finding.id} in ${finding.file ?? finding.module} (line ${String(finding.line ?? 'unknown')}).`,
+        ],
+        keyStillActive,
+    };
+}
+// ---------------------------------------------------------------------------
+// Posture scoring (show-the-math; floor, never ceil) — MF-4 FIX
+// ---------------------------------------------------------------------------
+/**
+ * Compute a security posture score 0–100.
+ * Deductions are itemised; score is Math.floor, never rounded up.
+ * Spec: "no gameable scoring"; "show-the-math transparency".
+ *
+ * MF-4 FIX: Replaces per-severity caps with a monotonic diminishing-returns formula.
+ * Each additional finding of the same severity adds a smaller (but nonzero) marginal
+ * penalty using: penalty(n) = perFinding × ∑_{i=1}^{n} (1 / i)  [harmonic series].
+ * This guarantees:
+ *   - penalty is strictly increasing with n (N+1 criticals score strictly below N).
+ *   - No hard cap; any number of criticals keeps reducing the score.
+ *   - Diminishing returns prevent a single category from zeroing the score alone
+ *     while still guaranteeing monotonicity.
+ * Combined with attack-path deductions, the score can still reach 0.
+ */
+export function computePostureScore(findings, attackPaths, nowMs) {
+    const deductions = [];
+    let raw = 100;
+    // Count findings by severity
+    const counts = {
+        critical: 0, high: 0, medium: 0, low: 0, info: 0,
+    };
+    for (const f of findings) {
+        counts[f.severity]++;
+    }
+    /**
+     * Monotonic harmonic penalty for `count` findings at `perFinding` base weight.
+     * penalty(n) = perFinding × H(n)  where H(n) = 1 + 1/2 + 1/3 + … + 1/n.
+     * Strictly increasing: penalty(n+1) > penalty(n) for all n ≥ 0 with count > 0.
+     */
+    function harmonicPenalty(count, perFinding) {
+        let h = 0;
+        for (let i = 1; i <= count; i++) {
+            h += 1 / i;
+        }
+        return perFinding * h;
+    }
+    // Deduction rules: [severity, per-finding-base-weight]
+    // No caps — monotonic penalty guarantees N+1 criticals score strictly lower than N.
+    const deductionRules = [
+        ['critical', 20],
+        ['high', 8],
+        ['medium', 3],
+        ['low', 1],
+    ];
+    for (const [severity, perFinding] of deductionRules) {
+        const count = counts[severity];
+        if (count > 0) {
+            const pts = harmonicPenalty(count, perFinding);
+            deductions.push({
+                reason: `${count} ${severity} finding(s); harmonic penalty (base ${perFinding}pts × H(${count}))`,
+                points: pts,
+            });
+            raw -= pts;
+        }
+    }
+    // Attack path deduction — also monotonic harmonic
+    if (attackPaths.length > 0) {
+        const pts = harmonicPenalty(attackPaths.length, 10);
+        deductions.push({
+            reason: `${attackPaths.length} attack path(s); harmonic penalty (base 10pts × H(${attackPaths.length}))`,
+            points: pts,
+        });
+        raw -= pts;
+    }
+    // Truncate to 2dp at/above 0 (never round up). Integer Math.floor previously TIED
+    // scores once the marginal harmonic penalty fell below 1 (e.g. 26 vs 27 criticals
+    // both floored to 22); 2dp truncation keeps strict monotonicity to ~2000 findings.
+    const score = truncate2(Math.max(0, raw));
+    let grade;
+    if (score >= 90)
+        grade = 'A';
+    else if (score >= 75)
+        grade = 'B';
+    else if (score >= 60)
+        grade = 'C';
+    else if (score >= 40)
+        grade = 'D';
+    else
+        grade = 'F';
+    return {
+        score,
+        grade,
+        deductions,
+        calculatedAt: new Date(nowMs).toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Ranking — MF-5 FIX: structured CVE correlation
+// ---------------------------------------------------------------------------
+/**
+ * Rank findings by severity × EPSS × blast-radius (descending).
+ * Show-the-math: each component is preserved on the RankedFinding.
+ * EPSS defaults to 0.5 when unknown (conservative assumption, not zero).
+ *
+ * MF-5 FIX: CVE correlation is done via structured package-name matching
+ * against the Finding.file field (formatted as "pkg:<name>@<version>" by
+ * cveToFinding), NOT substring-of-description. This prevents false matches
+ * for short package names like "os", "fs", "ms".
+ *
+ * For non-CVE findings, EPSS defaults to 0.5.
+ */
+export function rankFindings(findings, cveIndex, blastRadiusWeight) {
+    const ranked = findings.map((f) => {
+        const sw = SEVERITY_WEIGHT[f.severity] ?? 1;
+        // Structured CVE correlation: match on pkg:<packageName>@ prefix in f.file.
+        // This avoids false-positive substring matches on short names (os/fs/ms).
+        let epss = 0.5; // default when no CVE correlation
+        if (f.file?.startsWith('pkg:')) {
+            // f.file format: "pkg:<packageName>@<version>"
+            const pkgPart = f.file.slice(4); // drop "pkg:"
+            const atIdx = pkgPart.indexOf('@');
+            const pkgName = atIdx >= 0 ? pkgPart.slice(0, atIdx) : pkgPart;
+            // Exact package-name match (not substring). When a package has multiple CVEs,
+            // take the MAX EPSS so ranking is deterministic regardless of CVE iteration order.
+            let matched = false;
+            for (const cve of cveIndex.values()) {
+                if (cve.packageName === pkgName) {
+                    epss = matched ? Math.max(epss, cve.epss) : cve.epss;
+                    matched = true;
+                }
+            }
+        }
+        const ps = priorityScore(f, epss, blastRadiusWeight);
+        return {
+            finding: f,
+            priorityScore: ps,
+            severityWeight: sw,
+            epss,
+            blastRadiusWeight,
+            complianceTags: complianceTags(f),
+        };
+    });
+    // Sort descending (highest priority first); stable-ish via id tiebreak
+    return ranked.sort((a, b) => {
+        const diff = b.priorityScore - a.priorityScore;
+        if (diff !== 0)
+            return diff;
+        return a.finding.id.localeCompare(b.finding.id);
+    });
+}
+// ---------------------------------------------------------------------------
+// The Sentinel — main orchestration class
+// ---------------------------------------------------------------------------
+/**
+ * The Sentinel orchestrates the security engine agents and provides the
+ * continuous production security layer. It is a pure, fixture/event-driven
+ * class — it accepts pre-collected engine findings as inputs and composes
+ * them into a ranked, chained, baseline-diffed SecurityScanResult.
+ *
+ * Rationale: engine agents (07, 34–38) each run I/O (HTTP, FS, browser).
+ * The Sentinel's job is the higher-order logic: deduplicate, chain,
+ * gate on reachability, rank, score, and escalate. Tests inject findings
+ * directly, avoiding live network calls.
+ *
+ * Engine-agent contract (MF-7):
+ *  - MODULE_NAME constants in ENGINE_MODULE are imported from ./types.
+ *    They match the `module` field values emitted by agents 07/34–38
+ *    ('security-headers', 'xss-scanner', 'csrf-tester', 'auth-fuzzer',
+ *     'dependency-scanner', 'secrets-scanner').
+ *  - A rename in an engine agent is NOT compiler-caught here (best-effort string match);
+ *    the ENFORCED coupling is the integration test asserting COMPOSED_ENGINE_AGENTS exist
+ *    as registered 'security'-squad agents (renumber/regroup breaks the build).
+ *  - Integration tests in __tests__/security-audit.test.ts drive realistic
+ *    engine-output shapes (findings with correct module values) through
+ *    the pipeline and assert the composition contract end-to-end.
+ */
+export class SecuritySentinel {
+    config;
+    now;
+    constructor(config) {
+        this.config = config;
+        this.now = config.clock ?? (() => Date.now());
+    }
+    /**
+     * Run a sentinel scan.
+     *
+     * @param target       — scan surface description.
+     * @param engineFindings — pre-collected findings from engine agents 07/34–38.
+     * @param cves         — enriched CVE entries (from KEV/EPSS feeds via The Net).
+     * @param canaryContent — telemetry/log content to check canary tokens against.
+     * @param canarySource  — label describing where canaryContent came from.
+     *
+     * FAIL-CLOSED (MF-3): when budget is exhausted mid-scan, the skipped check name
+     * is appended to skippedChecks[] and budgetTruncated is set to true in the result.
+     * A budget-truncated scan is NEVER treated as clean — callers must check budgetTruncated.
+     *
+     * PROD SAFETY (MF-2): buildProofOfExploit is called with both stagingBaseUrl AND
+     * prodBaseUrl so the runtime guard can reject prod === staging equality.
+     */
+    scan(target, engineFindings, cves, canaryContent, canarySource) {
+        const nowMs = this.now();
+        // Fail-closed target-safety gate (MF-2): if prod and staging resolve to the same URL we
+        // cannot tell them apart, so any active probe could hit production. Refuse up front —
+        // regardless of whether a critical finding would later trigger a proof-of-exploit.
+        if (target.prodBaseUrl !== '' && target.prodBaseUrl === target.stagingBaseUrl) {
+            throw new Error(`[Sentinel] SAFETY VIOLATION: prodBaseUrl and stagingBaseUrl are identical ` +
+                `("${target.stagingBaseUrl}"). Refusing to scan — cannot guarantee staging-only actions.`);
+        }
+        const governor = new FrugalGovernor(this.config.budget.totalUnits);
+        const blastWeight = BLAST_RADIUS_WEIGHT[target.dataSensitivity];
+        const skippedChecks = [];
+        // 1. Diff-aware: compute which endpoints to skip (contentHash unchanged).
+        const skippedEndpoints = computeSkippedEndpoints(target, this.config.scanBaseline);
+        // 2. Passive check (cheapest first) — canary tokens.
+        const canaryAlerts = (() => {
+            if (!governor.tryConsume(SCAN_COST['passive'])) {
+                skippedChecks.push('canary-token-check');
+                return [];
+            }
+            return detectCanaryUse(this.config.canaryTokens ?? [], canaryContent, canarySource, nowMs);
+        })();
+        // 3. CVE reachability gate.
+        const { alertable: reachableCves, suppressed: suppressedUnreachableCves } = (() => {
+            if (!governor.tryConsume(SCAN_COST['cveReachability'])) {
+                skippedChecks.push('cve-reachability-gate');
+                return { alertable: [], suppressed: [] };
+            }
+            return partitionCvesByReachability(cves);
+        })();
+        // 4. Convert reachable CVEs to findings and merge with engine findings.
+        const cveFindings = reachableCves.map(cveToFinding);
+        // 5. IaC posture check.
+        const iacFindings = (() => {
+            if (!governor.tryConsume(SCAN_COST['iacCheck'])) {
+                skippedChecks.push('iac-posture-check');
+                return [];
+            }
+            return [...checkIacBlobs(target.iacBlobs)];
+        })();
+        // 6. Merge + dedup + baseline-diff all findings.
+        const allRaw = dedup([...engineFindings, ...cveFindings]);
+        const newFindings = applyBaseline(allRaw, this.config.acceptedBaseline);
+        // 7. Exploit-chain analysis.
+        const attackPaths = buildAttackPaths(newFindings);
+        // 8. Rank findings.
+        const cveIndex = new Map(cves.map((c) => [c.cveId, c]));
+        const rankedFindings = rankFindings(newFindings, cveIndex, blastWeight);
+        // 9. Active checks — sandbox proof-of-exploit for critical/high findings
+        //    (staging only; gated by budget; never prod).
+        //    MF-2: pass prodBaseUrl so runtime guard can catch staging===prod equality.
+        const proofOfExploits = [];
+        for (const rf of rankedFindings) {
+            if (rf.finding.severity !== 'critical' && rf.finding.severity !== 'high')
+                continue;
+            if (!governor.tryConsume(SCAN_COST['sandboxExploit'])) {
+                skippedChecks.push(`sandbox-exploit:${rf.finding.id}`);
+                continue; // continue, not break — record all skipped exploits
+            }
+            proofOfExploits.push(buildProofOfExploit(rf.finding, target.stagingBaseUrl, nowMs, target.prodBaseUrl));
+        }
+        // 10. Virtual patches (for human apply).
+        const virtualPatches = newFindings
+            .filter((f) => f.severity === 'critical' || f.severity === 'high' || f.module === ENGINE_MODULE.SECURITY_HEADERS)
+            .map(draftVirtualPatch);
+        // 11. Secret rotation runbooks (for human apply; never auto-applied).
+        const rotationRunbooks = newFindings
+            .filter((f) => f.module === ENGINE_MODULE.SECRETS_SCANNER)
+            .map((f) => draftRotationRunbook(f, null));
+        // 12. Posture score (show-the-math; floor).
+        const postureScore = computePostureScore(newFindings, attackPaths, nowMs);
+        // 13. Governor finalisation.
+        const budgetTruncated = governor.wasHalted;
+        const governorResult = governor.result(budgetTruncated
+            ? 'Budget exhausted — deep scans were halted; scan is INCOMPLETE'
+            : 'Scan completed within budget');
+        return {
+            scanId: makeScanId(nowMs),
+            runMode: governor.remaining >= SCAN_COST['deepDast'] ? 'deep' : 'active',
+            budgetTruncated,
+            findings: newFindings,
+            rankedFindings,
+            attackPaths,
+            suppressedUnreachableCves,
+            canaryAlerts,
+            iacFindings,
+            proofOfExploits,
+            virtualPatches,
+            rotationRunbooks,
+            postureScore,
+            skippedEndpoints: [...skippedEndpoints],
+            skippedChecks,
+            governorResult,
+            completedAt: new Date(nowMs).toISOString(),
+        };
+    }
+    /**
+     * Clean-target check: run against a known-clean target and assert no findings.
+     * Returns true if no findings, no canary alerts, no IaC findings, no attack paths,
+     * AND the scan was not budget-truncated (an incomplete scan can never be declared clean).
+     *
+     * MF-6 FIX: now includes iacFindings and attackPaths in the soundness check.
+     * A budget-truncated scan also fails isClean (fail-closed).
+     * Spec: "no false alarm on a clean target."
+     */
+    isClean(result) {
+        return (result.findings.length === 0 &&
+            result.canaryAlerts.length === 0 &&
+            result.iacFindings.length === 0 &&
+            result.attackPaths.length === 0 &&
+            result.proofOfExploits.length === 0 &&
+            !result.budgetTruncated);
+    }
+}
+//# sourceMappingURL=sentinel.js.map