phpwarden 2.0.0__py3-none-any.whl

phpwarden/deps.py

@@ -0,0 +1,283 @@
+"""Composer dependency scanning — the Snyk-gap closer for PHP shops.
+
+Reads a composer.lock (exact pinned versions) and matches every package against
+the feed's Composer advisories, using composer-style version constraints
+(comma = AND, pipe = OR, operators >= > <= < =).
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from phpwarden import version as V
+from phpwarden.vulndb import ComposerAdvisory, Feed
+
+# One comparator: optional operator, then a version or a wildcard (11.0.*, 1.x, *).
+_TOKEN = re.compile(r"(>=|<=|==|!=|=|>|<)?\s*([0-9][0-9A-Za-z.\-+_*]*|\*)")
+_WILD = re.compile(r"^(\d+(?:\.\d+)*)\.(?:\*|x|X)$")
+
+
+def _satisfies_one(ver_tuple, comparator: str) -> bool:
+    comparator = comparator.strip()
+    if comparator in ("*", "x", "X"):
+        return True
+    m = _TOKEN.fullmatch(comparator)
+    if not m:
+        return False
+    op, rhs_s = (m.group(1) or "="), m.group(2)
+    w = _WILD.match(rhs_s)
+    if w:
+        # "11.0.*" means >=11.0,<11.1 regardless of any operator in front of it
+        lower = V.parse_loose(w.group(1))
+        upper = lower[:-1] + (lower[-1] + 1,)
+        return V.compare_loose(ver_tuple, lower) >= 0 and V.compare_loose(ver_tuple, upper) < 0
+    rhs = V.parse_loose(rhs_s)
+    if rhs is None:
+        return False
+    c = V.compare_loose(ver_tuple, rhs)
+    return {">=": c >= 0, "<=": c <= 0, ">": c > 0, "<": c < 0,
+            "=": c == 0, "==": c == 0, "!=": c != 0}[op]
+
+
+def _comparators(group: str):
+    """Comparators of one AND-group. Composer joins them with ',' OR whitespace
+    (">=6.3.0 <6.3.1" is common in advisories), and allows ">= 1.0" with a space,
+    so tokenise instead of splitting on a single separator."""
+    return [m.group(0).strip() for m in _TOKEN.finditer(group) if m.group(0).strip()]
+
+
+def constraint_matches(ver_str: str, affected: str) -> bool:
+    """True if version string `ver_str` satisfies any OR-group of `affected`.
+
+    Uses loose dotted-version comparison so 2-, 3- and 4-segment ecosystem
+    versions (Composer, WordPress) all work; "|" or "||" separates OR-groups.
+    """
+    vt = V.parse_loose(ver_str)
+    if vt is None:
+        return False
+    for group in re.split(r"\|\|?", affected):
+        comps = _comparators(group)
+        if comps and all(_satisfies_one(vt, c) for c in comps):
+            return True
+    return False
+
+
+@dataclass
+class DepFinding:
+    package: str
+    installed: str
+    advisory: ComposerAdvisory
+    fixed: List[str]
+
+
+def parse_composer_lock(path) -> List[tuple]:
+    """Return [(package, version), ...] from a composer.lock."""
+    try:
+        doc = json.loads(Path(path).read_text())
+    except (OSError, ValueError):
+        return []
+    out = []
+    for section in ("packages", "packages-dev"):
+        for pkg in doc.get(section, []) or []:
+            name = pkg.get("name")
+            ver = (pkg.get("version") or "").lstrip("v")
+            if name and ver:
+                out.append((name, ver))
+    return out
+
+
+# --- reachability: is a vulnerable package actually used in your code? ------- #
+# Dependency scanners flag every CVE in the lockfile — most of the noise is in
+# transitive or dev-only packages you never call. We read each package's declared
+# PSR-4/PSR-0 namespaces from the lock and check whether the project's own source
+# (comments stripped) references them. The result feeds the ranking that
+# `rank_findings` applies and that the CLI / dashboard order follows:
+#
+#   1. known_exploited (KEV) first
+#   2. reach: used > unknown > unreferenced > dev-only
+#   3. EPSS descending
+#   4. CVSS descending
+#
+# "unknown" ranks ABOVE "unreferenced" on purpose: a package we could not check
+# (no autoload namespace, or no project source to scan) must not be demoted as
+# if we had proven it unused. When the project directory does not exist or has
+# no PHP sources, every package is "unknown".
+
+REACH_ORDER = {"used": 0, "unknown": 1, "unreferenced": 2, "dev-only": 3}
+_SEV_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+
+def strip_php_comments(src: str) -> str:
+    """Remove //, # and /* */ comments (docblocks included) from PHP source,
+    leaving string literal contents untouched so `'// not a comment'` survives.
+    Comment bodies are replaced by a single space so tokens never fuse."""
+    out = []
+    i, n = 0, len(src)
+    while i < n:
+        c = src[i]
+        if c in "'\"":                       # string literal: copy verbatim
+            quote = c
+            j = i + 1
+            while j < n:
+                if src[j] == "\\":
+                    j += 2
+                    continue
+                if src[j] == quote:
+                    break
+                j += 1
+            out.append(src[i:j + 1])
+            i = j + 1
+        elif c == "/" and i + 1 < n and src[i + 1] == "*":
+            j = src.find("*/", i + 2)
+            i = n if j < 0 else j + 2
+            out.append(" ")
+        elif (c == "#" and not (i + 1 < n and src[i + 1] == "[")) or \
+                (c == "/" and i + 1 < n and src[i + 1] == "/"):
+            # `#[Attr]` is a PHP 8 attribute, not a comment — keep it
+            j = src.find("\n", i)
+            i = n if j < 0 else j         # keep the newline itself
+            out.append(" ")
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+def _package_meta(lock_doc: dict) -> dict:
+    """{package: {"ns": [namespace prefixes], "dev": bool}} from a composer.lock."""
+    meta = {}
+    for section in ("packages", "packages-dev"):
+        for pkg in lock_doc.get(section, []) or []:
+            name = pkg.get("name")
+            if not name:
+                continue
+            ns = set()
+            au = pkg.get("autoload", {}) or {}
+            for key in ("psr-4", "psr-0"):
+                for prefix in (au.get(key, {}) or {}).keys():
+                    p = prefix.rstrip("\\")
+                    if p:
+                        ns.add(p)
+            meta[name] = {"ns": sorted(ns), "dev": section == "packages-dev"}
+    return meta
+
+
+def _project_source(project_dir, max_files=4000, max_bytes=24_000_000):
+    """(concatenated comment-stripped PHP source, file count) for the project's
+    own code, excluding vendor/ and caches. A missing directory yields ("", 0)."""
+    import os
+    skip = {"vendor", "node_modules", ".git", "var", "cache", "storage", "tests", "test"}
+    buf, nbytes, nfiles = [], 0, 0
+    if not Path(project_dir).is_dir():
+        return "", 0
+    for root, dirs, files in os.walk(project_dir):
+        dirs[:] = [d for d in dirs if d.lower() not in skip and not d.startswith(".")]
+        for fn in files:
+            if not fn.endswith((".php", ".inc", ".phtml")):
+                continue
+            try:
+                data = Path(root, fn).read_text(errors="ignore")
+            except OSError:
+                continue
+            buf.append(strip_php_comments(data))
+            buf.append("\n")
+            nbytes += len(data)
+            nfiles += 1
+            if nfiles >= max_files or nbytes >= max_bytes:
+                return "".join(buf), nfiles
+    return "".join(buf), nfiles
+
+
+def analyze_reachability(lock_path, project_dir) -> dict:
+    """{package: reach} with reach in used | dev-only | unreferenced | unknown.
+
+    Every package is "unknown" when there is nothing to scan (the project dir is
+    missing or has no PHP sources): absence of evidence is not "unreferenced".
+    Namespaces that appear only inside comments do not count as used."""
+    try:
+        doc = json.loads(Path(lock_path).read_text())
+    except (OSError, ValueError):
+        return {}
+    meta = _package_meta(doc)
+    src, nfiles = _project_source(project_dir)
+    if nfiles == 0:
+        return {name: "unknown" for name in meta}
+    out = {}
+    for name, m in meta.items():
+        if not m["ns"]:
+            out[name] = "unknown"          # no autoload namespace to look for
+            continue
+        used = any((ns + "\\") in src for ns in m["ns"])
+        out[name] = "used" if used else ("dev-only" if m["dev"] else "unreferenced")
+    return out
+
+
+def rank_findings(findings: List[DepFinding], reach: dict = None) -> List[DepFinding]:
+    """Sort findings by the documented order: KEV first, then reach
+    (used > unknown > unreferenced > dev-only), then EPSS desc, then CVSS desc.
+    Packages absent from `reach` count as "unknown"."""
+    reach = reach or {}
+    return sorted(findings, key=lambda f: (
+        0 if f.advisory.known_exploited else 1,
+        REACH_ORDER.get(reach.get(f.package, "unknown"), REACH_ORDER["unknown"]),
+        -(f.advisory.epss or 0),
+        -(f.advisory.cvss or 0),
+        _SEV_ORDER.get(f.advisory.severity, 9)))
+
+
+def _installed_from_doc(doc: dict) -> List[tuple]:
+    out = []
+    for section in ("packages", "packages-dev"):
+        for pkg in doc.get(section, []) or []:
+            name = pkg.get("name")
+            ver = (pkg.get("version") or "").lstrip("v")
+            if name and ver:
+                out.append((name, ver))
+    return out
+
+
+def _scan_installed(installed, feed: Feed) -> List[DepFinding]:
+    by_pkg = {}
+    for adv in feed.composer:
+        by_pkg.setdefault(adv.package, []).append(adv)
+    findings = []
+    for name, ver_str in installed:
+        if V.parse_loose(ver_str) is None:
+            continue
+        for adv in by_pkg.get(name, []):
+            if constraint_matches(ver_str, adv.affected):
+                findings.append(DepFinding(name, ver_str, adv, adv.fixed))
+    sev = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+    findings.sort(key=lambda f: (
+        0 if f.advisory.known_exploited else 1,
+        -(f.advisory.epss or 0),
+        sev.get(f.advisory.severity, 9), -f.advisory.cvss))
+    return findings
+
+
+def scan_lock_doc(doc: dict, feed: Feed) -> List[DepFinding]:
+    """Scan an already-parsed composer.lock dict (e.g. pasted into the web UI)."""
+    return _scan_installed(_installed_from_doc(doc), feed)
+
+
+def scan_lock(path, feed: Feed) -> List[DepFinding]:
+    installed = parse_composer_lock(path)
+    by_pkg = {}
+    for adv in feed.composer:
+        by_pkg.setdefault(adv.package, []).append(adv)
+    findings = []
+    for name, ver_str in installed:
+        if V.parse_loose(ver_str) is None:
+            continue
+        for adv in by_pkg.get(name, []):
+            if constraint_matches(ver_str, adv.affected):
+                findings.append(DepFinding(name, ver_str, adv, adv.fixed))
+    sev = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+    findings.sort(key=lambda f: (
+        0 if f.advisory.known_exploited else 1,          # actively exploited first
+        -(f.advisory.epss or 0),                          # then by exploitation probability
+        sev.get(f.advisory.severity, 9), -f.advisory.cvss))
+    return findings

phpwarden/detect.py

@@ -0,0 +1,194 @@
+"""Signature detection: scan logs for the marks of attempted exploitation.
+
+Each CVE in the feed may carry detectors. This module handles the stateless
+ones — request-signature (an exploit marker in an access-log line) and
+response-signature (a leak marker in a response). Each detector declares the
+stream it applies to ("access" or "response"), so scanning an access log never
+fires a response-only signature (which would false-positive on normal logging).
+
+Matching is done against the REQUEST TARGET (path + query) of a parsed
+access-log line, not the whole line, so a Referer or User-Agent never triggers
+a hit. Three pattern classes are told apart because naive substring matching
+flagged ordinary traffic:
+
+  * "%xx" single-byte patterns (e.g. "%ad" for CVE-2024-4577, "%0a" for
+    CVE-2019-11043): the percent-decoded bytes of the part they appear in must
+    be INVALID UTF-8 (a lone 0xAD) or a control byte in the PATH. The "%ad"
+    inside the valid UTF-8 "%C3%AD" ("í") is not an exploit, and "%0A" in a
+    search query is form input, not a PATH_INFO injection.
+  * bare ini-directive words ("allow_url_include", "auto_prepend_file"): only
+    when used as an assignment ("...=" / "...%3d"), which is how the php-cgi
+    argument-injection exploits pass them. A blog title or "#allow_url_include"
+    anchor in a docs URL is not.
+  * anything else ("php://input", "/cgi-bin/..."): plain substring.
+
+Raw bytes that nginx/apache log as "\\xAD" are normalised to "%ad" first, so the
+unencoded variant of an exploit is caught too. One Hit is produced per CVE per
+line, listing every pattern that matched.
+
+The stateful worker-corruption detector (OOM on a worker, then that worker
+reused) is the job of the continuous guard daemon and is referenced here, not
+reimplemented.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from phpwarden.vulndb import Feed
+
+_KIND_STREAM = {"request-signature": "access", "response-signature": "response"}
+
+# Common/Combined access-log line: IP - - [time] "request" status size "ref" "ua"
+# An optional leading "vhost:port " prefix (nginx/apache vhost_combined) is accepted.
+_ACCESS_RE = re.compile(
+    r'^(?:[\w.\-]+(?::\d+)?\s+)?(?P<ip>\d[\d.]*|[0-9a-fA-F:]+)\s+\S+\s+\S+\s+\[(?P<when>[^\]]+)\]\s+'
+    r'"(?P<req>[^"]*)"\s+(?P<status>\d{3})'
+    r'(?:\s+\S+(?:\s+"[^"]*"\s+"(?P<ua>[^"]*)")?)?')
+
+_HEXESC = re.compile(r"\\x([0-9a-fA-F]{2})")      # how servers log raw bytes
+_PCT = re.compile(r"%([0-9a-fA-F]{2})")
+_PCT_BYTE = re.compile(r"^%[0-9a-f]{2}$")
+_WORD = re.compile(r"^[a-z_][a-z0-9_]*$")
+
+
+def parse_access_line(line: str) -> dict:
+    """Best-effort structured fields from a common/combined access-log line."""
+    m = _ACCESS_RE.match(line.strip())
+    if not m:
+        return {}
+    out = {k: (m.group(k) or "") for k in ("ip", "when", "req", "status", "ua")}
+    try:
+        out["log_ts"] = int(datetime.strptime(out["when"], "%d/%b/%Y:%H:%M:%S %z").timestamp())
+    except (ValueError, OverflowError):
+        out["log_ts"] = None
+    return out
+
+
+def _normalize(s: str) -> str:
+    return _HEXESC.sub(lambda m: "%" + m.group(1), s).lower()
+
+
+def _decoded(s: str) -> bytes:
+    return _PCT.sub(lambda m: chr(int(m.group(1), 16)), s).encode("latin-1", "replace")
+
+
+def _valid_utf8(b: bytes) -> bool:
+    try:
+        b.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        return False
+
+
+def _target(req: str):
+    """("/path", "query") from 'GET /path?q=1 HTTP/1.1' (or the raw string)."""
+    parts = req.split(" ")
+    tgt = parts[1] if len(parts) >= 2 and parts[1].startswith("/") else req
+    path, _, query = tgt.partition("?")
+    return path, query
+
+
+def _pattern_hits(pat: str, path: str, query: str, whole: str) -> bool:
+    """Does one (lower-cased, normalised) pattern fire on this request?"""
+    if _PCT_BYTE.match(pat):
+        byte = int(pat[1:], 16)
+        if pat in path and (byte < 0x20 or not _valid_utf8(_decoded(path))):
+            return True
+        if pat in query and not _valid_utf8(_decoded(query)):
+            return True
+        return False
+    if _WORD.match(pat):
+        return re.search(re.escape(pat) + r"\s*(=|%3d)", whole) is not None
+    return pat in whole
+
+
+@dataclass
+class Hit:
+    cve_id: str
+    kind: str
+    pattern: str
+    line_no: int
+    excerpt: str
+    note: str
+    ip: str = ""
+    when: str = ""
+    request: str = ""
+    status: str = ""
+    ua: str = ""
+    log_ts: Optional[int] = None
+
+
+class SignatureScanner:
+    def __init__(self, feed: Feed):
+        self.sigs = []        # (cve_id, kind, stream, pattern, note)
+        seen = set()
+        for cve in feed.cves:
+            for det in cve.detectors:
+                kind = det.get("kind")
+                if kind not in _KIND_STREAM:
+                    continue
+                stream = det.get("on", _KIND_STREAM[kind])
+                for pat in det.get("patterns", []):
+                    key = (cve.id, kind, pat.lower())
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    self.sigs.append((cve.id, kind, stream, pat, det.get("note", "")))
+        self.worker_corruption_cves = [
+            c.id for c in feed.cves if "worker-corruption" in c.detector_kinds()]
+        # set by scan_file
+        self.scanned_lines = 0
+        self.total_hits = 0
+        self.truncated = False
+
+    def scan_line(self, line: str, stream: str = "access", line_no: int = 0) -> List[Hit]:
+        parsed = parse_access_line(line) if stream == "access" else {}
+        if parsed.get("req"):
+            path, query = _target(_normalize(parsed["req"]))
+        else:
+            # not a recognisable access line (raw request dump, other formats):
+            # fall back to the whole line, treated as a path
+            path, query = _normalize(line.strip()), ""
+        whole = path + ("?" + query if query else "")
+        per_cve = {}      # cve_id -> (kind, [patterns], note)
+        for cve_id, kind, sig_stream, pat, note in self.sigs:
+            if sig_stream != stream:
+                continue
+            if _pattern_hits(_normalize(pat), path, query, whole):
+                entry = per_cve.setdefault(cve_id, (kind, [], note))
+                entry[1].append(pat)
+        hits = []
+        for cve_id, (kind, pats, note) in per_cve.items():
+            hits.append(Hit(cve_id, kind, ", ".join(pats), line_no, line.strip()[:300], note,
+                            ip=parsed.get("ip", ""), when=parsed.get("when", ""),
+                            request=parsed.get("req", ""), status=parsed.get("status", ""),
+                            ua=parsed.get("ua", ""), log_ts=parsed.get("log_ts")))
+        return hits
+
+    def scan_file(self, path, stream: str = "access", max_hits: int = 500) -> List[Hit]:
+        """Scan a whole log. Keeps at most `max_hits` Hit objects but scans EVERY
+        line (so total_hits is accurate and nothing is silently skipped); sets
+        self.truncated when more hits existed than were kept. Raises
+        FileNotFoundError / IsADirectoryError / OSError for unusable input —
+        callers must not report a missing file as "clean"."""
+        p = Path(path)
+        if p.is_dir():
+            raise IsADirectoryError(f"{path} is a directory, not a log file")
+        if not p.is_file():
+            raise FileNotFoundError(f"log file not found: {path}")
+        out = []
+        self.scanned_lines = self.total_hits = 0
+        with p.open(errors="replace") as fh:
+            for i, line in enumerate(fh, 1):
+                self.scanned_lines = i
+                hits = self.scan_line(line, stream, i)
+                self.total_hits += len(hits)
+                room = max_hits - len(out)
+                if room > 0:
+                    out.extend(hits[:room])
+        self.truncated = self.total_hits > len(out)
+        return out

phpwarden/engine.py

@@ -0,0 +1,137 @@
+"""Exposure engine: assess a PHP environment against the whole CVE feed.
+
+This is the deterministic backbone — given what we know about a host (PHP
+version, which SAPI, OS, and any confirmed config facts), it returns one finding
+per applicable CVE with a calibrated confidence. It never guesses a version is
+safe: unknowns stay unknown.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Set
+
+from phpwarden import version as V
+from phpwarden.vulndb import CVE, Feed
+
+
+@dataclass
+class Environment:
+    version: Optional[V.Version] = None
+    sapi: Optional[str] = None            # "fpm" | "cgi" | "cli" | None(unknown)
+    os: Optional[str] = None              # "linux" | "windows" | None(unknown)
+    arch: Optional[str] = None            # "32" | "64" | None
+    config_true: Set[str] = field(default_factory=set)   # confirmed-true exposure checks
+
+    @classmethod
+    def from_version_string(cls, text, **kw):
+        return cls(version=V.parse(text), **kw)
+
+
+@dataclass
+class Finding:
+    cve: CVE
+    verdict: str            # EXPOSED | POSSIBLY_EXPOSED | CLEARED
+    confidence: str         # high | medium | low
+    reasons: List[str]
+    fixed: Optional[str]
+
+    @property
+    def exposed(self):
+        return self.verdict in ("EXPOSED", "POSSIBLY_EXPOSED")
+
+
+def _sapi_match(cve: CVE, env: Environment):
+    """(matches, confident). 'any' always matches with confidence."""
+    if cve.sapi == ["any"]:
+        return True, True
+    if env.sapi is None:
+        return True, False          # could match; we can't confirm
+    return (env.sapi in cve.sapi), True
+
+
+def _os_match(cve: CVE, env: Environment):
+    if cve.os == ["any"]:
+        return True, True
+    if env.os is None:
+        return True, False
+    return (env.os in cve.os), True
+
+
+def assess_one(cve: CVE, env: Environment) -> Finding:
+    fixed = cve.fixed_for(env.version) if env.version else None
+    if env.version is None:
+        # Version unknown — but a CVE that needs a SAPI or OS we KNOW this host
+        # doesn't have is still ruled out (a Windows/CGI-only bug on linux/cli).
+        sapi_ok, sapi_conf = _sapi_match(cve, env)
+        os_ok, os_conf = _os_match(cve, env)
+        if (sapi_conf and not sapi_ok) or (os_conf and not os_ok):
+            why = ("SAPI not in the vulnerable set" if (sapi_conf and not sapi_ok)
+                   else "OS not in the vulnerable set")
+            return Finding(cve, "CLEARED", "medium", [why + " (PHP version unknown)"], fixed)
+        return Finding(cve, "POSSIBLY_EXPOSED", "low",
+                       ["PHP version unknown; cannot rule this out"], fixed)
+
+    vs = cve.version_status(env.version)
+    if vs in ("PATCHED", "NOT_APPLICABLE"):
+        reason = ("at or above the fixed release on this branch" if vs == "PATCHED"
+                  else "this PHP branch is not in the vulnerable set")
+        return Finding(cve, "CLEARED", "high", [reason], fixed)
+
+    reasons = []
+    if vs == "EOL_AFFECTED":
+        reasons.append("PHP branch is end-of-life with no upstream fix for this CVE")
+    else:
+        reasons.append(f"version is below the fixed release {fixed} on this branch")
+
+    sapi_ok, sapi_conf = _sapi_match(cve, env)
+    os_ok, os_conf = _os_match(cve, env)
+    if not sapi_ok:
+        return Finding(cve, "CLEARED", "high",
+                       [f"this CVE affects only {'/'.join(cve.sapi)} SAPI; host runs {env.sapi}"], fixed)
+    if not os_ok:
+        return Finding(cve, "CLEARED", "high",
+                       [f"this CVE affects only {'/'.join(cve.os)}; host runs {env.os}"], fixed)
+
+    confident = sapi_conf and os_conf
+    if cve.sapi != ["any"] and not sapi_conf:
+        reasons.append(f"applies only to {'/'.join(cve.sapi)} SAPI (not confirmed on this host)")
+    if cve.os != ["any"] and not os_conf:
+        reasons.append(f"applies only on {'/'.join(cve.os)} (not confirmed on this host)")
+
+    # Config-gated CVEs: note unconfirmed conditions, downgrade confidence.
+    unconfirmed_conf = [c for c in cve.exposure if c.get("check") not in env.config_true]
+    if unconfirmed_conf:
+        for c in unconfirmed_conf:
+            reasons.append("conditional: " + c.get("desc", c.get("check", "")))
+
+    if confident and not unconfirmed_conf:
+        return Finding(cve, "EXPOSED", "high", reasons, fixed)
+    verdict = "POSSIBLY_EXPOSED"
+    conf = "medium" if confident or not unconfirmed_conf else "low"
+    return Finding(cve, verdict, conf, reasons, fixed)
+
+
+def assess(env: Environment, feed: Feed) -> List[Finding]:
+    """Assess every CVE; return findings sorted worst-first."""
+    findings = [assess_one(c, env) for c in feed.cves]
+    sev = {"critical": 0, "high": 1, "medium": 2, "low": 3, "unknown": 4}
+    verd = {"EXPOSED": 0, "POSSIBLY_EXPOSED": 1, "CLEARED": 2}
+    findings.sort(key=lambda f: (
+        verd[f.verdict],
+        0 if f.cve.exploited_in_wild else 1,
+        -(f.cve.epss or 0),
+        sev.get(f.cve.severity, 9), -f.cve.cvss))
+    return findings
+
+
+def summarize(findings: List[Finding]) -> dict:
+    exposed = [f for f in findings if f.verdict == "EXPOSED"]
+    possible = [f for f in findings if f.verdict == "POSSIBLY_EXPOSED"]
+    return {
+        "exposed": len(exposed),
+        "possibly_exposed": len(possible),
+        "cleared": sum(1 for f in findings if f.verdict == "CLEARED"),
+        "worst_severity": exposed[0].cve.severity if exposed else (
+            possible[0].cve.severity if possible else "none"),
+        "exploited_in_wild": sorted({f.cve.id for f in exposed + possible if f.cve.exploited_in_wild}),
+    }