@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-tools/clis/maggie_security_intel.py

@@ -0,0 +1,1294 @@
+#!/usr/bin/env python3
+"""Vulnerability intelligence (docs/maggie-security/01-vuln-intel-prd.md).
+
+Commands: ``inventory``, ``vuln-watch``, ``osv-query``, ``wp-check``,
+``eol-watch``, ``node-check``, ``advisory``, ``consent``.
+
+Coverage across stacks:
+
+- every package ecosystem OSV knows (npm, PyPI, Maven, Go, RubyGems,
+  crates.io, NuGet, Packagist) and OS packages on Debian, Ubuntu, Alpine,
+  Rocky and Alma, through OSV ``querybatch`` (OSV evaluates the ranges; we
+  re-check locally to pick the fix);
+- the Go toolchain through OSV ``Go/stdlib``; Node.js core through the Node
+  security-wg index;
+- PHP, nginx, Apache, MySQL, MariaDB, Redis, Memcached, SQLite, curl and
+  ImageMagick versions, plus WordPress core/plugins/themes, through
+  WPVulnerability (endpoint shapes and fields as the upstream plugin reads
+  them: ``data.vulnerability[].operator``, ``closed``, ``unfixed``);
+- anything else in ``watch.products`` (Java, Python, PostgreSQL, MongoDB,
+  Tomcat, Elasticsearch, ...) through the cvelistV5 delta with a product-name
+  match, and every runtime/database/server/distro through endoflife.date
+  (packaged snapshot when offline);
+- CISA KEV and FIRST EPSS joined onto every CVE.
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import re
+import sys
+from datetime import timedelta
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_inventory as inventory
+import maggie_security_versions as versions
+
+OSV_API = "https://api.osv.dev/v1"
+WPV = "https://www.wpvulnerability.net"
+EOL_API = "https://endoflife.date/api/v1/products"
+EPSS_API = "https://api.first.org/data/v1/epss"
+core.SOURCES.setdefault("epss", {"hosts": ["api.first.org"], "ttl": "24h", "url": EPSS_API})
+core.SOURCES["cvelistv5-zip"] = {"hosts": ["github.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com"], "ttl": "30d",
+                                 "url": "https://github.com/CVEProject/cvelistV5/releases/download/{tag}/{asset}"}
+core.SOURCES["cvelistv5-record"] = {"hosts": ["raw.githubusercontent.com"], "ttl": "7d",
+                                    "url": "https://raw.githubusercontent.com/CVEProject/cvelistV5/main/cves/{year}/{group}xxx/{id}.json"}
+
+# Ecosystem names as OSV spells them.
+OSV_ECOSYSTEMS = {"npm": "npm", "pypi": "PyPI", "maven": "Maven", "go": "Go", "rubygems": "RubyGems", "crates.io": "crates.io",
+                  "nuget": "NuGet", "packagist": "Packagist", "debian": "Debian", "ubuntu": "Ubuntu", "alpine": "Alpine",
+                  "rocky linux": "Rocky Linux", "almalinux": "AlmaLinux"}
+
+# Runtime/service names -> WPVulnerability software endpoint.
+WPV_SOFTWARE = {"php": "php", "nginx": "nginx", "apache": "apache", "mysql": "mysql", "mariadb": "mariadb", "redis": "redis",
+                "memcached": "memcached", "sqlite": "sqlite", "curl": "curl", "imagemagick": "imagemagick"}
+
+# Maggie runtime name -> endoflife.date product.
+EOL_PRODUCTS = {
+    "node": "nodejs", "python": "python", "php": "php", "ruby": "ruby", "go": "go", "java": "eclipse-temurin", "dotnet": "dotnet",
+    "rust": "rust", "perl": "perl", "deno": "deno", "bun": "bun", "mysql": "mysql", "mariadb": "mariadb", "postgresql": "postgresql",
+    "redis": "redis", "valkey": "valkey", "mongodb": "mongodb", "memcached": "memcached", "sqlite": "sqlite", "elasticsearch": "elasticsearch",
+    "opensearch": "opensearch", "mssqlserver": "mssqlserver", "rabbitmq": "rabbitmq", "kafka": "apache-kafka", "nginx": "nginx",
+    "apache": "apache-http-server", "tomcat": "tomcat", "caddy": "caddy", "haproxy": "haproxy", "traefik": "traefik", "openssl": "openssl",
+    "docker-engine": "docker-engine", "kubernetes": "kubernetes", "ubuntu": "ubuntu", "debian": "debian", "alpine": "alpine-linux",
+    "rhel": "rhel", "rocky-linux": "rocky-linux", "almalinux": "almalinux", "centos": "centos", "amazon-linux": "amazon-linux",
+    "fedora": "fedora", "sles": "sles", "opensuse": "opensuse", "wordpress": "wordpress", "drupal": "drupal",
+}
+# Framework packages that also have an EOL cycle.
+EOL_PACKAGES = {("npm", "next"): "nextjs", ("npm", "nuxt"): "nuxt", ("npm", "@angular/core"): "angular", ("npm", "react"): "react",
+                ("npm", "vue"): "vue", ("npm", "express"): "express", ("Packagist", "laravel/framework"): "laravel",
+                ("Packagist", "symfony/symfony"): "symfony", ("Packagist", "symfony/http-kernel"): "symfony", ("PyPI", "django"): "django",
+                ("RubyGems", "rails"): "ruby-on-rails", ("Maven", "org.springframework.boot:spring-boot"): "spring-boot",
+                ("Maven", "org.springframework.boot:spring-boot-starter-parent"): "spring-boot",
+                ("Maven", "org.springframework:spring-core"): "spring-framework"}
+# Runtimes with a version-aware source of their own (Node security-wg, WPVulnerability, OSV Go/stdlib).
+DEDICATED_SOURCES = {"node", "go", "php", "nginx", "apache", "mysql", "mariadb", "redis", "memcached", "sqlite", "curl", "imagemagick", "wordpress"}
+OS_RUNTIMES = {"ubuntu", "debian", "alpine", "rhel", "rocky-linux", "almalinux", "centos", "amazon-linux", "fedora", "sles", "opensuse"}
+
+# CVE vendor/product strings that mean one of our product names (PRD 01 section 8.2).
+PRODUCT_ALIASES = {
+    "nginx": ["nginx", "f5 nginx", "nginx open source"], "php": ["php", "php group"], "node": ["node.js", "nodejs", "node"],
+    "wordpress": ["wordpress"], "openssl": ["openssl"], "next": ["next.js", "nextjs"], "apache": ["http server", "apache http server", "httpd"],
+    "mysql": ["mysql", "mysql server"], "mariadb": ["mariadb", "mariadb server"], "postgresql": ["postgresql"], "redis": ["redis"],
+    "mongodb": ["mongodb", "mongodb server"], "tomcat": ["tomcat", "apache tomcat"], "java": ["java se", "jdk", "openjdk", "jre"],
+    "python": ["python", "cpython"], "ruby": ["ruby"], "go": ["go", "golang"], "elasticsearch": ["elasticsearch"], "memcached": ["memcached"],
+    "docker-engine": ["docker", "moby", "docker engine"], "kubernetes": ["kubernetes"], "astro": ["astro"], "dotnet": [".net", ".net core", "asp.net core"],
+    "sqlite": ["sqlite"], "haproxy": ["haproxy"], "caddy": ["caddy"], "traefik": ["traefik"], "rabbitmq": ["rabbitmq", "rabbitmq server"],
+    "openssh": ["openssh"], "valkey": ["valkey"], "opensearch": ["opensearch"], "drupal": ["drupal", "drupal core"],
+}
+SEVERITY_WORDS = {"critical": "critical", "high": "high", "important": "high", "moderate": "medium", "medium": "medium", "low": "low",
+                  "none": "info", "info": "info"}
+
+
+# --------------------------------------------------------------------------- shared helpers
+
+
+def cvss_from_osv(record: dict) -> dict | None:
+    for item in record.get("severity") or []:
+        if item.get("type") == "CVSS_V3":
+            score = core.cvss3_base_score(item.get("score", ""))
+            if score is not None:
+                return {"version": item["score"].split("/")[0].split(":")[1], "score": score, "vector": item["score"]}
+    for affected in record.get("affected") or []:
+        for item in affected.get("severity") or []:
+            if item.get("type") == "CVSS_V3":
+                score = core.cvss3_base_score(item.get("score", ""))
+                if score is not None:
+                    return {"version": "3.1", "score": score, "vector": item["score"]}
+    return None
+
+
+def cve_ids(ids) -> list[str]:
+    return [i for i in ids if isinstance(i, str) and i.upper().startswith("CVE-")]
+
+
+def primary_of(record_id: str, aliases) -> str:
+    cves = sorted(cve_ids([record_id, *aliases]))
+    return cves[0] if cves else record_id
+
+
+def short(text: str | None, limit: int = 140) -> str:
+    text = re.sub(r"\s+", " ", (text or "").strip())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def target_for(comp_or_runtime: dict, site: str) -> dict:
+    location = comp_or_runtime.get("location")
+    host = comp_or_runtime.get("host")
+    if location and "#" in str(location):
+        location = location.split("#", 1)[0]
+    return {"path": location if location and not host else None, "host": host,
+            "image": comp_or_runtime.get("image")}
+
+
+def internet_facing(stack: dict, host: str | None) -> bool:
+    if not host:
+        return True
+    return any(h.get("id") == host and h.get("public") is not False for h in stack.get("hosts") or []) or not stack.get("hosts")
+
+
+def load_kev(ctx: core.Context) -> dict[str, dict]:
+    data = ctx.cache.get_json("kev", core.SOURCES["kev"]["url"])
+    if not data:
+        return {}
+    return {v["cveID"]: v for v in data.get("vulnerabilities") or [] if v.get("cveID")}
+
+
+def kev_entry(kev: dict, aliases) -> dict | None:
+    for cve in cve_ids(aliases):
+        if cve in kev:
+            item = kev[cve]
+            return {"listed": True, "date_added": item.get("dateAdded"), "ransomware": (item.get("knownRansomwareCampaignUse") or "unknown").lower(),
+                    "due_date": item.get("dueDate")}
+    return None
+
+
+def join_epss(ctx: core.Context, findings: list[dict]) -> None:
+    """FIRST EPSS for every CVE alias, 100 per request, cached 24 h. No key needed."""
+    if "epss" not in ctx.sources or getattr(ctx.args, "no_epss", False):
+        return
+    wanted = sorted({c for f in findings for c in cve_ids(f.get("aliases") or [])})
+    scores: dict[str, dict] = {}
+    for start in range(0, len(wanted), 100):
+        chunk = wanted[start:start + 100]
+        data = ctx.cache.get_json("epss", f"{EPSS_API}?cve={','.join(chunk)}")
+        for row in (data or {}).get("data") or []:
+            try:
+                scores[row["cve"]] = {"score": float(row["epss"]), "percentile": float(row["percentile"]), "date": row.get("date")}
+            except (KeyError, ValueError):
+                continue
+    for finding in findings:
+        best = max((scores[c] for c in cve_ids(finding.get("aliases") or []) if c in scores), key=lambda e: e["score"], default=None)
+        if best:
+            finding["epss"] = best
+            finding["priority"] = core.compute_priority(finding)
+
+
+def apply_kev(findings: list[dict], kev: dict, stack: dict) -> None:
+    for finding in findings:
+        entry = kev_entry(kev, finding.get("aliases") or [])
+        if entry:
+            finding["kev"] = entry
+            remediation = finding.setdefault("remediation", {"summary": "", "steps": [], "snippets": [], "references": [], "cheat_sheet": None}) or {}
+            note = f"Listed by CISA as exploited in the wild on {entry['date_added']}."
+            if note not in (remediation.get("steps") or []):
+                remediation.setdefault("steps", []).append(note)
+            finding["remediation"] = remediation
+            finding["priority"] = core.compute_priority(finding, internet_facing=internet_facing(stack, (finding.get("target") or {}).get("host")))
+
+
+# --------------------------------------------------------------------------- OSV
+
+
+def osv_query_batch(ctx: core.Context, queries: list[dict]) -> list[list[str]]:
+    """Return vulnerability ids per query; [] for each query when OSV is unavailable."""
+    results: list[list[str]] = [[] for _ in queries]
+    for start in range(0, len(queries), 1000):
+        chunk = queries[start:start + 1000]
+        body = json.dumps({"queries": chunk}, sort_keys=True).encode()
+        data = ctx.cache.get_json("osv-api", f"{OSV_API}/querybatch", method="POST", body=body,
+                                  headers={"Content-Type": "application/json"}, ttl=getattr(ctx.args, "osv_ttl", None) or "6h")
+        if data is None:
+            continue
+        for index, result in enumerate(data.get("results") or []):
+            results[start + index] = [v["id"] for v in result.get("vulns") or [] if v.get("id")]
+            # Pages: OSV returns next_page_token per query when a package has very many records.
+            token = result.get("next_page_token")
+            guard = 0
+            while token and guard < 10:
+                guard += 1
+                page = ctx.cache.get_json("osv-api", f"{OSV_API}/query", method="POST",
+                                          body=json.dumps({**chunk[index], "page_token": token}).encode(), headers={"Content-Type": "application/json"})
+                if not page:
+                    break
+                results[start + index] += [v["id"] for v in page.get("vulns") or []]
+                token = page.get("next_page_token")
+    return results
+
+
+def osv_record(ctx: core.Context, vuln_id: str) -> dict | None:
+    return ctx.cache.get_json("osv-api", f"{OSV_API}/vulns/{vuln_id}", ttl="24h")
+
+
+def osv_records(ctx: core.Context, ids: set[str]) -> dict[str, dict]:
+    out: dict[str, dict] = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+        for vid, record in zip(sorted(ids), pool.map(lambda i: osv_record(ctx, i), sorted(ids))):
+            if record:
+                out[vid] = record
+    return out
+
+
+def osv_component_finding(ctx: core.Context, stack: dict, comp: dict, record: dict, command: str) -> dict | None:
+    if record.get("withdrawn"):
+        return None
+    eco = comp["ecosystem"]
+    entries = [a for a in record.get("affected") or []
+               if (a.get("package") or {}).get("name", "").lower() == comp["name"].lower()
+               and (a.get("package") or {}).get("ecosystem", "").split(":", 1)[0].lower() == eco.split(":", 1)[0].lower()]
+    hit, fixed, how = False, [], "none"
+    for entry in entries:
+        h, f, w = versions.osv_affected(comp["version"], entry, eco)
+        fixed += f
+        if h:
+            hit, how = True, w
+    # OSV said it matches; if our local evaluation cannot confirm (unparseable version, GIT-only ranges), keep it as "likely".
+    confidence = "confirmed" if hit else "likely"
+    if entries and not hit and all(r.get("type") in ("SEMVER", "ECOSYSTEM") for e in entries for r in e.get("ranges") or []) and any(e.get("ranges") for e in entries):
+        return None  # local evaluation says not affected: a stale OSV index, do not report
+    aliases = [record["id"], *(record.get("aliases") or [])]
+    cvss = cvss_from_osv(record)
+    vendor = ((record.get("database_specific") or {}).get("severity") or "").lower()
+    severity = core.severity_from_cvss(cvss["score"]) if cvss else SEVERITY_WORDS.get(vendor)
+    kind = "malicious-package" if record["id"].startswith("MAL-") else "vulnerability"
+    if kind == "malicious-package":
+        severity = "critical"
+    recommended = versions.recommended_fix(comp["version"], fixed, eco)
+    fix_available = bool(recommended)
+    is_os = comp.get("scope") == "os"
+    component_type = "os" if is_os else ("js-bundle" if str(comp.get("location", "")).endswith(".js") else "library")
+    steps = []
+    if recommended:
+        steps.append(_upgrade_step(comp, recommended))
+    references = [r["url"] for r in record.get("references") or [] if r.get("type") in ("ADVISORY", "FIX", "WEB")][:4]
+    references.append(f"https://osv.dev/vulnerability/{record['id']}")
+    finding = core.make_finding(
+        kind=kind, command=command, primary_id=primary_of(record["id"], record.get("aliases") or []), site=stack["site"]["id"],
+        title=f"{comp['name']} {comp['version']}: {short(record.get('summary') or record.get('details') or record['id'], 120)}",
+        severity=severity or "medium", severity_source="cvss" if cvss else ("vendor" if vendor else "maggie"), cvss=cvss,
+        confidence=confidence, aliases=aliases, cwe_ids=[c for c in (record.get("database_specific") or {}).get("cwe_ids") or [] if re.match(r"^CWE-\d+$", c)],
+        asvs_ids=["V15.2.1"],
+        affected={"purl": comp.get("purl"), "ecosystem": eco, "name": comp["name"], "version": comp["version"], "component_type": component_type,
+                  "direct": comp.get("direct"), "scope": comp.get("scope")},
+        fix={"fixed_versions": fixed, "recommended": recommended, "available": fix_available},
+        target=target_for(comp, stack["site"]["id"]) if not is_os else {"host": comp.get("host")},
+        evidence=[{"path": str(comp.get("location") or ""), "excerpt": f"{comp['name']} {comp['version']}"}],
+        tool=None, feed="osv", fetched_at=core.iso(), rule_id=record["id"],
+        remediation={"summary": f"Upgrade {comp['name']} to {recommended} or later." if recommended else
+                     f"No fixed version of {comp['name']} is published yet; consider removing or replacing it.",
+                     "steps": steps, "snippets": [], "references": references, "cheat_sheet": None},
+        internet_facing=True, untrusted={"details": short(record.get("details"), 500)} if record.get("details") else None)
+    finding["_how"] = how
+    return finding
+
+
+def _upgrade_step(comp: dict, version: str) -> str:
+    eco = comp["ecosystem"].split(":", 1)[0].lower()
+    name = comp["name"]
+    return {
+        "npm": f"npm install {name}@{version}  (or pnpm add / yarn add)", "pypi": f"pip install '{name}>={version}' and update your lock file",
+        "packagist": f"composer require {name}:^{version}", "maven": f"set {name} to {version} in pom.xml / build.gradle",
+        "go": f"go get {name}@v{version} && go mod tidy", "rubygems": f"bundle update {name} (needs >= {version})",
+        "crates.io": f"cargo update -p {name} --precise {version}", "nuget": f"dotnet add package {name} --version {version}",
+        "debian": f"apt-get install --only-upgrade {name}  (fixed in {version})", "ubuntu": f"apt-get install --only-upgrade {name}  (fixed in {version})",
+        "alpine": f"apk upgrade {name}  (fixed in {version})",
+    }.get(eco, f"upgrade {name} to {version}")
+
+
+def osv_queries_for(stack: dict) -> tuple[list[dict], list[dict]]:
+    """(queries, the component or runtime each query is for)."""
+    queries, owners = [], []
+    for comp in stack.get("components") or []:
+        eco_key = comp["ecosystem"].split(":", 1)[0].lower()
+        osv_eco = OSV_ECOSYSTEMS.get(eco_key)
+        if not osv_eco:
+            continue
+        ecosystem = comp["ecosystem"] if ":" in comp["ecosystem"] else osv_eco
+        if eco_key in ("rocky linux", "almalinux"):
+            ecosystem = f"{osv_eco}:{versions.cycle_of(comp['ecosystem'].split(':', 1)[1], 1)}" if ":" in comp["ecosystem"] else osv_eco
+        queries.append({"package": {"ecosystem": ecosystem, "name": comp["name"]}, "version": comp["version"]})
+        owners.append(comp)
+    for runtime in stack.get("runtimes") or []:
+        if runtime["name"] == "go" and runtime["version"].count(".") >= 1:
+            version = runtime["version"] if runtime["version"].count(".") == 2 else runtime["version"] + ".0"
+            queries.append({"package": {"ecosystem": "Go", "name": "stdlib"}, "version": version})
+            owners.append({"ecosystem": "Go", "name": "stdlib", "version": version, "scope": "runtime", "direct": True,
+                           "location": runtime.get("source"), "host": runtime.get("host"), "purl": "pkg:golang/stdlib@" + version})
+    return queries, owners
+
+
+def match_osv(ctx: core.Context, stack: dict, command: str) -> tuple[list[dict], bool]:
+    queries, owners = osv_queries_for(stack)
+    if not queries:
+        return [], True
+    import maggie_security_mirror as mirror
+
+    local = mirror.LocalOsv(ctx.state)
+    if getattr(ctx.args, "offline", False) and any(local.available(q["package"]["ecosystem"]) for q in queries):
+        return match_osv_local(ctx, stack, command, queries, owners, local)
+    ids_per = osv_query_batch(ctx, queries)
+    if any(item["id"] == "osv-api" and item["status"] == "degraded" for item in ctx.cache.report):
+        return [], False
+    records = osv_records(ctx, {i for ids in ids_per for i in ids})
+    findings = []
+    for owner, ids in zip(owners, ids_per):
+        for vid in ids:
+            record = records.get(vid)
+            if record:
+                finding = osv_component_finding(ctx, stack, owner, record, command)
+                if finding:
+                    finding.pop("_how", None)
+                    findings.append(finding)
+    return findings, True
+
+
+def match_osv_local(ctx: core.Context, stack: dict, command: str, queries: list[dict], owners: list[dict], local) -> tuple[list[dict], bool]:
+    """--offline with OSV ecosystem zips in .maggie/security/db/osv (feeds mirror --to-project)."""
+    findings, missing = [], set()
+    for query, owner in zip(queries, owners):
+        ecosystem = query["package"]["ecosystem"]
+        if not local.available(ecosystem):
+            missing.add(ecosystem.split(":", 1)[0])
+            continue
+        for record in local.query(ecosystem, query["package"]["name"], query["version"]):
+            finding = osv_component_finding(ctx, stack, owner, record, command)
+            if finding:
+                finding.pop("_how", None)
+                finding["source"]["feed"] = "osv-local"
+                findings.append(finding)
+    ctx.run["sources"].append({"id": "osv-local", "status": "ok" if not missing else "degraded",
+                               "error": f"no local OSV database for {', '.join(sorted(missing))}" if missing else None})
+    if missing:
+        ctx.run["degraded"].append("osv-local")
+    return findings, not missing
+
+
+# --------------------------------------------------------------------------- runtimes: Node core, WPVulnerability software, CVE product match
+
+
+def runtime_finding(stack: dict, runtime: dict, command: str, *, primary: str, aliases, title: str, severity: str | None,
+                    cvss: dict | None, fixed: list[str], confidence: str, feed: str, references: list[str],
+                    cwe_ids=(), unfixed: bool = False, untrusted: dict | None = None) -> dict:
+    name = runtime["name"]
+    component_type = "os" if name in OS_RUNTIMES else ("wordpress-core" if name == "wordpress" else
+                                                       "service" if name in WPV_SOFTWARE or name in ("postgresql", "mongodb", "elasticsearch", "tomcat") else "runtime")
+    recommended = None if unfixed else versions.recommended_fix(runtime["version"], fixed)
+    return core.make_finding(
+        kind="vulnerability", command=command, primary_id=primary, site=stack["site"]["id"], title=f"{name} {runtime['version']}: {short(title, 120)}",
+        severity=severity or "medium", severity_source="cvss" if cvss else "vendor", cvss=cvss, confidence=confidence, aliases=aliases,
+        cwe_ids=[c for c in cwe_ids if re.match(r"^CWE-\d+$", str(c))], asvs_ids=["V15.2.1"],
+        affected={"purl": None, "ecosystem": None, "name": name, "version": runtime["version"], "component_type": component_type,
+                  "direct": True, "scope": "runtime"},
+        fix={"fixed_versions": fixed, "recommended": recommended, "available": bool(recommended)},
+        target={"host": runtime.get("host"), "image": runtime.get("image"),
+                "path": None if runtime.get("host") or runtime.get("image") or runtime.get("source") in ("image", "declared", "files", "flag") else runtime.get("source")},
+        evidence=[{"path": runtime.get("source") or "", "excerpt": f"{name} {runtime['version']}"}],
+        feed=feed, fetched_at=core.iso(),
+        remediation={"summary": f"Upgrade {name} to {recommended} or later." if recommended else f"No fixed {name} release known for this line; plan an upgrade to a supported line.",
+                     "steps": [f"maggie security advisory --cve {primary} --component {name}"] if primary.startswith("CVE-") else [],
+                     "snippets": [], "references": references[:5], "cheat_sheet": None},
+        internet_facing=internet_facing(stack, runtime.get("host")), untrusted=untrusted)
+
+
+def load_node_index(ctx: core.Context) -> dict:
+    return ctx.cache.get_json("node-core", core.SOURCES["node-core"]["url"]) or {}
+
+
+def node_core_findings(ctx: core.Context, stack: dict, index: dict, command: str, only_version: str | None = None) -> list[dict]:
+    findings = []
+    runtimes = [r for r in stack.get("runtimes") or [] if r["name"] == "node"]
+    if only_version:
+        runtimes = [{"name": "node", "version": only_version, "source": "flag", "host": getattr(ctx.args, "host", None)}]
+    for runtime in runtimes:
+        version = runtime["version"] if runtime["version"].count(".") == 2 else None
+        if not version:
+            continue
+        for key, entry in index.items():
+            vulnerable, patched = entry.get("vulnerable") or "", entry.get("patched") or ""
+            if not vulnerable or not versions.satisfies(version, vulnerable) or (patched and versions.satisfies(version, patched)):
+                continue
+            fixed = []
+            for clause in patched.split("||"):
+                match = re.search(r"(\d+\.\d+\.\d+)", clause)
+                if match:
+                    fixed.append(match.group(1))
+            cves = entry.get("cve") or []
+            findings.append(runtime_finding(stack, runtime, command, primary=(cves[0] if cves else f"nodejs-core-{key}"),
+                                            aliases=[f"nodejs-core-{key}", *cves], title=entry.get("description") or entry.get("overview") or key,
+                                            severity=SEVERITY_WORDS.get((entry.get("severity") or "").lower()), cvss=None, fixed=fixed,
+                                            confidence="confirmed", feed="node-core", references=[entry.get("ref")] if entry.get("ref") else []))
+    return findings
+
+
+PHP_OPS = {"lt": "<", "<": "<", "le": "<=", "<=": "<=", "gt": ">", ">": ">", "ge": ">=", ">=": ">=", "eq": "==", "==": "==", "=": "==",
+           "ne": "!=", "!=": "!=", "<>": "!="}
+
+
+def php_version_compare(a: str, b: str, op: str) -> bool:
+    c = versions.compare_generic(a, b)
+    op = PHP_OPS.get((op or "").strip().lower(), "")
+    return {"<": c < 0, "<=": c <= 0, ">": c > 0, ">=": c >= 0, "==": c == 0, "!=": c != 0}.get(op, False)
+
+
+def wpv_applicable(entry: dict, version: str | None) -> bool:
+    """Port of wpvulnerability_is_vulnerability_applicable() (EUPL-1.2 plugin; logic re-implemented)."""
+    op = entry.get("operator") or {}
+    if not version:
+        return False
+    if op.get("min_operator") and op.get("max_operator"):
+        return php_version_compare(version, op.get("min_version", "0"), op["min_operator"]) and \
+            php_version_compare(version, op.get("max_version", "0"), op["max_operator"])
+    if op.get("max_operator"):
+        return php_version_compare(version, op.get("max_version", "0"), op["max_operator"])
+    if op.get("min_operator"):
+        return php_version_compare(version, op.get("min_version", "0"), op["min_operator"])
+    return False
+
+
+def wpv_fetch(ctx: core.Context, kind: str, slug: str) -> dict | None:
+    data = ctx.cache.get_json("wpvulnerability", f"{WPV}/{kind}/{slug}/", ttl="12h")
+    if data is None or data.get("error"):
+        return None
+    return data.get("data") or {}
+
+
+WPV_LETTERS = {"c": "critical", "h": "high", "m": "medium", "l": "low", "n": "info"}
+
+
+def wpv_severity(value) -> str | None:
+    text = str(value or "").strip().lower()
+    return WPV_LETTERS.get(text) or SEVERITY_WORDS.get(text)
+
+
+def wpv_entry_to_finding(stack: dict, comp: dict, entry: dict, command: str) -> dict | None:
+    """One WPVulnerability entry. Entries with an ``operator`` carry their own range
+    (software and plugin endpoints return every advisory for the product);
+    core entries have none because the core endpoint is already per version."""
+    version = comp.get("version")
+    operator = entry.get("operator") or {}
+    if (operator.get("min_operator") or operator.get("max_operator")) and not wpv_applicable(entry, version):
+        return None
+    if not operator and comp.get("kind") != "wordpress-core" and not comp.get("runtime"):
+        return None  # no range on a plugin/theme entry: cannot tell
+    impact = entry.get("impact") if isinstance(entry.get("impact"), dict) else {}
+    cvss_info = impact.get("cvss3") or impact.get("cvss") or {}
+    cvss = None
+    try:
+        if cvss_info.get("score"):
+            cvss = {"version": str(cvss_info.get("version") or "3.1"), "score": float(cvss_info["score"]), "vector": cvss_info.get("vector") or ""}
+    except (TypeError, ValueError):
+        cvss = None
+    sources = [s for s in entry.get("source") or [] if isinstance(s, dict)]
+    cves = cve_ids([s.get("id") for s in sources] + [s.get("name") for s in sources])
+    others = [f"wpvuln-{str(s.get('id'))[:12]}" for s in sources if s.get("id") and not str(s.get("id")).upper().startswith("CVE-")]
+    fixed = [operator["max_version"]] if operator.get("max_operator") in ("lt", "<") and operator.get("max_version") else []
+    unfixed = str(operator.get("unfixed", entry.get("unfixed", "0"))) == "1"
+    title = entry.get("name") or ""
+    if comp.get("runtime") and re.search(r"(<=?|>=?|unfixed|\d+\.\d+)", title) and cves:
+        # Software entries are named by range ("PHP 7.4 <= 7.4.33 (unfixed)"); the CVE says more.
+        title = ", ".join(cves[:2]) + (" — no fixed release on this line; move to a supported line" if unfixed
+                                       else f" — fixed in {operator.get('max_version')}" if operator.get("max_operator") in ("lt", "<") else "")
+    if comp.get("kind") == "wordpress-core" or re.fullmatch(r"[\d.]+", title or ""):
+        title = next((s.get("name") for s in sources if s.get("name") and not str(s.get("name")).upper().startswith("CVE-")), title)
+    references = [s.get("link") for s in sources if s.get("link")]
+    primary = cves[0] if cves else (others[0] if others else f"wpvuln-{str(entry.get('uuid', 'x'))[:12]}")
+    cwe = [c.get("cwe") for c in impact.get("cwe") or [] if isinstance(c, dict) and c.get("cwe")]
+    description = next((s.get("description") for s in sources if s.get("description")), None) or entry.get("description")
+    untrusted = {"description": short(description, 500)} if description else None
+    severity = wpv_severity(cvss_info.get("severity")) or (core.severity_from_cvss(cvss["score"]) if cvss else None)
+    if comp.get("kind") in ("wordpress-plugin", "wordpress-theme", "wordpress-core"):
+        slug = comp["name"]
+        recommended = None if unfixed else versions.recommended_fix(version or "0", fixed)
+        fix_text = (f"Update {slug} to {recommended} or later in WordPress > Updates." if recommended else
+                    f"No fixed release of {slug} is known; deactivate and replace it." if unfixed or comp["kind"] != "wordpress-core" else
+                    "Update WordPress to the latest release in Dashboard > Updates.")
+        finding = core.make_finding(
+            kind="vulnerability", command=command, primary_id=primary, site=stack["site"]["id"], title=f"{slug} {version}: {short(title, 120)}",
+            severity=severity or "medium", severity_source="cvss" if cvss else "vendor", cvss=cvss, confidence="confirmed" if version else "possible",
+            aliases=cves + others or [primary], cwe_ids=[c for c in cwe if re.match(r"^CWE-\d+$", str(c))], asvs_ids=["V15.2.1"],
+            affected={"purl": f"pkg:wordpress/{slug}@{version}" if version else None, "ecosystem": "wordpress", "name": slug, "version": version,
+                      "component_type": comp["kind"], "direct": True, "scope": "runtime"},
+            fix={"fixed_versions": fixed, "recommended": recommended, "available": bool(recommended)},
+            target={"path": comp.get("location")}, feed="wpvulnerability", fetched_at=core.iso(), untrusted=untrusted,
+            remediation={"summary": fix_text, "steps": [], "snippets": [], "references": references[:5], "cheat_sheet": None},
+            internet_facing=comp.get("active") is not False)
+    else:
+        finding = runtime_finding(stack, comp["runtime"], command, primary=primary, aliases=cves + others or [primary], title=title or primary,
+                                  severity=severity, cvss=cvss, fixed=fixed, confidence="confirmed", feed="wpvulnerability",
+                                  references=references, cwe_ids=cwe, unfixed=unfixed, untrusted=untrusted)
+    if impact.get("kev") is True and not finding.get("kev"):
+        finding["kev"] = {"listed": True}
+        finding["priority"] = core.compute_priority(finding)
+    return finding
+
+
+def wordpress_findings(ctx: core.Context, stack: dict, command: str, include_inactive: bool = True, budget: int = 300) -> tuple[list[dict], bool]:
+    findings: list[dict] = []
+    ok = True
+    wp = stack.get("wordpress") or {}
+    items: list[dict] = []
+    if wp.get("core"):
+        items.append({"kind": "wordpress-core", "name": "wordpress", "version": wp["core"], "location": "wp-includes/version.php"})
+    for kind, bucket in (("wordpress-plugin", "plugins"), ("wordpress-theme", "themes")):
+        for item in wp.get(bucket) or []:
+            items.append({"kind": kind, "name": item["slug"], "version": item.get("version"), "active": item.get("active"),
+                          "location": f"wp-content/{bucket}/{item['slug']}/"})
+    for item in items[:budget]:
+        api_kind = {"wordpress-core": "core", "wordpress-plugin": "plugin", "wordpress-theme": "theme"}[item["kind"]]
+        data = wpv_fetch(ctx, api_kind, item["version"] if api_kind == "core" else item["name"])
+        if data is None:
+            continue
+        if api_kind != "core" and str(data.get("closed", "0")) == "1":
+            findings.append(core.make_finding(
+                kind="exposure", command=command, primary_id=f"wp-closed-{item['name']}", site=stack["site"]["id"],
+                title=f"{item['name']} is closed on WordPress.org: replace it", severity="high", severity_source="vendor", confidence="confirmed",
+                affected={"purl": None, "ecosystem": "wordpress", "name": item["name"], "version": item.get("version"),
+                          "component_type": item["kind"], "direct": True, "scope": "runtime"},
+                target={"path": item["location"]}, feed="wpvulnerability", asvs_ids=["V15.2.1"],
+                remediation={"summary": "Closed plugins/themes get no security fixes. Replace it with a maintained alternative.", "steps": [],
+                             "snippets": [], "references": [f"https://wordpress.org/plugins/{item['name']}/"], "cheat_sheet": None}))
+        for entry in data.get("vulnerability") or []:
+            finding = wpv_entry_to_finding(stack, item, entry, command)
+            if finding:
+                if item.get("active") is False and not include_inactive:
+                    finding["severity"] = "info"
+                findings.append(finding)
+    if len(items) > budget:
+        ok = False
+        ctx.degrade("wpvulnerability", f"request budget: {len(items) - budget} items left for the next run")
+    if any(s["id"] == "wpvulnerability" and s["status"] == "degraded" for s in ctx.cache.report):
+        ok = False
+    return findings, ok
+
+
+def software_findings(ctx: core.Context, stack: dict, command: str) -> tuple[list[dict], set[str]]:
+    """PHP, nginx, Apache, MySQL/MariaDB, Redis, Memcached, SQLite, curl, ImageMagick through WPVulnerability."""
+    findings, covered = [], set()
+    for runtime in stack.get("runtimes") or []:
+        endpoint = WPV_SOFTWARE.get(runtime["name"])
+        if not endpoint or runtime["version"].count(".") < 2:
+            continue
+        data = wpv_fetch(ctx, endpoint, runtime["version"])
+        if data is None:
+            continue
+        covered.add(core.finding_locator({"name": runtime["name"], "component_type": "service"}, {"host": runtime.get("host")}))
+        for entry in data.get("vulnerability") or []:
+            finding = wpv_entry_to_finding(stack, {"runtime": runtime, "version": runtime["version"]}, entry, command)
+            if finding:
+                findings.append(finding)
+    return findings, covered
+
+
+# CVE JSON 5 ------------------------------------------------------------------
+
+
+def cve_record_url(cve: str) -> str:
+    year, number = cve.split("-")[1], cve.split("-")[2]
+    group = number[:-3] if len(number) > 3 else "0"
+    return f"https://raw.githubusercontent.com/CVEProject/cvelistV5/main/cves/{year}/{group}xxx/{cve}.json"
+
+
+def norm_product(text: str) -> str:
+    return re.sub(r"[^a-z0-9.+ ]+", " ", (text or "").lower()).strip()
+
+
+def products_in(record: dict, watch: list[str]) -> list[tuple[str, dict]]:
+    """(watch product, CNA affected entry) pairs that name one of our products."""
+    out = []
+    containers = record.get("containers") or {}
+    affected = list((containers.get("cna") or {}).get("affected") or [])
+    for adp in containers.get("adp") or []:
+        affected += adp.get("affected") or []
+    for entry in affected:
+        product = norm_product(entry.get("product", ""))
+        vendor = norm_product(entry.get("vendor", ""))
+        package = norm_product(entry.get("packageName", ""))
+        for name in watch:
+            aliases = PRODUCT_ALIASES.get(name, [name])
+            if product in aliases or package in aliases or f"{vendor} {product}".strip() in aliases:
+                out.append((name, entry))
+    return out
+
+
+def cve_metrics(record: dict) -> tuple[dict | None, str | None]:
+    containers = record.get("containers") or {}
+    blocks = [(containers.get("cna") or {})] + list(containers.get("adp") or [])
+    for block in blocks:
+        for metric in block.get("metrics") or []:
+            for key in ("cvssV3_1", "cvssV3_0"):
+                if key in metric:
+                    data = metric[key]
+                    return {"version": data.get("version", "3.1"), "score": float(data.get("baseScore", 0)), "vector": data.get("vectorString", "")}, None
+            if "cvssV4_0" in metric:
+                data = metric["cvssV4_0"]
+                return {"version": "4.0", "score": float(data.get("baseScore", 0)), "vector": data.get("vectorString", "")}, None
+            if "other" in metric:
+                content = (metric["other"].get("content") or {})
+                text = str(content.get("text") or content.get("value") or "").lower()
+                if text in SEVERITY_WORDS:
+                    return None, SEVERITY_WORDS[text]
+    return None, None
+
+
+def cve_title(record: dict) -> str:
+    cna = (record.get("containers") or {}).get("cna") or {}
+    if cna.get("title"):
+        return cna["title"]
+    for item in cna.get("descriptions") or []:
+        if item.get("lang", "en").startswith("en"):
+            return item.get("value", "")
+    return record.get("cveMetadata", {}).get("cveId", "")
+
+
+def cve_findings_for_record(stack: dict, record: dict, command: str) -> list[dict]:
+    meta = record.get("cveMetadata") or {}
+    if meta.get("state") == "REJECTED":
+        return []
+    cve = meta.get("cveId")
+    if not cve:
+        return []
+    watch = (stack.get("watch") or {}).get("products") or []
+    runtimes = stack.get("runtimes") or []
+    findings = []
+    cvss, vendor_sev = cve_metrics(record)
+    cna = (record.get("containers") or {}).get("cna") or {}
+    cwes = [d.get("cweId") for p in cna.get("problemTypes") or [] for d in p.get("descriptions") or [] if d.get("cweId")]
+    refs = [r.get("url") for r in cna.get("references") or [] if r.get("url")]
+    by_runtime: dict[int, list[dict]] = {}
+    for name, entry in products_in(record, watch):
+        for index, runtime in enumerate(runtimes):
+            if runtime["name"] == name:
+                by_runtime.setdefault(index, []).append(entry)
+    for index, entries in by_runtime.items():
+        runtime = runtimes[index]
+        results, fixes = [], []
+        for entry in entries:
+            usable = [v for v in entry.get("versions") or []
+                      if str(v.get("version", "0")).strip() in ("0", "*", "n/a", "unspecified", "") or re.match(r"^v?\d", str(v.get("version", "")))]
+            if entry.get("versions") and not usable:
+                continue  # product-specific version names (e.g. "R36"): not comparable
+            result, entry_fixes = versions.cve_versions_affected(runtime["version"], usable, entry.get("defaultStatus", "unknown"))
+            results.append(result)
+            fixes += [f for f in entry_fixes if re.match(r"^\d", f) and versions.cycle_of(f, 1) == versions.cycle_of(runtime["version"], 1)]
+        if not results or (False in results and True not in results):
+            continue
+        result = True if True in results else None
+        if result is None and runtime["name"] in DEDICATED_SOURCES:
+            continue  # a better source covers this runtime; a rangeless CVE adds only noise
+        confidence = "likely" if result else "possible"
+        findings.append(runtime_finding(stack, runtime, command, primary=cve, aliases=[cve], title=cve_title(record),
+                                        severity=core.severity_from_cvss(cvss["score"]) if cvss else vendor_sev, cvss=cvss, fixed=sorted(set(fixes), key=versions.sort_key(None)),
+                                        confidence=confidence, feed="cvelistv5", references=refs, cwe_ids=cwes,
+                                        untrusted={"description": short(cve_title(record), 400)}))
+    return findings
+
+
+CVE_ZIP_MEMBER_LIMIT = 4 * 1024 * 1024
+CVE_ZIP_TOTAL_LIMIT = 400 * 1024 * 1024
+
+
+def delta_zip_urls(floor, now) -> list[tuple[str, str, str]]:
+    """(url, ttl, label) for the cvelistV5 release zips that cover floor..now.
+
+    Past days use the end-of-day delta; today uses the newest hourly delta
+    (records changed since midnight). Asset names as published in the
+    cvelistV5 Releases (README "Releases").
+    """
+    base = "https://github.com/CVEProject/cvelistV5/releases/download"
+    out = []
+    day = floor.date()
+    while day < now.date():
+        d = day.isoformat()
+        out.append((f"{base}/cve_{d}_at_end_of_day/{d}_delta_CVEs_at_end_of_day.zip", "30d", d))
+        day += timedelta(days=1)
+    today = now.date().isoformat()
+    for hour in range(now.hour, -1, -1):
+        out.append((f"{base}/cve_{today}_{hour:02d}00Z/{today}_delta_CVEs_at_{hour:02d}00Z.zip", "1h", f"{today}T{hour:02d}"))
+    return out
+
+
+def records_from_zip(data: bytes) -> list[dict]:
+    import io
+    import zipfile
+
+    records, total = [], 0
+    with zipfile.ZipFile(io.BytesIO(data)) as archive:
+        for info in archive.infolist():
+            if not info.filename.endswith(".json") or "/CVE-" not in "/" + info.filename.replace("\\", "/"):
+                continue
+            if info.file_size > CVE_ZIP_MEMBER_LIMIT:
+                continue
+            total += info.file_size
+            if total > CVE_ZIP_TOTAL_LIMIT:
+                raise core.DegradedError("cvelistV5 delta zip larger than expected; refusing to unpack more")
+            try:
+                records.append(json.loads(archive.read(info).decode("utf-8")))
+            except (ValueError, UnicodeDecodeError):
+                continue
+    return records
+
+
+def cve_delta(ctx: core.Context, stack: dict, command: str, since: timedelta, budget: int) -> tuple[list[dict], bool]:
+    """New and updated CVE records since the cursor, matched by product name.
+
+    Reads the cvelistV5 release delta zips (one per past day plus today's
+    latest hourly zip); falls back to deltaLog.json + one request per record
+    (bounded by --cve-budget) when the zips are unavailable.
+    """
+    watch = (stack.get("watch") or {}).get("products") or []
+    if not watch or not any(r["name"] in watch for r in stack.get("runtimes") or []):
+        ctx.run.setdefault("inputs", {})["cve_delta"] = {"note": "no watched runtime in the stack"}
+        return [], True
+    cursor = ctx.cache.cursor("cvelistv5-delta")
+    now = core.utcnow()
+    floor = core.parse_time(cursor) if cursor else now - since
+    records: list[dict] = []
+    ok = True
+    today_found = False
+    for url, ttl, label in delta_zip_urls(floor, now):
+        if label.startswith(now.date().isoformat()) and today_found:
+            continue
+        data = ctx.cache.get("cvelistv5-zip", url, ttl=ttl, allow_stale=False)
+        if data is None:
+            if "T" not in label:  # an end-of-day zip should exist
+                ok = False
+            continue
+        if "T" in label:
+            today_found = True
+        try:
+            records += records_from_zip(data)
+        except Exception as error:  # noqa: BLE001 - a bad archive degrades the source
+            ok = False
+            ctx.degrade("cvelistv5-zip", f"{label}: {error}")
+    via = "release-zips"
+    if not ok or not records:
+        records, ok = cve_records_one_by_one(ctx, floor, budget)
+        via = "deltaLog"
+    fresh = []
+    for record in records:
+        updated = (record.get("cveMetadata") or {}).get("dateUpdated") or (record.get("cveMetadata") or {}).get("datePublished")
+        try:
+            if updated and core.parse_time(updated) <= floor:
+                continue
+        except ValueError:
+            pass
+        fresh.append(record)
+    findings: list[dict] = []
+    for record in fresh:
+        findings += cve_findings_for_record(stack, record, command)
+    ctx.run.setdefault("inputs", {})["cve_delta"] = {"via": via, "records": len(fresh), "since": core.iso(floor)}
+    # Zip runs drop the cvelistv5-zip 404 noise from today's hours that are not published yet.
+    ctx.cache.report = [r for r in ctx.cache.report if not (r["id"] == "cvelistv5-zip" and r["status"] == "degraded" and ok)]
+    if ok:
+        ctx._pending_cursor = ("cvelistv5-delta", core.iso(now))  # type: ignore[attr-defined]
+    return findings, ok
+
+
+def cve_records_one_by_one(ctx: core.Context, floor, budget: int) -> tuple[list[dict], bool]:
+    delta = ctx.cache.get_json("cvelistv5-delta", core.SOURCES["cvelistv5-delta"]["url"])
+    if delta is None:
+        return [], False
+    wanted: dict[str, str] = {}
+    for batch in delta if isinstance(delta, list) else []:
+        fetched = batch.get("fetchTime")
+        if not fetched or core.parse_time(fetched) <= floor:
+            continue
+        for item in (batch.get("new") or []) + (batch.get("updated") or []):
+            if item.get("cveId"):
+                wanted[item["cveId"]] = item.get("githubLink") or cve_record_url(item["cveId"])
+    ids = sorted(wanted)
+    complete = len(ids) <= budget
+
+    def fetch(cve: str):
+        url = wanted[cve].replace("https://github.com/CVEProject/cvelistV5/blob/main/", "https://raw.githubusercontent.com/CVEProject/cvelistV5/main/")
+        return ctx.cache.get_json("cvelistv5-record", url, ttl="7d")
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+        records = [r for r in pool.map(fetch, ids[:budget]) if r]
+    if not complete:
+        ctx.degrade("cvelistv5-delta", f"record budget {budget} reached; {len(ids) - budget} records left")
+    return records, complete
+
+
+def kev_product_findings(ctx: core.Context, stack: dict, kev: dict, existing: list[dict], command: str, since: timedelta) -> list[dict]:
+    """KEV additions that name a product we run but no version match: 'exploited elsewhere; confirm your version' (PRD 01 8.5)."""
+    known = {a for f in existing for a in f.get("aliases") or []}
+    cursor = ctx.cache.cursor("kev")
+    floor = (core.parse_time(cursor) if cursor else core.utcnow() - since).date()
+    out = []
+    for cve, entry in kev.items():
+        try:
+            added = core.parse_time(entry.get("dateAdded", "1970-01-01")).date()
+        except ValueError:
+            continue
+        if added < floor or cve in known:
+            continue
+        product = norm_product(entry.get("product", ""))
+        vendor = norm_product(entry.get("vendorProject", ""))
+        for runtime in stack.get("runtimes") or []:
+            aliases = PRODUCT_ALIASES.get(runtime["name"], [runtime["name"]])
+            if product in aliases or f"{vendor} {product}" in aliases:
+                finding = runtime_finding(stack, runtime, command, primary=cve, aliases=[cve],
+                                          title=f"exploited in the wild elsewhere; confirm your version ({entry.get('vulnerabilityName') or cve})",
+                                          severity="high", cvss=None, fixed=[], confidence="possible", feed="kev",
+                                          references=[f"https://www.cve.org/CVERecord?id={cve}"])
+                finding["kev"] = {"listed": True, "date_added": entry.get("dateAdded"), "ransomware": (entry.get("knownRansomwareCampaignUse") or "unknown").lower()}
+                finding["priority"] = "p2"
+                out.append(finding)
+    ctx._kev_cursor = core.iso()  # type: ignore[attr-defined]
+    return out
+
+
+# --------------------------------------------------------------------------- EOL
+
+
+def eol_product(ctx: core.Context, product: str) -> list[dict] | None:
+    """Release cycles in snapshot shape: releaseCycle, eol, eoas, latest. API first, packaged snapshot as fallback."""
+    if not getattr(ctx.args, "offline", False):
+        data = ctx.cache.get_json("eol", f"{EOL_API}/{product}/", ttl="24h")
+        result = (data or {}).get("result") or {}
+        if result.get("releases"):
+            return [{"releaseCycle": r.get("name"), "eol": r.get("eolFrom") if r.get("eolFrom") else r.get("isEol"),
+                     "isEol": r.get("isEol"), "eoas": r.get("eoasFrom"), "latest": (r.get("latest") or {}).get("name"),
+                     "isMaintained": r.get("isMaintained")} for r in result["releases"]]
+    snapshot = core.read_json(core.DATA_DIR / "eol-snapshot.json")
+    releases = snapshot["products"].get(product)
+    if releases is not None:
+        ctx.run.setdefault("inputs", {}).setdefault("eol_snapshot", snapshot["snapshot"])
+    return releases
+
+
+def pick_cycle(releases: list[dict], version: str) -> dict | None:
+    cycles = sorted((r for r in releases if r.get("releaseCycle")), key=lambda r: -len(str(r["releaseCycle"])))
+    for release in cycles:
+        cycle = str(release["releaseCycle"])
+        if version == cycle or version.startswith(cycle + ".") or version.startswith(cycle + "-") or (cycle.isdigit() and version.split(".")[0] == cycle):
+            return release
+    return None
+
+
+def eol_findings(ctx: core.Context, stack: dict, command: str, warn_days: tuple[int, int] = (90, 30)) -> tuple[list[dict], set[str]]:
+    today = core.utcnow().date()
+    findings, covered = [], set()
+    subjects = [(r, EOL_PRODUCTS.get(r["name"])) for r in stack.get("runtimes") or []]
+    for comp in stack.get("components") or []:
+        product = EOL_PACKAGES.get((comp["ecosystem"], comp["name"]))
+        if product and comp.get("direct") is not False:
+            subjects.append(({"name": comp["name"], "version": comp["version"], "source": comp.get("location"), "host": None, "_package": comp}, product))
+    for override in getattr(ctx.args, "product", None) or []:
+        name, _, cycle = override.partition("=")
+        subjects.append(({"name": name, "version": cycle, "source": "flag", "host": None}, EOL_PRODUCTS.get(name, name)))
+    cache: dict[str, list[dict] | None] = {}
+    for subject, product in subjects:
+        if not product:
+            continue
+        if product not in cache:
+            cache[product] = eol_product(ctx, product)
+        releases = cache[product]
+        if not releases:
+            continue
+        release = pick_cycle(releases, subject["version"])
+        locator_affected = {"name": subject["name"], "component_type": "runtime"}
+        covered.add(core.finding_locator(locator_affected, {"host": subject.get("host")}))
+        if not release:
+            continue
+        eol = release.get("eol")
+        eol_date = None
+        if isinstance(eol, str) and re.match(r"\d{4}-\d{2}-\d{2}", eol):
+            eol_date = core.parse_time(eol).date()
+        is_eol = (eol is True) or (eol_date is not None and eol_date <= today) or release.get("isEol") is True
+        days = (eol_date - today).days if eol_date else (-1 if is_eol else None)
+        public = internet_facing(stack, subject.get("host"))
+        latest = release.get("latest")
+        cycle = str(release["releaseCycle"])
+        if is_eol:
+            severity = "high" if public else "medium"
+            title = f"{subject['name']} {cycle} reached end of life" + (f" on {eol_date}" if eol_date else "")
+        elif days is not None and days <= warn_days[1]:
+            severity, title = "medium", f"{subject['name']} {cycle} reaches end of life on {eol_date} ({days} days)"
+        elif days is not None and days <= warn_days[0]:
+            severity, title = "low", f"{subject['name']} {cycle} reaches end of life on {eol_date} ({days} days)"
+        elif latest and versions.compare_generic(subject["version"], str(latest)) < 0 and subject["version"].count(".") >= 1 \
+                and str(latest).startswith(cycle) and subject.get("source") not in ("declared",):
+            severity, title = "info", f"{subject['name']} {subject['version']} is behind the latest {cycle} patch ({latest})"
+        else:
+            continue
+        supported = sorted((str(r["releaseCycle"]) for r in releases if not (r.get("eol") is True or
+                            (isinstance(r.get("eol"), str) and re.match(r"\d{4}", r["eol"]) and core.parse_time(r["eol"]).date() <= today))),
+                           key=versions.sort_key(None))
+        finding = core.make_finding(
+            kind="eol", command=command, primary_id=f"eol-{product}-{cycle}" + ("-patch" if severity == "info" else ""),
+            site=stack["site"]["id"], title=title, severity=severity, severity_source="maggie", confidence="confirmed",
+            asvs_ids=["V15.2.1"],
+            affected={"purl": (subject.get("_package") or {}).get("purl"), "ecosystem": (subject.get("_package") or {}).get("ecosystem"),
+                      "name": subject["name"], "version": subject["version"],
+                      "component_type": "os" if subject["name"] in OS_RUNTIMES else ("library" if subject.get("_package") else "runtime"),
+                      "direct": True, "scope": "runtime"},
+            fix={"fixed_versions": [str(latest)] if latest else [], "recommended": (str(latest) if severity == "info" else (supported[-1] if supported else None)),
+                 "available": bool(supported) or bool(latest)},
+            target={"host": subject.get("host"), "image": subject.get("image"),
+                    "path": None if subject.get("host") or subject.get("image") or subject.get("source") in ("image", "declared", "files", "flag") else subject.get("source")},
+            feed="eol", fetched_at=core.iso(), internet_facing=public,
+            remediation={"summary": (f"Move to a supported {subject['name']} line ({', '.join(supported[-3:])})." if severity != "info" and supported
+                                     else f"Update to {latest}." if latest else "Plan an upgrade."),
+                         "steps": [], "snippets": [], "references": [f"https://endoflife.date/{product}"], "cheat_sheet": None})
+        finding["_eol_days"] = days
+        finding["priority"] = core.compute_priority(finding, internet_facing=public)
+        finding.pop("_eol_days", None)
+        findings.append(finding)
+    return findings, covered
+
+
+# --------------------------------------------------------------------------- commands
+
+
+def _since(ctx: core.Context, default: str = "24h") -> timedelta:
+    span = core.parse_duration(ctx.args.since or default)
+    return min(span, timedelta(days=30))
+
+
+def _commit_cursors(ctx: core.Context) -> None:
+    """Cursors move only after the run file is written (PRD 01 6.2)."""
+    pending = getattr(ctx, "_pending_cursor", None)
+    if pending and pending[1]:
+        ctx.cache.set_cursor(*pending)
+    kev_cursor = getattr(ctx, "_kev_cursor", None)
+    if kev_cursor:
+        ctx.cache.set_cursor("kev", kev_cursor)
+
+
+def _locators(stack: dict, ok_osv: bool) -> set[str]:
+    covered = set()
+    if ok_osv:
+        _, owners = osv_queries_for(stack)
+        for owner in owners:
+            affected = {"purl": owner.get("purl"), "name": owner["name"], "component_type": "library"}
+            covered.add(core.finding_locator(affected, {}))
+    return covered
+
+
+def vuln_watch(ctx: core.Context):
+    args = ctx.args
+    stack = inventory.load_stack(ctx, rebuild=args.rebuild_inventory)
+    enabled = set((args.sources or "osv,node,wp,software,cvelistv5,kev,epss").split(","))
+    kev = load_kev(ctx)  # always joined onto CVE findings; "kev" in --sources adds product-only alerts
+    findings: list[dict] = []
+    covered: set[str] = set()
+    if "osv" in enabled:
+        found, ok = match_osv(ctx, stack, "vuln-watch")
+        findings += found
+        covered |= _locators(stack, ok)
+    if "node" in enabled and any(r["name"] == "node" for r in stack.get("runtimes") or []):
+        index = load_node_index(ctx)
+        if index:
+            findings += node_core_findings(ctx, stack, index, "vuln-watch")
+            covered |= {core.finding_locator({"name": "node", "component_type": "runtime"}, {"host": r.get("host")})
+                        for r in stack["runtimes"] if r["name"] == "node"}
+    if "software" in enabled:
+        found, cov = software_findings(ctx, stack, "vuln-watch")
+        findings += found
+        covered |= cov
+    if "wp" in enabled and stack.get("wordpress"):
+        found, ok = wordpress_findings(ctx, stack, "vuln-watch", budget=args.wp_budget)
+        findings += found
+        if ok:
+            wp = stack["wordpress"]
+            covered |= {f"wordpress-plugin:{p['slug']}" for p in wp.get("plugins") or []} | {f"wordpress-theme:{t['slug']}" for t in wp.get("themes") or []}
+            covered.add("wordpress-core:wordpress")
+    if "cvelistv5" in enabled:
+        found, _ok = cve_delta(ctx, stack, "vuln-watch", _since(ctx), args.cve_budget)
+        findings += found
+    apply_kev(findings, kev, stack)
+    if "kev" in enabled and kev:
+        findings += kev_product_findings(ctx, stack, kev, findings, "vuln-watch", _since(ctx, "7d"))
+    join_epss(ctx, findings)
+    ctx.run["inputs"].update({"stack": str(ctx.state.path("inventory", "stack.json").relative_to(ctx.project)), "stack_hash": stack["hash"],
+                              "sources": sorted(enabled)})
+    doc = ctx.finish(findings, covered=covered)
+    _commit_cursors(ctx)
+    write_runtime_advisories(ctx, doc, Path(args.advisory_out) if args.advisory_out else ctx.state.path("advisories"))
+    return doc
+
+
+def osv_query(ctx: core.Context):
+    args = ctx.args
+    site = ctx.site
+    if args.id:
+        record = osv_record(ctx, args.id)
+        if record is None:
+            ctx.degrade("osv-api", f"{args.id} not found or OSV unavailable")
+            args.no_ledger = True
+            return ctx.finish([])
+        cvss = cvss_from_osv(record)
+        finding = core.make_finding(kind="malicious-package" if record["id"].startswith("MAL-") else "vulnerability", command="osv-query",
+                                    primary_id=primary_of(record["id"], record.get("aliases") or []), site=site,
+                                    title=short(record.get("summary") or record.get("details") or record["id"], 200), cvss=cvss,
+                                    severity=SEVERITY_WORDS.get(((record.get("database_specific") or {}).get("severity") or "").lower(), "medium"),
+                                    severity_source="cvss" if cvss else "vendor", confidence="possible",
+                                    aliases=[record["id"], *(record.get("aliases") or [])], target={}, feed="osv",
+                                    remediation={"summary": "Lookup only; run vuln-watch to match it against your stack.", "steps": [], "snippets": [],
+                                                 "references": [f"https://osv.dev/vulnerability/{record['id']}"], "cheat_sheet": None},
+                                    untrusted={"details": short(record.get("details"), 1000)})
+        apply_kev([finding], load_kev(ctx), {"hosts": []})
+        args.no_ledger = True
+        return ctx.finish([finding])
+    if args.stack:
+        stack = inventory.load_stack(ctx)
+    else:
+        if args.purl:
+            match = re.match(r"^pkg:([^/]+)/(.+)@([^@?#]+)$", args.purl)
+            if not match:
+                raise core.UsageError("--purl must include a version, e.g. pkg:npm/next@14.2.10")
+            kind, name, version = match.groups()
+            eco = {"npm": "npm", "pypi": "PyPI", "maven": "Maven", "golang": "Go", "gem": "RubyGems", "cargo": "crates.io", "nuget": "NuGet",
+                   "composer": "Packagist"}.get(kind, kind)
+            name = name.replace("%40", "@")
+            if eco == "Maven":
+                name = name.replace("/", ":")
+        elif args.ecosystem and args.name and args.version:
+            eco, name, version = args.ecosystem, args.name, args.version
+        else:
+            raise core.UsageError("give --purl, --ecosystem/--name/--version, --id or --stack")
+        stack = {"site": {"id": site}, "hosts": [], "runtimes": [],
+                 "components": [{"purl": core.make_purl(eco, name, version), "ecosystem": eco, "name": name, "version": version,
+                                 "scope": "runtime", "direct": True, "location": "query"}]}
+        args.no_ledger = True
+    findings, ok = match_osv(ctx, stack, "osv-query")
+    apply_kev(findings, load_kev(ctx), stack)
+    join_epss(ctx, findings)
+    return ctx.finish(findings, covered=_locators(stack, ok) if args.stack else ())
+
+
+def wp_check(ctx: core.Context):
+    args = ctx.args
+    if args.wordpress:
+        inv = inventory.Inventory(ctx.project, ctx.site, "wordpress")
+        inv.parse_wordpress(Path(args.wordpress))
+        if args.wp_cli_json:
+            inv.apply_wp_cli(Path(args.wp_cli_json))
+        stack = inv.stack([], [])
+    else:
+        stack = inventory.load_stack(ctx)
+    if not stack.get("wordpress"):
+        raise core.UsageError("no WordPress install found (pass --wordpress PATH)")
+    findings, ok = wordpress_findings(ctx, stack, "wp-check", include_inactive=args.include_inactive, budget=args.wp_budget)
+    soft, soft_cov = software_findings(ctx, stack, "wp-check")
+    findings += soft
+    apply_kev(findings, load_kev(ctx), stack)
+    join_epss(ctx, findings)
+    covered = set(soft_cov)
+    if ok:
+        wp = stack["wordpress"]
+        covered |= {f"wordpress-plugin:{p['slug']}" for p in wp.get("plugins") or []} | {f"wordpress-theme:{t['slug']}" for t in wp.get("themes") or []}
+        covered.add("wordpress-core:wordpress")
+    return ctx.finish(findings, covered=covered)
+
+
+def eol_watch(ctx: core.Context):
+    stack = inventory.load_stack(ctx)
+    warn = tuple(int(x) for x in (ctx.args.warn_days or "90,30").split(","))
+    findings, covered = eol_findings(ctx, stack, "eol-watch", (max(warn), min(warn)))
+    if not any(r["name"] == "astro" for r in stack.get("runtimes") or []) and any(c["name"] == "astro" for c in stack.get("components") or []):
+        ctx.run["inputs"]["note"] = "astro has no endoflife.date entry; it is covered by OSV through vuln-watch"
+    return ctx.finish(findings, covered=covered)
+
+
+def node_check(ctx: core.Context):
+    args = ctx.args
+    version = args.node_version
+    if args.local and not version:
+        import subprocess
+
+        out = subprocess.run(["node", "--version"], capture_output=True, text=True, check=False).stdout.strip()
+        version = out.lstrip("v") or None
+    stack = {"site": {"id": ctx.site}, "hosts": [], "runtimes": [], "components": []} if version else inventory.load_stack(ctx)
+    index = load_node_index(ctx)
+    if not index:
+        ctx.degrade("node-core", "Node security-wg index unavailable")
+        return ctx.finish([])
+    findings = node_core_findings(ctx, stack, index, "node-check", only_version=version)
+    apply_kev(findings, load_kev(ctx), stack)
+    covered = {core.finding_locator({"name": "node", "component_type": "runtime"}, {"host": args.host if version else r.get("host")})
+               for r in (stack.get("runtimes") or [{"host": args.host}]) if version or r["name"] == "node"}
+    return ctx.finish(findings, covered=covered)
+
+
+# --------------------------------------------------------------------------- advisory bridge (PRD 01 6.7)
+
+
+def advisory_from(component: str, cve: str, fixed: list[str], eol_releases: list[dict] | None) -> dict:
+    by_line: dict[str, str] = {}
+    for version in sorted(set(fixed), key=versions.sort_key(None)):
+        line = versions.cycle_of(version, 2)
+        by_line.setdefault(line, version)
+    unsupported = []
+    today = core.utcnow().date()
+    for release in eol_releases or []:
+        eol = release.get("eol")
+        if eol is True or (isinstance(eol, str) and re.match(r"\d{4}-\d{2}-\d{2}", eol) and core.parse_time(eol).date() <= today):
+            unsupported.append(str(release["releaseCycle"]))
+    data = {"id": cve, "component": component, "fixed": by_line, "unsupportedLines": sorted(unsupported, key=versions.sort_key(None))}
+    if component not in ("php",):
+        data["planner"] = "manual"
+    return data
+
+
+def advisory(ctx: core.Context) -> dict:
+    args = ctx.args
+    if args.finding:
+        finding = None
+        runs = sorted(ctx.state.path("runs").glob("*.json"), reverse=True) if ctx.state.path("runs").is_dir() else []
+        for path in runs:
+            doc = core.read_json(path)
+            finding = next((f for f in doc.get("findings") or [] if f["id"] == args.finding), None)
+            if finding:
+                break
+        if not finding:
+            raise core.UsageError(f"finding {args.finding} not found in .maggie/security/runs/")
+        component = (finding.get("affected") or {}).get("name")
+        cve = next(iter(cve_ids(finding.get("aliases") or [])), finding["source"].get("rule_id"))
+        fixed = (finding.get("fix") or {}).get("fixed_versions") or []
+    else:
+        if not (args.cve and args.component):
+            raise core.UsageError("give --finding ID, or --cve and --component")
+        component, cve = args.component, args.cve.upper()
+        fixed = []
+        record = ctx.cache.get_json("cvelistv5-record", cve_record_url(cve), ttl="7d")
+        if record:
+            for name, entry in products_in(record, [component]):
+                for item in entry.get("versions") or []:
+                    if item.get("lessThan") and item.get("lessThan") != "*":
+                        fixed.append(str(item["lessThan"]))
+                    if item.get("status") == "unaffected" and item.get("version"):
+                        fixed.append(str(item["version"]))
+        if not fixed:
+            ctx.degrade("cvelistv5-record", f"no fixed versions for {component} in {cve}")
+    data = advisory_from(component, cve, fixed, eol_product(ctx, EOL_PRODUCTS.get(component, component)))
+    out = Path(args.out) if args.out else ctx.state.path("advisories", f"{cve}-{component}.json")
+    core.write_json(out, data)
+    return {"schema": "maggie-security-advisory-result.v1", "advisory": data, "path": str(out),
+            "next": f"maggie deployment runtime-inventory --ssh deploy@<host> --advisory {out}",
+            "note": "Maggie does not run that for you: it needs ssh-read consent, and any migration needs host-lock.",
+            "exit_code": core.EXIT_DEGRADED if ctx.run["degraded"] else core.EXIT_OK}
+
+
+def write_runtime_advisories(ctx: core.Context, doc: dict, directory: Path) -> None:
+    for finding in doc.get("findings") or []:
+        affected = finding.get("affected") or {}
+        if finding.get("status") != "new" or affected.get("component_type") not in ("runtime", "service", "os"):
+            continue
+        cves = cve_ids(finding.get("aliases") or [])
+        if not cves:
+            continue
+        data = advisory_from(affected["name"], cves[0], (finding.get("fix") or {}).get("fixed_versions") or [], None)
+        core.write_json(directory / f"{cves[0]}-{affected['name']}.json", data)
+
+
+# --------------------------------------------------------------------------- consent (H-1)
+
+
+def consent_cmd(ctx: core.Context) -> dict:
+    args = ctx.args
+    path = ctx.state.path("consent.json")
+    data = core.read_json(path) if path.is_file() else {"schema": "maggie-security-consent.v1", "grants": []}
+    if args.action == "list":
+        return data
+    if not args.host or not args.level:
+        raise core.UsageError("consent grant/revoke needs --host and --level")
+    if args.level not in core.CONSENT_LEVELS or args.level in core.IMPLICIT_CONSENT:
+        raise core.UsageError(f"--level must be one of {', '.join(l for l in core.CONSENT_LEVELS if l not in core.IMPLICIT_CONSENT)}")
+    if args.action == "grant":
+        if args.level == "host-change":
+            raise core.PolicyError("host-change is never granted to a security command")
+        if not sys.stdin.isatty() and not args.yes_i_am_human:
+            raise core.PolicyError("consent is granted interactively only (routines and agents cannot grant it)")
+        if sys.stdin.isatty():
+            print(f"Grant {args.level} on host '{args.host}'? This lets maggie security run read-only commands over SSH. Type the host alias to confirm: ",
+                  end="", file=sys.stderr, flush=True)
+            if sys.stdin.readline().strip() != args.host:
+                raise core.PolicyError("not confirmed")
+        grant = {"host": args.host, "level": args.level, "granted_at": core.iso(), "by": "user",
+                 "until": core.iso(core.utcnow() + core.parse_duration(args.days + "d"))[:10] if args.days else None}
+        data["grants"].append(grant)
+    else:
+        for grant in data["grants"]:
+            if grant["host"] == args.host and grant["level"] == args.level and not grant.get("revoked_at"):
+                grant["revoked_at"] = core.iso()
+    core.write_json(path, data)
+    return data
+
+
+# --------------------------------------------------------------------------- registration
+
+
+def _vw(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--sources", help="comma list: osv,node,wp,software,cvelistv5,kev,epss (default all)")
+    p.add_argument("--rebuild-inventory", action="store_true")
+    p.add_argument("--full-rematch", action="store_true", help="ignore the OSV query cache")
+    p.add_argument("--advisory-out", help="directory for runtime advisories (default .maggie/security/advisories)")
+    p.add_argument("--cve-budget", type=int, default=1500, help="max CVE records fetched per run")
+    p.add_argument("--wp-budget", type=int, default=300)
+    p.add_argument("--no-epss", action="store_true")
+
+
+def _oq(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--purl")
+    p.add_argument("--ecosystem")
+    p.add_argument("--name")
+    p.add_argument("--version")
+    p.add_argument("--id", help="OSV/GHSA/CVE id lookup")
+    p.add_argument("--stack", action="store_true", help="query every component in stack.json")
+    p.add_argument("--no-epss", action="store_true")
+
+
+def _wp(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--wordpress")
+    p.add_argument("--wp-cli-json")
+    p.add_argument("--include-inactive", action="store_true", default=True)
+    p.add_argument("--wp-budget", type=int, default=300)
+    p.add_argument("--no-epss", action="store_true")
+
+
+def _eol(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--warn-days", default="90,30")
+    p.add_argument("--product", action="append", help="NAME=CYCLE to check without an inventory, e.g. php=8.1")
+
+
+def _node(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--node-version")
+    p.add_argument("--host")
+    p.add_argument("--local", action="store_true", help="use `node --version` on this machine")
+
+
+def _adv(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--finding")
+    p.add_argument("--cve")
+    p.add_argument("--component")
+    p.add_argument("--out")
+
+
+def _consent(p: argparse.ArgumentParser) -> None:
+    p.add_argument("action", choices=["grant", "revoke", "list"])
+    p.add_argument("--host")
+    p.add_argument("--level")
+    p.add_argument("--days", help="grant expiry in days")
+    p.add_argument("--yes-i-am-human", action="store_true", help=argparse.SUPPRESS)
+
+
+WATCH_SOURCES = ["osv-api", "kev", "node-core", "wpvulnerability", "cvelistv5-zip", "cvelistv5-delta", "cvelistv5-record", "epss", "eol"]
+
+COMMANDS = [
+    core.Command("inventory", "build the stack inventory (lockfiles, manifests, images, WordPress, host evidence)", [],
+                 inventory.configure, inventory.run, findings=False),
+    core.Command("vuln-watch", "daily watch: OSV, Node core, WPVulnerability, CVE delta, KEV, EPSS against the stack", WATCH_SOURCES, _vw, vuln_watch),
+    core.Command("osv-query", "look up one package, one advisory id, or the whole stack in OSV", ["osv-api", "kev", "epss"], _oq, osv_query),
+    core.Command("wp-check", "WordPress core, plugins, themes and server software via WPVulnerability", ["wpvulnerability", "kev", "epss"], _wp, wp_check),
+    core.Command("eol-watch", "end-of-life and patch-behind for runtimes, databases, servers, distros and frameworks", ["eol"], _eol, eol_watch),
+    core.Command("node-check", "Node.js core advisories for the node versions in use", ["node-core", "kev"], _node, node_check),
+    core.Command("advisory", "write a runtime-inventory --advisory file for a CVE or finding", ["cvelistv5-record", "eol", "osv-api"], _adv, advisory,
+                 findings=False),
+    core.Command("consent", "grant, revoke or list per-host consent (interactive only)", [], _consent, consent_cmd, findings=False, routine_safe=False),
+]