penthera 1.4.0 → 1.6.0

package/lib/deps/capabilities.js

@@ -48,8 +48,30 @@ export const CAPABILITIES = {
     why: "Runs an AI coding CLI (claude, gemini, q), the pattern used by the s1ngularity attack to search the disk for secrets." },
   "token-harvest": { label: "GitHub token harvesting", severity: "critical", confidence: "likely",
     why: "Reads GitHub credentials: runs the gh CLI to print its token, reads gh's hosts file or git's credential store, or matches token-shaped strings next to network code." },
+  // Python only (lib/deps/python): code that runs whenever the interpreter starts, and unpickling.
+  "startup-hook": { label: "runs at Python startup", severity: "high", confidence: "confirmed",
+    why: "Ships a .pth file with an import line, or writes one. Python runs those lines on every interpreter start in that environment, a known persistence trick." },
+  deserialize: { label: "unpickles data", severity: "low", confidence: "likely",
+    why: "Loads pickle, marshal or unsafe YAML data, which runs code if the data is attacker-controlled." },
 };
 
+/** Python wording for capabilities whose npm description names npm or Node APIs. */
+const PY_WHY = {
+  "install-scripts": "Runs code at install time: a setup.py with custom commands, or an in-tree build backend, executes when pip builds the package from source.",
+  shell: "Can run arbitrary programs (subprocess, os.system, os.popen, pty).",
+  network: "Can open network connections (socket, urllib, requests, httpx, aiohttp and similar).",
+  env: "Reads os.environ.",
+  "env-bulk": "Serialises or enumerates all of os.environ, which holds tokens and keys.",
+  eval: "Builds code at runtime with eval, exec or compile.",
+  "dynamic-require": "Imports modules whose names are computed at runtime (__import__, importlib).",
+  native: "Ships native extensions (.so, .pyd) or loads libraries with ctypes, which this scanner cannot read.",
+  obfuscated: "Code looks deliberately hidden (encoded blobs or compressed payloads handed to exec, escape-heavy strings, PyArmor).",
+  "ai-cli-invoke": "Runs an AI coding CLI (claude, gemini, q) through a subprocess, the pattern used by the s1ngularity attack to search the disk for secrets.",
+};
+
+/** Why a capability matters, worded for the package's ecosystem. */
+export const capabilityWhy = (id, ecosystem) => (ecosystem === "pypi" && PY_WHY[id]) || CAPABILITIES[id]?.why || id;
+
 /** Stable display order. */
 export const CAPABILITY_ORDER = Object.keys(CAPABILITIES);
 
@@ -193,20 +215,25 @@ const GH_TOKEN_CMD_RE = new RegExp(j("\\bgh\\s+auth\\s+", "token\\b"));
 const GH_CRED_FILE_RE = new RegExp(`(?:${j("\\.git-", "credentials")}|${j("gh[/\\\\\\\\]", "hosts\\.yml")})`);
 const GH_TOKEN_REGEX_RE = new RegExp(`(?:${j("gh", "p_")}|${j("gh", "o_")}|${j("github", "_pat_")}|${j("gh", "\\[pousr")}|${j("gh", "\\[ps")})`);
 
+/** Attack-indicator patterns shared with the Python scanner (lib/deps/python). */
+export const INDICATORS = {
+  AI_CONFIG_RE, DESKTOP_CONFIG_RE, AI_CLIS, AI_CLI_FLAG_RE, GH_TOKEN_CMD_RE, GH_CRED_FILE_RE, GH_TOKEN_REGEX_RE,
+};
+
 const DECODE_RE = /\batob\s*\(|\bBuffer\.from\([^)]*['"`](?:base64|hex)['"`]|String\.fromCharCode\s*\(|\bdecodeURIComponent\s*\(\s*escape\s*\(/;
 
 const SUSPICIOUS_INSTALL_CMD = /\b(?:curl|wget|powershell|Invoke-WebRequest|iwr)\b|\|\s*(?:ba)?sh\b|base64\s+(?:-d|--decode)/i;
-const RISKY_FOR_INSTALL = ["network", "eval", "obfuscated", "env-bulk", "ai-config-write", "ai-cli-invoke", "token-harvest"];
+export const RISKY_FOR_INSTALL = ["network", "eval", "obfuscated", "env-bulk", "ai-config-write", "ai-cli-invoke", "token-harvest"];
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
-function snippet(line, idx) {
+export function snippet(line, idx) {
   const start = Math.max(0, idx - 40);
   const s = line.slice(start, start + 120).trim();
   return (start > 0 ? "…" : "") + s + (start + 120 < line.length ? "…" : "");
 }
 
-function add(caps, id, ev) {
+export function add(caps, id, ev) {
   const list = caps[id] || (caps[id] = { count: 0, evidence: [] });
   list.count++;
   if (list.evidence.length < MAX_EVIDENCE) list.evidence.push(ev);
@@ -228,7 +255,7 @@ export function entropy(s) {
  * Obfuscation signals for one file (comment-blanked code).
  * Returns { flagged, signals: string[], line }.
  */
-export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
+export function obfuscationSignals(code, { hasDynamicCode = false, evalRes = P.eval, decodeRe = DECODE_RE, strongEscapes = true } = {}) {
   const signals = [];
   let line = 1;
   let strong = 0;
@@ -243,7 +270,7 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   // Printable characters only: ANSI colour codes (\x1b) and control bytes are normal.
   const hexEsc = code.match(/\\x[2-7][0-9a-fA-F]/g);
   if (hexEsc && hexEsc.length >= 50 && (hexEsc.length * 4) / code.length >= 0.05) {
-    strong++;
+    if (strongEscapes) strong++;
     signals.push(`\\x escape density ${Math.round(((hexEsc.length * 4) / code.length) * 100)}%`);
     if (line === 1) line = lineOf(code, code.indexOf("\\x"));
   }
@@ -273,8 +300,8 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   let payload = null;
   if (blobs.length && hasDynamicCode) {
     const offsets = (res) => res.flatMap((re) => [...code.matchAll(new RegExp(re.source, "g"))].map((m) => m.index));
-    const evals = offsets(P.eval);
-    const decodes = offsets([DECODE_RE]);
+    const evals = offsets(evalRes);
+    const decodes = offsets([decodeRe]);
     const near = (b, list) => list.some((o) => o >= b.index - PAYLOAD_WINDOW && o <= b.end + PAYLOAD_WINDOW);
     payload = blobs.find((b) => near(b, evals) && near(b, decodes)) || null;
   }
@@ -287,14 +314,14 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   return { flagged, signals, line };
 }
 
-function lineOf(code, idx) {
+export function lineOf(code, idx) {
   if (idx <= 0) return 1;
   let n = 1;
   for (let i = 0; i < idx; i++) if (code.charCodeAt(i) === 10) n++;
   return n;
 }
 
-function findLine(text, needle) {
+export function findLine(text, needle) {
   const lines = text.split("\n");
   for (let i = 0; i < lines.length; i++) if (lines[i].includes(needle)) return i + 1;
   return 1;
@@ -393,7 +420,7 @@ export function scanSource(src, file) {
   return { caps, exfil, aiConfigProject };
 }
 
-function mergeCaps(into, from) {
+export function mergeCaps(into, from) {
   for (const [id, v] of Object.entries(from)) {
     const t = into[id] || (into[id] = { count: 0, evidence: [] });
     t.count += v.count;
@@ -426,7 +453,9 @@ export function nodeScriptTargets(cmd) {
  * Scan a package through a source (see source.js).
  * @param {{ files(): string[], read(rel): Buffer, size(rel): number }} source
  * @param {{ prefix?: string }} opts prefix is prepended to evidence paths (e.g. node_modules/foo/)
- * @returns {{ name, version, capabilities, installScripts, exfil, filesScanned, skipped }}
+ * @returns {{ name, version, capabilities, installScripts, exfil, filesScanned, skipped, unscanned }}
+ *   unscanned: why the package could not be fully read (archive anomaly, no
+ *   package.json), else null. Callers must not treat such a package as clean.
  */
 export function scanPackage(source, opts = {}) {
   const prefix = opts.prefix || "";
@@ -434,10 +463,17 @@ export function scanPackage(source, opts = {}) {
   const files = source.files();
   let pkg = {};
   let pkgText = "";
+  // Install scripts come only from package.json, so a package whose archive or
+  // manifest could not be read is unscanned, never clean (fail closed).
+  let unscanned = source.anomaly || null;
   try {
     pkgText = source.read("package.json").toString("utf-8");
     pkg = JSON.parse(pkgText);
-  } catch { /* no or broken package.json */ }
+    if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) throw new Error("not an object");
+  } catch {
+    pkg = {};
+    unscanned = unscanned || "package.json is missing or not valid JSON, so its install scripts are unknown";
+  }
 
   const installScripts = {};
   for (const hook of INSTALL_HOOKS) {
@@ -519,5 +555,6 @@ export function scanPackage(source, opts = {}) {
     exfil,
     filesScanned,
     skipped,
+    unscanned,
   };
 }

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,9 +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";
@@ -62,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,
@@ -118,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;
@@ -130,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],
     }));
   }
@@ -141,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"],
     }));
   }
@@ -152,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"],
     }));
   }
@@ -165,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));
@@ -186,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" },
     }));
@@ -199,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 },
     }));
@@ -213,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;
@@ -267,6 +365,7 @@ function summarize(tree) {
 
 /** Load the old tree for --diff (lockfile path or project folder) or --base (git ref). */
 function loadBase(root, opts) {
+  if (opts.baseLock) return { lock: opts.baseLock, treeRoot: null, label: opts.baseLabel || "base" };
   if (opts.base) {
     return { lock: readLockfileAtRef(root, opts.base), treeRoot: null, label: opts.base };
   }
@@ -282,31 +381,36 @@ 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 }} opts treeRoot: where installed packages live, when
- *           the lockfile describes a tree that is not installed beside it (penthera install)
+ * @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 = findLockfile(root);
+  const lockPath = opts.lock ? join(root, "package-lock.json") : findLockfile(root);
   if (!lockPath) throw new Error(`No package-lock.json in ${root}. penthera deps reads the lockfile; run \`npm install --package-lock-only\` first.`);
-  const lock = readLockfile(lockPath);
+  const lock = opts.lock || readLockfile(lockPath);
   const ctx = { cache: new Map(), cacheDirs: [].concat(opts.cacheDir || npmCacheDir()) };
   const keep = (p) => !p.link && p.version && (!opts.prod || !p.dev);
 
-  const pkgs = parseLockfile(lock).filter(keep);
+  const diffing = !!(opts.diff || opts.base || opts.baseLock);
+  const base = diffing ? loadBase(root, opts) : null;
+  let pkgs = parseLockfile(lock).filter(keep);
+  if (diffing && opts.changedOnly) {
+    const before = new Set(parseLockfile(base.lock).map((p) => `${p.name}@${p.version}`));
+    pkgs = pkgs.filter((p) => !before.has(`${p.name}@${p.version}`));
+  }
   onPhase(`Scanning ${pkgs.length} packages from ${basename(lockPath)} (offline)`);
   const tree = scanTree(pkgs, opts.treeRoot || root, ctx);
   const direct = new Set(directDependencies(lock));
 
   let diff = null;
-  let base = null;
-  if (opts.diff || opts.base) {
-    base = loadBase(root, opts);
+  if (diffing) {
     const oldPkgs = parseLockfile(base.lock).filter(keep);
     const byVersion = new Map(tree.map((p) => [`${p.name}@${p.version}`, p]));
     const newNames = new Set(tree.map((p) => p.name));
@@ -338,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));
@@ -363,9 +469,19 @@ export async function scanDeps(root, opts = {}) {
   const typos = findTyposquats(nameScope);
   findings.push(...typosquatFindings(typos, new Map(tree.map((p) => [p.name, p])), direct));
 
+  // License policy: the whole tree, or in diff mode only what changed.
+  let licenses = null;
+  if (opts.licensePolicy) {
+    const scope = tree.filter((p) => inScope.has(p));
+    onPhase(`Checking ${scope.length} package license(s) against the policy`);
+    const r = checkLicenses(scope, opts.licensePolicy, { treeRoot: opts.treeRoot || root, lockfileHasLicenses: (lock.lockfileVersion || 1) >= 2 });
+    findings.push(...r.findings);
+    licenses = r.summary;
+  }
+
   // 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;
@@ -378,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,
@@ -387,8 +505,103 @@ 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) => ({
+        name: p.name,
+        version: p.version,
+        path: p.path,
+        dev: p.dev,
+        license: p.license,
+        direct: direct.has(p.name),
+        source: p.source,
+        capabilities: p.capabilities,
+      })),
+      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,
@@ -396,6 +609,7 @@ export async function scanDeps(root, opts = {}) {
         dev: p.dev,
         direct: direct.has(p.name),
         source: p.source,
+        ecosystem: "pypi",
         capabilities: p.capabilities,
       })),
       typosquats: typos,
@@ -414,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);
+}