penthera 1.8.0-rc.1 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-10-21
+
+1.8.0 is 1.8.0-rc.1 plus the changes below; there was no separate rc.2
+release. Highlights across both: fixes from a second independent security
+review, a fix loop that cannot edit the tests that judge it, the redesigned
+dashboard (Simple and Advanced mode), release checks on Linux, macOS and
+Windows, and now runtime advisories, starting with PHP's critical security
+release of 21 October 2026, in a new signed `advisories` rule pack (1.8.0-rc.1
+cannot load it). The benchmark gained two PHP cases: precision 0.88 (95% CI
+0.69 to 0.96) and recall 0.91 (0.73 to 0.98) on 24 scored findings.
+
+### Added
+
+- **Runtime advisories: is the PHP, Apache, nginx, Node.js, Python or OpenSSL
+  you run affected?** URL scans read `Server` and `X-Powered-By` banners, the
+  `PHPSESSID` cookie name and `.php` pages. Repo scans read Dockerfile and
+  compose images, `.tool-versions`, `.php-version`, `.nvmrc`,
+  `.python-version`, `runtime.txt` and `composer.json`. Each product and
+  version gets one answer: affected, end of life with no fix, check on server,
+  or has the fix (as advertised). A hidden version is never reported as safe.
+  A distribution build (`8.1.2-1ubuntu2.19`, or any version behind a `Server`
+  header that names a distribution) is never reported as affected, because
+  distributions backport fixes under the same version number. Advisories that
+  need more than a version (Windows, CGI) stay `potential`. See
+  [docs/runtime-advisories.md](docs/runtime-advisories.md).
+- **Two rule-pack kinds, `runtime-advisory` and `runtime-eol`**, so a new
+  advisory ships as a signed data pack (`--rules`) the same day, without a
+  release. End of life is judged by the pack's date, not the scan's clock.
+- **A bundled `advisories` pack** with the PHP security release of 21 October
+  2026 (CVE-2026-109618 and CVE-2026-109619, both Critical, CVSS 4.0 9.2,
+  fixed in 8.2.35, 8.3.36, 8.4.27 and 8.5.12, from the php-src advisories),
+  vendor-checked worked examples (CVE-2024-4577 and CVE-2024-8926 for PHP-CGI on Windows, CVE-2021-41773 and
+  CVE-2021-42013 for Apache HTTP Server 2.4.49 and 2.4.50) and end-of-life
+  release lines. Benchmark cases for both URL and repo scans.
+
+### Site
+
+- **A landing page in `site/`**, a static site for Vercel: the positioning,
+  `npx penthera`, prompts for Claude Code, Cursor and Codex, the hero loop and
+  the walkthrough, the limits and the research plan. No third-party scripts,
+  analytics or cookies; fonts are self-hosted or system fonts.
+- **A check in the browser.** Drop or paste a `package.json`, `.mcp.json`,
+  `.claude/settings.json`, `CLAUDE.md` or `AGENTS.md` and Penthera's own
+  `lib/` code runs in the tab: the agent-config rules, the secret patterns,
+  install scripts, typosquats against the vendored popular list, and the
+  bundled IOC pack. `site/build.mjs` bundles `lib/` at build time, so the site
+  and the CLI run the same rules; `tests/site.test.js` holds the page to the
+  CLI on the agents and deps fixtures. The page is served with
+  `connect-src 'none'`, so it cannot send the files anywhere.
+- **Runtime advisories in the browser check.** Drop a `Dockerfile`,
+  `compose.yaml`, `.php-version`, `.tool-versions` or `composer.json`, or
+  paste the response headers `curl -sI` printed for your site (the page never
+  contacts it), and `lib/advisories` runs on them: the same findings and
+  confidence as the CLI, with "check on the server: distributions backport
+  fixes" next to every version-only verdict. `tests/site.test.js` compares
+  pasted headers with a URL scan of a loopback server sending the same
+  headers, and runtime pins with `runtimeAdvisoriesForRepo`.
+- `penthera deps` findings are built in `lib/deps/findings.js` (moved from
+  `lib/deps/index.js`, no behaviour change), so the browser check uses the
+  same wording.
+- `scripts/docs-commands.mjs` also checks every command the site shows.
+
+### Docs
+
+- **New title for the launch:** "Penthera: your open-source cyber security
+  agent", in the README, docs index, `penthera --help`, the GitHub Action name
+  (which renames its Marketplace listing), the dashboard and the report
+  footer.
+
+- **README hero is a 12-second loop** of the terminal and the dashboard
+  (setup, an offline scan, Simple and Advanced mode, a fix approved), cut from
+  the walkthrough video by `scripts/media/hero-gif.sh`, and it loops without a
+  jump. The terminal-only scan clip is now `assets/demo-scan.gif`. The Demo
+  media workflow re-cuts the loop on every release.
+- **The README diagram is back**, updated: what Penthera checks, where the
+  findings go, and that the fix loop asks first and cannot edit its own tests.
+
 ## [1.8.0-rc.1] - 2026-10-20
 
 Release candidate for 1.8.0, published on npm's `next` dist-tag

package/README.md

@@ -1,10 +1,12 @@
 <div align="center">
 
-<img src="assets/penthera-social.jpg" alt="Penthera: Cyber Security Agent" width="840">
+<img src="assets/penthera-social.jpg" alt="Penthera: your open-source cyber security agent" width="840">
 
 <br/><br/>
 
-**Penthera: an open-source cyber security agent you can use today, and verify yourself.**
+**Penthera: your open-source cyber security agent**
+
+The security review you never had time for. Offline, rule-based, and you can verify every finding yourself.
 
 <br/>
 
@@ -16,7 +18,7 @@
 
 <br/>
 
-<img src="assets/demo.gif" alt="Penthera running an interactive security scan in the terminal" width="760">
+<img src="assets/demo.gif" alt="A 12-second loop: npx penthera sets up a project, an offline scan runs in the terminal, the dashboard shows the verdict in Simple mode and the triage matrix in Advanced mode, and a fix is approved" width="760">
 
 <br/><br/>
 
@@ -89,6 +91,29 @@ Penthera needs Node.js 22 or later. To run it in a container:
 
 ## What it does
 
+```mermaid
+flowchart LR
+    U["You or your AI agent"] --> P(("Penthera<br/>on your machine"))
+
+    P --> APP["Your app<br/>URL scan, repo scan"]
+    P --> DEP["Your dependencies<br/>capabilities, install firewall<br/>typosquats, upgrade diff"]
+    P --> AI["Your AI tooling<br/>skills, MCP, hooks<br/>plugins, rule files"]
+
+    APP --> F[["Findings<br/>severity, confidence<br/>evidence at file:line"]]
+    DEP --> F
+    AI --> F
+
+    F --> FIX["Fix loop<br/>asks first, local branch<br/>cannot edit its own tests"]
+    FIX -. "re-scan proves it" .-> F
+    F --> R["Reports and dashboard<br/>terminal, Markdown, SARIF<br/>penthera ui"]
+    F --> E["Evidence<br/>signed bundle<br/>NIS2 and CRA drafts"]
+
+    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff
+    classDef box fill:#ffffff,stroke:#000000,color:#000000
+    class P core
+    class U,APP,DEP,AI,F,FIX,R,E box
+```
+
 ### Before you deploy
 
 | Job | What Penthera does | Command |
@@ -127,7 +152,7 @@ Each feature goes through the same path: **method → evidence → tool.**
 - **Method.** The [methodology](docs/METHODOLOGY.md) states the threat model,
   what black-box (HTTP) and white-box (source) analysis can and cannot see, the
   confidence model, and the false-positive controls on each probe. Each design
-  choice cites the research or standard it rests on: 57 verified references, in
+  choice cites the research or standard it rests on: 92 verified references, in
   APA style, in [docs/references.md](docs/references.md).
 - **Evidence.** A benchmark runs on every release, and the release gate fails
   if precision or recall drops by more than 0.02. Experiments that decide what
@@ -138,17 +163,17 @@ Each feature goes through the same path: **method → evidence → tool.**
 
 | Measure | Result today |
 |---|---|
-| Precision on the bundled benchmark | 0.86, 95% CI 0.67 to 0.95 (19 true positives, 3 false positives) |
-| Recall on the bundled benchmark | 0.90, 95% CI 0.71 to 0.97 (2 misses, [each one explained](bench/RESULTS.md)) |
+| Precision on the bundled benchmark | 0.88, 95% CI 0.69 to 0.96 (21 true positives, 3 false positives) |
+| Recall on the bundled benchmark | 0.91, 95% CI 0.73 to 0.98 (2 misses, [each one explained](bench/RESULTS.md)) |
 | Requests to non-loopback hosts during the benchmark | 0 |
 | Detection rules, all readable | 14 URL scan templates, 20 secret and AI-key patterns, 15 dependency capabilities, 39 AI-tooling rules, 5 fix recipes |
 
-These numbers come from 22 findings in small labs that we wrote ourselves, so
+These numbers come from 24 findings in small labs that we wrote ourselves, so
 they catch regressions; they do not measure real-world accuracy. Measuring that
 on real projects is experiment E1, the first step of the
 [research plan](docs/vision-2.0.md). Intervals are Wilson. What Penthera cannot
 see is listed under [Known limitations](docs/METHODOLOGY.md#known-limitations).
-Counts as of 2026-10-20; refresh them with `npm run docs:numbers` and
+Counts as of 2026-10-21; refresh them with `npm run docs:numbers` and
 `npm run bench`.
 
 **Cite this repository** with the button on GitHub or
@@ -240,9 +265,9 @@ What changed, what we are measuring, and what comes next, in one place.
 
 | | Where it stands | Read more |
 |---|---|---|
-| **Latest release** | 1.7.0 (2026-10-19): one-command setup (`npx penthera`), the dashboard, signed rule packs | [CHANGELOG](CHANGELOG.md) |
-| **On main, unreleased** | Fixes from a second independent security review, a fix loop that cannot edit the tests that judge it, release checks on Linux, macOS and Windows, docs tested as code | [Unreleased](CHANGELOG.md#unreleased) |
-| **Now** | 1.8.0 feature freeze: fixes only, a release candidate on npm's `next` tag first | [Roadmap: now](ROADMAP.md#now-180-feature-freeze) |
+| **Latest release** | 1.8.0 (2026-10-21): runtime advisories starting with PHP's critical release, fixes from a second security review, a fix loop that cannot edit its own tests, the redesigned dashboard | [CHANGELOG](CHANGELOG.md) |
+| **On main, unreleased** | Whatever lands after 1.8.0 | [Unreleased](CHANGELOG.md#unreleased) |
+| **Now** | Toward 1.9: accuracy on real code (E1) and an MCP server, so coding agents can call Penthera | [Roadmap](ROADMAP.md#next) |
 | **Research** | E1, accuracy on real code, is pre-registered; the benchmark tooling is in review. After the 2026 agent incidents: a checklist for running agents safely and a draft experiment (E8) | [E1 pre-registration](docs/research/prereg/E1-real-world-accuracy.md), [agents safely](docs/agents-safely.md), [what the incidents mean](docs/research/agent-incidents-2026.md) |
 | **Next** | Real-world precision and recall with intervals, published whatever the result | [Roadmap: next](ROADMAP.md#next), [research plan](docs/vision-2.0.md) |
 

package/SECURITY.md

@@ -9,8 +9,8 @@ Security fixes land on the latest minor release only. Upgrade to get them.
 
 | Version | Supported |
 | ------- | --------- |
-| 1.7.x   | Yes       |
-| < 1.7   | No        |
+| 1.8.x   | Yes       |
+| < 1.8   | No        |
 
 ## Reporting a vulnerability
 

package/lib/advisories/evidence.js

@@ -0,0 +1,248 @@
+/**
+ * Evidence that a runtime or server is in use, and at which version.
+ *
+ * Black-box: what one HTTP response says about itself (Server, X-Powered-By,
+ * a PHPSESSID cookie, links to .php pages). White-box: what the repository
+ * pins (Dockerfile and compose images, .tool-versions, .php-version, .nvmrc,
+ * .python-version, runtime.txt, composer.json).
+ *
+ * Every item is `{ product, version, kind, where, raw, distro? }`:
+ *   version  the parsed version (lib/advisories/versions.js) or null
+ *   kind     "exact"   an upstream x.y.z
+ *            "branch"  only x.y (a floating Docker tag, `.python-version: 3.12`)
+ *            "distro"  a version with a distribution build string, or on a
+ *                      response whose Server header names a distribution
+ *            "present" the product is in use, the version is not visible
+ *   where    the header, cookie or file it came from
+ *   raw      the text it was read from (a header value, a line), for the report
+ *
+ * Nothing here decides whether anything is vulnerable; that is index.js.
+ */
+import { readdirSync, lstatSync, openSync, fstatSync, readSync, closeSync, constants } from "node:fs";
+import { join, relative, basename } from "node:path";
+import { PRODUCTS, DISTRO_HINT } from "./products.js";
+import { parseVersion } from "./versions.js";
+
+const clip = (s, n = 200) => (s.length > n ? `${s.slice(0, n)}…` : s);
+
+function kindOf(product, v, distro) {
+  if (!v) return "present";
+  if (v.patch !== null) return distro || v.suffix ? "distro" : "exact";
+  // "php:8" spans release lines; "php:8.3" and "node:20" name one.
+  return PRODUCTS[product].branchOf(v) ? "branch" : "present";
+}
+
+// ── Black-box ─────────────────────────────────────────────────────────────
+
+/**
+ * Evidence from one response's headers, cookies and page links.
+ * @param {{ headers?: Record<string,string>, cookieNames?: string[], phpLink?: string|null }} fp
+ *   what lib/crawler.js fingerprint() collected for the homepage
+ * @param {{ phpPaths?: string[] }} [more]  .php paths the endpoint discovery found reachable
+ */
+export function evidenceFromResponse(fp = {}, more = {}) {
+  const headers = fp.headers || {};
+  const out = [];
+  const server = String(headers.server || "");
+  const poweredBy = String(headers["x-powered-by"] || "");
+  const distro = DISTRO_HINT.test(server);
+
+  for (const [id, p] of Object.entries(PRODUCTS)) {
+    let found = false;
+    for (const [name, value] of [["server", server], ["x-powered-by", poweredBy]]) {
+      if (!value) continue;
+      const m = p.banner && p.banner.exec(value);
+      if (m) {
+        const v = parseVersion(m[1]);
+        if (v) {
+          out.push({ product: id, version: v, kind: kindOf(id, v, distro), where: `${name} header`, raw: clip(`${name}: ${value}`) });
+          found = true;
+          continue;
+        }
+      }
+      if (p.present && p.present.test(value)) {
+        out.push({ product: id, version: null, kind: "present", where: `${name} header`, raw: clip(`${name}: ${value}`) });
+        found = true;
+      }
+    }
+    if (id === "php" && !found) {
+      if ((fp.cookieNames || []).some((n) => n.toUpperCase() === "PHPSESSID")) {
+        out.push({ product: id, version: null, kind: "present", where: "Set-Cookie", raw: "PHPSESSID cookie (PHP's default session cookie name)" });
+        found = true;
+      }
+    }
+    if (id === "php" && !found) {
+      const link = fp.phpLink || (more.phpPaths || [])[0];
+      if (link) out.push({ product: id, version: null, kind: "present", where: fp.phpLink ? "homepage links" : "endpoint discovery", raw: clip(`.php page: ${link}`) });
+    }
+  }
+  return dedupe(out);
+}
+
+// ── White-box ─────────────────────────────────────────────────────────────
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", "coverage", "reports", "vendor",
+  "venv", ".venv", "site-packages", "__pycache__", ".tox", ".nox", ".obsidian",
+]);
+const MAX_DEPTH = 4;
+const MAX_FILE_BYTES = 256 * 1024;
+
+const isDockerfile = (n) => /^(?:Dockerfile|Containerfile)(?:\..+)?$/i.test(n) || /\.(?:dockerfile|containerfile)$/i.test(n);
+const isCompose = (n) => /^(?:docker-)?compose(?:\.[\w-]+)?\.ya?ml$/i.test(n);
+const VERSION_FILES = new Set(Object.values(PRODUCTS).flatMap((p) => p.versionFiles));
+const ROOT_ONLY = new Set([".tool-versions", "runtime.txt", "composer.json"]);
+
+function wanted(name, depth) {
+  if (isDockerfile(name) || isCompose(name) || VERSION_FILES.has(name)) return true;
+  return depth === 0 && ROOT_ONLY.has(name);
+}
+
+function readSmall(path) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK || 0) | (constants.O_NOFOLLOW || 0));
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > MAX_FILE_BYTES) return null;
+    const buf = Buffer.alloc(st.size);
+    const n = st.size ? readSync(fd, buf, 0, st.size, 0) : 0;
+    return buf.subarray(0, n).toString("utf-8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function walk(dir, depth, files) {
+  if (depth > MAX_DEPTH) return;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const full = join(dir, e.name);
+    if (e.isFile()) {
+      if (wanted(e.name, depth)) files.push({ full, depth });
+      continue;
+    }
+    if (!e.isDirectory()) continue;
+    // Not a symlinked folder, and not a nested repo or worktree.
+    let st;
+    try { st = lstatSync(full); } catch { continue; }
+    if (!st.isDirectory()) continue;
+    try { lstatSync(join(full, ".git")); continue; } catch { /* no nested .git */ }
+    walk(full, depth + 1, files);
+  }
+}
+
+const imageProduct = new Map(Object.entries(PRODUCTS).flatMap(([id, p]) => p.dockerImages.map((img) => [img, id])));
+
+/**
+ * `php:8.3.12-fpm-alpine`, `docker.io/library/node:20`, `python@sha256:…`.
+ * Official images are upstream builds, so a variant after the version
+ * (`-fpm-alpine`, `-slim-bookworm`) is not a distro build string.
+ */
+export function parseImageRef(ref) {
+  const noDigest = ref.split("@")[0];
+  const slash = noDigest.lastIndexOf("/");
+  const colon = noDigest.indexOf(":", slash + 1);
+  const repo = colon === -1 ? noDigest : noDigest.slice(0, colon);
+  const tag = colon === -1 ? "" : noDigest.slice(colon + 1);
+  const path = repo.toLowerCase().replace(/^(?:docker\.io\/)?(?:library\/)?/, "");
+  const product = imageProduct.get(path);
+  if (!product) return null;
+  const m = /^(\d+(?:\.\d+){0,2})(?:$|-)/.exec(tag);
+  const v = m ? parseVersion(m[1]) : null;
+  return { product, version: v, kind: kindOf(product, v, false), tag: tag || "latest" };
+}
+
+function fromDockerfile(text, where) {
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)/i.exec(line);
+    if (!m || m[1].includes("$")) continue;
+    const img = parseImageRef(m[1]);
+    if (img) out.push({ product: img.product, version: img.version, kind: img.kind, where, raw: clip(line.trim()) });
+  }
+  return out;
+}
+
+function fromCompose(text, where) {
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*image:\s*["']?([^\s"'#]+)/.exec(line);
+    if (!m || m[1].includes("$")) continue;
+    const img = parseImageRef(m[1]);
+    if (img) out.push({ product: img.product, version: img.version, kind: img.kind, where, raw: clip(line.trim()) });
+  }
+  return out;
+}
+
+function versionLine(product, value, where, raw) {
+  const v = parseVersion(value);
+  return { product, version: v, kind: kindOf(product, v, false), where, raw: clip(raw) };
+}
+
+function fromToolVersions(text, where) {
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const [tool, value] = line.trim().split(/\s+/);
+    if (!tool || !value || tool.startsWith("#")) continue;
+    const id = Object.keys(PRODUCTS).find((k) => PRODUCTS[k].toolVersions.includes(tool));
+    if (id) out.push(versionLine(id, value, where, line.trim()));
+  }
+  return out;
+}
+
+function fromVersionFile(name, text, where) {
+  const id = Object.keys(PRODUCTS).find((k) => PRODUCTS[k].versionFiles.includes(name));
+  const value = text.split(/\r?\n/).map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
+  if (!id || !value) return [];
+  return [versionLine(id, value, where, `${name}: ${value}`)];
+}
+
+function fromComposer(text, where) {
+  let j;
+  try { j = JSON.parse(text); } catch { return []; }
+  if (!j || typeof j !== "object") return [];
+  // `require.php` is a constraint and `config.platform.php` a version Composer
+  // pretends to have while resolving; neither is the PHP that runs. Both only
+  // say PHP is in use.
+  const constraint = typeof j.require?.php === "string" ? ` (require.php: ${clip(j.require.php, 60)})` : "";
+  return [{ product: "php", version: null, kind: "present", where, raw: `composer.json${constraint}` }];
+}
+
+/**
+ * Evidence from a repository's pins.
+ * @param {string} root
+ */
+export function evidenceFromRepo(root) {
+  const files = [];
+  walk(root, 0, files);
+  const out = [];
+  for (const { full } of files) {
+    const text = readSmall(full);
+    if (text === null) continue;
+    const name = basename(full);
+    const where = relative(root, full).split("\\").join("/");
+    if (isDockerfile(name)) out.push(...fromDockerfile(text, where));
+    else if (isCompose(name)) out.push(...fromCompose(text, where));
+    else if (name === ".tool-versions") out.push(...fromToolVersions(text, where));
+    else if (name === "runtime.txt") {
+      const m = /^\s*python-(\d+\.\d+(?:\.\d+)?)\s*$/m.exec(text);
+      if (m) out.push(versionLine("python", m[1], where, `runtime.txt: python-${m[1]}`));
+    } else if (name === "composer.json") out.push(...fromComposer(text, where));
+    else out.push(...fromVersionFile(name, text, where));
+  }
+  return dedupe(out);
+}
+
+function dedupe(items) {
+  const seen = new Set();
+  return items.filter((e) => {
+    const k = `${e.product}|${e.version?.raw ?? ""}|${e.kind}|${e.where}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}

package/lib/advisories/index.js

@@ -0,0 +1,228 @@
+/**
+ * Runtime advisories: is the PHP, nginx, Apache, Node.js, Python or OpenSSL
+ * this app runs affected by a published security advisory?
+ *
+ * Evidence (./evidence.js) says which product and, if visible, which version.
+ * Rule packs say which versions each advisory affects (`runtime-advisory`) and
+ * which release lines are past end of support (`runtime-eol`). This module
+ * compares the two and never claims more than the evidence carries:
+ *
+ *   exact upstream version, below the fix      affected          adv. severity, likely
+ *   exact version on an end-of-life line       unsupported       adv. severity, potential
+ *   version hidden, a floating tag, a distro
+ *     build below the fix, a line the advisory
+ *     does not list                            check on server   medium, needs-human-review
+ *   exact version at or above every fix        patched           info
+ *   no evidence of the product                 nothing           (absence is not "safe")
+ *
+ * A distro build (8.1.2-1ubuntu2.19, or any version behind a Server header
+ * that names a distribution) is never "affected": distributions backport fixes
+ * without changing the upstream number. An advisory with a `condition` (an OS,
+ * a SAPI, a module) gives at most `potential`, since neither a banner nor a pin
+ * shows the condition. Matching uses only the pack's data and dates, never the
+ * scan's clock, so the same input and packs give the same findings.
+ */
+import { rulesOf } from "../rules/index.js";
+import { PRODUCTS } from "./products.js";
+import { compareVersions, compareBranches } from "./versions.js";
+import { evidenceFromResponse, evidenceFromRepo } from "./evidence.js";
+
+export { evidenceFromResponse, evidenceFromRepo };
+
+const SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+const bySeverity = (a, b) => SEV_RANK[a.severity] - SEV_RANK[b.severity] || a.id.localeCompare(b.id);
+
+function ids(adv) {
+  const list = [...adv.cves, ...adv.ghsa];
+  return list.length ? list.join(", ") : adv.id;
+}
+
+function advLine(adv) {
+  const cvss = adv.cvss ? `, CVSS ${adv.cvss.version} ${adv.cvss.score}` : "";
+  return `${adv.title} (${ids(adv)}${cvss}; ${adv.source})`;
+}
+
+/** End-of-life record for `branch`, if the pack says it had ended by the rule's own date. */
+function eolOf(eolRules, product, branch) {
+  if (!branch) return null;
+  for (const r of eolRules) {
+    if (r.product !== product) continue;
+    const b = r.branches.find((x) => x.branch === branch);
+    if (b && b.eol <= r.date) return { ...b, rule: r };
+  }
+  return null;
+}
+
+/** Merge evidence of the same product, version and kind seen in several places. */
+function group(evidence) {
+  const groups = new Map();
+  for (const e of evidence) {
+    const key = `${e.product}|${e.version?.raw ?? ""}|${e.kind}`;
+    if (!groups.has(key)) groups.set(key, { ...e, wheres: [], raws: [] });
+    const g = groups.get(key);
+    if (!g.wheres.includes(e.where)) g.wheres.push(e.where);
+    if (!g.raws.includes(e.raw)) g.raws.push(e.raw);
+  }
+  return [...groups.values()];
+}
+
+/**
+ * Verdict of one advisory for one evidence group.
+ * @returns {{ verdict: "affected"|"unsupported"|"check"|"patched"|"none", fix?: object, why?: string }}
+ */
+export function verdictFor(adv, ev, eol) {
+  const p = PRODUCTS[ev.product];
+  const branch = ev.version ? p.branchOf(ev.version) : null;
+  const fix = branch ? adv.fixed.find((f) => f.branch === branch) : null;
+  const newest = adv.fixed.map((f) => f.branch).sort(compareBranches).at(-1);
+  const newerLine = branch && !fix && newest && compareBranches(branch, newest) > 0;
+
+  if (ev.kind === "present") return { verdict: "check", why: "the version is not visible" };
+  if (newerLine) return { verdict: "none" };
+
+  if (ev.kind === "branch") {
+    if (!fix && eol) return { verdict: "unsupported", why: `release line ${branch} is end of life` };
+    return { verdict: "check", fix, why: fix ? `only the release line (${branch}) is pinned, not the exact version` : `the advisory lists no fix for release line ${branch}` };
+  }
+
+  // exact or distro: the upstream version is known.
+  if (fix) {
+    if (fix.introduced && compareVersions(ev.version, fix.introduced) < 0) return { verdict: "none" };
+    if (compareVersions(ev.version, fix.version) >= 0) return { verdict: "patched", fix };
+    if (ev.kind === "distro") return { verdict: "check", fix, why: "it is a distribution build, which may carry the fix as a backport under the same upstream version" };
+    return { verdict: "affected", fix };
+  }
+  if (ev.kind === "distro") return { verdict: "check", why: `release line ${branch} has no upstream fix, but distributions support some lines longer` };
+  if (eol) return { verdict: "unsupported", why: `release line ${branch} is end of life` };
+  return { verdict: "check", why: `the advisory lists no fix for release line ${branch}` };
+}
+
+function evidenceText(ev) {
+  return ev.raws.map((r) => `- ${r}`).join("\n");
+}
+
+/**
+ * Findings for a set of evidence.
+ * @param {object[]} evidence  from evidenceFromResponse() or evidenceFromRepo()
+ * @param {{ advisories?: object[], eol?: object[], url?: string }} [opts]  rules (default: the
+ *   active packs); `url` is the scanned page, used as the finding location for black-box evidence
+ */
+export function matchRuntimeAdvisories(evidence, opts = {}) {
+  const advisories = opts.advisories || rulesOf("runtime-advisory");
+  const eolRules = opts.eol || rulesOf("runtime-eol");
+  const findings = [];
+
+  for (const ev of group(evidence)) {
+    const p = PRODUCTS[ev.product];
+    const label = ev.version ? `${p.name} ${ev.version.raw}` : p.name;
+    const branch = ev.version ? p.branchOf(ev.version) : null;
+    const eol = ev.kind === "present" ? null : eolOf(eolRules, ev.product, branch);
+    const url = opts.url || ev.wheres[0];
+    const base = { url, category: "runtime-advisory", source: "runtime-advisory", evidence: ev.raws.join("\n") };
+    const checks = [];
+    const patched = [];
+    const start = findings.length;
+
+    for (const adv of advisories.filter((a) => a.product === ev.product).sort(bySeverity)) {
+      const v = verdictFor(adv, ev, eol);
+      if (v.verdict === "affected") {
+        findings.push({
+          ...base,
+          severity: adv.severity,
+          confidence: adv.condition ? "potential" : "likely",
+          title: `${label} is affected by ${adv.title}`,
+          description: [
+            `${label} (seen in ${ev.wheres.join(", ")}) is below ${v.fix.version}, the first fixed version on the ${v.fix.branch} line, for ${advLine(adv)}.`,
+            adv.kev ? `CISA lists it as exploited in the wild (Known Exploited Vulnerabilities catalog, added ${adv.kev}).` : "",
+            adv.condition ? `It only applies when: ${adv.condition}. A version alone cannot show that, so confirm it on the server.` : "",
+            adv.description || "",
+            `Evidence:\n${evidenceText(ev)}`,
+          ].filter(Boolean).join("\n\n"),
+          remediation: `Upgrade ${p.name} to ${v.fix.version} or later on the ${v.fix.branch} line, or to a newer supported line. Then confirm with \`${p.checkCommand}\` on the server.`,
+          cves: adv.cves,
+          rule: adv.id,
+        });
+      } else if (v.verdict === "unsupported") {
+        findings.push({
+          ...base,
+          severity: adv.severity,
+          confidence: "potential",
+          title: `${label} is on an end-of-life line with no fix for ${adv.title}`,
+          description: [
+            `${label} (seen in ${ev.wheres.join(", ")}) is on release line ${branch}, which ${p.name} stopped supporting on ${eol.eol} (${eol.rule.source}). The advisory ${advLine(adv)} lists fixes only for ${adv.fixed.map((f) => f.branch).join(", ")}, so this line gets none. Whether the flaw exists on ${branch} is not stated; treat it as affected.`,
+            `Evidence:\n${evidenceText(ev)}`,
+          ].join("\n\n"),
+          remediation: `Move to a supported ${p.name} line (${adv.fixed.map((f) => `${f.branch}: ${f.version}+`).join(", ")}).`,
+          cves: adv.cves,
+          rule: adv.id,
+        });
+      } else if (v.verdict === "check") {
+        checks.push({ adv, ...v });
+      } else if (v.verdict === "patched") {
+        patched.push(adv);
+      }
+    }
+
+    if (checks.length) {
+      const why = [...new Set(checks.map((c) => c.why))].join("; ");
+      findings.push({
+        ...base,
+        severity: "medium",
+        confidence: "needs-human-review",
+        title: `${label} in use: check whether it is affected by ${checks.length === 1 ? checks[0].adv.title : `${checks.length} advisories`}`,
+        description: [
+          `Penthera cannot tell from outside whether ${label} has the fix: ${why}. That is not a sign it is safe.`,
+          `Advisories to check:\n${checks.map((c) => `- ${advLine(c.adv)}${c.fix ? `: fixed in ${c.fix.version} on ${c.fix.branch}` : ""}`).join("\n")}`,
+          `Evidence:\n${evidenceText(ev)}`,
+        ].join("\n\n"),
+        remediation: `Run \`${p.checkCommand}\` on the server (or in the container) and compare with the fixed versions above. For a distribution package, check the distribution's security tracker for the CVE instead of the upstream number.`,
+        cves: [...new Set(checks.flatMap((c) => c.adv.cves))],
+        rule: checks.map((c) => c.adv.id).join(","),
+      });
+    }
+
+    if (eol) {
+      const distro = ev.kind === "distro";
+      findings.push({
+        ...base,
+        severity: distro ? "medium" : "high",
+        confidence: distro ? "needs-human-review" : "likely",
+        title: distro
+          ? `${label} is a distribution build of an end-of-life ${p.name} line`
+          : `${label} is end of life: no more security fixes`,
+        description: [
+          `${p.name} ${branch} reached end of support on ${eol.eol} (${eol.rule.source}). Upstream publishes no security fixes for it, including for future advisories.`,
+          distro ? "This is a distribution build, and some distributions keep patching a line after upstream stops. Check your distribution's support period for this package." : "",
+          `Evidence:\n${evidenceText(ev)}`,
+        ].filter(Boolean).join("\n\n"),
+        remediation: `Upgrade to a supported ${p.name} release line.`,
+        rule: eol.rule.id,
+      });
+    }
+
+    // "Has the fix" only when nothing else about this version needs attention.
+    if (patched.length && findings.length === start) {
+      findings.push({
+        ...base,
+        severity: "info",
+        confidence: ev.kind === "exact" ? "likely" : "potential",
+        title: `${label} has the fix for ${patched.length === 1 ? patched[0].title : `${patched.length} known advisories`} (as advertised)`,
+        description: [
+          `The version ${ev.kind === "distro" ? "string" : "banner or pin"} is at or above the fixed version for: ${patched.map((a) => ids(a)).join(", ")}. This is what ${ev.wheres.join(", ")} says; a proxy or a stale banner can differ from what runs.`,
+          `Evidence:\n${evidenceText(ev)}`,
+        ].join("\n\n"),
+      });
+    }
+  }
+  return findings;
+}
+
+/** Black-box: runtime-advisory findings for a URL scan's homepage fingerprint. */
+export function runtimeAdvisoriesForResponse(fingerprint, opts = {}) {
+  return matchRuntimeAdvisories(evidenceFromResponse(fingerprint || {}, { phpPaths: opts.phpPaths }), opts);
+}
+
+/** White-box: runtime-advisory findings for a repository's runtime pins. */
+export function runtimeAdvisoriesForRepo(root, opts) {
+  return matchRuntimeAdvisories(evidenceFromRepo(root), opts);
+}