feat(security): advisory early-warning correlation and audit provenance records

.github/actions/ci-wechat-runtime-audit/audit.sh

@@ -138,12 +138,116 @@ for package_spec in "$wechat_spec" "qrcode-terminal@0.12.0" "zod@4.4.3"; do
 done
 
 audit_status=0
+audit_started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 npm --prefix "$runtime_dir" audit \
   --userconfig "$trusted_npmrc" \
   --registry "$npm_registry" \
   --omit=dev \
   --audit-level=low \
   --json >"$report_dir/npm-audit.json" || audit_status=$?
+audit_finished_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Record scanner/database provenance next to the raw report so a later reader
+# can establish exactly which registry endpoint served this audit (#7338).
+# Mirrors the *.provenance.json sidecars scripts/audit-reviewed-npm-graph.mts
+# writes for the reviewed graphs. Keep the endpoint derivation and GHSA id
+# extraction below in sync with deriveAuditEndpoints/extractAdvisoryIds in
+# that script; a shared implementation would need a Node module boundary this
+# shell action does not have.
+REPORT_PATH="$report_dir/npm-audit.json" \
+  PROVENANCE_PATH="$report_dir/npm-audit.provenance.json" \
+  CONFIGURED_REGISTRY="$npm_registry" \
+  PACKAGE_SPEC="$wechat_spec" \
+  STARTED_AT="$audit_started_at" \
+  FINISHED_AT="$audit_finished_at" \
+  AUDIT_STATUS="$audit_status" \
+  NPM_VERSION="$(npm --version)" \
+  node <<'NODE'
+const fs = require("node:fs");
+let report = {};
+let failure;
+try {
+  report = JSON.parse(fs.readFileSync(process.env.REPORT_PATH, "utf8"));
+} catch {
+  // A transport failure can leave a non-JSON report; the audit status check
+  // below still fails the run, and the sidecar records the attempt.
+  failure = "npm audit did not produce a parseable JSON report";
+}
+if (typeof report !== "object" || report === null || Array.isArray(report)) {
+  // JSON.parse also accepts null, arrays, and bare strings, which real npm
+  // never emits; normalize so the checks below cannot crash and the sidecar
+  // still records the attempt as failed.
+  report = {};
+  if (failure === undefined) {
+    failure = "npm audit did not produce a JSON object report";
+  }
+}
+// npm's dominant failure mode writes PARSEABLE error JSON (`{"error": ...}`)
+// and exits nonzero; mirror parseAuditReport in
+// scripts/audit-reviewed-npm-graph.mts so such a run is never mistaken for a
+// clean scan: report.error, exit status above 1, or a nonzero exit with zero
+// findings all mark the attempt as failed.
+const auditStatus = Number(process.env.AUDIT_STATUS);
+const severities = ["info", "low", "moderate", "high", "critical"];
+const severityCounts = report?.metadata?.vulnerabilities;
+const hasCompleteSeverityCounts =
+  severityCounts &&
+  typeof severityCounts === "object" &&
+  !Array.isArray(severityCounts) &&
+  severities.every((severity) => {
+    const count = severityCounts[severity];
+    return typeof count === "number" && Number.isSafeInteger(count) && count >= 0;
+  });
+const findingCount = hasCompleteSeverityCounts
+  ? severities.reduce((total, severity) => total + severityCounts[severity], 0)
+  : 0;
+if (failure === undefined && report.error !== undefined) {
+  failure = `npm audit returned an error report: ${JSON.stringify(report.error)}`;
+} else if (failure === undefined && !hasCompleteSeverityCounts) {
+  failure = "npm audit did not produce a complete vulnerability finding report";
+} else if (
+  failure === undefined &&
+  (!Number.isSafeInteger(auditStatus) ||
+    auditStatus > 1 ||
+    (auditStatus !== 0 && findingCount === 0))
+) {
+  failure = `npm audit exited ${process.env.AUDIT_STATUS} without vulnerability findings`;
+}
+const advisoryIds = new Set();
+const findings = report && typeof report.vulnerabilities === "object" ? report.vulnerabilities : {};
+for (const finding of Object.values(findings ?? {})) {
+  const via = Array.isArray(finding?.via) ? finding.via : [];
+  for (const cause of via) {
+    const url = typeof cause === "object" && cause !== null ? cause.url : undefined;
+    if (typeof url !== "string") continue;
+    for (const match of url.match(/GHSA(?:-[23456789cfghjmpqrvwx]{4}){3}/gi) ?? []) {
+      advisoryIds.add(`GHSA${match.slice(4).toLowerCase()}`);
+    }
+  }
+}
+const registryBase = process.env.CONFIGURED_REGISTRY.replace(/\/+$/, "");
+const provenance = {
+  schemaVersion: 1,
+  scanner: {
+    name: "npm audit",
+    npmVersion: process.env.NPM_VERSION,
+    nodeVersion: process.version,
+  },
+  registry: {
+    configuredRegistry: process.env.CONFIGURED_REGISTRY,
+    bulkAdvisoryEndpoint: `${registryBase}/-/npm/v1/security/advisories/bulk`,
+    note: "npm audit posts the dependency graph to the bulk advisory endpoint of the configured registry; on request failure npm reports no advisory data.",
+  },
+  run: { startedAt: process.env.STARTED_AT, finishedAt: process.env.FINISHED_AT },
+  graph: { label: "WeChat locked runtime graph", packageSpecs: [process.env.PACKAGE_SPEC] },
+  // rawReportPath is relative to the directory containing the sidecar.
+  rawReportPath: "npm-audit.json",
+  advisoryIds: [...advisoryIds].sort(),
+  ...(failure === undefined ? {} : { failure }),
+};
+fs.writeFileSync(process.env.PROVENANCE_PATH, `${JSON.stringify(provenance, null, 2)}\n`);
+if (failure !== undefined) process.exitCode = 1;
+NODE
 
 signature_status=0
 npm --prefix "$runtime_dir" audit signatures \

docs/security/advisory-early-warning.md

@@ -0,0 +1,101 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Advisory Early Warning and Audit Provenance
+
+Status: correlation module, scan CLI, and audit provenance implemented.
+Scheduled operation and the response policy are a separate follow-up, gated on
+product/security-owner sign-off recorded on issue #7338 (evidence from #7276).
+
+Public upstream GitHub Security Advisories are often published weeks before the
+global reviewed ecosystem record that `npm audit` enforces. For
+`fast-uri` (GHSA-4c8g-83qw-93j6) the upstream repository advisory appeared on
+June 29 while the reviewed record propagated on July 21, so the same vulnerable
+version audited clean at 18:46 UTC and reported High at 20:09 UTC. This page
+documents the early-warning correlation that narrows that gap and the
+provenance every audit now records so such timelines are provable from retained
+artifacts.
+
+The correlation draws on all three types of the global advisory database, which
+contribute differently:
+
+- reviewed records are the corpus `npm audit` enforces — a match here means
+  package-level enforcement is imminent or already active, and the signal
+  confirms the reviewed gate will catch it;
+- unreviewed records are NVD-sourced and often appear before curation reaches
+  the reviewed feed — they usually lack a verified npm mapping, so they flow
+  through the ambiguous, informational-only path and provide the earlier
+  heads-up;
+- malware records name npm packages published as malware — a match against the
+  reviewed inventory correlates like any other record and is equally
+  non-blocking.
+
+Polling upstream *repository* advisories directly (the earliest public signal,
+e.g. `fastify/fast-uri`'s own advisory) needs a package-to-repository map and
+is the planned extension; the correlation module already accepts that record
+shape unchanged.
+
+## How the early-warning correlation works
+
+- `scripts/lib/advisory-early-warning.mts` correlates GitHub Security Advisory
+  JSON (repository-level and global records share the shape) with the reviewed
+  npm inventory and emits structured signals:
+  `{advisoryId, package, vulnerableRange, matchedVersions, source, confidence, action}`.
+- The inventory is derived from `ci/reviewed-npm-audit.json`: every committed
+  archive package spec plus the installed packages of each locked graph's
+  `package-lock.json`.
+- Confidence is encoded, never guessed: only an exact npm ecosystem +
+  package-name + parseable semver-range match yields `confidence: "exact"` and
+  `action: "investigate"`. Name collisions from non-npm (CPE-derived) records
+  and unparseable ranges yield `confidence: "ambiguous"` and
+  `action: "informational"`. Ambiguous matches never block or mutate a release.
+- The reviewed npm audit gate (`scripts/audit-reviewed-npm-graph.mts`, enforced
+  in CI) remains enabled and authoritative for exact npm package/version-range
+  decisions. The early-warning path only triggers investigation and rescanning.
+
+`scripts/advisory-early-warning-scan.mts` is the CLI over the module.
+It reads only local files and exits 0 whether or not signals are found.
+It does not modify input files or external state.
+With `--output`, it writes the requested local signals file:
+
+```sh
+# List inventory package names (one per line), the input for advisory queries.
+node --experimental-strip-types scripts/advisory-early-warning-scan.mts \
+  --list-packages
+
+# Correlate fetched advisory records with the inventory.
+node --experimental-strip-types scripts/advisory-early-warning-scan.mts \
+  --advisories advisories.json --output signals.json
+```
+
+Advisory records come from the GitHub `/advisories` API — all three types,
+paginated, filtered by `affects=` batches of the inventory package names.
+
+Running this correlation on a schedule and routing signals to an alert
+destination is deliberately not wired up yet: #7338 requires product/security
+owners to define the supported historical-image scope, rescan ownership, alert
+destination, and response expectations first. A follow-up adds the scheduled
+workflow once that sign-off is recorded on the issue.
+
+## Provenance recorded per audit
+
+Each reviewed npm audit report now has a `*.provenance.json` sidecar
+(`coverage/reviewed-npm-audit/` artifacts, and `npm-audit.provenance.json` for
+the WeChat locked runtime graph audit) recording:
+
+- scanner identity: `npm audit`, npm version, Node.js version;
+- the configured registry, with URL credentials removed, plus the derived bulk
+  advisory endpoint npm posts the dependency graph to (npm >= 7 has no
+  quick-audit fallback: on request failure npm reports no advisory data, and
+  the note records this);
+- run start and finish timestamps (ISO 8601);
+- the audited graph label and committed package specs;
+- the raw machine-readable report path (`rawReportPath`, by convention
+  relative to the directory containing the sidecar);
+- the GHSA advisory ids extracted from the report; and
+- a `failure` marker when the audit attempt itself failed, so the sidecar
+  still records the attempt.
+
+Comparing the `advisoryIds` of consecutive retained runs identifies the last
+comparable non-detection and the first detection of a newly surfaced advisory,
+even when an unrelated finding failed the earlier run.

scripts/advisory-early-warning-scan.mts

@@ -0,0 +1,106 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// CLI entry for the advisory early-warning path (#7338). Correlates public
+// GitHub Security Advisory JSON with the reviewed npm inventory derived from
+// ci/reviewed-npm-audit.json (committed package specs plus the locked-graph
+// package-locks) and prints structured, NON-blocking signals. Signals never
+// fail the process: enforcement stays with the reviewed npm audit gate.
+//
+// Usage:
+//   advisory-early-warning-scan.mts --list-packages
+//   advisory-early-warning-scan.mts --advisories <advisories.json> [--output <signals.json>]
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  type AdvisorySignal,
+  correlateAdvisories,
+  type InventoryEntry,
+  parseInventoryFromAuditConfig,
+  parseInventoryFromPackageLock,
+} from "./lib/advisory-early-warning.mts";
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG_RELATIVE_PATH = path.join("ci", "reviewed-npm-audit.json");
+
+function loadReviewedInventory(): InventoryEntry[] {
+  const config = JSON.parse(
+    fs.readFileSync(path.join(REPO_ROOT, CONFIG_RELATIVE_PATH), "utf-8"),
+  ) as Record<string, unknown>;
+  const inventory = parseInventoryFromAuditConfig(config, CONFIG_RELATIVE_PATH);
+  const lockedGraphs = Array.isArray(config.lockedGraphs) ? config.lockedGraphs : [];
+  for (const graph of lockedGraphs) {
+    const directory = (graph as Record<string, unknown> | null)?.directory;
+    if (typeof directory !== "string" || directory.length === 0) continue;
+    const lockRelativePath = path.join(directory, "package-lock.json");
+    const lockPath = path.join(REPO_ROOT, lockRelativePath);
+    if (!fs.existsSync(lockPath)) continue;
+    const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8")) as unknown;
+    inventory.push(...parseInventoryFromPackageLock(lock, lockRelativePath));
+  }
+  return inventory;
+}
+
+function loadAdvisories(advisoriesPath: string): unknown[] {
+  const parsed = JSON.parse(fs.readFileSync(advisoriesPath, "utf-8")) as unknown;
+  return Array.isArray(parsed) ? parsed : [parsed];
+}
+
+function describeSignal(signal: AdvisorySignal): string {
+  return `${signal.advisoryId} ${signal.package} ${signal.vulnerableRange || "(no range)"} -> ${signal.action} (${signal.confidence}, matched ${signal.matchedVersions.join(", ")})`;
+}
+
+function readFlagValue(argv: readonly string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  if (index < 0) return undefined;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function main(argv: readonly string[]): void {
+  const inventory = loadReviewedInventory();
+  if (argv.includes("--list-packages")) {
+    const names = [...new Set(inventory.map((entry) => entry.name))].sort();
+    for (const name of names) console.log(name);
+    return;
+  }
+  const advisoriesPath = readFlagValue(argv, "--advisories");
+  if (!advisoriesPath) {
+    throw new Error(
+      "usage: advisory-early-warning-scan.mts --list-packages | --advisories <file> [--output <file>]",
+    );
+  }
+  const advisories = loadAdvisories(advisoriesPath);
+  const signals = correlateAdvisories(advisories, inventory);
+  const outputPath = readFlagValue(argv, "--output");
+  if (outputPath) {
+    fs.writeFileSync(outputPath, `${JSON.stringify(signals, null, 2)}\n`);
+  }
+  console.log(
+    `advisory early warning: ${advisories.length} advisories, ${inventory.length} inventory entries, ${signals.length} signals`,
+  );
+  for (const signal of signals) console.log(describeSignal(signal));
+  // Signals are intentionally non-blocking: the process exits 0 either way,
+  // and the caller routes signals to a tracking issue for investigation.
+}
+
+function isMainModule(): boolean {
+  return process.argv[1]
+    ? import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+    : false;
+}
+
+if (isMainModule()) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

scripts/audit-reviewed-npm-graph.mts

@@ -153,6 +153,7 @@ function main(): void {
   );
   fs.rmSync(artifactDirectory, { recursive: true, force: true });
   fs.mkdirSync(artifactDirectory, { recursive: true });
+  const npmVersion = run("npm", ["--version"], REPO_ROOT).stdout.trim();
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-reviewed-npm-audit-"));
   try {
     const reports = [
@@ -162,6 +163,12 @@ function main(): void {
           directory: materializeArchiveGraph(config.archivePackages, tempRoot),
           exceptionFile,
           graph: config.archiveGraphId,
+          provenance: {
+            label: "reviewed archive graph",
+            nodeVersion: process.version,
+            npmVersion,
+            packageSpecs: config.archivePackages.map((reviewed) => reviewed.packageSpec),
+          },
           reportFile: path.join(artifactDirectory, "reviewed-archive-graph.json"),
           resultFile: path.join(artifactDirectory, "reviewed-archive-graph-policy.json"),
           threshold: config.severityThreshold,
@@ -174,6 +181,12 @@ function main(): void {
           directory: materializeLockedGraph(graph, tempRoot),
           exceptionFile,
           graph: graph.id,
+          provenance: {
+            label: graph.label,
+            nodeVersion: process.version,
+            npmVersion,
+            packageSpecs: [graph.packageSpec],
+          },
           reportFile: path.join(artifactDirectory, `locked-graph-${index + 1}.json`),
           resultFile: path.join(artifactDirectory, `locked-graph-${index + 1}-policy.json`),
           threshold: config.severityThreshold,