penthera 1.2.0 → 1.5.0

package/lib/memory/repo-suppress.js

@@ -0,0 +1,64 @@
+/**
+ * Optional repo file `penthera.suppress.json`. This is the ONLY thing Penthera
+ * reads from a scanned repo that changes what a report shows, so it is held to
+ * a strict, data-only shape and every effect is labelled in the report as
+ * "suppressed by repo file" with its reason. A PR that adds an entry is visible
+ * in review, and so is the suppressed finding in the report.
+ *
+ *   {
+ *     "version": 1,
+ *     "suppress": [
+ *       { "id": "3f9a0c1d2b4e5f60", "reason": "test fixture key", "expires": "2027-01-01" },
+ *       { "fingerprint": "repo-secret|secret|...|...", "reason": "..." }
+ *     ]
+ *   }
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const REPO_SUPPRESS_FILE = "penthera.suppress.json";
+const MAX_BYTES = 64 * 1024;
+const MAX_ENTRIES = 500;
+
+/**
+ * Load and validate the repo file. Returns { entries, warnings }. Invalid
+ * entries are dropped with a warning, never guessed at.
+ */
+export function loadRepoSuppressions(repoPath, { now = new Date().toISOString() } = {}) {
+  const warnings = [];
+  const path = join(repoPath, REPO_SUPPRESS_FILE);
+  if (!existsSync(path)) return { entries: [], warnings, path: null };
+  const st = statSync(path);
+  if (!st.isFile()) return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is not a regular file, ignored`], path };
+  if (st.size > MAX_BYTES) return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is larger than 64 KB, ignored`], path };
+
+  let doc;
+  try { doc = JSON.parse(readFileSync(path, "utf-8")); } catch (e) {
+    return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is not valid JSON (${e.message}), ignored`], path };
+  }
+  if (!doc || typeof doc !== "object" || doc.version !== 1 || !Array.isArray(doc.suppress)) {
+    return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} needs { "version": 1, "suppress": [...] }, ignored`], path };
+  }
+
+  const nowMs = Date.parse(now);
+  const entries = [];
+  doc.suppress.slice(0, MAX_ENTRIES).forEach((e, i) => {
+    const where = `${REPO_SUPPRESS_FILE} entry ${i + 1}`;
+    if (!e || typeof e !== "object") { warnings.push(`${where}: not an object, ignored`); return; }
+    const id = typeof e.id === "string" && /^[0-9a-f]{16}$/.test(e.id) ? e.id : null;
+    const fingerprint = typeof e.fingerprint === "string" && e.fingerprint.length <= 2000 ? e.fingerprint : null;
+    if (!id && !fingerprint) { warnings.push(`${where}: needs "id" (16 hex chars) or "fingerprint", ignored`); return; }
+    const reason = typeof e.reason === "string" ? e.reason.trim() : "";
+    if (!reason || reason.length > 500) { warnings.push(`${where}: needs a "reason" (1-500 chars), ignored`); return; }
+    let expires = null;
+    if (e.expires != null) {
+      const t = Date.parse(e.expires);
+      if (typeof e.expires !== "string" || Number.isNaN(t)) { warnings.push(`${where}: "expires" is not a date, ignored`); return; }
+      if (t <= nowMs) { warnings.push(`${where}: expired on ${e.expires}, not applied`); return; }
+      expires = e.expires;
+    }
+    entries.push({ id, fingerprint, reason, expires, actor: "repo" });
+  });
+  if (doc.suppress.length > MAX_ENTRIES) warnings.push(`${REPO_SUPPRESS_FILE}: only the first ${MAX_ENTRIES} entries are read`);
+  return { entries, warnings, path };
+}

package/lib/memory/store.js

@@ -0,0 +1,325 @@
+/**
+ * Local learning store: an append-only, hash-chained event log per project.
+ *
+ *   ~/.penthera/memory/<project-id>/events.jsonl   one event per line
+ *   ~/.penthera/memory/<project-id>/head.json      { count, hash } of the tip
+ *   ~/.penthera/memory/<project-id>/meta.json      human label for `memory show`
+ *
+ * Each line is { v, ts, type, data, prev, hash } with
+ *   hash = sha256(prev + canonicalJson({ v, ts, type, data }))
+ * and the first event's prev bound to the project id, so a log copied from
+ * another project does not verify either.
+ *
+ * Safety rules (see docs/local-loop.md):
+ * - Memory is data. Nothing read from it is executed, evaluated, imported, or
+ *   used as a file path or shell command. Views only re-order and suppress.
+ * - Memory lives under the user's home (or PENTHERA_HOME), never in the
+ *   scanned repo, so a repo cannot ship pre-poisoned memory.
+ * - Writes take an exclusive lock file, then append one line with a single
+ *   O_APPEND write, so concurrent scans neither interleave nor fork the chain.
+ */
+import { createHash } from "node:crypto";
+import {
+  openSync, writeSync, closeSync, readFileSync, writeFileSync, renameSync,
+  mkdirSync, existsSync, rmSync, statSync, unlinkSync, constants as FS,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+
+export const EVENT_VERSION = 1;
+export const EVENT_TYPES = Object.freeze([
+  "scan", "fix_applied", "fix_verified", "fix_failed", "fp_suppressed", "probe_yield", "loop_run",
+]);
+const MAX_LINE_BYTES = 256 * 1024;
+const LOCK_STALE_MS = 30_000;
+const LOCK_TIMEOUT_MS = 10_000;
+
+export function sha256(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+/**
+ * Deterministic JSON: object keys sorted, no whitespace. Only plain JSON values
+ * are accepted (no functions, symbols, undefined, NaN, class instances), so the
+ * same event always hashes the same way.
+ */
+export function canonicalJson(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string": return JSON.stringify(value);
+    case "boolean": return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("canonicalJson: non-finite number");
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new TypeError("canonicalJson: only plain objects are allowed");
+      }
+      const keys = Object.keys(value).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    }
+    default:
+      throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+  }
+}
+
+export function hashEvent(prev, { v, ts, type, data }) {
+  return sha256(prev + canonicalJson({ v, ts, type, data }));
+}
+
+/** The chain's genesis value: binds line 1 to this project. */
+export function genesisHash(projectId) {
+  return sha256(`penthera-memory-v1:${projectId}`);
+}
+
+/** Memory root: $PENTHERA_HOME/memory, else ~/.penthera/memory. */
+export function memoryRoot(env = process.env) {
+  const base = env.PENTHERA_HOME ? resolve(env.PENTHERA_HOME) : join(homedir(), ".penthera");
+  return join(base, "memory");
+}
+
+/** Remove credentials from a URL-ish string before it is hashed or shown. */
+export function stripCredentials(u) {
+  const s = String(u || "").trim();
+  try {
+    const url = new URL(s);
+    url.username = "";
+    url.password = "";
+    return url.toString();
+  } catch {
+    return s.replace(/\/\/[^@/]+@/, "//"); // scp-like or odd remotes
+  }
+}
+
+/**
+ * Read the origin remote URL from .git/config without running git. Running git
+ * inside an untrusted repo can execute its hooks or core.fsmonitor, so we parse
+ * the config text ourselves. Worktrees (.git is a file) follow gitdir/commondir.
+ */
+export function readGitRemote(repoPath) {
+  try {
+    let gitDir = join(repoPath, ".git");
+    if (!existsSync(gitDir)) return null;
+    if (statSync(gitDir).isFile()) {
+      const m = readFileSync(gitDir, "utf-8").match(/^gitdir:\s*(.+)$/m);
+      if (!m) return null;
+      gitDir = resolve(repoPath, m[1].trim());
+      const common = join(gitDir, "commondir");
+      if (existsSync(common)) gitDir = resolve(gitDir, readFileSync(common, "utf-8").trim());
+    }
+    const cfg = readFileSync(join(gitDir, "config"), "utf-8");
+    let section = null;
+    let first = null;
+    for (const raw of cfg.split(/\r?\n/)) {
+      const line = raw.trim();
+      const sec = line.match(/^\[\s*remote\s+"([^"]+)"\s*\]$/);
+      if (sec) { section = sec[1]; continue; }
+      if (line.startsWith("[")) { section = null; continue; }
+      const kv = section && line.match(/^url\s*=\s*(.+)$/);
+      if (kv) {
+        if (section === "origin") return stripCredentials(kv[1]);
+        first ??= stripCredentials(kv[1]);
+      }
+    }
+    return first;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project id: sha256 of the repo's absolute path + git remote, or of the
+ * target origin for URL-only scans. Returns { id, label }.
+ */
+export function projectIdFor({ repo, url } = {}) {
+  if (repo) {
+    const abs = resolve(repo);
+    const remote = readGitRemote(abs) || "";
+    return { id: sha256(`repo\n${abs}\n${remote}`), label: remote ? `${abs} (${remote})` : abs };
+  }
+  if (url) {
+    const origin = new URL(stripCredentials(url)).origin;
+    return { id: sha256(`url\n${origin}`), label: origin };
+  }
+  throw new Error("projectIdFor: need a repo path or a URL");
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withLock(dir, fn) {
+  const lock = join(dir, "events.lock");
+  const started = Date.now();
+  let fd;
+  for (;;) {
+    try {
+      fd = openSync(lock, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY, 0o600);
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { unlinkSync(lock); continue; }
+      } catch { continue; } // lock vanished between calls: retry
+      if (Date.now() - started > LOCK_TIMEOUT_MS) throw new Error(`memory: lock busy (${lock})`);
+      sleepMs(5 + Math.floor(Math.random() * 20));
+    }
+  }
+  try {
+    writeSync(fd, String(process.pid));
+    return fn();
+  } finally {
+    closeSync(fd);
+    try { unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf-8")); } catch { return null; }
+}
+
+function writeJsonAtomic(path, obj) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Split the log into lines, keeping a trailing partial line visible to verify(). */
+function readLines(file) {
+  if (!existsSync(file)) return [];
+  const text = readFileSync(file, "utf-8");
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+function isPlainObject(x) {
+  return x !== null && typeof x === "object" && !Array.isArray(x)
+    && (Object.getPrototypeOf(x) === Object.prototype || Object.getPrototypeOf(x) === null);
+}
+
+/** Walk a list of raw lines and check every link. */
+export function verifyLines(lines, projectId) {
+  let prev = genesisHash(projectId);
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    let ev;
+    try { ev = JSON.parse(lines[i]); } catch {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "line is not valid JSON" };
+    }
+    if (!isPlainObject(ev) || ev.v !== EVENT_VERSION || typeof ev.ts !== "string"
+      || !EVENT_TYPES.includes(ev.type) || !isPlainObject(ev.data)
+      || typeof ev.prev !== "string" || typeof ev.hash !== "string") {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "malformed event" };
+    }
+    if (ev.prev !== prev) {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "prev does not match the previous line's hash (line removed, reordered, or inserted)" };
+    }
+    let expect;
+    try { expect = hashEvent(prev, ev); } catch {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "event is not canonical JSON" };
+    }
+    if (ev.hash !== expect) {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "hash mismatch (line edited)" };
+    }
+    prev = ev.hash;
+  }
+  return { ok: true, count: lines.length, tip: prev };
+}
+
+/**
+ * Open (lazily create) the memory for a project. Nothing touches disk until the
+ * first append, so read-only commands on an unknown project leave no trace.
+ */
+export function openMemory(projectId, { root = memoryRoot(), label = null, now = () => new Date().toISOString() } = {}) {
+  if (!/^[0-9a-f]{64}$/.test(String(projectId))) throw new Error("openMemory: project id must be a sha256 hex string");
+  const dir = join(root, projectId);
+  const file = join(dir, "events.jsonl");
+  const headFile = join(dir, "head.json");
+  const metaFile = join(dir, "meta.json");
+
+  function ensureDir() {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeJsonAtomic(metaFile, { projectId, label, createdAt: now() });
+    }
+  }
+
+  /** Validated, parsed events (only call after verify() says ok). */
+  function events() {
+    return readLines(file).map((l) => JSON.parse(l));
+  }
+
+  function verify() {
+    const lines = readLines(file);
+    const res = verifyLines(lines, projectId);
+    if (!res.ok) return res;
+    // The chain alone cannot see the tail being cut off; head.json can.
+    const head = readJson(headFile);
+    if (lines.length === 0) {
+      if (head && head.count > 0) return { ok: false, count: 0, brokenAt: 1, reason: `log is empty but head.json records ${head.count} events (lines deleted)` };
+      return res;
+    }
+    if (!head || !Number.isInteger(head.count) || head.count < 1 || typeof head.hash !== "string") {
+      return { ok: false, count: lines.length, brokenAt: lines.length, reason: "head.json missing or malformed" };
+    }
+    if (head.count > lines.length) {
+      return { ok: false, count: lines.length, brokenAt: lines.length + 1, reason: `head.json records ${head.count} events, log has ${lines.length} (lines deleted from the end)` };
+    }
+    const atHead = JSON.parse(lines[head.count - 1]).hash;
+    if (atHead !== head.hash) {
+      return { ok: false, count: lines.length, brokenAt: head.count, reason: "head.json hash does not match the log (log rewritten)" };
+    }
+    return { ...res, headStale: head.count < lines.length };
+  }
+
+  /**
+   * Append one event. `event` is { type, data, ts? }. Returns the stored line
+   * object. Refuses unknown types, non-plain data, and oversized lines.
+   */
+  function append(event) {
+    const type = event?.type;
+    if (!EVENT_TYPES.includes(type)) throw new Error(`memory: unknown event type "${type}"`);
+    const data = event.data ?? {};
+    if (!isPlainObject(data)) throw new Error("memory: event data must be a plain object");
+    const ts = typeof event.ts === "string" ? event.ts : now();
+    canonicalJson(data); // throws on anything that is not plain JSON
+    ensureDir();
+    return withLock(dir, () => {
+      const lines = readLines(file);
+      const prev = lines.length ? JSON.parse(lines[lines.length - 1]).hash : genesisHash(projectId);
+      const body = { v: EVENT_VERSION, ts, type, data };
+      const rec = { ...body, prev, hash: hashEvent(prev, body) };
+      const line = JSON.stringify(rec) + "\n";
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) throw new Error("memory: event too large");
+      const fd = openSync(file, FS.O_CREAT | FS.O_APPEND | FS.O_WRONLY, 0o600);
+      try { writeSync(fd, line); } finally { closeSync(fd); }
+      writeJsonAtomic(headFile, { count: lines.length + 1, hash: rec.hash });
+      return rec;
+    });
+  }
+
+  function meta() {
+    return readJson(metaFile);
+  }
+
+  /** Delete this project's memory. */
+  function forget() {
+    const existed = existsSync(dir);
+    rmSync(dir, { recursive: true, force: true });
+    return existed;
+  }
+
+  return { projectId, dir, file, append, verify, events, meta, forget, exists: () => existsSync(file) };
+}
+
+/** Delete every project's memory under the root. */
+export function forgetAll({ root = memoryRoot() } = {}) {
+  const existed = existsSync(root);
+  // Only ever remove the memory/ directory itself, never its parent.
+  if (dirname(root) === root) throw new Error("refusing to remove a filesystem root");
+  rmSync(root, { recursive: true, force: true });
+  return existed;
+}

package/lib/memory/views.js

@@ -0,0 +1,198 @@
+/**
+ * Read-only views over memory events, plus the two pure helpers scans use:
+ * rankFindings() re-orders, isSuppressed() hides. Neither can add a finding,
+ * change a severity, or run anything: memory content is only ever compared and
+ * counted. Every field read from an event is type-checked, so a malformed or
+ * hostile event degrades to "ignored", never to behaviour.
+ */
+import { fingerprintFinding } from "../audit-loop.js";
+import { sha256 } from "./store.js";
+
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+const MAX_STR = 500;
+
+/** Short, stable id for a finding: sha256 of the audit-loop fingerprint. */
+export function findingId(f) {
+  return sha256(fingerprintFinding(f)).slice(0, 16);
+}
+
+const str = (x) => (typeof x === "string" && x.length > 0 && x.length <= MAX_STR ? x : null);
+const int = (x) => (Number.isInteger(x) && x >= 0 ? x : null);
+const time = (x) => { const t = Date.parse(x); return Number.isNaN(t) ? null : t; };
+const key = (x) => (str(x) ? x.toLowerCase() : "unknown");
+
+function median(nums) {
+  if (!nums.length) return null;
+  const s = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+/**
+ * Build the views from a verified event list.
+ * @param {object[]} events  parsed events from openMemory().events()
+ * @param {{ now?: string }} opts  `now` decides which suppressions have expired
+ */
+export function buildViews(events, { now = new Date().toISOString() } = {}) {
+  const nowMs = time(now) ?? Date.now();
+  const recipes = new Map();      // `${framework}\0${recipe}` -> stats
+  const lastApplied = new Map();  // finding id -> { recipe, framework, category, ts }
+  const firstSeen = new Map();    // finding id -> ms
+  const seenCount = new Map();    // finding id -> scans it appeared in
+  const fixDurations = [];
+  const suppressions = new Map(); // finding id -> latest suppression
+  const probes = new Map();       // `${stack}\0${probe}` -> stats
+  let scans = 0;
+
+  const recipeStats = (framework, recipe) => {
+    const k = `${framework}\0${recipe}`;
+    if (!recipes.has(k)) recipes.set(k, { framework, recipe, applied: 0, verified: 0, failed: 0, categories: new Set() });
+    return recipes.get(k);
+  };
+
+  for (const ev of events || []) {
+    const d = ev?.data;
+    if (!d || typeof d !== "object") continue;
+    const ts = time(ev.ts);
+    switch (ev.type) {
+      case "scan": {
+        scans++;
+        const ids = Array.isArray(d.ids) ? d.ids.filter(str) : [];
+        for (const id of ids) {
+          if (!firstSeen.has(id) && ts != null) firstSeen.set(id, ts);
+          seenCount.set(id, (seenCount.get(id) || 0) + 1);
+        }
+        break;
+      }
+      case "fix_applied": {
+        const id = str(d.id) || str(d.fingerprint);
+        const recipe = str(d.recipe);
+        if (!recipe) break;
+        const framework = key(d.framework);
+        const s = recipeStats(framework, recipe);
+        s.applied++;
+        if (str(d.category)) s.categories.add(d.category);
+        if (id) lastApplied.set(id, { recipe, framework, category: str(d.category), ts });
+        break;
+      }
+      case "fix_verified":
+      case "fix_failed": {
+        const id = str(d.id) || str(d.fingerprint);
+        const prior = id ? lastApplied.get(id) : null;
+        const recipe = str(d.recipe) || prior?.recipe;
+        if (!recipe) break;
+        const framework = str(d.framework) ? key(d.framework) : (prior?.framework || "unknown");
+        const s = recipeStats(framework, recipe);
+        if (ev.type === "fix_verified") {
+          s.verified++;
+          if (id && ts != null && firstSeen.has(id)) fixDurations.push(Math.max(0, ts - firstSeen.get(id)));
+        } else {
+          s.failed++;
+        }
+        break;
+      }
+      case "fp_suppressed": {
+        const id = str(d.id) || (str(d.fingerprint) ? sha256(d.fingerprint).slice(0, 16) : null);
+        const reason = str(d.reason);
+        if (!id || !reason) break; // a suppression without a reason is ignored
+        const expires = str(d.expires);
+        if (expires && (time(expires) == null || time(expires) <= nowMs)) { suppressions.delete(id); break; }
+        suppressions.set(id, {
+          id, reason, actor: str(d.actor) || "unknown", since: ev.ts, expires: expires || null, source: "memory",
+        });
+        break;
+      }
+      case "probe_yield": {
+        const probe = str(d.probe);
+        const findings = int(d.findings);
+        if (!probe || findings == null) break;
+        const stack = key(d.stack);
+        const k = `${stack}\0${probe}`;
+        if (!probes.has(k)) probes.set(k, { stack, probe, runs: 0, findings: 0 });
+        const p = probes.get(k);
+        p.runs++;
+        p.findings += findings;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const recipeSuccess = [...recipes.values()].map((s) => {
+    const decided = s.verified + s.failed;
+    return {
+      framework: s.framework, recipe: s.recipe, applied: s.applied, verified: s.verified, failed: s.failed,
+      rate: decided ? s.verified / decided : null, categories: [...s.categories].sort(),
+    };
+  }).sort((a, b) => a.framework.localeCompare(b.framework) || (b.rate ?? -1) - (a.rate ?? -1) || a.recipe.localeCompare(b.recipe));
+
+  const probeRanking = {};
+  for (const p of probes.values()) {
+    (probeRanking[p.stack] ||= []).push({ probe: p.probe, runs: p.runs, findings: p.findings, yield: p.findings / p.runs });
+  }
+  for (const list of Object.values(probeRanking)) {
+    list.sort((a, b) => b.yield - a.yield || b.findings - a.findings || a.probe.localeCompare(b.probe));
+  }
+
+  const med = median(fixDurations);
+  return {
+    scans,
+    recipeSuccess,
+    suppressions: [...suppressions.values()],
+    probeRanking,
+    medianTimeToFixMs: med,
+    medianTimeToFixDays: med == null ? null : Math.round((med / 86_400_000) * 10) / 10,
+    seen: Object.fromEntries(seenCount),
+  };
+}
+
+/**
+ * Add repo-file suppressions to a views object. They keep their own source so
+ * reports can say "suppressed by repo file". A local-memory suppression for the
+ * same id wins (the user decided it, not the repo).
+ */
+export function withRepoSuppressions(views, repoEntries) {
+  const have = new Set((views?.suppressions || []).map((s) => s.id));
+  const extra = (repoEntries || []).filter((s) => !have.has(s.id)).map((s) => ({ ...s, source: "repo-file" }));
+  return { ...(views || {}), suppressions: [...(views?.suppressions || []), ...extra] };
+}
+
+/**
+ * Is this finding suppressed? Returns the suppression record or null.
+ * Matches on the finding's id (or its full fingerprint, for repo files).
+ */
+export function isSuppressed(finding, views) {
+  const list = views?.suppressions;
+  if (!list?.length) return null;
+  const fp = fingerprintFinding(finding);
+  const id = sha256(fp).slice(0, 16);
+  return list.find((s) => s.id === id || (s.fingerprint && s.fingerprint === fp)) || null;
+}
+
+/**
+ * Re-order findings using what memory learned. Severity always comes first and
+ * is never changed. Within a severity:
+ *   1. findings whose category has a recipe with a proven fix rate (quick wins),
+ *   2. findings seen in more past scans (persistent problems),
+ *   3. then the original order (the sort is stable).
+ * Returns a new array with exactly the same findings.
+ */
+export function rankFindings(findings, views, { framework = null } = {}) {
+  const fw = framework ? String(framework).toLowerCase() : null;
+  const bestRate = new Map(); // category -> best verified rate
+  for (const r of views?.recipeSuccess || []) {
+    if (r.rate == null || (fw && r.framework !== fw && r.framework !== "unknown")) continue;
+    for (const c of r.categories || []) bestRate.set(c, Math.max(bestRate.get(c) ?? 0, r.rate));
+  }
+  const seen = views?.seen || {};
+  return (findings || [])
+    .map((f, i) => ({
+      f, i,
+      sev: SEV_ORDER[f.severity] ?? 5,
+      fix: bestRate.get(f.category) ?? 0,
+      seen: seen[findingId(f)] || 0,
+    }))
+    .sort((a, b) => a.sev - b.sev || b.fix - a.fix || b.seen - a.seen || a.i - b.i)
+    .map((x) => x.f);
+}

package/lib/params.js

@@ -14,20 +14,12 @@
  * Inspired by: Arjun (6.2k stars), ParamSpider
  */
 
+import { fetchText } from "../src/utils/http.js";
+
 const PARAM_TIMEOUT = 8_000;
 
-async function safeFetch(url, opts = {}) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), opts.timeout || PARAM_TIMEOUT);
-  try {
-    const res = await fetch(url, { ...opts, signal: controller.signal, redirect: "manual" });
-    const body = await res.text().catch(() => "");
-    return { status: res.status, body, size: body.length, ok: true };
-  } catch {
-    return { status: 0, body: "", size: 0, ok: false };
-  } finally {
-    clearTimeout(timeout);
-  }
+function safeFetch(url, opts = {}) {
+  return fetchText(url, { timeout: PARAM_TIMEOUT, probe: "param-discovery", ...opts });
 }
 
 function simpleHash(str) {

package/lib/provenance.js

@@ -26,6 +26,7 @@ const SOURCE_CONFIDENCE = {
   "openapi-scan": "confirmed",
   "email-dns-probe": "confirmed",
   "framework-check": "likely",
+  "deps-scan": "likely",
   "static-analysis": "likely",
   "trust-boundary": "likely",
   "auth-probe": "likely",
@@ -59,6 +60,7 @@ const CATEGORY_CONFIDENCE = {
   ssrf: "likely",
   "open-redirect": "likely",
   fuzzing: "potential",
+  "dependency-risk": "likely",
 };
 
 /** Honest-confidence label for a finding. An explicit finding.confidence wins. */