@kushankurdas/npm-sentinel 0.1.0

package/lib/diff-signals.js

@@ -0,0 +1,99 @@
+import { getRootDependencyResolution } from "./parse-npm-lockfile.js";
+import { fetchVersionScripts, summarizeLifecycleScripts } from "./packument.js";
+
+/**
+ * @typedef {{ type: string, severity: 'error'|'warn', message: string, package?: string, detail?: object }} Signal
+ */
+
+/**
+ * @param {object} baselineSnapshot - from buildBaselineSnapshot / loadBaseline
+ * @param {ReturnType<import('./parse-npm-lockfile.js').parseNpmLockfile>} parsed
+ * @param {string[]} watchNames
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<Signal[]>}
+ */
+export async function diffAgainstBaseline(
+  baselineSnapshot,
+  parsed,
+  watchNames,
+  fetchImpl = fetch
+) {
+  /** @type {Signal[]} */
+  const signals = [];
+  const saved = baselineSnapshot.packages || {};
+
+  for (const name of watchNames) {
+    const prev = saved[name];
+    const cur = getRootDependencyResolution(parsed, name);
+
+    if (!prev) continue;
+
+    if (!cur) {
+      signals.push({
+        type: "missing_resolution",
+        severity: "error",
+        message: `Watched package "${name}" no longer resolves at node_modules (removed from tree?)`,
+        package: name,
+      });
+      continue;
+    }
+
+    if (prev.resolvedVersion && cur.version !== prev.resolvedVersion) {
+      signals.push({
+        type: "version_change",
+        severity: "warn",
+        message: `Watched package "${name}" version changed: ${prev.resolvedVersion} → ${cur.version}`,
+        package: name,
+        detail: { from: prev.resolvedVersion, to: cur.version },
+      });
+    }
+
+    const prevDeps = new Set(prev.directDependencyNames || []);
+    const curDeps = new Set(cur.directDependencyNames || []);
+
+    for (const d of curDeps) {
+      if (!prevDeps.has(d)) {
+        signals.push({
+          type: "new_dependency",
+          severity: "error",
+          message: `New direct dependency "${d}" on watched package "${name}"`,
+          package: name,
+          detail: { dependency: d },
+        });
+      }
+    }
+
+    for (const d of prevDeps) {
+      if (!curDeps.has(d)) {
+        signals.push({
+          type: "dependency_removed",
+          severity: "warn",
+          message: `Direct dependency "${d}" removed from watched package "${name}" (review for takeover)`,
+          package: name,
+          detail: { dependency: d },
+        });
+      }
+    }
+
+    const scripts = await fetchVersionScripts(name, cur.version, fetchImpl);
+    const sum =
+      scripts === null
+        ? { keys: [], hashes: {} }
+        : summarizeLifecycleScripts(scripts);
+    const prevKeys = new Set(prev.lifecycleScriptKeys || []);
+
+    for (const k of sum.keys) {
+      if (!prevKeys.has(k)) {
+        signals.push({
+          type: "new_lifecycle_script",
+          severity: "error",
+          message: `New lifecycle script "${k}" on watched package "${name}"@${cur.version}`,
+          package: name,
+          detail: { script: k },
+        });
+      }
+    }
+  }
+
+  return signals;
+}

package/lib/dns-allowlist-default.json

@@ -0,0 +1,27 @@
+{
+  "suffixes": [
+    "npmjs.org",
+    "registry.npmjs.org",
+    "nodejs.org",
+    "github.com",
+    "codeload.github.com",
+    "objects.githubusercontent.com",
+    "raw.githubusercontent.com",
+    "api.github.com",
+    "unpkg.com",
+    "jsdelivr.net",
+    "fastly.com",
+    "cloudflare.com",
+    "googleapis.com",
+    "gstatic.com",
+    "microsoft.com",
+    "azureedge.net",
+    "amazonaws.com",
+    "docker.io",
+    "docker.com"
+  ],
+  "exactHosts": [
+    "localhost",
+    "127.0.0.1"
+  ]
+}

package/lib/merge-findings.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { maxSeverityFromVulns, normalizeSeverity, compareSeverity } from "./osv-client.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const offlineIocs = JSON.parse(
+  readFileSync(join(__dirname, "offline-iocs.json"), "utf8")
+);
+
+/**
+ * @param {Array<{package: {name: string, version: string}, vulns: object[]}>} osvResults
+ * @returns {Array<{name: string, version: string, source: string, severity: string, ids: string[], summary?: string}>}
+ */
+export function flattenOsvFindings(osvResults) {
+  const out = [];
+  for (const row of osvResults) {
+    const { name, version } = row.package;
+    if (!row.vulns?.length) continue;
+    const severity = maxSeverityFromVulns(row.vulns);
+    const ids = row.vulns.map((v) => v.id || v.alias || "unknown").filter(Boolean);
+    const summary = row.vulns[0]?.summary || row.vulns[0]?.details?.slice?.(0, 200);
+    out.push({
+      name,
+      version,
+      source: "osv",
+      severity,
+      ids,
+      summary,
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {Array<{name: string, version: string}>} packages
+ * @returns {Array<{name: string, version: string, source: string, severity: string, ids: string[], summary?: string}>}
+ */
+export function matchOfflineIocs(packages) {
+  const iocs = offlineIocs.packages || [];
+  const byName = new Map(iocs.map((p) => [p.name, p]));
+  const out = [];
+  for (const { name, version } of packages) {
+    const entry = byName.get(name);
+    if (!entry) continue;
+    if (!entry.versions.includes(version)) continue;
+    out.push({
+      name,
+      version,
+      source: "offline-ioc",
+      severity: "critical",
+      ids: [entry.id || `ioc-${name}`],
+      summary: entry.summary,
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {string} minSeverity
+ * @param {Array<{severity: string}>} findings
+ */
+export function filterByMinSeverity(minSeverity, findings) {
+  const min = normalizeSeverity(minSeverity);
+  return findings.filter((f) => compareSeverity(f.severity, min) <= 0);
+}

package/lib/offline-iocs.json

@@ -0,0 +1,17 @@
+{
+  "description": "Exact version IOCs for known malicious npm releases (supplement when OSV/offline). Not a package watch list.",
+  "packages": [
+    {
+      "name": "axios",
+      "versions": ["1.14.1", "0.30.4"],
+      "id": "ioc-axios-2026-03",
+      "summary": "Supply-chain compromised releases (March 2026); see Elastic Security Labs / Microsoft guidance"
+    },
+    {
+      "name": "plain-crypto-js",
+      "versions": ["4.2.1"],
+      "id": "ioc-plain-crypto-js-2026-03",
+      "summary": "Malicious postinstall dropper associated with compromised axios releases"
+    }
+  ]
+}

package/lib/osv-client.js

@@ -0,0 +1,97 @@
+/**
+ * OSV batch query API — https://google.github.io/osv.dev/
+ */
+
+const OSV_BATCH = "https://api.osv.dev/v1/querybatch";
+
+const SEVERITY_ORDER = ["critical", "high", "moderate", "low", "unknown"];
+
+/**
+ * @param {string} a
+ * @param {string} b
+ */
+export function compareSeverity(a, b) {
+  const ia = SEVERITY_ORDER.indexOf(normalizeSeverity(a));
+  const ib = SEVERITY_ORDER.indexOf(normalizeSeverity(b));
+  return ia - ib;
+}
+
+export function normalizeSeverity(s) {
+  const x = String(s || "").toLowerCase();
+  if (SEVERITY_ORDER.includes(x)) return x;
+  return "unknown";
+}
+
+/**
+ * @param {Array<{name: string, version: string}>} packages
+ * @param {typeof fetch} fetchImpl
+ * @param {number} chunkSize
+ */
+export async function queryOsvBatch(packages, fetchImpl = fetch, chunkSize = 500) {
+  /** @type {Array<{package: {name: string, version: string}, vulns: object[]}>} */
+  const results = [];
+
+  for (let i = 0; i < packages.length; i += chunkSize) {
+    const chunk = packages.slice(i, i + chunkSize);
+    const body = {
+      queries: chunk.map((p) => ({
+        package: { ecosystem: "npm", name: p.name },
+        version: p.version,
+      })),
+    };
+
+    const res = await fetchImpl(OSV_BATCH, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`OSV batch failed: ${res.status} ${text.slice(0, 200)}`);
+    }
+
+    const json = await res.json();
+    const batchResults = json.results || [];
+    for (let j = 0; j < chunk.length; j++) {
+      const pkg = chunk[j];
+      const r = batchResults[j] || {};
+      const vulns = r.vulns || [];
+      results.push({ package: pkg, vulns });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * @param {object[]} vulns - OSV vuln objects
+ * @returns {string}
+ */
+export function maxSeverityFromVulns(vulns) {
+  let best = "unknown";
+  for (const v of vulns) {
+    const s = extractSeverity(v);
+    if (compareSeverity(s, best) < 0) best = s;
+  }
+  return best;
+}
+
+function extractSeverity(vuln) {
+  const ss = vuln.severity;
+  if (Array.isArray(ss)) {
+    for (const s of ss) {
+      if (s?.type === "CVSS_V3" && s.score) {
+        const num = parseFloat(String(s.score));
+        if (num >= 9) return "critical";
+        if (num >= 7) return "high";
+        if (num >= 4) return "moderate";
+        if (num > 0) return "low";
+      }
+    }
+  }
+  if (vuln.database_specific?.severity) {
+    return normalizeSeverity(vuln.database_specific.severity);
+  }
+  return "moderate";
+}

package/lib/packument.js

@@ -0,0 +1,59 @@
+/**
+ * Fetch npm registry packument / version metadata for lifecycle scripts.
+ */
+
+const REGISTRY = "https://registry.npmjs.org";
+
+/**
+ * @param {string} name - package name (scoped ok)
+ * @param {string} version - exact version
+ * @returns {Promise<Record<string, string> | null>} scripts object or null
+ */
+export async function fetchVersionScripts(name, version, fetchImpl = fetch) {
+  const enc = encodeURIComponent(name).replace(/%40/g, "@").replace(/%2F/g, "/");
+  const url = `${REGISTRY}/${enc}/${encodeURIComponent(version)}`;
+  const res = await fetchImpl(url, {
+    headers: { accept: "application/json" },
+  });
+  if (!res.ok) return null;
+  const json = await res.json();
+  const scripts = json.scripts;
+  if (!scripts || typeof scripts !== "object") return {};
+  return /** @type {Record<string, string>} */ (scripts);
+}
+
+const LIFECYCLE = new Set([
+  "preinstall",
+  "install",
+  "postinstall",
+  "preprepare",
+  "prepare",
+  "postprepare",
+  "prepublish",
+  "prepublishOnly",
+]);
+
+/**
+ * @param {Record<string, string>} scripts
+ * @returns {{ keys: string[], hashes: Record<string, string> }}
+ */
+export function summarizeLifecycleScripts(scripts) {
+  const keys = [];
+  const hashes = {};
+  for (const key of Object.keys(scripts)) {
+    if (LIFECYCLE.has(key)) {
+      keys.push(key);
+      const body = scripts[key] || "";
+      hashes[key] = simpleHash(body);
+    }
+  }
+  return { keys, hashes };
+}
+
+function simpleHash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  }
+  return String(h);
+}

package/lib/parse-npm-lockfile.js

@@ -0,0 +1,144 @@
+/**
+ * Parse npm package-lock.json v1 and v2/v3; enumerate packages and root dependency resolutions.
+ */
+
+/**
+ * @param {string} pathKey - e.g. "node_modules/foo" or "node_modules/@scope/pkg"
+ * @returns {string} package name
+ */
+export function pathKeyToPackageName(pathKey) {
+  if (!pathKey || pathKey === "") return "";
+  const prefix = "node_modules/";
+  if (!pathKey.startsWith(prefix)) return pathKey;
+  return pathKey.slice(prefix.length).replace(/\\/g, "/");
+}
+
+/**
+ * @param {object} lock
+ * @returns {{ lockfileVersion: number, packages: Array<{path: string, name: string, version: string, dependencies: Record<string, string>, directDependencyNames: string[]}> }}
+ */
+export function parseNpmLockfile(lock) {
+  const lv = lock.lockfileVersion ?? 1;
+  if (lv === 1 || !lock.packages) {
+    return parseLockfileV1(lock);
+  }
+  return parseLockfileV2(lock, lv);
+}
+
+function parseLockfileV1(lock) {
+  /** @type {Array<{path: string, name: string, version: string, dependencies: Record<string, string>}>} */
+  const packages = [];
+  const seen = new Set();
+
+  function walk(deps, prefixPath) {
+    if (!deps) return;
+    for (const [name, spec] of Object.entries(deps)) {
+      if (!spec || typeof spec !== "object") continue;
+      const version = spec.version;
+      if (!version) continue;
+      const pathKey =
+        prefixPath === ""
+          ? `node_modules/${name}`
+          : `${prefixPath}/node_modules/${name}`;
+      if (!seen.has(pathKey)) {
+        seen.add(pathKey);
+        const depObj = spec.dependencies || {};
+        const directDependencyNames = Object.keys(depObj);
+        const dependencies = {};
+        for (const k of directDependencyNames) dependencies[k] = "*";
+        packages.push({
+          path: pathKey,
+          name,
+          version,
+          dependencies,
+          directDependencyNames,
+        });
+      }
+      if (spec.dependencies) {
+        walk(spec.dependencies, pathKey);
+      }
+    }
+  }
+
+  walk(lock.dependencies || {}, "");
+
+  return {
+    lockfileVersion: 1,
+    packages,
+    rootDependencies: lock.dependencies || {},
+  };
+}
+
+function parseLockfileV2(lock, lockfileVersion) {
+  const map = lock.packages || {};
+  /** @type {Array<{path: string, name: string, version: string, dependencies: Record<string, string>}>} */
+  const packages = [];
+
+  for (const [pathKey, pkg] of Object.entries(map)) {
+    if (pathKey === "") continue;
+    if (!pkg || typeof pkg !== "object") continue;
+    const version = pkg.version;
+    if (!version) continue;
+    const name = pkg.name || pathKeyToPackageName(pathKey);
+    const depRecord = pkg.dependencies || {};
+    const directDependencyNames = Object.keys(depRecord);
+    packages.push({
+      path: pathKey.replace(/\\/g, "/"),
+      name,
+      version,
+      dependencies: depRecord,
+      directDependencyNames,
+    });
+  }
+
+  const root = map[""] || {};
+  return {
+    lockfileVersion,
+    packages,
+    rootDependencies: root.dependencies || {},
+  };
+}
+
+/**
+ * Unique (name, version) pairs for OSV batching.
+ * @param {ReturnType<parseNpmLockfile>} parsed
+ * @returns {Array<{name: string, version: string}>}
+ */
+export function getAllNameVersionPairs(parsed) {
+  const key = (n, v) => `${n}@${v}`;
+  const out = new Map();
+  for (const p of parsed.packages) {
+    const k = key(p.name, p.version);
+    if (!out.has(k)) {
+      out.set(k, { name: p.name, version: p.version });
+    }
+  }
+  return [...out.values()];
+}
+
+/**
+ * Path under node_modules for a root dependency name (e.g. axios -> node_modules/axios, @x/y -> node_modules/@x/y)
+ * @param {string} depName
+ */
+export function rootNodeModulesPath(depName) {
+  return `node_modules/${depName.replace(/\\/g, "/")}`;
+}
+
+/**
+ * Resolved version + direct dependency names for a root-level dependency from package.json.
+ * @param {ReturnType<parseNpmLockfile>} parsed
+ * @param {string} depName - key as in package.json dependencies
+ * @returns {{ version: string, directDependencyNames: string[] } | null}
+ */
+export function getRootDependencyResolution(parsed, depName) {
+  const targetPath = rootNodeModulesPath(depName);
+  const entry = parsed.packages.find((p) => p.path === targetPath);
+  if (!entry) return null;
+  const directDependencyNames =
+    entry.directDependencyNames ||
+    Object.keys(entry.dependencies || {});
+  return {
+    version: entry.version,
+    directDependencyNames,
+  };
+}

package/lib/sandbox/dns-parse.js

@@ -0,0 +1,54 @@
+/**
+ * Extract hostnames from tcpdump -n udp port 53 style lines.
+ */
+
+const RE_A = /A\?\s+([a-zA-Z0-9*.-]+)\.\s/;
+const RE_AAAA = /AAAA\?\s+([a-zA-Z0-9*.-]+)\.\s/;
+const RE_CNAME = /CNAME\?\s+([a-zA-Z0-9*.-]+)\.\s/;
+
+/**
+ * @param {string} logText
+ * @returns {Set<string>}
+ */
+export function extractHostsFromTcpdump(logText) {
+  const hosts = new Set();
+  for (const line of logText.split("\n")) {
+    for (const re of [RE_A, RE_AAAA, RE_CNAME]) {
+      const m = line.match(re);
+      if (m) {
+        hosts.add(m[1].toLowerCase().replace(/\.$/, ""));
+      }
+    }
+  }
+  return hosts;
+}
+
+/**
+ * @param {string} host
+ * @param {{ suffixes: string[], exactHosts: string[] }} allow
+ */
+export function isHostAllowed(host, allow) {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  if (!h) return true;
+  for (const ex of allow.exactHosts || []) {
+    if (h === ex.toLowerCase()) return true;
+  }
+  for (const suf of allow.suffixes || []) {
+    const s = suf.toLowerCase();
+    if (h === s || h.endsWith("." + s)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {Set<string>} hosts
+ * @param {object} allow
+ * @returns {string[]}
+ */
+export function filterDisallowedHosts(hosts, allow) {
+  const bad = [];
+  for (const h of hosts) {
+    if (!isHostAllowed(h, allow)) bad.push(h);
+  }
+  return [...new Set(bad)].sort();
+}