Merge pull request #84 from sonukapoor/feature/issue-79-advisory-db-freshness

[Enhancement] Add advisory DB freshness metadata and stale warnings

Author: sonukapoor

src/advisory/local-db.ts

@@ -11,6 +11,11 @@ type AdvisoryRangeRow = {
   last_affected: string | null;
 };
 
+export type AdvisoryDbMetadata = {
+  lastSyncAt: string | null;
+  sourceUrl: string | null;
+};
+
 const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS advisories (
     id TEXT PRIMARY KEY,
@@ -35,6 +40,12 @@ const SCHEMA_SQL = `
 
   CREATE INDEX IF NOT EXISTS idx_advisory_packages_advisory
     ON advisory_packages (advisory_id);
+
+  CREATE TABLE IF NOT EXISTS advisory_db_metadata (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    last_sync_at TEXT,
+    source_url TEXT
+  );
 `;
 
 export class LocalAdvisoryDatabase {
@@ -59,6 +70,32 @@ export class LocalAdvisoryDatabase {
     this.db.close();
   }
 
+  setMetadata(metadata: AdvisoryDbMetadata): void {
+    this.db.prepare(`
+      INSERT INTO advisory_db_metadata (id, last_sync_at, source_url)
+      VALUES (1, @last_sync_at, @source_url)
+      ON CONFLICT(id) DO UPDATE SET
+        last_sync_at = excluded.last_sync_at,
+        source_url = excluded.source_url
+    `).run({
+      last_sync_at: metadata.lastSyncAt,
+      source_url: metadata.sourceUrl,
+    });
+  }
+
+  getMetadata(): AdvisoryDbMetadata {
+    const row = this.db.prepare(`
+      SELECT last_sync_at, source_url
+      FROM advisory_db_metadata
+      WHERE id = 1
+    `).get() as { last_sync_at: string | null; source_url: string | null } | undefined;
+
+    return {
+      lastSyncAt: row?.last_sync_at ?? null,
+      sourceUrl: row?.source_url ?? null,
+    };
+  }
+
   upsertVulnerability(vuln: OsvVuln): void {
     const advisoryRows = deriveAdvisoryPackageRows(vuln);
     const advisoryJson = JSON.stringify(vuln);

src/advisory/osv-sync.ts

@@ -6,6 +6,7 @@ import type { OsvVuln } from "../types.js";
 import { LocalAdvisoryDatabase } from "./local-db.js";
 
 const DEFAULT_OSV_NPM_DUMP_URL = "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip";
+export const ADVISORY_DB_STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
 
 export type SyncOsvAdvisoriesOptions = {
   outputPath?: string;
@@ -165,6 +166,11 @@ export async function syncOsvAdvisories(
       }
     }
 
+    db.setMetadata({
+      lastSyncAt: new Date().toISOString(),
+      sourceUrl,
+    });
+
     onProgress?.({
       phase: "complete",
       advisoryCount,

src/index.ts

@@ -89,13 +89,24 @@ async function main() {
   }
 
   let advisorySourceLine: string;
+  let advisoryDbFreshnessLine: string | null = null;
+  let advisoryDbWarning: string | null = null;
   try {
     const advisorySource = createAdvisorySource({
       osvUrl: options.osvUrl,
       offline: options.offline,
       offlineDb: options.offlineDb,
     });
     advisorySourceLine = advisorySource.sourceLabel;
+    if (advisorySource.offline) {
+      const metadata = advisorySource.advisoryDbMetadata;
+      advisoryDbFreshnessLine = formatAdvisoryDbFreshness(metadata?.lastSyncAt ?? null);
+      if (advisorySource.advisoryDbIsStale) {
+        advisoryDbWarning = metadata?.lastSyncAt
+          ? "The local advisory DB appears stale. Re-run `cve-lite advisories sync` to refresh it."
+          : "The local advisory DB has no recorded sync timestamp. Re-run `cve-lite advisories sync` to refresh it.";
+      }
+    }
     advisorySource.cleanup();
   } catch (error) {
     if (options.offline || options.offlineDb) {
@@ -108,6 +119,12 @@ async function main() {
     console.log(chalk.gray("Offline mode:") + " " + chalk.yellow("enabled") + " " + chalk.gray("(no external advisory calls will be made)"));
   }
   console.log(`${chalk.gray("Advisory source:")} ${formatAdvisorySourceLine(advisorySourceLine)}`);
+  if (advisoryDbFreshnessLine) {
+    console.log(`${chalk.gray("Advisory DB freshness:")} ${advisoryDbFreshnessLine}`);
+  }
+  if (advisoryDbWarning) {
+    logWarn(advisoryDbWarning, options);
+  }
 
   const scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth);
   const packages = scanInput.packages;
@@ -195,3 +212,38 @@ function formatAdvisorySourceLine(sourceLabel: string): string {
 
   return `${match[1]} (${chalk.cyan(match[2])})`;
 }
+
+function formatAdvisoryDbFreshness(lastSyncAt: string | null): string {
+  if (!lastSyncAt) {
+    return chalk.yellow("unknown");
+  }
+
+  const timestamp = Date.parse(lastSyncAt);
+  if (Number.isNaN(timestamp)) {
+    return chalk.yellow("unknown");
+  }
+
+  return `${relativeAge(timestamp)} ${chalk.gray(`(${lastSyncAt})`)}`;
+}
+
+function relativeAge(timestamp: number): string {
+  const deltaMs = Math.max(0, Date.now() - timestamp);
+  const minute = 60 * 1000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+
+  if (deltaMs < minute) {
+    return "just synced";
+  }
+  if (deltaMs < hour) {
+    const minutes = Math.floor(deltaMs / minute);
+    return `synced ${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  }
+  if (deltaMs < day) {
+    const hours = Math.floor(deltaMs / hour);
+    return `synced ${hours} hour${hours === 1 ? "" : "s"} ago`;
+  }
+
+  const days = Math.floor(deltaMs / day);
+  return `synced ${days} day${days === 1 ? "" : "s"} ago`;
+}

src/scanner.ts

@@ -7,14 +7,16 @@ import { createSpinner } from "./output/spinner.js";
 import { OsvAdvisorySource } from "./advisory/osv-advisory-source.js";
 import { AdvisorySource } from "./advisory/advisory-source.js";
 import { LocalAdvisorySource } from "./advisory/local-advisory-source.js";
-import { LocalAdvisoryDatabase } from "./advisory/local-db.js";
-import { getDefaultAdvisoryDbPath } from "./advisory/osv-sync.js";
+import { AdvisoryDbMetadata, LocalAdvisoryDatabase } from "./advisory/local-db.js";
+import { ADVISORY_DB_STALE_AFTER_MS, getDefaultAdvisoryDbPath } from "./advisory/osv-sync.js";
 import { resolveRecommendedParentUpgrade } from "./remediation/parent-upgrade.js";
 
 type AdvisorySourceContext = {
   advisorySource: AdvisorySource;
   offline: boolean;
   sourceLabel: string;
+  advisoryDbMetadata: AdvisoryDbMetadata | null;
+  advisoryDbIsStale: boolean;
   cleanup: () => void;
 };
 
@@ -32,6 +34,8 @@ export function createAdvisorySource(options?: {
       advisorySource: new LocalAdvisorySource(db),
       offline: true,
       sourceLabel: `local advisory database (${dbPath})`,
+      advisoryDbMetadata: db.getMetadata(),
+      advisoryDbIsStale: isAdvisoryDbStale(db.getMetadata()),
       cleanup: () => db.close(),
     };
   }
@@ -42,6 +46,8 @@ export function createAdvisorySource(options?: {
     sourceLabel: options?.osvUrl
       ? `custom OSV endpoint (${options.osvUrl})`
       : "OSV (https://api.osv.dev)",
+    advisoryDbMetadata: null,
+    advisoryDbIsStale: false,
     cleanup: () => {},
   };
 }
@@ -226,6 +232,19 @@ export async function scanPackages(
   }
 }
 
+function isAdvisoryDbStale(metadata: AdvisoryDbMetadata): boolean {
+  if (!metadata.lastSyncAt) {
+    return true;
+  }
+
+  const timestamp = Date.parse(metadata.lastSyncAt);
+  if (Number.isNaN(timestamp)) {
+    return true;
+  }
+
+  return Date.now() - timestamp > ADVISORY_DB_STALE_AFTER_MS;
+}
+
 function classifyRelationship(paths: string[][]): "direct" | "transitive" | "unknown" {
   if (paths.length === 0) return "unknown";
   const shortest = Math.min(...paths.map(p => p.length));

tests/cli-integration.test.ts

@@ -53,6 +53,10 @@ jest.unstable_mockModule("../src/scanner.js", () => ({
       : options?.osvUrl
         ? `custom OSV endpoint (${options.osvUrl})`
         : "OSV (https://api.osv.dev)",
+    advisoryDbMetadata: options?.offline || options?.offlineDb
+      ? { lastSyncAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), sourceUrl: "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip" }
+      : null,
+    advisoryDbIsStale: false,
     cleanup: jest.fn(),
   })),
 }));
@@ -321,6 +325,47 @@ describe("CLI integration", () => {
     expect(stripAnsi(result.stdout[0] ?? "")).toContain("Offline mode: enabled");
     expect(stripAnsi(result.stdout[1] ?? "")).toContain("Advisory source: local advisory database");
     expect(stripAnsi(result.stdout[1] ?? "")).toContain("/tmp/advisories.db");
+    expect(stripAnsi(result.stdout[2] ?? "")).toContain("Advisory DB freshness: synced");
+  });
+
+  it("warns when the local advisory DB appears stale", async () => {
+    const createAdvisorySourceMock = (await import("../src/scanner.js")).createAdvisorySource as jest.Mock;
+    createAdvisorySourceMock.mockReturnValueOnce({
+      advisorySource: { queryBatch: jest.fn(), getVuln: jest.fn() },
+      offline: true,
+      sourceLabel: "local advisory database (/tmp/advisories.db)",
+      advisoryDbMetadata: {
+        lastSyncAt: new Date(Date.now() - 10 * 24 * 60 * 60 * 1000).toISOString(),
+        sourceUrl: "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip",
+      },
+      advisoryDbIsStale: true,
+      cleanup: jest.fn(),
+    });
+
+    parseArgsMock.mockReturnValue({
+      command: "scan",
+      options: {
+        json: true,
+        offline: true,
+        offlineDb: "/tmp/advisories.db",
+        failOn: "critical",
+        batchSize: "100",
+        searchDepth: "4",
+        minSeverity: "medium",
+      },
+      projectArg: ".",
+    });
+    loadPackagesMock.mockReturnValue(createScanInput({
+      packages: [{ name: "lodash", version: "4.17.21", ecosystem: "npm", paths: [["project", "lodash"]] }],
+    }));
+
+    const result = await runIndexModule();
+
+    expect(result.exitCode).toBe(0);
+    expect(logWarnMock).toHaveBeenCalledWith(
+      "The local advisory DB appears stale. Re-run `cve-lite advisories sync` to refresh it.",
+      expect.anything(),
+    );
   });
 
   it("routes advisories sync through the sync module and exits successfully", async () => {

tests/local-advisory-source.test.ts

@@ -160,4 +160,24 @@ describe("LocalAdvisorySource", () => {
       cleanupDbPath(dbPath);
     }
   });
+
+  it("stores and returns advisory DB metadata", () => {
+    const dbPath = createTempDbPath();
+    const db = new LocalAdvisoryDatabase(dbPath);
+
+    try {
+      db.setMetadata({
+        lastSyncAt: "2026-04-04T00:00:00.000Z",
+        sourceUrl: "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip",
+      });
+
+      expect(db.getMetadata()).toEqual({
+        lastSyncAt: "2026-04-04T00:00:00.000Z",
+        sourceUrl: "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip",
+      });
+    } finally {
+      db.close();
+      cleanupDbPath(dbPath);
+    }
+  });
 });

tests/osv-sync.test.ts

@@ -86,6 +86,10 @@ describe("syncOsvAdvisories", () => {
 
       const db = new LocalAdvisoryDatabase(dbPath, { readonly: true });
       try {
+        expect(db.getMetadata()).toMatchObject({
+          lastSyncAt: expect.any(String),
+          sourceUrl: "https://mirror.example/npm/all.zip",
+        });
         expect(db.getVulnerability("OSV-1")).toMatchObject({ id: "OSV-1" });
         expect(db.findMatchingVulnerabilityIds({ ecosystem: "npm", name: "lodash", version: "4.17.20" })).toEqual(["OSV-1"]);
         expect(db.findMatchingVulnerabilityIds({ ecosystem: "npm", name: "lodash", version: "4.17.21" })).toEqual([]);
@@ -128,6 +132,7 @@ describe("syncOsvAdvisories", () => {
 
       const db = new LocalAdvisoryDatabase(dbPath, { readonly: true });
       try {
+        expect(db.getMetadata().lastSyncAt).toEqual(expect.any(String));
         expect(db.getVulnerability("OSV-3")).toMatchObject({ id: "OSV-3" });
       } finally {
         db.close();