penthera 1.2.0 → 1.5.0

package/lib/injections.js

@@ -14,28 +14,26 @@
  *   - Nuclei, pattern-based detection
  *   - Burp Suite, time-based blind SQLi
  *
- * WARNING: These probes send attack payloads to the target.
+ * What this file is, for anyone reviewing the package:
+ *   The strings below are test inputs, the same well-known probes found in
+ *   OWASP testing guides and scanners like sqlmap, Burp and Nuclei. Penthera
+ *   never executes them. They are sent as request parameters to the one target
+ *   URL the user names, and only when the user opts in with --deep (or the
+ *   deep profile). Detection happens by reading that target's responses.
+ *   Nothing here runs on, or reaches out from, the machine running Penthera;
+ *   the HTTP client in src/utils/http.js refuses other hosts under --offline.
+ *
  * Only use against targets you have permission to test.
  */
 
 import { redirectsToHost } from "../src/utils/url.js";
+import { fetchText } from "../src/utils/http.js";
 
 const INJECT_TIMEOUT = 10_000;
 
-async function safeFetch(url, opts = {}) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), opts.timeout || INJECT_TIMEOUT);
-  const start = Date.now();
-  try {
-    const res = await fetch(url, { ...opts, signal: controller.signal, redirect: "manual" });
-    const elapsed = Date.now() - start;
-    const body = await res.text().catch(() => "");
-    return { status: res.status, body, headers: Object.fromEntries(res.headers.entries()), elapsed, ok: true };
-  } catch {
-    return { status: 0, body: "", headers: {}, elapsed: Date.now() - start, ok: false };
-  } finally {
-    clearTimeout(timeout);
-  }
+/** A fetch bound to one probe name, so failures are attributed in result.errors. */
+function clientFor(probe) {
+  return (url, opts = {}) => fetchText(url, { timeout: INJECT_TIMEOUT, probe, ...opts });
 }
 
 // ── Timing-based detection helpers ───────────────────────────────────────
@@ -125,6 +123,7 @@ const SQLI_PAYLOADS = [
  * @returns {object[]} Findings
  */
 export async function probeSqli(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("sqli");
   const findings = [];
   const method = opts.method || "GET";
 
@@ -253,6 +252,7 @@ export function sstiEvaluated(body, payload, expr, product) {
  * Test an endpoint for SSTI.
  */
 export async function probeSsti(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("ssti");
   const findings = [];
   const { probes, expr, product } = buildSstiProbes();
 
@@ -316,6 +316,7 @@ const SSRF_TARGETS = [
  * Test an endpoint for SSRF via URL parameters.
  */
 export async function probeSsrf(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("ssrf");
   const findings = [];
 
   // Identify URL-like parameters in the path or common parameter names
@@ -373,6 +374,7 @@ const REDIRECT_PAYLOADS = [
  * Test an endpoint for open redirect.
  */
 export async function probeOpenRedirect(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("open-redirect");
   const findings = [];
   const redirectParams = ["redirect", "redirect_uri", "return", "return_to", "next", "url", "callback", "redir", "destination", "go"];
 
@@ -421,6 +423,7 @@ const CMDI_PAYLOADS = [
  * Test an endpoint for OS command injection.
  */
 export async function probeCmdi(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("cmdi");
   const findings = [];
   const method = opts.method || "POST";
 
@@ -512,6 +515,7 @@ export function isHtmlResponse(res) {
  *   5. Verify the payload is reflected unescaped
  */
 export async function probeXss(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("xss");
   const findings = [];
   const CANARY = makeCanary();
   const inputParams = ["q", "search", "query", "name", "input", "text", "value", "msg", "error", "redirect", "url", "id"];

package/lib/install/index.js

@@ -0,0 +1,271 @@
+/**
+ * `penthera install`: an install firewall on top of the `penthera deps` engine.
+ *
+ *   1. Resolve. `npm install --package-lock-only --ignore-scripts [pkg...]` runs
+ *      in a temporary copy of package.json / package-lock.json / .npmrc. Not in
+ *      place: npm rewrites node_modules/.package-lock.json even in lock-only
+ *      mode, and an abort must leave the project byte for byte as it was.
+ *   2. Fetch. `npm cache add` puts each new tarball in npm's cache; nothing is
+ *      unpacked into node_modules and no package code runs. The deps engine
+ *      reads tarballs back from the cache only after verifying them against
+ *      the proposed lockfile's integrity (lib/deps/source.js).
+ *   3. Diff. lib/deps scans the proposed tree against the current lockfile:
+ *      new packages, capabilities gained, install scripts, typosquats.
+ *   4. Decide. lib/install/policy.js turns that into deny / needs-approval.
+ *   5. Apply (only when allowed). The vetted package.json and lockfile are
+ *      written into the project and `npm install` installs exactly that tree,
+ *      with `--ignore-scripts` unless the new install scripts were approved.
+ *
+ * Penthera makes no network calls here. npm talks to its configured registry
+ * (resolve and fetch); that is the one expected egress.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, copyFileSync, rmSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { scanDeps } from "../deps/index.js";
+import { parseLockfile } from "../deps/lockfile.js";
+import { sourceFromNpmCache, npmCacheDir } from "../deps/source.js";
+import { evaluatePolicy, normalizePolicy } from "./policy.js";
+
+const run = promisify(execFile);
+const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
+const LOCKFILES = ["package-lock.json", "npm-shrinkwrap.json"];
+const COPY = ["package.json", ...LOCKFILES, ".npmrc"];
+const QUIET = ["--no-audit", "--no-fund", "--no-update-notifier"];
+const LOCAL_SPEC = /^(file:|link:|portal:|\.{1,2}\/|\/)/;
+
+async function npm(args, opts) {
+  try {
+    return await run(NPM, args, { maxBuffer: 64 * 1024 * 1024, shell: process.platform === "win32", ...opts });
+  } catch (e) {
+    const msg = String(e.stderr || e.message).trim().split("\n").filter((l) => !/^npm (verbose|silly|timing)/.test(l)).slice(-8).join("\n");
+    throw new Error(`npm ${args[0]} failed:\n${msg}`);
+  }
+}
+
+/** npm's version and registry, as npm sees them from the project. */
+export async function npmInfo(root, env = process.env) {
+  const [version, registry] = await Promise.all([
+    npm(["--version"], { cwd: root, env }).then((r) => r.stdout.trim()),
+    npm(["config", "get", "registry"], { cwd: root, env }).then((r) => r.stdout.trim(), () => "the configured npm registry"),
+  ]);
+  const major = parseInt(version, 10) || 0;
+  // npm 12 blocks dependency install scripts unless package.json allowScripts lists them.
+  return { version, major, registry, allowScriptsPolicy: major >= 12 };
+}
+
+const key = (p) => `${p.path}@${p.version}#${p.integrity || ""}`;
+const scriptsOf = (s) => (s && Object.keys(s).length ? s : null);
+
+/** The rule ids a change raises (see lib/install/policy.js). */
+function flagsFor(caps, { newScripts, typosquat, unscanned }) {
+  const flags = [...(caps || [])].filter((id) => id !== "install-scripts");
+  if (newScripts) flags.unshift("install-scripts");
+  if (typosquat) flags.push("typosquat");
+  if (unscanned) flags.push("unscanned");
+  return flags;
+}
+
+/**
+ * Turn the deps diff into one change per new or upgraded package.
+ * `packages` is result.deps.packages, for the capabilities of an upgrade whose
+ * old version could not be read.
+ */
+export function changesFromDiff(diff, typosquats = [], packages = []) {
+  const typo = new Map(typosquats.map((t) => [t.name, t]));
+  const capsOf = (name, version) => {
+    const c = packages.find((p) => p.name === name && p.version === version)?.capabilities;
+    return c ? Object.keys(c) : null;
+  };
+  const out = [];
+  for (const a of diff.added) {
+    const scripts = scriptsOf(a.installScripts);
+    out.push({
+      change: "added",
+      name: a.name,
+      version: a.version,
+      capabilities: a.capabilities || [],
+      installScripts: scripts,
+      typosquatOf: typo.get(a.name)?.target || null,
+      flags: flagsFor(a.capabilities, { newScripts: !!scripts, typosquat: typo.has(a.name), unscanned: a.capabilities === null }),
+    });
+  }
+  for (const u of diff.upgraded) {
+    const scripts = scriptsOf(u.installScripts);
+    const before = scriptsOf(u.previousInstallScripts);
+    // A hook that is new, or whose command changed, is new code at install time.
+    const newScripts = !!scripts && JSON.stringify(scripts) !== JSON.stringify(before);
+    // Old version unreadable: judge the new version on everything it can do.
+    const gained = u.gained ?? (u.unavailable === "old" ? capsOf(u.name, u.to) : null);
+    out.push({
+      change: "upgraded",
+      name: u.name,
+      version: u.to,
+      from: u.from,
+      capabilities: gained || [],
+      installScripts: scripts,
+      previousInstallScripts: before,
+      compared: u.unavailable == null,
+      typosquatOf: null,
+      flags: flagsFor(gained, { newScripts, typosquat: false, unscanned: u.unavailable === "new" }),
+    });
+  }
+  return out;
+}
+
+function readIfExists(p) {
+  return existsSync(p) ? readFileSync(p) : null;
+}
+
+function checkProject(root, pkgJson) {
+  if (pkgJson.workspaces) throw new Error("npm workspaces are not supported by `penthera install` yet. Run `npm install --package-lock-only --ignore-scripts` and review with `penthera deps --base HEAD`.");
+  const local = Object.entries({ ...pkgJson.dependencies, ...pkgJson.devDependencies, ...pkgJson.optionalDependencies })
+    .filter(([, spec]) => LOCAL_SPEC.test(String(spec)));
+  if (local.length) throw new Error(`Local path dependencies (${local.map(([n]) => n).join(", ")}) cannot be resolved from a temporary copy. Run \`npm install --package-lock-only --ignore-scripts\` and review with \`penthera deps --base HEAD\`.`);
+}
+
+/**
+ * Work out what `npm install [specs]` would change, without running any
+ * package code and without writing to the project.
+ * @param {string} root project folder (has package.json)
+ * @param {string[]} specs packages as npm accepts them (name, name@range, ...)
+ * @param {{ policy?: object, saveDev?: boolean, saveExact?: boolean, offline?: boolean,
+ *           env?: object, onPhase?: Function, info?: object }} opts
+ */
+export async function planInstall(root, specs, opts = {}) {
+  root = resolve(root);
+  const env = opts.env || process.env;
+  const onPhase = opts.onPhase || (() => {});
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`No package.json in ${root}`);
+  checkProject(root, JSON.parse(readFileSync(pkgPath, "utf-8")));
+  const bad = specs.filter((s) => s.startsWith("-") || LOCAL_SPEC.test(s));
+  if (bad.length) throw new Error(`Unsupported package spec(s): ${bad.join(", ")}. Pass registry names (name, name@version, name@range).`);
+
+  const info = opts.info || await npmInfo(root, env);
+  const original = Object.fromEntries(COPY.map((f) => [f, readIfExists(join(root, f))]));
+  const lockName = LOCKFILES.find((f) => original[f]) || "package-lock.json";
+
+  const tmp = mkdtempSync(join(tmpdir(), "penthera-install-"));
+  try {
+    const work = join(tmp, "project");
+    mkdirSync(work);
+    for (const f of COPY) if (original[f]) copyFileSync(join(root, f), join(work, f));
+
+    const flags = [...(opts.saveDev ? ["--save-dev"] : []), ...(opts.saveExact ? ["--save-exact"] : []), ...(opts.offline ? ["--offline"] : [])];
+    onPhase(`Resolving in a temporary copy: npm install --package-lock-only --ignore-scripts${specs.length ? ` ${specs.join(" ")}` : ""}`);
+    await npm(["install", "--package-lock-only", "--ignore-scripts", ...QUIET, ...flags, ...specs], { cwd: work, env });
+
+    const proposedLockPath = join(work, lockName);
+    if (!existsSync(proposedLockPath)) throw new Error("npm did not write a lockfile");
+    const proposedLock = JSON.parse(readFileSync(proposedLockPath, "utf-8"));
+
+    // Base: the project's current lockfile, or an empty tree for a first install.
+    let baseLockPath = original[lockName] ? join(root, lockName) : null;
+    if (!baseLockPath) {
+      mkdirSync(join(tmp, "base"));
+      baseLockPath = join(tmp, "base", "package-lock.json");
+      writeFileSync(baseLockPath, JSON.stringify({ lockfileVersion: 3, packages: { "": {} } }));
+    }
+    const oldKeys = new Set(parseLockfile(JSON.parse(readFileSync(baseLockPath, "utf-8"))).map(key));
+    const fresh = parseLockfile(proposedLock).filter((p) => !p.link && p.version && !oldKeys.has(key(p)));
+
+    // New tarballs go into a private npm cache (npm cache add): nothing is
+    // unpacked or run. Private because npm will not reliably say where its own
+    // cache is (`npm config get cache` refuses some paths), and because the
+    // scan must not depend on what else that cache holds.
+    const userCache = npmCacheDir(env);
+    const fetchCache = join(tmp, "cache");
+    const toFetch = fresh.filter((p) => !p.integrity || !sourceFromNpmCache(p.integrity, userCache));
+    if (toFetch.length) {
+      onPhase(`Fetching ${toFetch.length} tarball(s) with npm cache add (nothing is unpacked or run)`);
+      const fetchSpecs = [...new Set(toFetch.map((p) => (p.resolved && !/^https?:/.test(p.resolved) ? p.resolved : `${p.name}@${p.version}`)))];
+      await npm(["cache", "add", "--cache", fetchCache, ...(opts.offline ? ["--offline"] : []), ...fetchSpecs], { cwd: tmp, env });
+    }
+
+    onPhase("Comparing capabilities with the current tree (offline, integrity-verified)");
+    const result = await scanDeps(work, { diff: baseLockPath, treeRoot: root, cacheDir: [fetchCache, userCache] });
+    const changes = changesFromDiff(result.deps.diff, result.deps.typosquats, result.deps.packages);
+    const verdict = evaluatePolicy(changes, opts.policy || normalizePolicy({}));
+
+    return {
+      root,
+      specs,
+      npm: info,
+      lockName,
+      original,
+      proposed: {
+        "package.json": readFileSync(join(work, "package.json")),
+        [lockName]: readFileSync(proposedLockPath),
+      },
+      changes,
+      removed: result.deps.diff.removed,
+      verdict,
+      findings: result.findings,
+      typosquats: result.deps.typosquats,
+      evidence: result.deps.diff.evidence,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** Packages whose new or changed install scripts would run. */
+export const scriptChanges = (plan) => plan.verdict.items.filter((i) => i.flags.includes("install-scripts"));
+
+/**
+ * Pin approved packages in package.json allowScripts (npm >= 12 runs a
+ * dependency's install scripts only when listed there). Returns new bytes.
+ */
+export function withAllowScripts(pkgJsonBuf, items) {
+  const text = pkgJsonBuf.toString("utf-8");
+  const pkg = JSON.parse(text);
+  const allow = { ...(pkg.allowScripts || {}) };
+  for (const i of items) {
+    if (allow[i.name] === false) continue; // an explicit denial in the project wins
+    allow[`${i.name}@${i.version}`] = true;
+  }
+  pkg.allowScripts = Object.fromEntries(Object.entries(allow).sort((a, b) => a[0].localeCompare(b[0])));
+  const indent = text.match(/^\{\r?\n([ \t]+)"/)?.[1] || "  ";
+  return Buffer.from(JSON.stringify(pkg, null, indent) + (text.endsWith("\n") ? "\n" : ""));
+}
+
+function restore(root, original) {
+  for (const [f, buf] of Object.entries(original)) {
+    const p = join(root, f);
+    if (buf) writeFileSync(p, buf);
+    else rmSync(p, { force: true });
+  }
+}
+
+/**
+ * Install the vetted tree. Writes the proposed package.json and lockfile,
+ * then runs `npm install` with no package arguments, so npm installs exactly
+ * the lockfile that was reviewed. Restores both files if npm fails.
+ * @param {{ runScripts: boolean, env?: object, stdio?: string, offline?: boolean }} opts
+ */
+export async function applyInstall(plan, opts) {
+  const { root, original } = plan;
+  const env = opts.env || process.env;
+  let pkgJson = plan.proposed["package.json"];
+  const approved = scriptChanges(plan);
+  if (opts.runScripts && plan.npm.allowScriptsPolicy && approved.length) pkgJson = withAllowScripts(pkgJson, approved);
+
+  writeFileSync(join(root, "package.json"), pkgJson);
+  writeFileSync(join(root, plan.lockName), plan.proposed[plan.lockName]);
+  const args = ["install", ...QUIET, ...(opts.runScripts ? [] : ["--ignore-scripts"]), ...(opts.offline ? ["--offline"] : [])];
+  try {
+    await npm(args, { cwd: root, env });
+  } catch (e) {
+    restore(root, original);
+    throw new Error(`${e.message}\npackage.json and ${plan.lockName} were restored; node_modules may be partly updated (run \`npm ci\` to reset it).`);
+  }
+
+  // npm should have installed the reviewed lockfile as is.
+  const want = new Set(parseLockfile(JSON.parse(plan.proposed[plan.lockName])).map(key));
+  const got = parseLockfile(JSON.parse(readFileSync(join(root, plan.lockName), "utf-8"))).map(key);
+  const drift = got.filter((k) => !want.has(k));
+  return { args, scriptsRan: opts.runScripts, allowScriptsAdded: pkgJson !== plan.proposed["package.json"] ? approved.map((i) => `${i.name}@${i.version}`) : [], drift };
+}

package/lib/install/policy.js

@@ -0,0 +1,125 @@
+/**
+ * `penthera.policy.json`: what an install may bring in without a human.
+ *
+ *   {
+ *     "allow": ["@acme/*", "esbuild", "sharp@0.33.5"],
+ *     "deny": ["ai-cli-invoke", "token-harvest"],
+ *     "requireApproval": ["install-scripts", "obfuscated", "typosquat"]
+ *   }
+ *
+ * `deny` and `requireApproval` list capability ids from lib/deps/capabilities.js,
+ * plus two of the firewall's own: `typosquat` (a new name close to a popular
+ * package) and `unscanned` (a new package whose files could not be read).
+ * `allow` lists package names or globs (`*` matches any run of characters),
+ * optionally pinned to one version with `@x.y.z`; an allowed package passes
+ * both lists. A field left out keeps its default; a field given replaces it.
+ * Everything here is pure: no files are read except the policy itself.
+ *
+ * The same file has two optional sections for other commands: `licenses`
+ * (penthera deps, lib/deps/license.js) and `hook` (penthera hook run,
+ * lib/hook/policy.js). Both come back as null / defaults when absent.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CAPABILITY_ORDER, CAPABILITIES } from "../deps/capabilities.js";
+import { normalizeLicensePolicy } from "../deps/license.js";
+import { normalizeHookPolicy } from "../hook/policy.js";
+
+export const POLICY_FILE = "penthera.policy.json";
+
+export const RULE_IDS = [...CAPABILITY_ORDER, "typosquat", "unscanned"];
+
+export const RULE_LABELS = {
+  ...Object.fromEntries(CAPABILITY_ORDER.map((id) => [id, CAPABILITIES[id].label])),
+  typosquat: "looks like a popular package",
+  unscanned: "could not be scanned",
+};
+
+export const DEFAULT_POLICY = Object.freeze({
+  allow: [],
+  deny: [],
+  requireApproval: ["install-scripts", "ai-config-write", "ai-cli-invoke", "token-harvest", "obfuscated", "typosquat", "unscanned"],
+});
+
+/**
+ * Validate and complete a policy object. Throws with a readable message on
+ * unknown fields, unknown rule ids, or non-string entries.
+ */
+export function normalizePolicy(raw, label = POLICY_FILE) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected a JSON object`);
+  const known = ["allow", "deny", "requireApproval", "licenses", "hook", "$schema", "description"];
+  const extra = Object.keys(raw).filter((k) => !known.includes(k));
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected allow, deny, requireApproval, licenses, hook)`);
+  const out = {};
+  for (const field of ["allow", "deny", "requireApproval"]) {
+    const v = raw[field] ?? DEFAULT_POLICY[field];
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string" || !x.trim())) {
+      throw new Error(`${label}: "${field}" must be an array of non-empty strings`);
+    }
+    out[field] = [...new Set(v.map((x) => x.trim()))];
+  }
+  for (const field of ["deny", "requireApproval"]) {
+    const bad = out[field].filter((id) => !RULE_IDS.includes(id));
+    if (bad.length) throw new Error(`${label}: unknown capability in "${field}": ${bad.join(", ")}. Known: ${RULE_IDS.join(", ")}`);
+  }
+  out.licenses = raw.licenses == null ? null : normalizeLicensePolicy(raw.licenses, `${label}: licenses`);
+  out.hook = normalizeHookPolicy(raw.hook, `${label}: hook`);
+  return out;
+}
+
+/**
+ * Load the policy: an explicit path, else penthera.policy.json in the project,
+ * else the defaults. Returns { policy, path } (path null for defaults).
+ */
+export function loadPolicy(root, explicitPath = null) {
+  const path = explicitPath || join(root, POLICY_FILE);
+  if (!existsSync(path)) {
+    if (explicitPath) throw new Error(`Policy file not found: ${explicitPath}`);
+    return { policy: normalizePolicy({}), path: null };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (e) {
+    throw new Error(`${path}: ${e.message}`);
+  }
+  return { policy: normalizePolicy(raw, path), path };
+}
+
+const escapeRe = (s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+
+/** Split "name@1.2.3" / "@scope/name@1.2.3" into { name, version }. */
+function splitEntry(entry) {
+  const at = entry.lastIndexOf("@");
+  if (at > 0) return { name: entry.slice(0, at), version: entry.slice(at + 1) };
+  return { name: entry, version: null };
+}
+
+/** The first allow entry matching name@version, or null. */
+export function matchAllow(allow, name, version) {
+  for (const entry of allow) {
+    const e = splitEntry(entry);
+    const re = new RegExp(`^${e.name.split("*").map(escapeRe).join(".*")}$`);
+    if (!re.test(name)) continue;
+    if (e.version && e.version !== "*" && e.version !== version) continue;
+    return entry;
+  }
+  return null;
+}
+
+/**
+ * Apply the policy to the changes an install would make.
+ * @param {{ name, version, flags: string[] }[]} changes flags: the rule ids this change raises
+ * @returns {{ items: object[], denied: object[], needsApproval: object[], clean: boolean }}
+ */
+export function evaluatePolicy(changes, policy) {
+  const items = changes.map((c) => {
+    const allowedBy = matchAllow(policy.allow, c.name, c.version);
+    const deny = allowedBy ? [] : c.flags.filter((id) => policy.deny.includes(id));
+    const approval = allowedBy ? [] : c.flags.filter((id) => policy.requireApproval.includes(id) && !deny.includes(id));
+    return { ...c, allowedBy, deny, approval };
+  });
+  const denied = items.filter((i) => i.deny.length);
+  const needsApproval = items.filter((i) => i.approval.length);
+  return { items, denied, needsApproval, clean: denied.length === 0 && needsApproval.length === 0 };
+}

package/lib/jurisdictions/nl.json

@@ -38,6 +38,15 @@
       "content": "Final report: detailed description, root cause, applied and ongoing mitigations, and any cross-border impact."
     }
   ],
+  "cra": {
+    "law": "Cyber Resilience Act, Regulation (EU) 2024/2847, Article 14 (reporting applies from 11 September 2026)",
+    "csirtCoordinator": "NCSC-NL (Nationaal Cyber Security Centrum)",
+    "csirtContact": "https://www.ncsc.nl/contact",
+    "srp": "https://portal.cra-srp.enisa.europa.eu/",
+    "timezone": "Europe/Amsterdam",
+    "source": "https://www.enisa.europa.eu/topics/product-security/vulnerability-services/eu-incident-response-and-cyber-crisis-management/single-reporting-platform-srp/list-of-csirts-designated-as-coordinators",
+    "note": "NCSC-NL is the Dutch CSIRT designated as coordinator on ENISA's list (checked 2026-10-19). It applies if your main establishment is in the Netherlands, i.e. where cybersecurity decisions about your products are predominantly taken (Art. 14(7))."
+  },
   "penalties": "Up to €10M or 2% of global annual turnover. Management can be held personally accountable.",
   "pointers": [
     "Determine whether you are an essential or important entity, and your sector's competent authority.",

package/lib/memory/history.js

@@ -0,0 +1,52 @@
+/**
+ * Report-side view over memory events: the scan trend (counts per scan) and
+ * the fix history per finding id (first seen → fix applied → verified or
+ * failed). Like views.js it only reads, and every field is type-checked.
+ */
+
+const MAX_STR = 500;
+const str = (x) => (typeof x === "string" && x.length > 0 && x.length <= MAX_STR ? x : null);
+const int = (x) => (Number.isInteger(x) && x >= 0 ? x : 0);
+const iso = (x) => (str(x) && !Number.isNaN(Date.parse(x)) ? x : null);
+
+/**
+ * @param {object[]} events  verified events from openMemory().events()
+ * @param {{ maxScans?: number }} opts  how many recent scans the trend keeps
+ * @returns {{ trend: object[], fixes: object[] }}
+ */
+export function buildHistory(events, { maxScans = 12 } = {}) {
+  const trend = [];
+  const fixes = new Map();
+  const fix = (id) => {
+    if (!fixes.has(id)) fixes.set(id, { id, firstSeen: null, applied: null, recipe: null, verified: null, failed: null });
+    return fixes.get(id);
+  };
+  const firstSeen = new Map();
+
+  for (const ev of events || []) {
+    const d = ev?.data;
+    const ts = iso(ev?.ts);
+    if (!d || typeof d !== "object" || !ts) continue;
+    if (ev.type === "scan") {
+      const c = d.counts && typeof d.counts === "object" ? d.counts : {};
+      trend.push({
+        ts, critical: int(c.critical), high: int(c.high), medium: int(c.medium), low: int(c.low),
+        total: int(c.total), suppressed: int(c.suppressed),
+      });
+      for (const id of Array.isArray(d.ids) ? d.ids : []) if (str(id) && !firstSeen.has(id)) firstSeen.set(id, ts);
+    } else if (ev.type === "fix_applied" || ev.type === "fix_verified" || ev.type === "fix_failed") {
+      const id = str(d.id);
+      if (!id) continue;
+      const f = fix(id);
+      if (ev.type === "fix_applied") {
+        f.applied = ts;
+        f.recipe = str(d.recipe) || f.recipe;
+        f.verified = null;
+        f.failed = null;
+      } else if (ev.type === "fix_verified") f.verified = ts;
+      else f.failed = ts;
+    }
+  }
+  for (const f of fixes.values()) f.firstSeen = firstSeen.get(f.id) || f.applied;
+  return { trend: trend.slice(-maxScans), fixes: [...fixes.values()] };
+}

package/lib/memory/index.js

@@ -0,0 +1,111 @@
+/**
+ * Local learning store (v1.4 "local loop", workstream W2). Public API:
+ *
+ *   openMemory(projectId)      -> { append(event), verify(), events(), forget() }
+ *   views(memory)              -> recipe success, suppressions, probe ranking, time-to-fix
+ *   rankFindings(findings, v)  -> same findings, re-ordered
+ *   isSuppressed(finding, v)   -> suppression record or null
+ *
+ * See docs/local-loop.md for the threat model.
+ */
+import { openMemory, projectIdFor, memoryRoot, forgetAll, EVENT_TYPES } from "./store.js";
+import { buildViews, rankFindings, isSuppressed, withRepoSuppressions, findingId } from "./views.js";
+import { loadRepoSuppressions, REPO_SUPPRESS_FILE } from "./repo-suppress.js";
+import { buildHistory } from "./history.js";
+
+export {
+  openMemory, projectIdFor, memoryRoot, forgetAll, EVENT_TYPES,
+  buildViews, rankFindings, isSuppressed, withRepoSuppressions, findingId,
+  loadRepoSuppressions, REPO_SUPPRESS_FILE, buildHistory,
+};
+
+/**
+ * Views for an opened memory. Returns null when the chain does not verify:
+ * a tampered log must not steer a scan, so callers fall back to no memory.
+ */
+export function views(memory, opts = {}) {
+  if (!memory.verify().ok) return null;
+  return buildViews(memory.events(), opts);
+}
+
+/** Lower-cased framework name for the scanned target, or "unknown". */
+export function detectStack(result) {
+  const fw = result?.fingerprint?.framework || result?.attackSurface?.find?.((r) => r?.framework)?.framework;
+  return typeof fw === "string" && fw ? fw.toLowerCase().slice(0, 64) : "unknown";
+}
+
+/** Findings per probe: executed probes count from 0, finding sources add to them. */
+export function probeYields(result) {
+  const counts = new Map();
+  for (const p of result?.executedProbes || []) if (typeof p === "string") counts.set(p, 0);
+  for (const f of result?.findings || []) {
+    const probe = typeof f.source === "string" && f.source ? f.source : "unknown";
+    counts.set(probe, (counts.get(probe) || 0) + 1);
+  }
+  return [...counts].map(([probe, findings]) => ({ probe, findings }));
+}
+
+/**
+ * The `--memory` scan hook. Mutates `merged`:
+ *   merged.findings   -> unsuppressed findings, ranked
+ *   merged.suppressed -> suppressed findings, each with .suppression { source, reason, actor }
+ *   merged.memory     -> { projectId, chain: "ok" | "broken", ... }
+ * then appends `scan` and `probe_yield` events. Returns { warnings }.
+ *
+ * Fail-closed: if the chain is broken, memory suppressions and ranking are not
+ * applied and nothing is appended (the repo file, which is labelled, still is).
+ */
+export function applyMemoryToScan(merged, { repo = null, url = null, now = new Date().toISOString(), root } = {}) {
+  const warnings = [];
+  const { id: projectId, label } = projectIdFor({ repo, url });
+  const mem = openMemory(projectId, { root, label, now: () => now });
+  const check = mem.verify();
+  const stack = detectStack(merged);
+
+  let v = { suppressions: [], recipeSuccess: [], seen: {} };
+  if (check.ok) {
+    v = buildViews(mem.events(), { now });
+  } else {
+    warnings.push(`memory chain broken at line ${check.brokenAt} (${check.reason}); memory not applied. Run \`penthera memory verify\`.`);
+  }
+
+  if (repo) {
+    const rs = loadRepoSuppressions(repo, { now });
+    warnings.push(...rs.warnings);
+    v = withRepoSuppressions(v, rs.entries);
+  }
+
+  const all = merged.findings || [];
+  const kept = [];
+  const suppressed = [];
+  for (const f of all) {
+    const fid = findingId(f);
+    const s = isSuppressed(f, v);
+    if (s) suppressed.push({ ...f, fid, suppression: { source: s.source, reason: s.reason, actor: s.actor, expires: s.expires || null } });
+    else kept.push({ ...f, fid });
+  }
+  merged.findings = check.ok ? rankFindings(kept, v, { framework: stack }) : kept;
+  merged.suppressed = suppressed;
+  merged.memory = { projectId, stack, chain: check.ok ? "ok" : "broken", events: check.count };
+
+  if (check.ok) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of all) if (counts[f.severity] != null) counts[f.severity]++;
+    mem.append({
+      type: "scan",
+      ts: now,
+      data: {
+        stack,
+        modes: merged.modes || (merged.mode ? [merged.mode] : []),
+        counts: { ...counts, total: all.length, suppressed: suppressed.length },
+        ids: all.filter((f) => f.severity !== "info").map(findingId),
+      },
+    });
+    for (const p of probeYields({ executedProbes: merged.executedProbes, findings: all })) {
+      mem.append({ type: "probe_yield", ts: now, data: { probe: p.probe, stack, findings: p.findings } });
+    }
+    merged.memory.events = mem.verify().count;
+    merged.memory.history = buildHistory(mem.events());
+  }
+  return { warnings, projectId };
+}