penthera 1.7.0 → 1.8.0

package/SECURITY.md

@@ -1,13 +1,16 @@
 # Security Policy
 
+> **Starter and pro.** For "I found a vulnerability in Penthera itself: how do I
+> report it?"
+
 ## Supported versions
 
 Security fixes land on the latest minor release only. Upgrade to get them.
 
 | Version | Supported |
 | ------- | --------- |
-| 1.2.x   | Yes       |
-| < 1.2   | No        |
+| 1.8.x   | Yes       |
+| < 1.8   | No        |
 
 ## Reporting a vulnerability
 
@@ -21,7 +24,7 @@ scanning a target), please report it privately:
 
 Please do **not** open public issues for undisclosed vulnerabilities.
 
-**What to expect.** Penthera is maintained part-time, but security reports come
+**What to expect.** Penthera is maintained part-time, and security reports come
 first:
 
 - Acknowledgement within 3 working days.
@@ -48,6 +51,5 @@ XSS, command injection, API fuzzing).
 
 **Only scan systems you own or have explicit written permission to test.**
 Unauthorized scanning may be illegal in your jurisdiction. Penthera is built for
-defensive research and hardening your own applications — see the full
-[ethical-use policy](README.md#ethical-use--authorization) and
-[disclaimer](README.md#disclaimer) in the README.
+defensive research and hardening your own applications. See
+[Ethics and authorization](README.md#ethics-and-authorization) in the README.

package/docs/examples/pr-dependency-review.yml

@@ -50,7 +50,7 @@ jobs:
           (cd "$RUNNER_TEMP/base" && npm ci --ignore-scripts --no-audit --no-fund)
           npm ci --ignore-scripts --no-audit --no-fund
 
-      - uses: danoszz/penthera@0000000000000000000000000000000000000000 # v1.4.0 (replace with the release commit SHA)
+      - uses: danoszz/penthera@525895575f4a9bebe911707a43804a934eac0c4a # v1.6.1 (or a later release commit SHA)
         with:
           mode: deps
           fail-on: none # or high / critical to block the merge

package/lib/adaptive-probes.js

@@ -8,7 +8,7 @@
  * Results feed into the SecurityKnowledgeGraph for chain discovery.
  */
 
-import { request } from "../src/utils/http.js";
+import { request, readBody } from "../src/utils/http.js";
 
 const DEFAULT_TIMEOUT = 10_000;
 
@@ -26,9 +26,9 @@ async function probe(base, path, opts = {}) {
     let body = null;
     const ct = res.headers.get("content-type") || "";
     if (ct.includes("json")) {
-      try { body = await res.json(); } catch { body = null; }
+      try { body = JSON.parse(await readBody(res)); } catch { body = null; }
     } else {
-      try { body = await res.text(); } catch { body = null; }
+      try { body = await readBody(res); } catch { body = null; }
     }
     return {
       url: path, status: res.status,

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);
+}

package/lib/advisories/products.js

@@ -0,0 +1,83 @@
+/**
+ * The runtimes and servers runtime advisories can name, and how to recognize
+ * each one. Detection is code; which versions are affected is data, in signed
+ * rule packs (kind `runtime-advisory`, see lib/rules/pack.js).
+ */
+
+// Release line ("branch") of a version: the unit a vendor patches and ends
+// support for. Null when the version is too coarse to name one.
+const minorLine = (v) => (v.minor === null ? null : `${v.major}.${v.minor}`);
+
+export const PRODUCTS = Object.freeze({
+  php: {
+    branchOf: minorLine,
+    name: "PHP",
+    // On the server itself, the version and any distro build string.
+    checkCommand: "php -v",
+    banner: /\bPHP\/(\d+\.\d+(?:\.\d+)?[^\s,;()]*)/i,
+    // X-Powered-By: PHP, with the version stripped
+    present: /\bPHP\b/i,
+    dockerImages: ["php"],
+    toolVersions: ["php"],
+    versionFiles: [".php-version"],
+  },
+  "apache-httpd": {
+    branchOf: minorLine,
+    name: "Apache HTTP Server",
+    checkCommand: "httpd -v (or apache2 -v)",
+    banner: /\bApache\/(\d+\.\d+\.\d+[^\s,;()]*)/,
+    // not Apache-Coyote (Tomcat) or Apache-HttpClient
+    present: /^Apache(?![-\w])/,
+    dockerImages: ["httpd"],
+    toolVersions: [],
+    versionFiles: [],
+  },
+  nginx: {
+    branchOf: minorLine,
+    name: "nginx",
+    checkCommand: "nginx -v",
+    banner: /\bnginx\/(\d+\.\d+\.\d+[^\s,;()]*)/i,
+    present: /^nginx\b/i,
+    dockerImages: ["nginx"],
+    toolVersions: [],
+    versionFiles: [],
+  },
+  nodejs: {
+    branchOf: (v) => String(v.major),
+    name: "Node.js",
+    checkCommand: "node -v",
+    banner: null,
+    present: null,
+    dockerImages: ["node"],
+    toolVersions: ["nodejs", "node"],
+    versionFiles: [".nvmrc", ".node-version"],
+  },
+  python: {
+    branchOf: minorLine,
+    name: "Python",
+    checkCommand: "python3 --version",
+    // Werkzeug and http.server print "Python/3.12.1" in Server
+    banner: /\bPython\/(\d+\.\d+\.\d+[^\s,;()]*)/,
+    present: null,
+    dockerImages: ["python"],
+    toolVersions: ["python"],
+    versionFiles: [".python-version"],
+  },
+  openssl: {
+    branchOf: (v) => (v.major >= 3 ? minorLine(v) : v.patch === null ? null : `${v.major}.${v.minor}.${v.patch}`),
+    name: "OpenSSL",
+    checkCommand: "openssl version",
+    banner: /\bOpenSSL\/(\d+\.\d+\.\d+[a-z]{0,2}[^\s,;()]*)/,
+    present: null,
+    dockerImages: [],
+    toolVersions: [],
+    versionFiles: [],
+  },
+});
+
+export const PRODUCT_IDS = Object.freeze(Object.keys(PRODUCTS));
+
+// A Server banner that names a distribution: its packages carry backported
+// fixes under the upstream version number (Red Hat even prints no suffix), so
+// every version on that response is treated as a distro build.
+export const DISTRO_HINT = /\b(Debian|Ubuntu|Raspbian|CentOS|Red Hat|RHEL|AlmaLinux|Rocky|Oracle Linux|Amazon Linux|Fedora|SUSE|openSUSE|Alpine)\b/i;