@4da/mcp-server 5.0.4 → 6.0.1

package/dist/tools/vulnerability-scan-format.d.ts

@@ -0,0 +1,137 @@
+/**
+ * vulnerability_scan output: alias collapsing, relevance splits,
+ * recommendations, install drift, the shared severity grade, and resolution
+ * provenance. Split out of vulnerability-scan.ts, which keeps execution.
+ */
+import type { InstallDriftRecord, ResolutionProvenance, VulnerabilityScanResult } from "../live/types.js";
+/** What the formatter needs beyond the scan itself. */
+export interface ScanContext {
+    resolution: ResolutionProvenance | null;
+    reResolvedThisCall: boolean;
+    drift: InstallDriftRecord[];
+    includeDev: boolean;
+}
+/**
+ * Collapse advisories that are the same finding under different identifiers.
+ *
+ * OSV returns GHSA and RUSTSEC records for one vulnerability, each naming the
+ * other in `aliases`. Reported separately they double the count and read as two
+ * problems: `quinn-proto` showed as "2 high" for a single memory-exhaustion
+ * bug. Keeps the entry with the most usable detail (a CVSS score, then a fix
+ * version) and folds the rest into its alias list.
+ */
+export declare function collapseAliases(vulns: VulnerabilityScanResult["vulnerabilities"]): import("../live/types.js").VulnerabilityEntry[];
+/**
+ * Describe the platform filter truthfully, based on whether it actually ran.
+ *
+ * A crate is only knowable as platform-inactive when cargo could resolve the
+ * graph for this host. When it could not (cargo missing, offline resolution
+ * impossible, a non-Rust tree), every crate stays active — and saying
+ * "advisories are filtered to the host platform" would then be a claim about
+ * work that never happened.
+ */
+export declare function platformFilterNote(vulns: VulnerabilityScanResult["vulnerabilities"]): string;
+/** Shortest readable label for a manifest directory, relative to the scan root. */
+export declare function relativeDir(dir: string, root: string): string;
+export declare function formatScanResult(result: VulnerabilityScanResult, severityFilter: string | undefined, ctx: ScanContext): {
+    scan_time: string;
+    project: string;
+    project_root: string;
+    workspaces_with_findings: string[];
+    host_platform: string;
+    ecosystems_scanned: string[];
+    total_dependencies_scanned: number;
+    total_vulnerable_packages: number;
+    platform_inactive_packages: number;
+    by_severity: import("../live/severity-scope.js").SeverityCounts;
+    advisory_by_severity: import("../live/severity-scope.js").SeverityCounts;
+    vulnerabilities: {
+        package: string;
+        current_version: string;
+        /** Manifest directories pinning this version — where to apply the fix. */
+        source_dirs: string[];
+        ecosystem: import("../live/types.js").OsvEcosystem;
+        is_dev: boolean;
+        is_direct: boolean;
+        dev_scope_known: boolean;
+        target: string | null;
+        platform_active: boolean;
+        vuln_id: string;
+        aliases: string[];
+        severity: "critical" | "high" | "low" | "medium" | "unknown";
+        advisory_severity: "critical" | "high" | "low" | "medium" | "unknown";
+        severity_note?: string | undefined;
+        cvss_score: number | null;
+        summary: string;
+        fixed_version: string | null;
+        published: string;
+        references: string[];
+    }[];
+    platform_inactive_vulnerabilities: {
+        package: string;
+        current_version: string;
+        /** Manifest directories pinning this version — where to apply the fix. */
+        source_dirs: string[];
+        ecosystem: import("../live/types.js").OsvEcosystem;
+        is_dev: boolean;
+        is_direct: boolean;
+        dev_scope_known: boolean;
+        target: string | null;
+        platform_active: boolean;
+        vuln_id: string;
+        aliases: string[];
+        severity: "critical" | "high" | "low" | "medium" | "unknown";
+        advisory_severity: "critical" | "high" | "low" | "medium" | "unknown";
+        severity_note?: string | undefined;
+        cvss_score: number | null;
+        summary: string;
+        fixed_version: string | null;
+        published: string;
+        references: string[];
+    }[];
+    maintenance_notices: {
+        package: string;
+        current_version: string;
+        /** Manifest directories pinning this version — where to apply the fix. */
+        source_dirs: string[];
+        ecosystem: import("../live/types.js").OsvEcosystem;
+        is_dev: boolean;
+        is_direct: boolean;
+        dev_scope_known: boolean;
+        target: string | null;
+        platform_active: boolean;
+        vuln_id: string;
+        aliases: string[];
+        severity: "critical" | "high" | "low" | "medium" | "unknown";
+        advisory_severity: "critical" | "high" | "low" | "medium" | "unknown";
+        severity_note?: string | undefined;
+        cvss_score: number | null;
+        summary: string;
+        fixed_version: string | null;
+        published: string;
+        references: string[];
+    }[];
+    install_drift: Record<string, unknown>[];
+    recommendations: string[];
+    clean_dependencies: number;
+    scan_duration_ms: number;
+    _meta: {
+        source: string;
+        cached: boolean;
+        osv_cached: boolean;
+        offline: boolean;
+        privacy: string;
+        relevance: string;
+        severity_rule: string;
+        resolution: {
+            resolved_at: string | null;
+            lockfiles: {
+                path: string;
+                kind: "lockfile" | "manifest";
+                mtime: string | null;
+            }[];
+            re_resolved_this_call: boolean;
+            note: string;
+        };
+    };
+};

package/dist/tools/vulnerability-scan-format.js

@@ -0,0 +1,276 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * vulnerability_scan output: alias collapsing, relevance splits,
+ * recommendations, install drift, the shared severity grade, and resolution
+ * provenance. Split out of vulnerability-scan.ts, which keeps execution.
+ */
+import { hostTarget } from "../live/platform.js";
+import { maxSemver } from "../live/semver-utils.js";
+import { isMaintenanceNotice } from "../live/maintenance.js";
+import { countBySeverity, presentedSeverity, scopeAdjustmentReason, SEVERITY_RANK, } from "../live/severity-scope.js";
+import { buildDriftView, groupDriftRows, lockfileAlsoAffected } from "./install-drift-notes.js";
+const SEVERITY_RULE = "`severity` is the grade every 4DA surface presents: a transitive-only dependency caps critical at high, and a dev-only dependency drops one level (critical to high, high to medium, medium to low). Unknown dev scope gets no discount. `advisory_severity` is the advisory's own tier (counted in `advisory_by_severity`); `by_severity` counts the presented grade.";
+const RESOLUTION_NOTE = "Dependency versions were read from these files at resolved_at. Every call re-checks them (stat only) and re-resolves when one changes. `cached` and `osv_cached` describe the OSV advisory lookup, not dependency resolution.";
+/**
+ * Collapse advisories that are the same finding under different identifiers.
+ *
+ * OSV returns GHSA and RUSTSEC records for one vulnerability, each naming the
+ * other in `aliases`. Reported separately they double the count and read as two
+ * problems: `quinn-proto` showed as "2 high" for a single memory-exhaustion
+ * bug. Keeps the entry with the most usable detail (a CVSS score, then a fix
+ * version) and folds the rest into its alias list.
+ */
+export function collapseAliases(vulns) {
+    const kept = [];
+    const claimed = new Map(); // advisory id -> index in `kept`
+    const richness = (v) => (v.cvssScore !== null ? 2 : 0) + (v.fixedVersion ? 1 : 0);
+    for (const v of vulns) {
+        const scope = `${v.ecosystem}\0${v.package}\0${v.currentVersion}`;
+        const ids = [v.vulnId, ...v.aliases];
+        const hitIndex = ids
+            .map((id) => claimed.get(`${scope}\0${id}`))
+            .find((i) => i !== undefined);
+        if (hitIndex === undefined) {
+            const index = kept.length;
+            kept.push({ ...v, aliases: [...v.aliases] });
+            for (const id of ids)
+                claimed.set(`${scope}\0${id}`, index);
+            continue;
+        }
+        const incumbent = kept[hitIndex];
+        const winner = richness(v) > richness(incumbent) ? v : incumbent;
+        const merged = {
+            ...winner,
+            aliases: [
+                ...new Set([...incumbent.aliases, ...ids, incumbent.vulnId].filter((id) => id !== winner.vulnId)),
+            ],
+        };
+        kept[hitIndex] = merged;
+        for (const id of [merged.vulnId, ...merged.aliases])
+            claimed.set(`${scope}\0${id}`, hitIndex);
+    }
+    return kept;
+}
+/**
+ * Describe the platform filter truthfully, based on whether it actually ran.
+ *
+ * A crate is only knowable as platform-inactive when cargo could resolve the
+ * graph for this host. When it could not (cargo missing, offline resolution
+ * impossible, a non-Rust tree), every crate stays active — and saying
+ * "advisories are filtered to the host platform" would then be a claim about
+ * work that never happened.
+ */
+export function platformFilterNote(vulns) {
+    const host = hostTarget();
+    const platform = `${host.os}/${host.arch}`;
+    const inactive = vulns.filter((v) => v.platformActive === false).length;
+    const anyTargetKnown = vulns.some((v) => v.target);
+    if (inactive > 0) {
+        return `Filtered to ${platform}: ${inactive} advisor${inactive === 1 ? "y is" : "ies are"} against packages not built on this host, listed separately under platform_inactive_vulnerabilities.`;
+    }
+    if (anyTargetKnown) {
+        return `Filtered to ${platform}: every advisory below is against a package that IS built on this host.`;
+    }
+    return `Not platform-filtered: no per-package target information was resolvable (cargo metadata unavailable, or a non-Rust tree). Some advisories below may be against packages that never build on ${platform}.`;
+}
+/** Shortest readable label for a manifest directory, relative to the scan root. */
+export function relativeDir(dir, root) {
+    const n = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
+    const d = n(dir);
+    const r = n(root);
+    if (r && d.toLowerCase().startsWith(`${r.toLowerCase()}/`))
+        return d.slice(r.length + 1);
+    if (r && d.toLowerCase() === r.toLowerCase())
+        return ".";
+    return d;
+}
+export function formatScanResult(result, severityFilter, ctx) {
+    const root = result.projectPath;
+    const relative = (dir) => relativeDir(dir, root);
+    let vulns = collapseAliases(result.vulnerabilities);
+    // Filter and sort on the PRESENTED grade, the one the `severity` field shows.
+    if (severityFilter) {
+        const minRank = SEVERITY_RANK[severityFilter] ?? 0;
+        vulns = vulns.filter((v) => SEVERITY_RANK[presentedSeverity(v)] >= minRank);
+    }
+    vulns.sort((a, b) => SEVERITY_RANK[presentedSeverity(b)] - SEVERITY_RANK[presentedSeverity(a)]);
+    // Relevance split: advisories on deps NOT active on the host platform are not
+    // actionable for this user (e.g. a Linux-only crate's CVE shown to a Windows
+    // dev). Keep them, but separated and labeled so they don't pollute the signal.
+    const onHost = vulns.filter((v) => v.platformActive !== false);
+    const inactive = vulns.filter((v) => v.platformActive === false);
+    // Second relevance split: "X is unmaintained" is a maintenance notice, not a
+    // vulnerability. Nothing is exploitable and there is nothing to upgrade to.
+    // Live scan: 23 of 41 findings were these, generating 27 "Review X" lines
+    // that buried the six real upgrades. Kept, labelled, and out of the counts.
+    const active = onHost.filter((v) => !isMaintenanceNotice(v));
+    const maintenance = onHost.filter((v) => isMaintenanceNotice(v));
+    const drift = buildDriftView(result, ctx.drift, ctx.includeDev, relative);
+    const host = hostTarget();
+    const activePackages = new Set(active.map((v) => v.package)).size;
+    // Every distinct manifest directory the scan actually covered. A single
+    // "project" label hides the fact that a repo root can span several
+    // independently-versioned workspaces.
+    const scannedProjects = [...new Set(vulns.flatMap((v) => v.sourceDirs ?? []).map(relative))].sort();
+    return {
+        scan_time: result.scannedAt,
+        project: result.projectPath.split(/[/\\]/).pop() || result.projectPath,
+        project_root: result.projectPath,
+        // Workspaces under `project_root` that contributed a finding. Advisories
+        // below are attributed per entry via `source_dirs`.
+        workspaces_with_findings: scannedProjects,
+        host_platform: `${host.os}/${host.arch}`,
+        ecosystems_scanned: result.ecosystemsScanned,
+        total_dependencies_scanned: result.totalScanned,
+        total_vulnerable_packages: activePackages,
+        platform_inactive_packages: result.platformInactiveVulnerable,
+        // Counted over the listed findings: the same rows `vulnerabilities` shows,
+        // one per vulnerability (aliases collapsed). Counting every raw OSV row
+        // (alias duplicates, maintenance notices, other-platform advisories) gave
+        // "medium 3, low 1, unknown 9" beside three listed rows (2026-10-02 eval).
+        by_severity: countBySeverity(active, presentedSeverity),
+        advisory_by_severity: countBySeverity(active, (v) => v.severity),
+        vulnerabilities: active.map((v) => formatVuln(v, root, drift)),
+        // Advisories suppressed from the main list because the affected crate is not
+        // built on this host (e.g. cfg(not(windows)) deps on Windows). Surfaced for
+        // cross-platform builds, clearly labeled with the gating target.
+        platform_inactive_vulnerabilities: inactive.map((v) => formatVuln(v, root, drift)),
+        // Unmaintained-dependency notices: real information to plan around, but
+        // nothing exploitable and nothing to upgrade to. Separated so they cannot
+        // outnumber the advisories that need action today.
+        maintenance_notices: maintenance.map((v) => formatVuln(v, root, drift)),
+        // npm direct dependencies whose node_modules copy is not what the lockfile
+        // pins. The lockfile is what every other tool reads; this is what runs.
+        install_drift: drift.rows,
+        recommendations: buildRecommendations(active, result.vulnerabilities, relative),
+        clean_dependencies: result.cleanCount,
+        scan_duration_ms: result.scanDurationMs,
+        _meta: {
+            source: "osv.dev",
+            // Kept for compatibility; it has only ever described the OSV lookup.
+            cached: result.cached,
+            osv_cached: result.cached,
+            offline: result.offline,
+            privacy: "Only package names and versions were sent (public manifest data)",
+            // State what actually happened. This previously asserted that advisories
+            // WERE platform-filtered while reporting zero inactive packages and
+            // listing nine Linux-only crates on a Windows host — a claim of filtering
+            // is worse than no filtering, because it invites the reader to trust it.
+            relevance: platformFilterNote(vulns),
+            severity_rule: SEVERITY_RULE,
+            resolution: {
+                resolved_at: ctx.resolution?.resolvedAt ?? null,
+                lockfiles: (ctx.resolution?.sources ?? []).map((s) => ({
+                    path: relative(s.path),
+                    kind: s.kind,
+                    mtime: s.mtimeMs === null ? null : new Date(s.mtimeMs).toISOString(),
+                })),
+                re_resolved_this_call: ctx.reResolvedThisCall,
+                note: RESOLUTION_NOTE,
+            },
+        },
+    };
+}
+function buildRecommendations(active, all, relative) {
+    const lines = [];
+    const rankOf = (vulns) => Math.max(...vulns.map((v) => SEVERITY_RANK[presentedSeverity(v)]));
+    // Name the manifest directories that actually pin the vulnerable version.
+    // Without this a reader cannot tell a finding in the primary crate from one
+    // in a sibling workspace, and a patched primary reads as vulnerable.
+    const whereOf = (vulns) => {
+        const dirs = [...new Set(vulns.flatMap((v) => v.sourceDirs ?? []).map(relative))].sort();
+        return dirs.length > 0 ? ` in ${dirs.join(", ")}` : "";
+    };
+    // Recommendations are derived from platform-active, exploitable vulns only.
+    const byPackage = new Map();
+    for (const v of active) {
+        if (v.installDriftOf)
+            continue; // reinstall advice below, not an upgrade
+        const list = byPackage.get(v.package);
+        if (list)
+            list.push(v);
+        else
+            byPackage.set(v.package, [v]);
+    }
+    for (const [pkg, pkgVulns] of byPackage) {
+        const highest = pkgVulns[0];
+        const breakdown = severityBreakdown(pkgVulns);
+        // Target the HIGHEST published fix so the upgrade resolves every fixable CVE,
+        // not just the first one. (The old code picked the first fix version, which
+        // could leave higher-version-gated CVEs unfixed while claiming to fix them.)
+        const target = maxSemver(pkgVulns.map((v) => v.fixedVersion).filter((v) => Boolean(v)));
+        const total = pkgVulns.length;
+        const fixable = pkgVulns.filter((v) => v.fixedVersion).length;
+        const where = whereOf(pkgVulns);
+        let text;
+        if (target) {
+            const scope = fixable === total
+                ? `${total} CVE${total > 1 ? "s" : ""}`
+                : `${fixable} of ${total} CVEs (${total - fixable} with no published fix)`;
+            text = `Upgrade ${pkg} ${highest.currentVersion} → ${target}${where} — resolves ${scope} [${breakdown}]`;
+        }
+        else {
+            text = `Review ${pkg} ${highest.currentVersion}${where} — ${total} known vulnerabilit${total > 1 ? "ies" : "y"} [${breakdown}], no fix version published`;
+        }
+        lines.push({ rank: rankOf(pkgVulns), text });
+    }
+    // Installed copies the lockfile does not pin. The lockfile already says what
+    // should be installed, so the advice is the reinstall, not a version bump.
+    for (const entries of groupDriftRows(active)) {
+        const first = entries[0];
+        const count = entries.length;
+        const dirs = [...new Set(entries.flatMap((v) => v.sourceDirs ?? []).map(relative))]
+            .map((d) => (d === "." ? "the project root" : d))
+            .sort();
+        const where = dirs.length > 0 ? ` in ${dirs.join(", ")}` : "";
+        const command = first.installFix ?? "a reinstall";
+        const tail = entries.some((e) => lockfileAlsoAffected(e, all))
+            ? `the lockfile's ${first.installDriftOf} is also affected — upgrade it, then run \`${command}\`${where}`
+            : `the lockfile already pins ${first.installDriftOf}, which is not affected — run \`${command}\`${where}`;
+        lines.push({
+            rank: rankOf(entries),
+            text: `Reinstall ${first.package}${where}: node_modules has ${first.currentVersion} with ${count} known vulnerabilit${count > 1 ? "ies" : "y"} [${severityBreakdown(entries)}]; ${tail}`,
+        });
+    }
+    return lines
+        .map((line, index) => ({ ...line, index }))
+        .sort((a, b) => b.rank - a.rank || a.index - b.index)
+        .map((line) => line.text);
+}
+/** "1 critical, 3 high, 2 medium" (presented grades), omitting empty buckets. */
+function severityBreakdown(vulns) {
+    const counts = countBySeverity(vulns, presentedSeverity);
+    return ["critical", "high", "medium", "low", "unknown"]
+        .filter((s) => counts[s])
+        .map((s) => `${counts[s]} ${s}`)
+        .join(", ");
+}
+function formatVuln(v, root, drift) {
+    const presented = presentedSeverity(v);
+    const reason = scopeAdjustmentReason(v);
+    return {
+        package: v.package,
+        current_version: v.currentVersion,
+        /** Manifest directories pinning this version — where to apply the fix. */
+        source_dirs: [...new Set((v.sourceDirs ?? []).map((d) => relativeDir(d, root)))].sort(),
+        ecosystem: v.ecosystem,
+        is_dev: v.isDev,
+        is_direct: v.isDirect ?? null,
+        dev_scope_known: v.devScopeKnown ?? false,
+        target: v.target,
+        platform_active: v.platformActive,
+        vuln_id: v.vulnId,
+        aliases: v.aliases,
+        severity: presented,
+        advisory_severity: v.severity,
+        ...(reason
+            ? { severity_note: `Graded ${presented}: the advisory rates it ${v.severity}, and this is a ${reason}.` }
+            : {}),
+        cvss_score: v.cvssScore,
+        summary: v.summary,
+        fixed_version: v.fixedVersion,
+        published: v.published,
+        references: v.references,
+        ...drift.annotate(v),
+    };
+}