phpwarden 2.0.0__py3-none-any.whl

phpwarden/report.py

@@ -0,0 +1,206 @@
+"""Fleet dashboard — aggregate per-host JSON results into one HTML report.
+
+Reads the JSON emitted by `scan`, `deps` and `wordpress` (any mix), normalises
+every finding into one row, and renders a self-contained HTML page: summary
+tiles plus a severity-sorted table. This is the CNAPP bridge — a fleet-wide
+view of PHP exposure over time — not a cloud platform.
+"""
+from __future__ import annotations
+
+import html
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+_SEV_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "unknown": 4}
+
+
+@dataclass
+class Row:
+    host: str
+    source: str
+    ident: str
+    severity: str
+    cvss: float
+    status: str
+    title: str
+    fixed: str
+    wild: bool
+    epss: float = None
+    reach: str = ""
+
+
+def _rows_from_doc(host: str, doc: dict) -> List[Row]:
+    """One Row per finding. Every numeric field goes through `_num` / `_fnum`
+    and `fixed` through `_fixed`, for ALL three document types: a `cvss: null`,
+    a string epss or a null fixed list in any one finding must never raise."""
+    rows = []
+    # scan output
+    if "findings" in doc and "summary" in doc:
+        for f in doc["findings"]:
+            rows.append(Row(host, "engine", str(f["cve"]), _sev(f.get("severity")),
+                            _num(f.get("cvss")), str(f.get("verdict") or ""),
+                            str(f.get("title") or ""), _fixed(f.get("fixed")),
+                            bool(f.get("exploited_in_wild")), _fnum(f.get("epss"))))
+    # deps output
+    if "vulnerable" in doc:
+        for f in doc["vulnerable"]:
+            rows.append(Row(host, "composer", f"{f['package']} {f.get('installed', '')} / {f['cve']}",
+                            _sev(f.get("severity")), _num(f.get("cvss")), "EXPOSED",
+                            str(f.get("title") or ""), _fixed(f.get("fixed")),
+                            bool(f.get("known_exploited")), _fnum(f.get("epss")),
+                            str(f.get("reach") or "")))
+    # wordpress output
+    if "wordpress" in doc and "findings" in doc:
+        for f in doc["findings"]:
+            if "slug" in f:
+                rows.append(Row(host, f"wp-{f.get('kind') or '?'}",
+                                f"{f['slug']} {f.get('version') or ''} / {f['cve']}",
+                                _sev(f.get("severity")), _num(f.get("cvss")), "EXPOSED",
+                                str(f.get("title") or ""), _fixed(f.get("fixed")),
+                                bool(f.get("known_exploited")), _fnum(f.get("epss"))))
+    return rows
+
+
+_HOST_SUFFIX = re.compile(r"[-_.](deps|scan|wp|wordpress|detect)$", re.I)
+
+
+def _num(v, default=0.0) -> float:
+    """cvss as a float; None / "" / junk -> default (one bad field must not
+    take the whole file out of the report)."""
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def _fnum(v):
+    """epss as float or None."""
+    try:
+        return None if v in (None, "") else float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _sev(v) -> str:
+    """severity as a lowercase label; None / "" -> "unknown"."""
+    return str(v).lower() if v else "unknown"
+
+
+def _fixed(v) -> str:
+    """fixed-in versions as one display string: a list (deps/wp), a bare string
+    (scan), or None / junk -> "-"."""
+    if isinstance(v, (list, tuple)):
+        return ", ".join(str(x) for x in v if x) or "-"
+    return str(v) if v else "-"
+
+
+def _host_of(doc, fp: Path) -> str:
+    """Host label: the doc's own `host`, else the file stem with a tool suffix
+    stripped so web1.json + web1-deps.json are ONE host, not two."""
+    h = doc.get("host") if isinstance(doc, dict) else None
+    return h or _HOST_SUFFIX.sub("", fp.stem)
+
+
+def load_rows(paths, warn=None) -> List[Row]:
+    """Rows from scan/deps/wordpress JSON files. Unreadable or wrong-shape inputs
+    are reported through `warn(msg)` (default: stderr) and skipped — never
+    silently, and never by crashing the whole report."""
+    import sys
+    warn = warn or (lambda m: sys.stderr.write(f"report: {m}\n"))
+    rows = []
+    for p in paths:
+        fp = Path(p)
+        try:
+            doc = json.loads(fp.read_text())
+        except OSError as e:
+            warn(f"skipping {p}: {e.strerror or e}")
+            continue
+        except ValueError:
+            warn(f"skipping {p}: not valid JSON")
+            continue
+        if not isinstance(doc, dict):
+            warn(f"skipping {p}: not a phpwarden result document")
+            continue
+        try:
+            rows.extend(_rows_from_doc(_host_of(doc, fp), doc))
+        except (KeyError, TypeError, ValueError, AttributeError) as e:
+            warn(f"skipping {p}: unexpected document shape ({e.__class__.__name__}: {e})")
+            continue
+    rows.sort(key=lambda r: (0 if r.wild else 1, -(r.epss or 0),
+                             _SEV_ORDER.get(r.severity, 9), -r.cvss))
+    return rows
+
+
+def render_html(rows: List[Row], feed_version: str = "") -> str:
+    hosts = sorted({r.host for r in rows})
+    crit = sum(1 for r in rows if r.severity == "critical")
+    high = sum(1 for r in rows if r.severity == "high")
+    wild = sum(1 for r in rows if r.wild)
+    sev_color = {"critical": "#dc2626", "high": "#ea580c", "medium": "#ca8a04",
+                 "low": "#65a30d", "unknown": "#6b7280"}
+
+    def esc(s):
+        return html.escape(str(s))
+
+    def risk_cell(r):
+        bits = []
+        if r.wild:
+            bits.append('<span class="kev">KEV</span>')
+        if r.epss is not None:
+            bits.append(f'{r.epss * 100:.0f}%')
+        return " ".join(bits) or "-"
+
+    trs = "\n".join(
+        f'<tr><td>{esc(r.host)}</td><td><span class="src">{esc(r.source)}</span></td>'
+        f'<td class="id">{esc(r.ident)}</td>'
+        f'<td><span class="sev" style="background:{sev_color.get(r.severity,"#6b7280")}">'
+        f'{esc(r.severity)}</span></td><td>{r.cvss:g}</td>'
+        f'<td class="risk">{risk_cell(r)}</td>'
+        f'<td>{esc(r.status)}</td>'
+        f'<td>{esc(r.title)}</td><td class="fix">{esc(r.fixed)}</td></tr>'
+        for r in rows)
+
+    return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>phpwarden fleet report</title>
+<style>
+:root {{ --bg:#ffffff; --fg:#111827; --muted:#6b7280; --card:#f3f4f6; --border:#e5e7eb; }}
+@media (prefers-color-scheme: dark) {{ :root:not([data-theme=light]) {{
+  --bg:#0b0f17; --fg:#e5e7eb; --muted:#9ca3af; --card:#111827; --border:#1f2937; }} }}
+* {{ box-sizing:border-box; }}
+body {{ margin:0; background:var(--bg); color:var(--fg);
+  font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; padding:24px 16px; }}
+.wrap {{ max-width:1040px; margin:0 auto; }}
+h1 {{ font-size:22px; margin:0 0 4px; }}
+.sub {{ color:var(--muted); margin:0 0 20px; font-size:13px; }}
+.tiles {{ display:flex; flex-wrap:wrap; gap:12px; margin-bottom:20px; }}
+.tile {{ background:var(--card); border:1px solid var(--border); border-radius:10px;
+  padding:14px 18px; min-width:120px; }}
+.tile b {{ display:block; font-size:26px; line-height:1.1; }}
+.tile span {{ color:var(--muted); font-size:12px; text-transform:uppercase; letter-spacing:.04em; }}
+table {{ width:100%; border-collapse:collapse; font-size:13px; }}
+th,td {{ text-align:left; padding:8px 10px; border-bottom:1px solid var(--border); vertical-align:top; }}
+th {{ color:var(--muted); font-weight:600; text-transform:uppercase; font-size:11px; letter-spacing:.04em; }}
+.id {{ font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }}
+.fix {{ font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; color:var(--muted); }}
+.src {{ background:var(--border); border-radius:5px; padding:1px 7px; font-size:11px; }}
+.sev {{ color:#fff; border-radius:5px; padding:1px 8px; font-size:11px; font-weight:600; }}
+.risk {{ font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; white-space:nowrap; }}
+.kev {{ background:#dc2626; color:#fff; border-radius:5px; padding:1px 6px; font-size:10px; font-weight:700; }}
+.empty {{ color:var(--muted); padding:30px 0; text-align:center; }}
+</style></head><body><div class="wrap">
+<h1>phpwarden fleet report</h1>
+<p class="sub">{len(rows)} findings across {len(hosts)} host(s){' · feed ' + esc(feed_version) if feed_version else ''}</p>
+<div class="tiles">
+  <div class="tile"><b>{len(rows)}</b><span>findings</span></div>
+  <div class="tile"><b style="color:{sev_color['critical']}">{crit}</b><span>critical</span></div>
+  <div class="tile"><b style="color:{sev_color['high']}">{high}</b><span>high</span></div>
+  <div class="tile"><b style="color:{sev_color['critical']}">{wild}</b><span>actively exploited (KEV)</span></div>
+  <div class="tile"><b>{len(hosts)}</b><span>hosts</span></div>
+</div>
+{"<table><thead><tr><th>Host</th><th>Source</th><th>Finding</th><th>Severity</th><th>CVSS</th><th>Risk</th><th>Status</th><th>Detail</th><th>Fixed in</th></tr></thead><tbody>" + trs + "</tbody></table>" if rows else '<div class="empty">No findings. Every host assessed is clear against the current feed.</div>'}
+</div></body></html>"""

phpwarden/rules.py

@@ -0,0 +1,152 @@
+"""Generate WAF blocking rules from the feed's request signatures.
+
+phpwarden does not replace an edge WAF; it supplies the PHP-specific rules a
+generic WAF lacks, in the formats real WAFs enforce (ModSecurity, nginx). The
+same signatures power `phpwarden detect` (observe) and these rules (block).
+"""
+from __future__ import annotations
+
+import re
+from typing import List
+
+from phpwarden.vulndb import Feed
+
+RULE_ID_BASE = 9100000
+
+
+def _request_sigs(feed: Feed):
+    """[(cve_id, pattern, note), ...] for request-signature detectors only."""
+    out, seen = [], set()
+    for cve in feed.cves:
+        for det in cve.detectors:
+            if det.get("kind") != "request-signature":
+                continue
+            for pat in det.get("patterns", []):
+                key = (cve.id, pat.lower())
+                if key not in seen:
+                    seen.add(key)
+                    out.append((cve.id, pat, det.get("note", "")))
+    return out
+
+
+def _modsec_lines(entries, rid_base=RULE_ID_BASE):
+    """entries: [(cve_id, pattern, note), ...] -> ModSecurity SecRule lines."""
+    out, rid = [], rid_base
+    for cve_id, pat, note in entries:
+        rx = re.escape(pat)
+        # (?i): @rx is case-sensitive and real probes use "%AD"/"%0A"; the
+        # signature list is de-duplicated case-insensitively, so without this
+        # the upper-case variants were simply never blocked.
+        # REQUEST_URI_RAW: ARGS/REQUEST_URI are URL-decoded by the engine, so a
+        # percent-encoded pattern can only ever match the raw URI.
+        safe_note = note.replace("'", "`").replace('"', "`")
+        out.append(
+            f'SecRule REQUEST_URI_RAW|REQUEST_URI|REQUEST_HEADERS:Content-Type|ARGS '
+            f'"@rx (?i){rx}" '
+            f'"id:{rid},phase:2,deny,status:403,'
+            f'msg:\'phpwarden: {cve_id} exploitation signature\','
+            f'logdata:\'{safe_note}\',tag:\'phpwarden\',tag:\'{cve_id}\'"')
+        rid += 1
+    return out
+
+
+def _nginx_lines(entries):
+    out = []
+    for cve_id, pat, note in entries:
+        rx = re.escape(pat)
+        out.append(f'# {cve_id}: {note}')
+        out.append(f'if ($request_uri ~* "{rx}") {{ return 403; }}')
+    return out
+
+
+def modsecurity(feed: Feed) -> str:
+    lines = [
+        "# phpwarden-generated ModSecurity rules — PHP exploitation signatures.",
+        f"# feed {feed.feed_version}. Place in your CRS custom rules; tune IDs to avoid clashes.",
+        "",
+    ]
+    lines += _modsec_lines(_request_sigs(feed))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def nginx(feed: Feed) -> str:
+    lines = [
+        "# phpwarden-generated nginx rules — PHP exploitation signatures.",
+        f"# feed {feed.feed_version}. Include inside the server/location that proxies to PHP-FPM.",
+        "",
+    ]
+    lines += _nginx_lines(_request_sigs(feed))
+    lines.append("")
+    return "\n".join(lines)
+
+
+FORMATS = {"modsecurity": modsecurity, "nginx": nginx}
+
+
+def generate(feed: Feed, fmt: str) -> str:
+    gen = FORMATS.get(fmt)
+    if not gen:
+        raise ValueError(f"unknown format {fmt!r}; choose from {', '.join(FORMATS)}")
+    return gen(feed)
+
+
+# --- per-CVE virtual patch ("shields-up") ---------------------------------- #
+# Contain a single CVE *before* you can upgrade. The blocking rule is built from
+# (1) the feed's authoritative request-signature for that CVE, and (2) patterns
+# we actually observed probing this host (the attack log) — so the shield blocks
+# exactly what is being thrown at you. When neither exists, we emit a runtime
+# guard policy that recycles a poisoned PHP-FPM worker for that CVE instead.
+
+def _cve_entries(feed: Feed, cve_id: str, observed=None):
+    """Blocking entries for one CVE: feed signatures + observed attack patterns."""
+    entries, seen = [], set()
+    for cid, pat, note in _request_sigs(feed):
+        if cid == cve_id and pat.lower() not in seen:
+            seen.add(pat.lower())
+            entries.append((cid, pat, note or "feed exploitation signature"))
+    for pat in (observed or []):
+        if pat and pat.lower() not in seen:
+            seen.add(pat.lower())
+            entries.append((cve_id, pat, "observed in your logs"))
+    return entries
+
+
+def guard_policy(cve_id: str) -> str:
+    """A phpwarden runtime-guard policy fragment that enforces (recycles a
+    poisoned PHP-FPM worker) for this CVE — the containment layer a WAF can't do."""
+    return (
+        "# phpwarden runtime guard — enforce containment for this CVE.\n"
+        "# Add to your guard config and run the guard in ENFORCE mode:\n"
+        "#   phpwarden-guard --config guard.json --mode ENFORCE\n"
+        "{\n"
+        '  "mode": "ENFORCE",\n'
+        f'  "enforce_cves": ["{cve_id}"],\n'
+        '  "action": "recycle_worker"\n'
+        "}\n"
+    )
+
+
+def virtual_patch(feed: Feed, cve_id: str, fmt: str = "nginx", observed=None) -> dict:
+    """Build a one-CVE virtual patch. Returns {text, has_waf, kind}."""
+    entries = _cve_entries(feed, cve_id, observed)
+    header = [
+        f"# phpwarden virtual patch — {cve_id}",
+        f"# feed {feed.feed_version}. Contain this CVE now; remove once you've upgraded.",
+        "",
+    ]
+    if entries:
+        body = _nginx_lines(entries) if fmt == "nginx" else _modsec_lines(entries)
+        where = ("Include inside the server/location that proxies to PHP-FPM."
+                 if fmt == "nginx" else "Place in your CRS custom rules; tune IDs to avoid clashes.")
+        text = "\n".join(header + [f"# {where}", ""] + body + ["",
+               "# Runtime containment (defense in depth):", ""] + guard_policy(cve_id).splitlines())
+        return {"text": text + "\n", "has_waf": True, "kind": fmt}
+    # no signature and nothing observed yet -> guard policy only
+    text = "\n".join(header + [
+        "# No request-signature is available for this CVE, and nothing matching it",
+        "# has been seen in your logs yet, so an edge WAF rule can't target it precisely.",
+        "# Contain it at runtime instead — the guard recycles a poisoned PHP-FPM worker:",
+        "",
+    ] + guard_policy(cve_id).splitlines())
+    return {"text": text + "\n", "has_waf": False, "kind": "guard"}

phpwarden/version.py

@@ -0,0 +1,110 @@
+"""PHP version parsing and branch-aware range matching.
+
+A PHP version is (major, minor, patch) plus an optional prerelease marker. The
+"branch" is (major, minor) — PHP backports security fixes per branch, so a CVE
+is expressed as a fixed patch level per branch, not a single global threshold.
+"""
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, Optional
+
+_VER = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+# Anchored to the start of the text that follows X.Y.Z: "8.3.10RC1", "8.3.10-beta2".
+# Unanchored, "Architecture x64" (contains "rc") marked a patched build prerelease.
+_PRERELEASE = re.compile(r"(?i)^[\s\-~_.]?(alpha|beta|rc|dev|snapshot)(?![a-z])")
+
+
+class Version(NamedTuple):
+    major: int
+    minor: int
+    patch: int
+    prerelease: bool = False
+
+    @property
+    def branch(self):
+        return (self.major, self.minor)
+
+    def __str__(self):
+        s = f"{self.major}.{self.minor}.{self.patch}"
+        return s + " (prerelease)" if self.prerelease else s
+
+    def _cmp_key(self):
+        # A prerelease of X.Y.Z sorts just below the final X.Y.Z.
+        return (self.major, self.minor, self.patch, 0 if self.prerelease else 1)
+
+    def __lt__(self, other):
+        return self._cmp_key() < other._cmp_key()
+
+    def __ge__(self, other):
+        return self._cmp_key() >= other._cmp_key()
+
+
+def parse(text: str) -> Optional[Version]:
+    """Extract a Version from any string containing X.Y.Z, or None."""
+    if not text:
+        return None
+    m = _VER.search(text)
+    if not m:
+        return None
+    tail = text[m.end():]
+    return Version(int(m.group(1)), int(m.group(2)), int(m.group(3)),
+                   bool(_PRERELEASE.search(tail)))
+
+
+def parse_fixed(text: str) -> Optional[Version]:
+    """Parse a fixed-version string (always treated as a final release)."""
+    m = _VER.search(text or "")
+    if not m:
+        return None
+    return Version(int(m.group(1)), int(m.group(2)), int(m.group(3)), False)
+
+
+def is_below_fixed(ver: Version, fixed: Version) -> bool:
+    """True if `ver` is strictly below the fixed release on the same branch."""
+    return ver < fixed
+
+
+def compare(a: Version, b: Version) -> int:
+    """-1 if a<b, 0 if equal, 1 if a>b (prerelease-aware)."""
+    ka, kb = a._cmp_key(), b._cmp_key()
+    return (ka > kb) - (ka < kb)
+
+
+# --- loose dotted-version handling (Composer / WordPress ecosystems) -------- #
+# These can be 2, 3 or 4 segments (e.g. "6.9", "5.3.2", "6.3.0.1"); compare by
+# zero-padding to equal length. Build/prerelease suffixes are ignored.
+_OLDSTYLE = re.compile(r"^\d+\.x-(\d.*)$")          # Drupal contrib "8.x-5.20" -> "5.20"
+_LOOSE_NUM = re.compile(r"\d+(?:\.\d+)*")
+_LOOSE_PRE = re.compile(r"(?i)^[-~_.]?(alpha|beta|rc|dev|snapshot|pre|a|b)\d*")
+
+
+def parse_loose(s: str):
+    """Tuple key for a Composer/WordPress-style version.
+
+    Only the leading dotted numbers count ("5.3.2RC1" -> 5.3.2, not 5.3.2.1).
+    A prerelease suffix appends -1 so it sorts just below the final release
+    (compare_loose pads with 0): "5.3.2-beta1" < "5.3.2", so it matches "<5.3.2".
+    """
+    if not s:
+        return None
+    s = str(s).strip().lstrip("vV")
+    m = _OLDSTYLE.match(s)
+    if m:
+        s = m.group(1)
+    head = s.split("+")[0]
+    core, dash, suffix = head.partition("-")
+    mnum = _LOOSE_NUM.match(core)
+    if not mnum:
+        return None
+    nums = tuple(int(n) for n in mnum.group(0).split("."))
+    tail = core[mnum.end():] + (("-" + suffix) if dash else "")
+    pre = bool(tail) and bool(_LOOSE_PRE.match(tail))
+    return nums + ((-1,) if pre else ())
+
+
+def compare_loose(a, b) -> int:
+    n = max(len(a), len(b))
+    a = tuple(a) + (0,) * (n - len(a))
+    b = tuple(b) + (0,) * (n - len(b))
+    return (a > b) - (a < b)

phpwarden/vulndb.py

@@ -0,0 +1,186 @@
+"""The CVE knowledge base: load the feed, model each CVE, match a version.
+
+The feed is a JSON document (see data/php-cve-feed.json). It is the product's
+evolving content — the part a subscription keeps current. The engine that reads
+it is static and open; the feed is what grows over time.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+from phpwarden import version as V
+
+
+@dataclass
+class CVE:
+    id: str
+    title: str
+    cls: str
+    cvss: float
+    severity: str
+    published: str
+    exploited_in_wild: bool
+    sapi: List[str]
+    os: List[str]
+    branches: dict               # "8.3" -> {"fixed": "8.3.36"}
+    eol_affected: bool
+    exposure: list
+    detectors: list
+    remediation: str
+    references: List[str]
+    aka: List[str] = field(default_factory=list)
+    epss: Optional[float] = None
+    epss_percentile: Optional[float] = None
+    ransomware: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CVE":
+        return cls(
+            id=d["id"], title=d.get("title", ""), cls=d.get("class", "unknown"),
+            cvss=float(d.get("cvss", 0)), severity=d.get("severity", "unknown"),
+            published=d.get("published", ""), exploited_in_wild=bool(d.get("exploited_in_wild")),
+            sapi=d.get("sapi") or ["any"], os=d.get("os") or ["any"],
+            branches=d.get("branches", {}), eol_affected=bool(d.get("eol_affected")),
+            exposure=d.get("exposure", []), detectors=d.get("detectors", []),
+            remediation=d.get("remediation", ""), references=d.get("references", []),
+            aka=d.get("aka", []),
+            epss=d.get("epss"), epss_percentile=d.get("epss_percentile"),
+            ransomware=bool(d.get("ransomware")),
+        )
+
+    # --- version logic ---------------------------------------------------- #
+    def _listed_branches(self):
+        return sorted((tuple(int(x) for x in b.split(".")) for b in self.branches), reverse=False)
+
+    def version_status(self, ver: V.Version) -> str:
+        """VULNERABLE | PATCHED | EOL_AFFECTED | NOT_APPLICABLE for a version.
+
+        - branch is listed: below its fixed release -> VULNERABLE, else PATCHED.
+        - branch older than every listed branch: EOL_AFFECTED if the CVE marks
+          end-of-life branches affected (no upstream fix), else NOT_APPLICABLE.
+        - branch newer than every listed branch: NOT_APPLICABLE (the fix is
+          already in that branch's first release, or the bug post-dates it).
+        """
+        if not self.branches:
+            return "NOT_APPLICABLE"
+        bkey = f"{ver.major}.{ver.minor}"
+        if bkey in self.branches:
+            fixed = V.parse_fixed(self.branches[bkey]["fixed"])
+            return "VULNERABLE" if V.is_below_fixed(ver, fixed) else "PATCHED"
+        listed = self._listed_branches()
+        b = ver.branch
+        if b < listed[0]:
+            return "EOL_AFFECTED" if self.eol_affected else "NOT_APPLICABLE"
+        return "NOT_APPLICABLE"   # newer than any listed branch
+
+    def fixed_for(self, ver: V.Version) -> Optional[str]:
+        bkey = f"{ver.major}.{ver.minor}"
+        return self.branches.get(bkey, {}).get("fixed")
+
+    def detector_kinds(self):
+        return {d.get("kind") for d in self.detectors}
+
+
+@dataclass
+class ComposerAdvisory:
+    package: str
+    cve: str
+    title: str
+    cvss: float
+    severity: str
+    affected: str            # OR-groups ("A|B") of comma-AND comparators
+    fixed: List[str]
+    known_exploited: bool
+    references: List[str]
+    epss: Optional[float] = None
+    epss_percentile: Optional[float] = None
+    ransomware: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ComposerAdvisory":
+        return cls(
+            package=d["package"], cve=d.get("cve", ""), title=d.get("title", ""),
+            cvss=float(d.get("cvss", 0)), severity=d.get("severity", "unknown"),
+            affected=d.get("affected", ""), fixed=d.get("fixed", []),
+            known_exploited=bool(d.get("known_exploited")), references=d.get("references", []),
+            epss=d.get("epss"), epss_percentile=d.get("epss_percentile"),
+            ransomware=bool(d.get("ransomware")),
+        )
+
+
+@dataclass
+class WpAdvisory:
+    slug: str
+    type: str                # plugin | theme | core
+    cve: str
+    title: str
+    cvss: float
+    severity: str
+    affected: str
+    fixed: List[str]
+    known_exploited: bool
+    references: List[str]
+    epss: Optional[float] = None
+    epss_percentile: Optional[float] = None
+    ransomware: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WpAdvisory":
+        return cls(
+            slug=d["slug"], type=d.get("type", "plugin"), cve=d.get("cve", ""),
+            title=d.get("title", ""), cvss=float(d.get("cvss", 0)),
+            severity=d.get("severity", "unknown"), affected=d.get("affected", ""),
+            fixed=d.get("fixed", []), known_exploited=bool(d.get("known_exploited")),
+            references=d.get("references", []),
+            epss=d.get("epss"), epss_percentile=d.get("epss_percentile"),
+            ransomware=bool(d.get("ransomware")),
+        )
+
+
+@dataclass
+class Feed:
+    feed_version: str
+    channel: str
+    generated: str
+    cves: List[CVE]
+    composer: List[ComposerAdvisory] = field(default_factory=list)
+    wp: List[WpAdvisory] = field(default_factory=list)
+
+    @classmethod
+    def from_doc(cls, d: dict) -> "Feed":
+        return cls(
+            feed_version=d.get("feed_version", "?"),
+            channel=d.get("channel", "community"),
+            generated=d.get("generated", ""),
+            cves=[CVE.from_dict(c) for c in d.get("cves", [])],
+            composer=[ComposerAdvisory.from_dict(c) for c in d.get("composer_advisories", [])],
+            wp=[WpAdvisory.from_dict(w) for w in d.get("wp_advisories", [])],
+        )
+
+    @classmethod
+    def load(cls, path) -> "Feed":
+        return cls.from_doc(json.loads(Path(path).read_text()))
+
+    @classmethod
+    def bundled(cls) -> "Feed":
+        """Load the feed shipped inside the package.
+
+        Uses pkgutil.get_data so it works both on disk and inside a zipapp/zip,
+        where the data file is not a real filesystem path.
+        """
+        import pkgutil
+        raw = pkgutil.get_data("phpwarden", "data/php-cve-feed.json")
+        if raw:
+            return cls.from_doc(json.loads(raw.decode("utf-8")))
+        # dev fallback: source tree not installed as a package
+        here = Path(__file__).resolve().parent
+        cand = here / "data" / "php-cve-feed.json"
+        if cand.exists():
+            return cls.load(cand)
+        raise FileNotFoundError("bundled php-cve-feed.json not found")
+
+    def by_id(self, cve_id):
+        return next((c for c in self.cves if c.id == cve_id), None)