@4da/mcp-server 6.2.3 → 6.2.5

package/dist/live/osv-scanner.d.ts

@@ -9,6 +9,15 @@
 import type { LiveCache } from "./cache.js";
 import type { RateLimiter } from "./rate-limiter.js";
 import type { ResolvedDependency, OsvVulnerability, VulnerabilityEntry, VulnerabilityScanResult } from "./types.js";
+/** GHSA alias records read per scan to rate records that carry no severity (rateFromAliases). */
+export declare const MAX_ALIAS_LOOKUPS = 50;
+/** The whole alias lookup's time budget per scan; past it the records stay unknown, said so. */
+export declare const ALIAS_BUDGET_MS = 5000;
+/** Per-dependency advisory ids, null where there is no answer, and why. */
+export interface AdvisoryAnswer {
+    ids: Array<string[] | null>;
+    failure: string | null;
+}
 /**
  * Where advisories come from. The scanner asks which advisory ids affect each
  * exact (ecosystem, name, version), then for the records behind those ids.
@@ -22,8 +31,13 @@ import type { ResolvedDependency, OsvVulnerability, VulnerabilityEntry, Vulnerab
 export interface AdvisorySource {
     /** True when answers come over the network: rate-limited, and cached per dependency. */
     readonly network: boolean;
-    /** The advisory ids affecting each dependency, in input order. Throws when it cannot answer for all of them. */
-    query(deps: ResolvedDependency[]): Promise<string[][]>;
+    /**
+     * The advisory ids affecting each dependency, in input order. An entry is
+     * null when the source has NO answer for that dependency (unreachable,
+     * failed, timed out, out of query budget): never an empty list, which means
+     * "checked, nothing found". `failure` says why when any entry is null.
+     */
+    query(deps: ResolvedDependency[]): Promise<AdvisoryAnswer>;
     /** The full record of each id it can find; a missing id is left out, never fatal. */
     details(ids: string[]): Promise<Map<string, OsvVulnerability>>;
 }
@@ -31,9 +45,15 @@ export interface AdvisorySource {
 export declare class OsvHttpSource implements AdvisorySource {
     private readonly cache;
     private readonly rateLimiter;
+    /** Total wait for query budget per scan (tests shorten it). */
+    private readonly tokenWaitMs;
     readonly network = true;
-    constructor(cache: LiveCache, rateLimiter: RateLimiter);
-    query(deps: ResolvedDependency[]): Promise<string[][]>;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter, 
+    /** Total wait for query budget per scan (tests shorten it). */
+    tokenWaitMs?: number);
+    query(deps: ResolvedDependency[]): Promise<AdvisoryAnswer>;
+    /** One querybatch request, retried once after a throttle, a server error, a timeout or a network failure. */
+    private sendBatch;
     /**
      * Hydrate advisory detail for the given IDs. Cache-first (24h), then fetch the
      * misses from `/v1/vulns/{id}` with bounded concurrency. A failed fetch is
@@ -48,8 +68,29 @@ export declare class OsvScanner {
     private cache;
     private rateLimiter;
     private source;
-    constructor(cache: LiveCache, rateLimiter: RateLimiter, source?: AdvisorySource);
+    private aliasBudgetMs;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter, source?: AdvisorySource, options?: {
+        aliasBudgetMs?: number;
+    });
     scan(deps: ResolvedDependency[], projectPath: string): Promise<VulnerabilityScanResult>;
+    /**
+     * A severity for records that carry none, from their GHSA alias: one
+     * advisory, one grade, in every tool. Go's vulnerability database rates
+     * nothing: GO-2024-3333 (golang.org/x/net) has no severity, its alias
+     * GHSA-w32m-9786-jp63 is HIGH, and OSV returns only the GO record for the
+     * module (the GHSA names golang.org/x/net/html). dependency_check said
+     * `avoid` while vulnerability_scan graded the same record unknown (review
+     * of 6.2.5 M6, 2026-10-18). The two records name each other, so the
+     * alias's rating applies; it is read by the same rule as any record and
+     * the entry says where it came from (`severityFrom`).
+     *
+     * Through this scanner's own source: a pinned source answers from its
+     * records, never the network; with live lookups off nothing is fetched.
+     * At most MAX_ALIAS_LOOKUPS aliases, within ALIAS_BUDGET_MS in total.
+     * Anything not rated stays unknown and is listed as unresolved, with why;
+     * unknown is never clean.
+     */
+    private rateFromAliases;
     private batchQuery;
 }
 /**
@@ -63,6 +104,33 @@ export declare class OsvScanner {
  * next hour repeated both errors while the fixed resolver sat idle.
  */
 export declare function restampDepContext(cached: VulnerabilityEntry, dep: ResolvedDependency): VulnerabilityEntry;
+/**
+ * The shared rule for an unrated record (the 4DA app implements it
+ * identically): the HIGHEST grade among every GHSA alias that could be read;
+ * unknown when none could. `from` names the alias that gave it, the
+ * lexicographically smallest id on a tie. An alias that could not be read
+ * never lowers the grade; it is reported (`consulted`, grade "unreadable").
+ * Umbrella records name several: RUSTSEC-2020-0014 lists 8 GHSAs, so taking
+ * the first made the grade depend on alias order.
+ */
+export declare function gradeFromAliases(ghsas: string[], read: ReadonlyMap<string, VulnerabilityEntry["severity"]>): {
+    severity: VulnerabilityEntry["severity"];
+    from: string | null;
+    consulted: Array<{
+        id: string;
+        grade: VulnerabilityEntry["severity"] | "unreadable";
+    }>;
+};
+/**
+ * Derive a severity bucket honestly: a CVSS base score (numeric or computed
+ * from a vector) wins; otherwise the GitHub-advisory label; otherwise unknown.
+ * Never fabricates a default bucket — an advisory with no severity signal is
+ * reported as `unknown`, not silently labeled "medium".
+ */
+export declare function deriveSeverity(vuln: Partial<OsvVulnerability>): {
+    severity: VulnerabilityEntry["severity"];
+    cvssScore: number | null;
+};
 export declare function extractCvssScore(severity: Array<{
     type: string;
     score: string;
@@ -86,3 +154,17 @@ export declare function extractCvssScore(severity: Array<{
  * Hard guard: the returned version is never below the installed version.
  */
 export declare function extractFixedVersion(affected: OsvVulnerability["affected"] | undefined, packageName: string, ecosystem: string, installedVersion: string | null): string | null;
+/**
+ * npm's security holding placeholder: after a malicious package is taken down,
+ * npm republishes the name as an empty `0.0.<n>-security` release ("security
+ * holding package"). It has no code, so NO advisory applies to it, whichever
+ * database's id flags the name: crossenv 0.0.2-security under
+ * GHSA-c2m4-w5hm-vqjw read as installed malware when only MAL- ids were held
+ * (4DA audit L4, 2026-10-16). Only npm's own shape counts: a publisher's
+ * `1.0.0-security` prerelease is real code and stays affected. The same rule
+ * as the app's `fourda_depengine::matching::is_npm_security_holding`
+ * (shared vectors `holding.jsonl`).
+ */
+export declare function isSecurityHoldingRelease(ecosystem: string, version: string): boolean;
+/** A finding on an npm security holding placeholder (any advisory id): not installed code. */
+export declare function isNpmSecurityHolding(v: Pick<VulnerabilityEntry, "ecosystem" | "currentVersion">): boolean;

package/dist/live/osv-scanner.js

@@ -9,8 +9,11 @@
  */
 import { fetchWithTimeout } from "./http-utils.js";
 import { cvssBaseScore } from "./cvss.js";
-import { compareVersions, isComparable, maxVersion } from "./version-compare.js";
+import { compareToLowerBound, compareVersions, isComparable, maxVersion } from "./version-compare.js";
 import { collectAffectedSpans } from "./osv-ranges.js";
+import { isMaintenanceNotice, isMaintenanceRecord } from "./maintenance.js";
+import { gradeAliasGroups } from "./advisory-groups.js";
+import { cweIdsOf, isMalware } from "./malware.js";
 const OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch";
 const OSV_VULN_URL = "https://api.osv.dev/v1/vulns/";
 const OSV_TIMEOUT_MS = 15_000;
@@ -29,6 +32,10 @@ const HYDRATE_CONCURRENCY = 24;
 /** querybatch chunks (1,000 dependencies each) sent at once. */
 const BATCH_CONCURRENCY = 4;
 const DETAIL_RETRY_DELAY_MS = 750;
+/** GHSA alias records read per scan to rate records that carry no severity (rateFromAliases). */
+export const MAX_ALIAS_LOOKUPS = 50;
+/** The whole alias lookup's time budget per scan; past it the records stay unknown, said so. */
+export const ALIAS_BUDGET_MS = 5_000;
 /**
  * Detail fetches in flight, shared by every scanner in the process. The
  * startup warm-up scan and the first tool call's scan used to run side by
@@ -49,14 +56,39 @@ async function pool(items, limit, work) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
     return out;
 }
+/** How long a scan may wait, in total, for query-budget tokens before the rest of its batches go unanswered. */
+const MAX_TOKEN_WAIT_MS = 60_000;
+/** A failed querybatch request (network, timeout, 429, 5xx) is retried once after this. */
+const BATCH_RETRY_DELAY_MS = 1_000;
+/** Why one querybatch request failed, in words a reader can act on. */
+function describeFailure(error) {
+    if (error instanceof OsvHttpError)
+        return `OSV.dev returned HTTP ${error.status}`;
+    const name = error?.name;
+    if (name === "TimeoutError" || name === "AbortError")
+        return `OSV.dev did not answer within ${OSV_TIMEOUT_MS / 1000} s`;
+    const message = error instanceof Error ? error.message : String(error);
+    return `OSV.dev unreachable (${message.slice(0, 120)})`;
+}
+class OsvHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`OSV API error: ${status}`);
+        this.status = status;
+    }
+}
 /** OSV.dev over HTTP: querybatch for membership, per-id hydration for records. */
 export class OsvHttpSource {
     cache;
     rateLimiter;
+    tokenWaitMs;
     network = true;
-    constructor(cache, rateLimiter) {
+    constructor(cache, rateLimiter, 
+    /** Total wait for query budget per scan (tests shorten it). */
+    tokenWaitMs = MAX_TOKEN_WAIT_MS) {
         this.cache = cache;
         this.rateLimiter = rateLimiter;
+        this.tokenWaitMs = tokenWaitMs;
     }
     async query(deps) {
         // querybatch returns only `{ id, modified }`; the rich fields (severity,
@@ -64,31 +96,72 @@ export class OsvHttpSource {
         const chunks = [];
         for (let offset = 0; offset < deps.length; offset += MAX_BATCH_SIZE)
             chunks.push(deps.slice(offset, offset + MAX_BATCH_SIZE));
-        // Every chunk is answered or the scan fails: a partial answer would call
-        // the unanswered dependencies clean. The rate limit is checked for all of
-        // them before any is sent.
-        for (let i = 0; i < chunks.length; i++) {
-            if (!this.rateLimiter.consume("osv")) {
-                throw new Error("OSV rate limit reached before all dependency batches completed");
-            }
-        }
+        // Batches go out as query budget allows, waiting for it to refill (bounded),
+        // instead of the whole scan failing when a tree needs more batches than the
+        // bucket holds. A batch that gets no budget, or fails twice, is unanswered:
+        // its dependencies come back null, and the scan reports them as unchecked.
+        const deadline = Date.now() + this.tokenWaitMs;
+        let failure = null;
+        // A batch that failed twice means OSV.dev is down or refusing: batches not
+        // yet sent are not tried (an outage would otherwise cost a timeout each).
+        let outage = false;
         const answered = await pool(chunks, BATCH_CONCURRENCY, async (chunk) => {
-            const queries = chunk.map((d) => ({
-                package: { name: d.name, ecosystem: d.ecosystem },
-                ...(d.version ? { version: d.version } : {}),
-            }));
-            const response = await fetchWithTimeout(OSV_BATCH_URL, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ queries }),
-            }, OSV_TIMEOUT_MS);
-            if (!response.ok) {
-                throw new Error(`OSV API error: ${response.status}`);
+            if (outage)
+                return chunk.map(() => null);
+            if (!(await this.rateLimiter.acquire("osv", deadline))) {
+                failure ??= `the OSV.dev query budget (${MAX_BATCH_SIZE.toLocaleString("en-US")} dependencies per request) ran out for ${Math.round(this.tokenWaitMs / 1000)} s`;
+                return chunk.map(() => null);
+            }
+            try {
+                return await this.sendBatch(chunk);
+            }
+            catch (error) {
+                failure = describeFailure(error);
+                outage = true;
+                return chunk.map(() => null);
             }
-            const data = (await response.json());
-            return chunk.map((_, i) => (data.results[i]?.vulns ?? []).map((v) => v.id));
         });
-        return answered.flat();
+        return { ids: answered.flat(), failure };
+    }
+    /** One querybatch request, retried once after a throttle, a server error, a timeout or a network failure. */
+    async sendBatch(chunk) {
+        const queries = chunk.map((d) => ({
+            package: { name: d.name, ecosystem: d.ecosystem },
+            ...(d.version ? { version: d.version } : {}),
+        }));
+        let lastError = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (attempt > 0)
+                await new Promise((resolve) => setTimeout(resolve, BATCH_RETRY_DELAY_MS));
+            try {
+                const response = await fetchWithTimeout(OSV_BATCH_URL, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ queries }),
+                }, OSV_TIMEOUT_MS);
+                if (!response.ok) {
+                    lastError = new OsvHttpError(response.status);
+                    // A client error other than a throttle will not change on a retry.
+                    if (response.status !== 429 && response.status < 500)
+                        break;
+                    continue;
+                }
+                const data = (await response.json());
+                if (!Array.isArray(data?.results) || data.results.length !== chunk.length) {
+                    throw new Error(`OSV.dev answered ${Array.isArray(data?.results) ? data.results.length : "no"} results for ${chunk.length} queries`);
+                }
+                // `{}` is OSV's own "nothing found"; null, a string or a non-array `vulns` is not an answer
+                // and was read as clean, then cached for an hour (audit 6.2.5 B-4).
+                if (data.results.some((r) => r === null || typeof r !== "object" || ("vulns" in r && !Array.isArray(r.vulns)))) {
+                    throw new Error("OSV.dev answered a malformed result");
+                }
+                return chunk.map((_, i) => (data.results[i]?.vulns ?? []).map((v) => v.id));
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw lastError ?? new Error("OSV.dev querybatch failed");
     }
     /**
      * Hydrate advisory detail for the given IDs. Cache-first (24h), then fetch the
@@ -127,8 +200,14 @@ export class OsvHttpSource {
         for (let attempt = 0; attempt < 2; attempt++) {
             try {
                 const response = await fetchWithTimeout(`${OSV_VULN_URL}${encodeURIComponent(id)}`, {}, OSV_TIMEOUT_MS);
-                if (response.ok)
-                    return (await response.json());
+                if (response.ok) {
+                    // Only the record asked for is an answer: a 200 `{}` (or any other record) crashed the
+                    // scan downstream and was cached for 24 h (audit 6.2.5 B-8). Anything else is retried.
+                    const record = (await response.json());
+                    if (record && typeof record === "object" && record.id === id)
+                        return record;
+                    throw new Error(`OSV.dev answered a malformed record for ${id}`);
+                }
                 // 404 and other client errors are answers, not failures to retry.
                 if (response.status !== 429 && response.status < 500)
                     return null;
@@ -146,7 +225,9 @@ export class OsvScanner {
     cache;
     rateLimiter;
     source;
-    constructor(cache, rateLimiter, source) {
+    aliasBudgetMs;
+    constructor(cache, rateLimiter, source, options = {}) {
+        this.aliasBudgetMs = options.aliasBudgetMs ?? ALIAS_BUDGET_MS;
         this.cache = cache;
         this.rateLimiter = rateLimiter;
         this.source = source ?? new OsvHttpSource(cache, rateLimiter);
@@ -162,7 +243,7 @@ export class OsvScanner {
         const uncached = [];
         const cachedVulns = [];
         for (const dep of scannable) {
-            const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
+            const cacheKey = `osv:v3:${dep.ecosystem}:${dep.name}:${dep.version}`;
             const cached = network ? this.cache.get(cacheKey) : null;
             if (cached !== null) {
                 cachedVulns.push(...cached.map((v) => restampDepContext(v, dep)));
@@ -171,32 +252,51 @@ export class OsvScanner {
                 uncached.push(dep);
             }
         }
-        // Fetch uncached from OSV
+        // Fetch uncached from OSV. Dependencies it has no answer for fall back to
+        // an expired cached answer; with none they are UNCHECKED, counted and
+        // reported, and never counted clean.
         let fetchedVulns = [];
-        let offline = false;
+        let unanswered = [];
+        let failure = null;
         if (uncached.length > 0) {
-            if (network && !this.rateLimiter.canProceed("osv")) {
-                offline = true;
+            try {
+                const outcome = await this.batchQuery(uncached);
+                fetchedVulns = outcome.vulns;
+                unanswered = outcome.unanswered;
+                failure = outcome.failure;
+            }
+            catch (error) {
+                // The source layer turns network failures into `outcome.failure`; an
+                // exception here is a fault in this server, not an OSV outage, and
+                // telling the agent to retry would not help (audit 6.2.5 D-2).
+                unanswered = uncached;
+                const detail = error instanceof Error ? error.message.slice(0, 120) : String(error).slice(0, 120);
+                failure = `an internal error in this server stopped the vulnerability lookup (${detail}); retrying will not help, please report it at https://github.com/4DA-Systems/4da-mcp-server/issues`;
+            }
+        }
+        let staleAnswers = 0;
+        let staleOldest = null;
+        const unchecked = [];
+        for (const dep of unanswered) {
+            const stale = network ? this.cache.getStale(`osv:v3:${dep.ecosystem}:${dep.name}:${dep.version}`) : null;
+            if (stale) {
+                staleAnswers++;
+                if (!staleOldest || stale.fetchedAt < staleOldest)
+                    staleOldest = stale.fetchedAt;
+                cachedVulns.push(...stale.data.map((v) => restampDepContext(v, dep)));
             }
             else {
-                try {
-                    fetchedVulns = await this.batchQuery(uncached);
-                }
-                catch {
-                    offline = true;
-                    // Try stale cache for uncached deps
-                    for (const dep of uncached) {
-                        if (!network)
-                            break;
-                        const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
-                        const stale = this.cache.getStale(cacheKey);
-                        if (stale)
-                            cachedVulns.push(...stale.data.map((v) => restampDepContext(v, dep)));
-                    }
-                }
+                unchecked.push(dep);
             }
         }
-        const allVulns = [...cachedVulns, ...fetchedVulns];
+        const offline = unchecked.length > 0;
+        // npm's security holding packages (`fs@0.0.1-security`) are empty
+        // placeholders npm publishes after taking a malicious package down; the
+        // malware advisory covering every version does not apply to them (the
+        // desktop app's osv::matching::is_npm_security_holding; audit A5).
+        const rated = await this.rateFromAliases([...cachedVulns, ...fetchedVulns].filter((v) => !isNpmSecurityHolding(v)));
+        // One severity per advisory: every record of an alias group carries the group's most severe grade.
+        const allVulns = gradeAliasGroups(rated.vulns);
         const vulnerablePackages = new Set(allVulns.map((v) => v.package));
         const platformInactiveVulnerable = new Set(allVulns.filter((v) => !v.platformActive).map((v) => v.package)).size;
         const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
@@ -212,16 +312,115 @@ export class OsvScanner {
             platformInactiveVulnerable,
             bySeverity,
             vulnerabilities: allVulns,
-            cleanCount: offline ? 0 : scannable.length - vulnerablePackages.size,
+            // Answered dependencies with no advisory; an unchecked one is never clean.
+            cleanCount: Math.max(0, scannable.length - unchecked.length - vulnerableDependencyCount(allVulns)),
             scanDurationMs: Date.now() - start,
             cached: uncached.length === 0,
             offline,
+            unchecked: unchecked.length,
+            uncheckedReason: offline ? (failure ?? "OSV.dev could not be queried") : null,
+            staleAnswers,
+            // An expired answer is not a current one: every consumer says so (audit 6.2.5 B-2).
+            ...(staleAnswers > 0 ? { staleReason: failure ?? "OSV.dev could not be queried", staleOldestFetchedAt: staleOldest } : {}),
+            ...(rated.report ? { aliasSeverity: rated.report } : {}),
+        };
+    }
+    /**
+     * A severity for records that carry none, from their GHSA alias: one
+     * advisory, one grade, in every tool. Go's vulnerability database rates
+     * nothing: GO-2024-3333 (golang.org/x/net) has no severity, its alias
+     * GHSA-w32m-9786-jp63 is HIGH, and OSV returns only the GO record for the
+     * module (the GHSA names golang.org/x/net/html). dependency_check said
+     * `avoid` while vulnerability_scan graded the same record unknown (review
+     * of 6.2.5 M6, 2026-10-18). The two records name each other, so the
+     * alias's rating applies; it is read by the same rule as any record and
+     * the entry says where it came from (`severityFrom`).
+     *
+     * Through this scanner's own source: a pinned source answers from its
+     * records, never the network; with live lookups off nothing is fetched.
+     * At most MAX_ALIAS_LOOKUPS aliases, within ALIAS_BUDGET_MS in total.
+     * Anything not rated stays unknown and is listed as unresolved, with why;
+     * unknown is never clean.
+     */
+    async rateFromAliases(entries) {
+        // A GHSA alias that is itself one of this scan's records is graded already: no fetch.
+        const known = new Map();
+        for (const e of entries)
+            if (/^GHSA-/i.test(e.vulnId) && e.severity !== "unknown")
+                known.set(e.vulnId, e.severity);
+        const wanted = new Map(); // record id -> every GHSA alias it names
+        for (const e of entries) {
+            if (e.severity !== "unknown" || e.severityFrom || wanted.has(e.vulnId) || isMaintenanceNotice(e))
+                continue;
+            const ghsas = [...new Set(e.aliases.filter((a) => /^GHSA-/i.test(a) && a !== e.vulnId))];
+            if (ghsas.length > 0)
+                wanted.set(e.vulnId, ghsas);
+        }
+        if (wanted.size === 0)
+            return { vulns: entries, report: null };
+        // The cap and the budget count distinct GHSA ids.
+        const toRead = [...new Set([...wanted.values()].flat())].filter((id) => !known.has(id)).sort();
+        const asked = toRead.slice(0, MAX_ALIAS_LOOKUPS);
+        let records = new Map();
+        const reasons = toRead.length > asked.length ? [`more than ${MAX_ALIAS_LOOKUPS} aliases to read; the rest were not asked for`] : [];
+        if (asked.length > 0 && this.source.network && process.env.FOURDA_OFFLINE === "true") {
+            reasons.push("live lookups are disabled (FOURDA_OFFLINE=true)");
+        }
+        else if (asked.length > 0) {
+            let timer;
+            const deadline = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), this.aliasBudgetMs);
+            });
+            try {
+                // Fetches past the deadline keep running and fill the detail cache for the next call.
+                const answer = await Promise.race([this.source.details(asked).catch(() => new Map()), deadline]);
+                if (answer === null)
+                    reasons.push(`the alias records did not arrive within ${this.aliasBudgetMs / 1000} s`);
+                else
+                    records = answer;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        }
+        const read = new Map(known);
+        for (const [id, record] of records)
+            read.set(id, deriveSeverity(record).severity);
+        const unresolved = new Set();
+        const ungraded = [];
+        let ratedCount = 0;
+        const vulns = entries.map((e) => {
+            const ghsas = wanted.get(e.vulnId);
+            if (!ghsas)
+                return e;
+            const graded = gradeFromAliases(ghsas, read);
+            for (const c of graded.consulted)
+                if (c.grade === "unreadable")
+                    unresolved.add(c.id);
+            if (graded.severity === "unknown") {
+                if (!ungraded.includes(e.vulnId))
+                    ungraded.push(e.vulnId);
+                return e;
+            }
+            ratedCount++;
+            return { ...e, severity: graded.severity, severityFrom: graded.from };
+        });
+        if (unresolved.size > 0 && reasons.length === 0)
+            reasons.push("an alias record could not be read");
+        return {
+            vulns,
+            report: { rated: ratedCount, unresolved: [...unresolved].sort(), ungraded, reason: unresolved.size > 0 || ungraded.length > 0 ? reasons.join("; ") || "the aliases are unrated themselves" : null },
         };
     }
     async batchQuery(deps) {
         // Phase 1 — enumerate advisory IDs per dep (OSV: the lightweight batch index).
-        const idsPerDep = await this.source.query(deps);
-        const matches = deps.map((dep, i) => ({ dep, ids: idsPerDep[i] ?? [] }));
+        const answer = await this.source.query(deps);
+        const unanswered = deps.filter((_, i) => !Array.isArray(answer.ids[i]));
+        const matches = deps.flatMap((dep, i) => {
+            const ids = answer.ids[i];
+            return Array.isArray(ids) ? [{ dep, ids }] : [];
+        });
         // Phase 2 — the record behind each unique advisory, once.
         const uniqueIds = [...new Set(matches.flatMap((m) => m.ids))];
         const detailById = await this.source.details(uniqueIds);
@@ -235,14 +434,18 @@ export class OsvScanner {
             // and dropping a real advisory is worse than keeping an un-enriched one.
             const liveIds = ids.filter((id) => !detailById.get(id)?.withdrawn);
             const depVulns = liveIds.map((id) => mapVulnerability(detailById.get(id) ?? { id }, dep));
-            rows.push([`osv:${dep.ecosystem}:${dep.name}:${dep.version}`, depVulns]);
+            rows.push([`osv:v3:${dep.ecosystem}:${dep.name}:${dep.version}`, depVulns]);
             results.push(...depVulns);
         }
         if (this.source.network)
             this.cache.setMany(rows, "osv", OSV_CACHE_TTL);
-        return results;
+        return { vulns: results, unanswered, failure: unanswered.length > 0 ? (answer.failure ?? "OSV.dev gave no answer") : null };
     }
 }
+/** Distinct (ecosystem, name, version) instances with at least one advisory row. */
+function vulnerableDependencyCount(vulns) {
+    return new Set(vulns.map((v) => `${v.ecosystem}\0${v.package}\0${v.currentVersion}`)).size;
+}
 /**
  * Overwrite the dep-context fields of a cached advisory entry with the CURRENT
  * resolution's context. The advisory facts (id, severity, summary, fix version)
@@ -272,7 +475,11 @@ export function restampDepContext(cached, dep) {
     };
 }
 function mapVulnerability(vuln, dep) {
-    const { severity, cvssScore } = deriveSeverity(vuln);
+    const graded = deriveSeverity(vuln);
+    const malware = isMalware(vuln.id, vuln.aliases || [], cweIdsOf(vuln), vuln.summary ?? "");
+    // An installed malicious copy is critical in every tool, whatever the record grades (the 4DA lead, 2026-10-18).
+    const severity = malware ? "critical" : graded.severity;
+    const cvssScore = graded.cvssScore;
     const fixedVersion = extractFixedVersion(vuln.affected, dep.name, dep.ecosystem, dep.version);
     return {
         package: dep.name,
@@ -285,6 +492,8 @@ function mapVulnerability(vuln, dep) {
         aliases: vuln.aliases || [],
         severity,
         cvssScore,
+        ...(malware ? { malware: true } : {}),
+        maintenance: isMaintenanceRecord(vuln, dep.name, dep.ecosystem),
         summary: vuln.summary || vuln.details?.slice(0, 200) || vuln.id,
         fixedVersion,
         published: vuln.published || vuln.modified || "",
@@ -299,19 +508,43 @@ function mapVulnerability(vuln, dep) {
         installFix: dep.installFix,
     };
 }
+const GRADE_RANK = { unknown: 0, low: 1, medium: 2, high: 3, critical: 4 };
+/**
+ * The shared rule for an unrated record (the 4DA app implements it
+ * identically): the HIGHEST grade among every GHSA alias that could be read;
+ * unknown when none could. `from` names the alias that gave it, the
+ * lexicographically smallest id on a tie. An alias that could not be read
+ * never lowers the grade; it is reported (`consulted`, grade "unreadable").
+ * Umbrella records name several: RUSTSEC-2020-0014 lists 8 GHSAs, so taking
+ * the first made the grade depend on alias order.
+ */
+export function gradeFromAliases(ghsas, read) {
+    const consulted = [...new Set(ghsas)].sort().map((id) => ({ id, grade: read.get(id) ?? "unreadable" }));
+    let best = null;
+    for (const c of consulted) {
+        if (c.grade === "unreadable" || c.grade === "unknown")
+            continue;
+        if (!best || GRADE_RANK[c.grade] > GRADE_RANK[best.grade])
+            best = { id: c.id, grade: c.grade };
+    }
+    return { severity: best?.grade ?? "unknown", from: best?.id ?? null, consulted };
+}
 /**
  * Derive a severity bucket honestly: a CVSS base score (numeric or computed
  * from a vector) wins; otherwise the GitHub-advisory label; otherwise unknown.
  * Never fabricates a default bucket — an advisory with no severity signal is
  * reported as `unknown`, not silently labeled "medium".
  */
-function deriveSeverity(vuln) {
+export function deriveSeverity(vuln) {
+    // The curated label first, the CVSS band second (the rule shared with the 4DA app, 2026-10-18,
+    // severity vectors sv-015..sv-017): on the pinned corpus 123 of 3,923 records disagree, all GHSA,
+    // 113 beside a CVSS v4 vector neither engine scores and the label follows. A CVSS 0.0 goes by its label.
     const cvssScore = extractCvssScore(vuln.severity);
-    if (cvssScore !== null)
-        return { severity: cvssToSeverity(cvssScore), cvssScore };
     const label = labelToSeverity(vuln.database_specific?.severity);
     if (label !== "unknown")
-        return { severity: label, cvssScore: null };
+        return { severity: label, cvssScore };
+    if (cvssScore !== null)
+        return { severity: cvssToSeverity(cvssScore), cvssScore };
     return { severity: "unknown", cvssScore: null };
 }
 function labelToSeverity(label) {
@@ -399,7 +632,7 @@ export function extractFixedVersion(affected, packageName, ecosystem, installedV
     // The interval whose release line the installed version sits on. An
     // unreadable bound compares as 0, which keeps those intervals eligible on
     // the introduced side only; "0" (since inception) orders below everything.
-    const containing = intervals.find((i) => cmp(installedVersion, i.introduced) >= 0 &&
+    const containing = intervals.find((i) => compareToLowerBound(installedVersion, i.introduced, ecosystem) >= 0 &&
         (i.fixed !== null
             ? cmp(installedVersion, i.fixed) < 0
             : i.lastAffected === null || cmp(installedVersion, i.lastAffected) <= 0));
@@ -413,3 +646,21 @@ export function extractFixedVersion(affected, packageName, ecosystem, installedV
         return null;
     return above.reduce((min, v) => (cmp(v, min) < 0 ? v : min), above[0]);
 }
+/**
+ * npm's security holding placeholder: after a malicious package is taken down,
+ * npm republishes the name as an empty `0.0.<n>-security` release ("security
+ * holding package"). It has no code, so NO advisory applies to it, whichever
+ * database's id flags the name: crossenv 0.0.2-security under
+ * GHSA-c2m4-w5hm-vqjw read as installed malware when only MAL- ids were held
+ * (4DA audit L4, 2026-10-16). Only npm's own shape counts: a publisher's
+ * `1.0.0-security` prerelease is real code and stays affected. The same rule
+ * as the app's `fourda_depengine::matching::is_npm_security_holding`
+ * (shared vectors `holding.jsonl`).
+ */
+export function isSecurityHoldingRelease(ecosystem, version) {
+    return ecosystem.trim().toLowerCase() === "npm" && /^0\.0\.\d+-security$/.test(version.trim());
+}
+/** A finding on an npm security holding placeholder (any advisory id): not installed code. */
+export function isNpmSecurityHolding(v) {
+    return isSecurityHoldingRelease(v.ecosystem, v.currentVersion);
+}

package/dist/live/pinned-advisories.d.ts

@@ -14,7 +14,7 @@
  * Withdrawn records are still returned by `query`: the scanner drops them
  * after reading the record, exactly as it does with OSV's answers.
  */
-import type { AdvisorySource } from "./osv-scanner.js";
+import type { AdvisoryAnswer, AdvisorySource } from "./osv-scanner.js";
 import type { OsvVulnerability, ResolvedDependency } from "./types.js";
 export declare class PinnedRecordsSource implements AdvisorySource {
     readonly network = false;
@@ -26,6 +26,6 @@ export declare class PinnedRecordsSource implements AdvisorySource {
     get size(): number;
     /** The ids of the pinned records that affect this exact version (withdrawn ones included). */
     affecting(ecosystem: string, name: string, version: string): string[];
-    query(deps: ResolvedDependency[]): Promise<string[][]>;
+    query(deps: ResolvedDependency[]): Promise<AdvisoryAnswer>;
     details(ids: string[]): Promise<Map<string, OsvVulnerability>>;
 }