penthera 1.5.0 → 1.6.0

package/lib/deps/index.js

@@ -1,5 +1,8 @@
 /**
- * `penthera deps`: offline, deterministic dependency risk scanning for npm.
+ * `penthera deps`: offline, deterministic dependency risk scanning for npm and
+ * Python (PyPI). The Python side (lib/deps/python) loads uv/poetry/pdm/Pipfile
+ * lockfiles, requirements files and virtualenvs; everything below the tree
+ * loaders (findings, diff, typosquats, reports) is shared.
  *
  * Reads package-lock.json, statically scans every installed package for what
  * it can do (lib/deps/capabilities.js), checks names for typosquats against a
@@ -16,10 +19,11 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, dirname, relative, resolve, basename } from "node:path";
 import { findLockfile, readLockfile, parseLockfile, directDependencies, readLockfileAtRef } from "./lockfile.js";
 import { DirSource, sourceFromNpmCache, npmCacheDir } from "./source.js";
-import { scanPackage, CAPABILITIES, CAPABILITY_ORDER, maxSeverity } from "./capabilities.js";
+import { scanPackage, CAPABILITIES, CAPABILITY_ORDER, maxSeverity, capabilityWhy } from "./capabilities.js";
 import { diffTrees } from "./diff.js";
 import { findTyposquats, loadPopular } from "./typosquat.js";
 import { checkLicenses } from "./license.js";
+import { hasPythonInputs, loadPythonTree, loadPythonBase } from "./python/index.js";
 
 const SOURCE = "deps-scan";
 const CATEGORY = "dependency-risk";
@@ -63,11 +67,26 @@ function scanTree(pkgs, treeRoot, ctx) {
       ctx.cache.set(key, src ? { ...scanPackage(src, { prefix: `${p.path}/` }), source: src.kind } : null);
     }
     const r = ctx.cache.get(key);
+    // Fail closed: a package that could not be fully read has unknown
+    // capabilities (null), not an empty set.
+    const unscanned = r?.unscanned || null;
+    const installScripts = r?.installScripts || {};
+    // npm records hasInstallScript from the registry manifest. If it says there
+    // is a script and the files we read have none, the scan saw different files
+    // than npm will install (or the lockfile was edited): never "clean". One
+    // known, benign cause is exempt: a native package that had binding.gyp when
+    // it was published (so the registry added the implicit node-gyp install)
+    // but ships only prebuilt .node binaries without it, like fsevents 2.x.
+    // With no binding.gyp and no script in the files, npm runs nothing there.
+    const prebuiltOnly = !!r?.capabilities?.native;
+    const scriptMismatch = !!(r && !unscanned && p.hasInstallScript && Object.keys(installScripts).length === 0 && !prebuiltOnly);
     return {
       ...p,
       source: r?.source || null,
-      capabilities: r ? r.capabilities : null,
-      installScripts: r?.installScripts || {},
+      capabilities: r && !unscanned ? r.capabilities : null,
+      unscanned,
+      scriptMismatch,
+      installScripts,
       installRisk: r?.installRisk || [],
       exfil: r?.exfil || [],
       filesScanned: r?.filesScanned || 0,
@@ -119,8 +138,32 @@ function finding({ title, severity, confidence, method, description, pkg, ev, ca
 function riskFindings(pkg) {
   const out = [];
   const caps = pkg.capabilities;
-  if (!caps) return out;
   const at = `${pkg.name}@${pkg.version}`;
+  if (pkg.unscanned) {
+    out.push(finding({
+      title: `${at}: could not be scanned`,
+      severity: "high",
+      confidence: "confirmed",
+      method: "deps-capability-scan",
+      description: `${pkg.unscanned}. Penthera fails closed here: treat this package as able to do anything, including run install scripts, until you have read its tarball yourself.`,
+      pkg, ev: { file: `${pkg.path}/package.json` }, capabilities: [],
+      extra: { unscanned: pkg.unscanned },
+    }));
+  }
+  if (pkg.scriptMismatch) {
+    out.push(finding({
+      title: `${at}: lockfile lists an install script the scan did not find`,
+      severity: "high",
+      confidence: "confirmed",
+      method: "deps-capability-scan",
+      description: "package-lock.json marks this package `hasInstallScript`, but the package.json Penthera read declares no preinstall, install or postinstall script and there is no binding.gyp. Either the lockfile was edited, or the tarball shows a scanner different files than npm installs. Do not install it until the difference is explained.",
+      pkg, ev: { file: `${pkg.path}/package.json` }, capabilities: ["install-scripts"],
+      extra: { scriptMismatch: true },
+    }));
+  }
+  if (!caps) return out;
+  const py = pkg.ecosystem === "pypi";
+  const why = (id) => capabilityWhy(id, pkg.ecosystem);
 
   for (const id of KNOWN_BAD) {
     if (!caps[id]) continue;
@@ -131,7 +174,7 @@ function riskFindings(pkg) {
       severity: "critical",
       confidence: CAPABILITIES[id].confidence,
       method: "deps-capability-scan",
-      description: `${CAPABILITIES[id].why} Evidence: ${evidenceText(caps, [id])}`,
+      description: `${why(id)} Evidence: ${evidenceText(caps, [id])}`,
       pkg, ev, capabilities: [id],
     }));
   }
@@ -142,7 +185,7 @@ function riskFindings(pkg) {
       severity: "high",
       confidence: "potential",
       method: "deps-capability-scan",
-      description: `${CAPABILITIES.obfuscated.why} Signals at ${ev.file}:${ev.line}: ${ev.snippet}. Read the file before trusting it; minified code alone does not trigger this.`,
+      description: `${why("obfuscated")} Signals at ${ev.file}:${ev.line}: ${ev.snippet}. Read the file before trusting it; minified code alone does not trigger this.`,
       pkg, ev, capabilities: ["obfuscated"],
     }));
   }
@@ -153,7 +196,7 @@ function riskFindings(pkg) {
       severity: "high",
       confidence: "likely",
       method: "deps-capability-scan",
-      description: `process.env (tokens, keys, CI secrets) is serialised within a few lines of a network call, the shape of credential exfiltration. Evidence: ${ev.file}:${ev.line} \`${ev.snippet}\`. ${evidenceText(caps, ["network"])}`,
+      description: `${py ? "os.environ" : "process.env"} (tokens, keys, CI secrets) is serialised within a few lines of a network call, the shape of credential exfiltration. Evidence: ${ev.file}:${ev.line} \`${ev.snippet}\`. ${evidenceText(caps, ["network"])}`,
       pkg, ev, capabilities: ["env-bulk", "network"],
     }));
   }
@@ -166,18 +209,70 @@ function riskFindings(pkg) {
       severity: risky ? "medium" : "low",
       confidence: "confirmed",
       method: "deps-capability-scan",
-      description: `${CAPABILITIES["install-scripts"].why} ${hooks}.${risky ? ` Why it stands out: ${pkg.installRisk.join("; ")}.` : ""} Install with \`npm ci --ignore-scripts\` if the package works without it.`,
+      description: `${why("install-scripts")} ${hooks}.${risky ? ` Why it stands out: ${pkg.installRisk.join("; ")}.` : ""} ${py ? "Install from a wheel (`pip install --only-binary :all:`) so no build code runs, or read setup.py first." : "Install with `npm ci --ignore-scripts` if the package works without it."}`,
       pkg, ev, capabilities: ["install-scripts"],
     }));
   }
+  // Python: .pth import lines run on every interpreter start.
+  const hooks = pkg.startupHooks || [];
+  if (hooks.length) {
+    const risky = hooks.find((h) => h.risk.length);
+    const ev = risky || hooks[0];
+    out.push(finding({
+      title: `${at}: ${risky ? "runs risky code" : "runs code"} at every Python start (.pth)`,
+      severity: risky ? "high" : "low",
+      confidence: "confirmed",
+      method: "deps-capability-scan",
+      description: `${why("startup-hook")} ${ev.file}:${ev.line} \`${ev.snippet}\`.${risky ? ` Why it stands out: ${risky.risk.join("; ")}.` : " Editable installs, setuptools and virtualenv ship .pth files like this; check it is one of those."}`,
+      pkg, ev, capabilities: ["startup-hook"],
+    }));
+  } else if (caps["startup-hook"]) {
+    const ev = caps["startup-hook"].evidence[0];
+    out.push(finding({
+      title: `${at}: writes a .pth file (code that runs at every Python start)`,
+      severity: "medium",
+      confidence: "potential",
+      method: "deps-capability-scan",
+      description: `${why("startup-hook")} Evidence: ${ev.file}:${ev.line} \`${ev.snippet}\`. Installers and environment tools do this legitimately; a library has no reason to.`,
+      pkg, ev, capabilities: ["startup-hook"],
+    }));
+  }
+  if (pkg.modified?.length) {
+    out.push(finding({
+      title: `${at}: ${pkg.modified.length} installed file(s) changed since install`,
+      severity: "medium",
+      confidence: "confirmed",
+      method: "deps-capability-scan",
+      description: `These files no longer match the hashes pip recorded in RECORD when the package was installed: ${pkg.modified.slice(0, 5).join(", ")}${pkg.modified.length > 5 ? ", …" : ""}. Something edited them afterwards: a local patch, or code planting itself in the environment. Reinstall the package and see if it comes back.`,
+      pkg, ev: { file: pkg.modified[0], line: 1 }, capabilities: [],
+      extra: { modified: pkg.modified },
+    }));
+  }
   return out;
 }
 
+/** .pth files in site-packages that no installed distribution claims. */
+function unownedHookFindings(hooks) {
+  return hooks.map((h) => ({
+    title: `Unowned startup hook ${h.file.split("/").pop()} in site-packages`,
+    severity: h.risk.length ? "high" : "medium",
+    category: CATEGORY,
+    source: SOURCE,
+    method: "deps-capability-scan",
+    confidence: "confirmed",
+    description: `${CAPABILITIES["startup-hook"].why} No installed distribution lists this file in its RECORD, so something wrote it after install. ${h.file}:${h.line} \`${h.snippet}\`.${h.risk.length ? ` The line itself uses ${h.risk.join(", ")}.` : ""} Delete it if you cannot trace where it came from.`,
+    url: h.file,
+    line: h.line,
+    capabilities: ["startup-hook"],
+  }));
+}
+
 // Capabilities that riskFindings already reports on their own.
-const OWN_FINDING = new Set([...KNOWN_BAD, "obfuscated", "install-scripts"]);
+const OWN_FINDING = new Set([...KNOWN_BAD, "obfuscated", "install-scripts", "startup-hook"]);
 
-function diffFindings(diff) {
+function diffFindings(diff, ecosystem = "npm") {
   const out = [];
+  const why = (id) => capabilityWhy(id, ecosystem);
   for (const a of diff.added) {
     const ids = a.capabilities || [];
     const notable = ids.filter((id) => id !== "env" && id !== "dynamic-require" && !OWN_FINDING.has(id));
@@ -187,7 +282,7 @@ function diffFindings(diff) {
       severity: maxSeverity(notable.map((id) => CAPABILITIES[id].severity)),
       confidence: "likely",
       method: "deps-capability-diff",
-      description: `A package that was not in the base tree. It can: ${notable.map((id) => CAPABILITIES[id].why).join(" ")} Evidence: ${evidenceText(a.pkg.capabilities, notable)}`,
+      description: `A package that was not in the base tree. It can: ${notable.map(why).join(" ")} Evidence: ${evidenceText(a.pkg.capabilities, notable)}`,
       pkg: a.pkg, ev: firstEvidence(a.pkg.capabilities, notable), capabilities: notable,
       extra: { change: "added" },
     }));
@@ -200,7 +295,7 @@ function diffFindings(diff) {
       severity: sev,
       confidence: u.gained.some((id) => CAPABILITIES[id].confidence === "potential") && u.gained.length === 1 ? "potential" : "likely",
       method: "deps-capability-diff",
-      description: `This upgrade can do things the previous version could not. ${u.gained.map((id) => CAPABILITIES[id].why).join(" ")} Evidence: ${evidenceText(u.pkg.capabilities, u.gained)}`,
+      description: `This upgrade can do things the previous version could not. ${u.gained.map(why).join(" ")} Evidence: ${evidenceText(u.pkg.capabilities, u.gained)}`,
       pkg: u.pkg, ev: firstEvidence(u.pkg.capabilities, u.gained), capabilities: u.gained,
       extra: { change: "upgraded", from: u.from },
     }));
@@ -214,8 +309,10 @@ function diffFindings(diff) {
       source: SOURCE,
       method: "deps-capability-diff",
       confidence: "confirmed",
-      description: `No local copy to compare against for: ${missing.map((u) => `${u.name} ${u.from} → ${u.to}`).join(", ")}. Install the base tree (\`npm ci --ignore-scripts\` in a checkout of the base) and pass that folder to --diff, or rerun with --online to fetch the old tarballs from the registry.`,
-      url: "package-lock.json",
+      description: `No local copy to compare against for: ${missing.map((u) => `${u.name} ${u.from} → ${u.to}`).join(", ")}. ${ecosystem === "pypi"
+        ? "Create the base environment (`uv sync` or `pip install -r requirements.txt` in a checkout of the base, in a .venv) and pass that folder to --diff; old wheels already in pip's or uv's cache are used automatically when their hash matches the base lockfile."
+        : "Install the base tree (`npm ci --ignore-scripts` in a checkout of the base) and pass that folder to --diff, or rerun with --online to fetch the old tarballs from the registry."}`,
+      url: ecosystem === "pypi" ? diff.lockfile || "requirements.txt" : "package-lock.json",
     });
   }
   return out;
@@ -284,20 +381,15 @@ function loadBase(root, opts) {
 }
 
 /**
- * Scan a project's dependencies.
+ * npm: package-lock.json plus node_modules or npm's cache.
  * @param {string} root project folder containing package-lock.json
- * @param {{ diff?: string, base?: string, online?: boolean, prod?: boolean,
- *           onPhase?: Function, cacheDir?: string|string[], now?: number, fetchImpl?: Function,
- *           treeRoot?: string, lock?: object, baseLock?: object, baseLabel?: string,
- *           changedOnly?: boolean, licensePolicy?: object }} opts
- *   treeRoot: where installed packages live, when the lockfile describes a tree
- *     that is not installed beside it (penthera install)
- *   lock / baseLock: lockfile objects to use instead of reading them (the
- *     pre-commit hook passes the staged and HEAD lockfiles)
- *   changedOnly: in diff mode, scan only packages that changed (fast path)
- *   licensePolicy: from normalizeLicensePolicy(); adds category "license" findings
+ * @param {object} opts see scanDeps(). lock / baseLock: lockfile objects to use
+ *   instead of reading them (the pre-commit hook passes the staged and HEAD
+ *   lockfiles); changedOnly: in diff mode, scan only packages that changed (fast
+ *   path); licensePolicy: from normalizeLicensePolicy(), adds category "license"
+ *   findings
  */
-export async function scanDeps(root, opts = {}) {
+async function scanNpm(root, opts = {}) {
   const started = Date.now();
   const onPhase = opts.onPhase || (() => {});
   const lockPath = opts.lock ? join(root, "package-lock.json") : findLockfile(root);
@@ -350,8 +442,10 @@ export async function scanDeps(root, opts = {}) {
         // Verified against the base lockfile's integrity before anything is read.
         const src = await fetchTarballSource(oldPkg?.resolved, oldPkg?.integrity, { fetchImpl: opts.fetchImpl });
         if (!src) continue;
+        const old = scanPackage(src, { prefix: `${oldPkg.path}/` });
+        if (old.unscanned) continue; // still not comparable
         online.fetchedTarballs++;
-        const o = new Set(Object.keys(scanPackage(src, { prefix: `${oldPkg.path}/` }).capabilities));
+        const o = new Set(Object.keys(old.capabilities));
         const n = new Set(Object.keys(u.pkg.capabilities || {}));
         u.gained = CAPABILITY_ORDER.filter((id) => n.has(id) && !o.has(id));
         u.lost = CAPABILITY_ORDER.filter((id) => o.has(id) && !n.has(id));
@@ -386,8 +480,8 @@ export async function scanDeps(root, opts = {}) {
   }
 
   // Optional packages for other platforms (esbuild-style binaries) are expected to be absent.
-  const unavailable = tree.filter((p) => !p.capabilities && !p.optional);
-  const skippedOptional = tree.filter((p) => !p.capabilities && p.optional).length;
+  const unavailable = tree.filter((p) => !p.capabilities && !p.unscanned && !p.optional);
+  const skippedOptional = tree.filter((p) => !p.capabilities && !p.unscanned && p.optional).length;
   const rel = (p) => {
     const r = relative(process.cwd(), p);
     return r === "" ? "." : r.startsWith("..") ? p : r;
@@ -400,8 +494,10 @@ export async function scanDeps(root, opts = {}) {
     timestamp: new Date(started).toISOString(),
     duration: Date.now() - started,
     deps: {
+      ecosystem: "npm",
       lockfile: rel(lockPath),
       lockfileVersion: lock.lockfileVersion || 1,
+      format: `package-lock.json v${lock.lockfileVersion || 1}`,
       prod: !!opts.prod,
       network: opts.online ? "online (registry metadata only)" : "offline",
       total: tree.length,
@@ -409,6 +505,8 @@ export async function scanDeps(root, opts = {}) {
       skippedOptional,
       direct: [...direct],
       notInstalled: unavailable.map((p) => `${p.name}@${p.version}`),
+      unscanned: tree.filter((p) => p.unscanned).map((p) => ({ package: `${p.name}@${p.version}`, reason: p.unscanned })),
+      scriptMismatch: tree.filter((p) => p.scriptMismatch).map((p) => `${p.name}@${p.version}`),
       capabilityCounts: summarize(tree),
       popularList: loadPopular().source,
       packages: tree.map((p) => ({
@@ -424,6 +522,98 @@ export async function scanDeps(root, opts = {}) {
       typosquats: typos,
       licenses,
       online,
+      diff: diff ? {
+        base: base.label,
+        added: diff.added.map(({ pkg, ...a }) => ({ ...a, installScripts: pkg.installScripts, unscanned: pkg.unscanned || null, scriptMismatch: !!pkg.scriptMismatch })),
+        upgraded: diff.upgraded.map(({ pkg, prev, ...u }) => ({ ...u, installScripts: pkg.installScripts, previousInstallScripts: prev?.installScripts || null, unscanned: pkg.unscanned || null, scriptMismatch: !!pkg.scriptMismatch })),
+        removed: diff.removed,
+        evidence: Object.fromEntries([...diff.added, ...diff.upgraded].map((x) => {
+          const ids = x.gained || x.capabilities || [];
+          return [`${x.name}@${x.version || x.to}`, Object.fromEntries(ids.map((id) => [id, x.pkg.capabilities?.[id]?.evidence || []]))];
+        })),
+      } : null,
+    },
+    findings,
+  };
+}
+
+const relCwd = (p) => {
+  const r = relative(process.cwd(), p);
+  return r === "" ? "." : r.startsWith("..") ? p : r;
+};
+
+/** Python: uv/poetry/pdm/Pipfile lockfiles, requirements files, a virtualenv. */
+async function scanPython(root, opts = {}) {
+  const started = Date.now();
+  const onPhase = opts.onPhase || (() => {});
+  const cur = loadPythonTree(root, opts);
+  const keep = (p) => !opts.prod || !p.dev;
+  onPhase(`Scanning ${cur.tree.length} Python packages from ${cur.format} (offline)`);
+  const tree = cur.tree.filter(keep);
+  const direct = new Set(cur.direct);
+
+  let diff = null;
+  let base = null;
+  if (opts.diff || opts.base) {
+    base = loadPythonBase(root, opts, { ...cur, tree });
+    onPhase(`Comparing against ${base.label}: ${base.needOld} replaced version(s) to inspect`);
+    diff = diffTrees(base.tree.filter(keep), tree);
+    diff.lockfile = cur.lockfile;
+  }
+
+  const findings = [];
+  const inScope = diff
+    ? new Set([...diff.added.map((a) => a.pkg), ...diff.upgraded.map((u) => u.pkg)])
+    : new Set(tree);
+  for (const p of tree) if (inScope.has(p)) findings.push(...riskFindings(p));
+  if (diff) findings.push(...diffFindings(diff, "pypi"));
+  if (!diff) findings.push(...unownedHookFindings(cur.unownedHooks));
+
+  const nameScope = diff ? diff.added.map((a) => a.name) : tree.filter((p) => direct.has(p.name)).map((p) => p.name);
+  const typos = findTyposquats(nameScope, "pypi");
+  findings.push(...typosquatFindings(typos, new Map(tree.map((p) => [p.name, p])), direct));
+
+  let online = null;
+  if (opts.online) {
+    // Registry checks are npm-only for now; say so instead of silently skipping.
+    online = { checked: 0, unreachable: 0, fetchedTarballs: 0, note: "--online registry checks cover npm only; PyPI packages were scanned offline." };
+  }
+
+  const unavailable = tree.filter((p) => !p.capabilities);
+  return {
+    target: relCwd(root),
+    mode: "deps",
+    local: true,
+    reachable: true,
+    timestamp: new Date(started).toISOString(),
+    duration: Date.now() - started,
+    deps: {
+      ecosystem: "pypi",
+      lockfile: cur.lockfile,
+      lockfileVersion: cur.lockfileVersion,
+      format: cur.format,
+      venv: cur.venv,
+      prod: !!opts.prod,
+      network: "offline",
+      total: tree.length,
+      scanned: tree.filter((p) => p.capabilities).length,
+      skippedOptional: 0,
+      direct: [...direct],
+      notInstalled: unavailable.map((p) => (p.version ? `${p.name}@${p.version}` : `${p.name} (unpinned, not installed)`)),
+      capabilityCounts: summarize(tree),
+      popularList: loadPopular("pypi").source,
+      packages: tree.map((p) => ({
+        name: p.name,
+        version: p.version,
+        path: p.path,
+        dev: p.dev,
+        direct: direct.has(p.name),
+        source: p.source,
+        ecosystem: "pypi",
+        capabilities: p.capabilities,
+      })),
+      typosquats: typos,
+      online,
       diff: diff ? {
         base: base.label,
         added: diff.added.map(({ pkg, ...a }) => ({ ...a, installScripts: pkg.installScripts })),
@@ -438,3 +628,73 @@ export async function scanDeps(root, opts = {}) {
     findings,
   };
 }
+
+/** One result for a project with both npm and Python dependencies. */
+function combineResults(results) {
+  const [first] = results;
+  const ds = results.map((r) => r.deps);
+  const sum = (k) => ds.reduce((n, d) => n + (d[k] || 0), 0);
+  const counts = {};
+  for (const id of CAPABILITY_ORDER) counts[id] = ds.reduce((n, d) => n + (d.capabilityCounts[id] || 0), 0);
+  const diffs = ds.map((d) => d.diff).filter(Boolean);
+  return {
+    ...first,
+    duration: Math.max(...results.map((r) => r.duration)),
+    deps: {
+      ...ds[0],
+      ecosystem: ds.map((d) => d.ecosystem).join("+"),
+      ecosystems: ds.map((d) => d.ecosystem),
+      lockfile: ds.map((d) => d.lockfile).join(" + "),
+      format: ds.map((d) => d.format).join(" + "),
+      venv: ds.find((d) => d.venv)?.venv || null,
+      network: ds.map((d) => d.network).find((n) => n !== "offline") || "offline",
+      total: sum("total"),
+      scanned: sum("scanned"),
+      skippedOptional: sum("skippedOptional"),
+      direct: ds.flatMap((d) => d.direct),
+      notInstalled: ds.flatMap((d) => d.notInstalled),
+      capabilityCounts: counts,
+      popularList: ds.map((d) => d.popularList).join(", "),
+      packages: ds.flatMap((d) => d.packages.map((p) => ({ ecosystem: d.ecosystem, ...p }))),
+      typosquats: ds.flatMap((d) => d.typosquats),
+      online: ds.find((d) => d.online)?.online || null,
+      diff: diffs.length ? {
+        base: diffs[0].base,
+        added: diffs.flatMap((d) => d.added),
+        upgraded: diffs.flatMap((d) => d.upgraded),
+        removed: diffs.flatMap((d) => d.removed),
+        evidence: Object.assign({}, ...diffs.map((d) => d.evidence)),
+      } : null,
+      parts: ds,
+    },
+    findings: results.flatMap((r) => r.findings),
+  };
+}
+
+/**
+ * Scan a project's dependencies: npm (package-lock.json), Python (uv.lock,
+ * poetry.lock, pdm.lock, Pipfile.lock, requirements*.txt, a virtualenv), or both.
+ * @param {string} root project folder
+ * @param {{ diff?: string, base?: string, online?: boolean, prod?: boolean,
+ *           onPhase?: Function, cacheDir?: string|string[], now?: number, fetchImpl?: Function,
+ *           treeRoot?: string, ecosystem?: "npm"|"python"|"auto", venv?: string,
+ *           pipCacheDir?: string, uvCacheDir?: string, lock?: object, baseLock?: object,
+ *           baseLabel?: string, changedOnly?: boolean, licensePolicy?: object }} opts
+ *           lock, baseLock, changedOnly, licensePolicy: npm only, see scanNpm(). treeRoot: where installed
+ *           packages live, when the lockfile describes a tree that is not installed beside
+ *           it (penthera install). venv: the Python virtualenv to read (default .venv or venv).
+ */
+export async function scanDeps(root, opts = {}) {
+  // Lockfile objects passed in (the pre-commit hook) are npm lockfiles.
+  if (opts.lock || opts.baseLock) return scanNpm(root, opts);
+  const eco = opts.ecosystem || "auto";
+  const npm = eco !== "python" && !!findLockfile(root);
+  const python = eco === "python" || (eco !== "npm" && hasPythonInputs(root, opts.venv));
+  if (!npm && !python) {
+    throw new Error(`No package-lock.json in ${root}. penthera deps reads the lockfile; run \`npm install --package-lock-only\` first. For Python it reads uv.lock, poetry.lock, pdm.lock, Pipfile.lock, requirements*.txt or a .venv.`);
+  }
+  const results = [];
+  if (npm) results.push(await scanNpm(root, opts));
+  if (python) results.push(await scanPython(root, opts));
+  return results.length === 1 ? results[0] : combineResults(results);
+}

package/lib/deps/lockfile.js

@@ -93,16 +93,39 @@ export function findLockfile(dir) {
   return null;
 }
 
+/**
+ * Throws unless `ref` is a plain git revision: no leading "-" (it would be
+ * read as an option, e.g. --output=<file>) and only characters revisions use.
+ * `--base` reaches here from the command line and from CI inputs.
+ */
+export function assertSafeRef(ref) {
+  if (typeof ref !== "string" || !/^[A-Za-z0-9_./@^~{}+-]{1,256}$/.test(ref) || ref.startsWith("-") || ref.includes("..")) {
+    throw new Error(`Invalid git ref ${JSON.stringify(String(ref).slice(0, 80))}: use a branch, tag or commit (letters, digits and . _ / @ ^ ~ { } + -, not starting with -)`);
+  }
+  return ref;
+}
+
+/**
+ * git for reading a scanned repo: no fsmonitor, no hooks, no transports.
+ * Read-only plumbing only (rev-parse, show, ls-tree).
+ */
+export function readOnlyGit(dir) {
+  return (args) => execFileSync("git", ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", ...args], {
+    cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024, env: { ...process.env, GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0" },
+  });
+}
+
 /**
  * Read the lockfile as it was at a git ref (for `--base <ref>`).
  * Only runs `git show`; no fetch, no checkout.
  */
 export function readLockfileAtRef(dir, ref) {
-  const git = (args) => execFileSync("git", args, { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  assertSafeRef(ref);
+  const git = readOnlyGit(dir);
   const prefix = git(["rev-parse", "--show-prefix"]).trim();
   for (const f of ["package-lock.json", "npm-shrinkwrap.json"]) {
     try {
-      return JSON.parse(git(["show", `${ref}:${prefix}${f}`]));
+      return JSON.parse(git(["show", "--end-of-options", `${ref}:${prefix}${f}`]));
     } catch { /* try the next name */ }
   }
   throw new Error(`No package-lock.json at ${ref} in ${dir}`);