ohdear-npm-audit 1.3.0 → 1.5.0

package/README.md

@@ -33,7 +33,13 @@ export default withOhDearHealth({
 });
 ```
 
-The wrapper generates the manifest automatically when the config is evaluated (before the build starts). It also checks for critical vulnerabilities at build time and logs the results.
+The wrapper generates the manifest automatically when the config is evaluated (before the build starts). It also checks for critical vulnerabilities at build time and logs enriched results including dependency chains and vulnerable version ranges:
+
+```
+ohdear-npm-audit: 1 critical vulnerabilities:
+  - form-data@1.0.0 (via axios → form-data): unsafe random function
+    vulnerable: <1.0.1 — https://github.com/advisories/GHSA-xxx
+```
 
 ```js
 withOhDearHealth(nextConfig, {
@@ -72,8 +78,8 @@ This must match the secret configured in Oh Dear for your application health che
 
 ## How it works
 
-1. **Build time** — The CLI or Next.js wrapper runs `pnpm list` / `npm ls` to extract all production dependencies (including transitive) and writes them to a JSON manifest. When using the Next.js wrapper, a build-time vulnerability check is also performed and results are logged
-2. **Runtime** — On each GET request, the handler verifies the Oh Dear secret header, POSTs the manifest to the [npm bulk advisory API](https://docs.npmjs.com/about-audit-reports), filters for critical severity, and returns the result in the [Oh Dear health check format](https://ohdear.app/docs/features/application-health-monitoring)
+1. **Build time** — The CLI or Next.js wrapper runs `pnpm list` / `npm ls` to extract all production dependencies (including transitive) and writes them to a JSON manifest that includes a reverse dependency map for tracing dependency chains. When using the Next.js wrapper, a build-time vulnerability check is performed and results are logged with the full dependency chain (e.g. `axios → form-data`) and vulnerable version ranges
+2. **Runtime** — On each GET request, the handler verifies the Oh Dear secret header, POSTs the manifest to the [npm bulk advisory API](https://docs.npmjs.com/about-audit-reports), filters for critical severity, and returns the result in the [Oh Dear health check format](https://ohdear.app/docs/features/application-health-monitoring). Each vulnerability includes installed versions, vulnerable version range, and the dependency chain
 
 ### Response format
 
@@ -93,6 +99,19 @@ This must match the secret configured in Oh Dear for your application health che
 }
 ```
 
+When vulnerabilities are found, `meta.vulnerabilities` contains an array of:
+
+```json
+{
+  "package": "form-data",
+  "installedVersions": ["1.0.0"],
+  "title": "form-data uses unsafe random function",
+  "url": "https://github.com/advisories/GHSA-xxx",
+  "vulnerableVersions": "<1.0.1",
+  "dependencyChain": ["axios", "form-data"]
+}
+```
+
 `status` is `"ok"` when there are no critical vulnerabilities, `"warning"` when the npm advisory API is unreachable, `"failed"` otherwise.
 
 ## API
@@ -132,7 +151,7 @@ Defaults to `deps-manifest.json` in the current directory. Detects the package m
 ```
 src/
 ├── types.ts      # Shared types (DepsManifest, Vulnerability, HealthCheckResponse)
-├── generate.ts   # Manifest generation logic (build-time, execSync)
+├── generate.ts   # Manifest + reverse dep map generation (build-time, execSync)
 ├── handler.ts    # createHealthHandler factory — main export "."
 ├── next.ts       # withOhDearHealth wrapper — export "./next"
 └── bin.ts        # CLI entry point — bin "ohdear-deps-manifest"

package/dist/bin.js

@@ -11,5 +11,5 @@ if (outputIdx !== -1 && args[outputIdx + 1]) {
 }
 const cwd = process.cwd();
 const outputPath = (0, node_path_1.resolve)(cwd, output);
-const { manifest } = (0, generate_js_1.writeManifest)(outputPath, cwd);
-console.log(`deps-manifest.json: ${Object.keys(manifest).length} packages written`);
+const manifest = (0, generate_js_1.writeManifest)(outputPath, cwd);
+console.log(`${output}: ${Object.keys(manifest.packages).length} packages written`);

package/dist/generate.d.ts

@@ -1,11 +1,3 @@
 import type { DepsManifest } from "./types.js";
-export interface GenerateResult {
-    manifest: DepsManifest;
-    reverseDeps: Record<string, string[]>;
-}
-export declare function generateManifest(cwd: string): GenerateResult;
-export interface WriteManifestResult {
-    manifest: DepsManifest;
-    reverseMapPath: string;
-}
-export declare function writeManifest(outputPath: string, cwd: string): WriteManifestResult;
+export declare function generateManifest(cwd: string): DepsManifest;
+export declare function writeManifest(outputPath: string, cwd: string): DepsManifest;

package/dist/generate.js

@@ -23,9 +23,9 @@ function walkDeps(deps, acc, reverseDeps, parent) {
         if (!acc[name])
             acc[name] = new Set();
         acc[name].add(info.version);
+        if (!reverseDeps[name])
+            reverseDeps[name] = new Set();
         if (parent !== "root") {
-            if (!reverseDeps[name])
-                reverseDeps[name] = new Set();
             reverseDeps[name].add(parent);
         }
         walkDeps(info.dependencies, acc, reverseDeps, name);
@@ -75,21 +75,19 @@ function generateManifest(cwd) {
     const acc = {};
     const reverseAcc = {};
     walkDeps(tree.dependencies, acc, reverseAcc, "root");
-    const manifest = {};
+    const packages = {};
     for (const [name, versions] of Object.entries(acc)) {
-        manifest[name] = [...versions];
+        packages[name] = [...versions];
     }
     const reverseDeps = {};
     for (const [name, parents] of Object.entries(reverseAcc)) {
         reverseDeps[name] = [...parents];
     }
-    return { manifest, reverseDeps };
+    return { packages, reverseDeps };
 }
 function writeManifest(outputPath, cwd) {
-    const { manifest, reverseDeps } = generateManifest(cwd);
+    const manifest = generateManifest(cwd);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outputPath), { recursive: true });
     (0, node_fs_1.writeFileSync)(outputPath, JSON.stringify(manifest, null, 2) + "\n");
-    const reverseMapPath = (0, node_path_1.resolve)((0, node_path_1.dirname)(outputPath), "deps-reverse-map.json");
-    (0, node_fs_1.writeFileSync)(reverseMapPath, JSON.stringify(reverseDeps, null, 2) + "\n");
-    return { manifest, reverseMapPath };
+    return manifest;
 }

package/dist/handler.d.ts

@@ -1,9 +1,13 @@
-import type { DepsManifest } from "./types.js";
-export type { DepsManifest, HealthCheckResponse, Vulnerability, } from "./types.js";
+import type { DepsManifest, Severity } from "./types.js";
+export type { DepsManifest, HealthCheckResponse, HealthCheckResult, Severity, Vulnerability, } from "./types.js";
 export interface CreateHealthHandlerOptions {
     /** Environment variable name for the secret. Default: "OHDEAR_HEALTH_SECRET" */
     secretEnvVar?: string;
     /** Header name for the secret. Default: "oh-dear-health-check-secret" */
     secretHeader?: string;
+    /** Severity levels to report. Default: ["critical"] */
+    severity?: Severity[];
+    /** Package names to ignore (e.g. known/accepted vulnerabilities). Default: [] */
+    ignorePackages?: string[];
 }
 export declare function createHealthHandler(manifest: DepsManifest, options?: CreateHealthHandlerOptions): (request: Request) => Promise<Response>;

package/dist/handler.js

@@ -3,24 +3,49 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHealthHandler = createHealthHandler;
 const NPM_BULK_ADVISORY_URL = "https://registry.npmjs.org/-/npm/v1/security/advisories/bulk";
 const FETCH_TIMEOUT_MS = 8_000;
-function makeWarningResponse(message) {
-    return {
-        finishedAt: Math.floor(Date.now() / 1000),
-        checkResults: [
-            {
-                name: "npm_vulnerabilities",
-                label: "NPM Critical Vulnerabilities",
-                status: "warning",
-                notificationMessage: message,
-                shortSummary: "check error",
-                meta: {},
-            },
-        ],
-    };
+const SEVERITY_OHDEAR_STATUS = {
+    critical: "failed",
+    high: "warning",
+    moderate: "warning",
+    low: "warning",
+};
+function capitalize(s) {
+    return s[0].toUpperCase() + s.slice(1);
+}
+/** BFS from pkg up through reverseMap to find the shortest chain to a root dep. */
+function buildChain(pkg, reverseMap) {
+    const queue = [[pkg]];
+    const visited = new Set([pkg]);
+    while (queue.length > 0) {
+        const path = queue.shift();
+        const current = path[path.length - 1];
+        const parents = reverseMap[current];
+        if (!parents || parents.length === 0)
+            return [...path].reverse();
+        for (const parent of parents) {
+            if (visited.has(parent))
+                continue;
+            visited.add(parent);
+            queue.push([...path, parent]);
+        }
+    }
+    return [pkg];
+}
+function makeWarningResults(message, severityFilter) {
+    return severityFilter.map((sev) => ({
+        name: `npm_vulnerabilities_${sev}`,
+        label: `NPM ${capitalize(sev)} Vulnerabilities`,
+        status: "warning",
+        notificationMessage: message,
+        shortSummary: "check error",
+        meta: {},
+    }));
 }
 function createHealthHandler(manifest, options) {
     const envVar = options?.secretEnvVar ?? "OHDEAR_HEALTH_SECRET";
     const headerName = options?.secretHeader ?? "oh-dear-health-check-secret";
+    const severityFilter = options?.severity ?? ["critical"];
+    const ignorePackages = options?.ignorePackages ?? [];
     let didWarn = false;
     return async (request) => {
         const secret = request.headers.get(headerName);
@@ -36,7 +61,7 @@ function createHealthHandler(manifest, options) {
             res = await fetch(NPM_BULK_ADVISORY_URL, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(manifest),
+                body: JSON.stringify(manifest.packages),
                 signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
             });
         }
@@ -44,51 +69,65 @@ function createHealthHandler(manifest, options) {
             const message = err instanceof DOMException && err.name === "TimeoutError"
                 ? "npm advisory API timed out"
                 : "npm advisory API request failed";
-            return Response.json(makeWarningResponse(message));
+            return Response.json({
+                finishedAt: Math.floor(Date.now() / 1000),
+                checkResults: makeWarningResults(message, severityFilter),
+            });
         }
         if (!res.ok) {
-            return Response.json(makeWarningResponse(`npm advisory API returned HTTP ${res.status}`));
+            const msg = `npm advisory API returned HTTP ${res.status}`;
+            return Response.json({
+                finishedAt: Math.floor(Date.now() / 1000),
+                checkResults: makeWarningResults(msg, severityFilter),
+            });
         }
         let advisories;
         try {
             advisories = await res.json();
         }
         catch {
-            return Response.json(makeWarningResponse("Failed to parse npm advisory response"));
+            return Response.json({
+                finishedAt: Math.floor(Date.now() / 1000),
+                checkResults: makeWarningResults("Failed to parse npm advisory response", severityFilter),
+            });
         }
-        const critical = [];
+        // Group vulnerabilities by severity level
+        const bySeverity = new Map(severityFilter.map((sev) => [sev, []]));
         for (const [pkg, entries] of Object.entries(advisories)) {
+            if (ignorePackages.includes(pkg))
+                continue;
             for (const entry of entries) {
-                if (entry.severity === "critical") {
-                    const versions = manifest[pkg] ?? [];
-                    critical.push({
-                        package: pkg,
-                        installedVersion: versions.join(", "),
-                        title: entry.title,
-                        url: entry.url,
-                        vulnerableVersions: entry.vulnerable_versions ?? "",
-                    });
-                }
+                const sev = entry.severity;
+                const bucket = bySeverity.get(sev);
+                if (!bucket)
+                    continue;
+                bucket.push({
+                    package: pkg,
+                    installedVersions: manifest.packages[pkg] ?? [],
+                    title: entry.title,
+                    url: entry.url,
+                    vulnerableVersions: entry.vulnerable_versions ?? "",
+                    dependencyChain: buildChain(pkg, manifest.reverseDeps),
+                });
             }
         }
-        const status = critical.length === 0 ? "ok" : "failed";
-        const shortSummary = `${critical.length} critical`;
-        const notificationMessage = critical.length === 0
-            ? "No critical npm vulnerabilities found."
-            : `Critical vulnerabilities in: ${critical.map((v) => v.package).join(", ")}`;
-        const body = {
+        const checkResults = severityFilter.map((sev) => {
+            const vulns = bySeverity.get(sev);
+            const status = vulns.length === 0 ? "ok" : SEVERITY_OHDEAR_STATUS[sev];
+            return {
+                name: `npm_vulnerabilities_${sev}`,
+                label: `NPM ${capitalize(sev)} Vulnerabilities`,
+                status,
+                shortSummary: `${vulns.length} ${sev}`,
+                notificationMessage: vulns.length === 0
+                    ? `No ${sev} npm vulnerabilities found.`
+                    : `${capitalize(sev)} vulnerabilities in: ${vulns.map((v) => v.package).join(", ")}`,
+                meta: vulns.length > 0 ? { vulnerabilities: vulns } : {},
+            };
+        });
+        return Response.json({
             finishedAt: Math.floor(Date.now() / 1000),
-            checkResults: [
-                {
-                    name: "npm_vulnerabilities",
-                    label: "NPM Critical Vulnerabilities",
-                    status,
-                    notificationMessage,
-                    shortSummary,
-                    meta: critical.length > 0 ? { vulnerabilities: critical } : {},
-                },
-            ],
-        };
-        return Response.json(body);
+            checkResults,
+        });
     };
 }

package/dist/next.d.ts

@@ -1,8 +1,13 @@
+import type { Severity } from "./types.js";
 export interface WithOhDearHealthOptions {
     /** Output path for the manifest, relative to project root.
      *  Default: "src/app/api/health/deps-manifest.json" */
     output?: string;
     /** Check for critical vulnerabilities at build time. Default: true */
     checkOnBuild?: boolean;
+    /** Severity levels to check at build time. Default: ["critical"] */
+    severity?: Severity[];
+    /** Package names to ignore. Default: [] */
+    ignorePackages?: string[];
 }
 export declare function withOhDearHealth<T>(nextConfig: T, options?: WithOhDearHealthOptions): T;

package/dist/next.js

@@ -52,14 +52,21 @@ function hasRecentLock(output) {
  */
 function buildChainScript() {
     return [
-        `function buildChain(pkg, reverseMap, visited) {`,
-        `  if (visited.has(pkg)) return [pkg];`,
-        `  visited.add(pkg);`,
-        `  const parents = reverseMap[pkg];`,
-        `  if (!parents || parents.length === 0) return [pkg];`,
-        `  const chain = buildChain(parents[0], reverseMap, visited);`,
-        `  chain.push(pkg);`,
-        `  return chain;`,
+        `function buildChain(pkg, reverseMap) {`,
+        `  const queue = [[pkg]];`,
+        `  const visited = new Set([pkg]);`,
+        `  while (queue.length > 0) {`,
+        `    const path = queue.shift();`,
+        `    const current = path[path.length - 1];`,
+        `    const parents = reverseMap[current];`,
+        `    if (!parents || parents.length === 0) return path.slice().reverse();`,
+        `    for (const parent of parents) {`,
+        `      if (visited.has(parent)) continue;`,
+        `      visited.add(parent);`,
+        `      queue.push([...path, parent]);`,
+        `    }`,
+        `  }`,
+        `  return [pkg];`,
         `}`,
     ].join("\n");
 }
@@ -68,45 +75,57 @@ function buildChainScript() {
  * API. Output is inherited so logs appear in the build output. Does not
  * block the build — the subprocess runs in parallel with Next.js compilation.
  */
-function checkVulnerabilities(manifestPath, reverseMapPath) {
-    const safeManifestPath = JSON.stringify(manifestPath);
-    const safeReverseMapPath = JSON.stringify(reverseMapPath);
+function checkVulnerabilities(manifestPath, severity, ignorePackages) {
+    const safePath = JSON.stringify(manifestPath);
+    const safeSeverity = JSON.stringify(severity);
+    const safeIgnore = JSON.stringify(ignorePackages);
     const script = [
         `const fs = require("fs");`,
-        `const manifest = JSON.parse(fs.readFileSync(${safeManifestPath}, "utf-8"));`,
-        `const reverseMap = JSON.parse(fs.readFileSync(${safeReverseMapPath}, "utf-8"));`,
+        `const data = JSON.parse(fs.readFileSync(${safePath}, "utf-8"));`,
+        `const packages = data.packages;`,
+        `const reverseMap = data.reverseDeps;`,
+        `const severityFilter = ${safeSeverity};`,
+        `const ignorePackages = ${safeIgnore};`,
         buildChainScript(),
         `fetch("https://registry.npmjs.org/-/npm/v1/security/advisories/bulk", {`,
         `  method: "POST",`,
         `  headers: { "Content-Type": "application/json" },`,
-        `  body: JSON.stringify(manifest),`,
+        `  body: JSON.stringify(packages),`,
         `  signal: AbortSignal.timeout(8000),`,
         `})`,
         `.then(r => { if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); })`,
         `.then(data => {`,
-        `  const crits = [];`,
+        `  const bySev = {};`,
+        `  severityFilter.forEach(s => bySev[s] = []);`,
         `  for (const [pkg, entries] of Object.entries(data)) {`,
+        `    if (ignorePackages.includes(pkg)) continue;`,
         `    for (const e of entries) {`,
-        `      if (e.severity !== "critical") continue;`,
-        `      const versions = manifest[pkg] || [];`,
-        `      const chain = buildChain(pkg, reverseMap, new Set());`,
+        `      if (!bySev[e.severity]) continue;`,
+        `      const versions = packages[pkg] || [];`,
+        `      const chain = buildChain(pkg, reverseMap);`,
         `      const versionStr = versions.join(", ");`,
         `      const chainStr = chain.length > 1 ? " (via " + chain.join(" \\u2192 ") + ")" : "";`,
         `      let line = "  - " + pkg + "@" + versionStr + chainStr + ": " + e.title;`,
         `      if (e.vulnerable_versions) {`,
         `        line += "\\n    vulnerable: " + e.vulnerable_versions + " \\u2014 " + e.url;`,
         `      }`,
-        `      crits.push(line);`,
+        `      bySev[e.severity].push(line);`,
+        `    }`,
+        `  }`,
+        `  let total = 0;`,
+        `  for (const sev of severityFilter) {`,
+        `    const lines = bySev[sev];`,
+        `    total += lines.length;`,
+        `    if (lines.length > 0) {`,
+        `      console.warn("ohdear-npm-audit: " + lines.length + " " + sev + " vulnerabilities:");`,
+        `      lines.forEach(c => console.warn(c));`,
         `    }`,
         `  }`,
-        `  if (crits.length > 0) {`,
-        `    console.warn("ohdear-npm-audit: " + crits.length + " critical vulnerabilities:");`,
-        `    crits.forEach(c => console.warn(c));`,
-        `  } else {`,
-        `    console.log("ohdear-npm-audit: no critical vulnerabilities \\u2713");`,
+        `  if (total === 0) {`,
+        `    console.log("ohdear-npm-audit: no " + severityFilter.join("/") + " vulnerabilities \\u2713");`,
         `  }`,
         `})`,
-        `.catch(() => {});`,
+        `.catch(err => console.warn("ohdear-npm-audit: build-time vulnerability check failed:", err.message || err));`,
     ].join("\n");
     const child = (0, node_child_process_1.spawn)("node", ["-e", script], {
         stdio: "inherit",
@@ -121,8 +140,8 @@ function withOhDearHealth(nextConfig, options) {
     if (hasRecentLock(output))
         return nextConfig;
     try {
-        const { manifest, reverseMapPath } = (0, generate_js_1.writeManifest)(output, cwd);
-        console.log(`ohdear-npm-audit: ${Object.keys(manifest).length} packages written → ${output}`);
+        const manifest = (0, generate_js_1.writeManifest)(output, cwd);
+        console.log(`ohdear-npm-audit: ${Object.keys(manifest.packages).length} packages written → ${output}`);
         const routePath = deriveRoutePath((0, node_path_1.relative)(cwd, output));
         const domain = process.env.VERCEL_PROJECT_PRODUCTION_URL;
         if (routePath && domain) {
@@ -138,7 +157,7 @@ function withOhDearHealth(nextConfig, options) {
             console.warn("ohdear-npm-audit: OHDEAR_HEALTH_SECRET is not set — health check will reject all requests.");
         }
         if (options?.checkOnBuild !== false) {
-            checkVulnerabilities(output, reverseMapPath);
+            checkVulnerabilities(output, options?.severity ?? ["critical"], options?.ignorePackages ?? []);
         }
     }
     catch (err) {

package/dist/types.d.ts

@@ -1,7 +1,11 @@
-export type DepsManifest = Record<string, string[]>;
+export type Severity = "critical" | "high" | "moderate" | "low";
+export interface DepsManifest {
+    packages: Record<string, string[]>;
+    reverseDeps: Record<string, string[]>;
+}
 export interface Vulnerability {
     package: string;
-    installedVersion: string;
+    installedVersions: string[];
     title: string;
     url: string;
     vulnerableVersions: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ohdear-npm-audit",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Oh Dear Application Health check for npm audit critical vulnerabilities",
   "main": "./dist/handler.js",
   "types": "./dist/handler.d.ts",