vulnly 1.0.0__py3-none-any.whl

vulnly/__init__.py

@@ -0,0 +1,1385 @@
+__version__ = "1.0.0"
+
+import base64
+import json
+import html
+import mimetypes
+import os
+import re
+import struct
+import datetime
+import argparse
+import shutil
+import sys
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import Any, overload
+
+SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "unknown": 4}
+
+TEMPLATE_DIR = Path(__file__).parent
+# One theme-aware template per report type. The theme is applied as a
+# data-theme attribute on the root element rather than by picking a file.
+REPORT_TEMPLATE = TEMPLATE_DIR / "report_template.html"
+REPO_SUMMARY_TEMPLATE = TEMPLATE_DIR / "repo_summary_template.html"
+THEMES = ("dark", "light")
+# Pure-path SVG: no embedded text, so it needs no font and stays crisp at
+# any size. The wordmark beside it is HTML, styled per theme.
+DEFAULT_LOGO = TEMPLATE_DIR / "vulnly-icon.svg"
+# Chart.js is bundled rather than loaded from a CDN so reports render on hosts
+# with no outbound network access.
+CHART_JS = TEMPLATE_DIR / "chart.umd.min.js"
+# Inter, embedded for the same reason. Variable font covering weights 400-800.
+FONT_WOFF2 = TEMPLATE_DIR / "inter-var.woff2"
+# Browser-tab icon, embedded so a report saved to disk still shows it.
+FAVICON = TEMPLATE_DIR / "vulnly-favicon.png"
+
+
+def _read_chart_js() -> str:
+    """Return the bundled Chart.js source, or '' if it is missing."""
+    try:
+        return CHART_JS.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def _read_favicon_b64() -> str:
+    """Return the bundled favicon as base64, or '' if it is missing."""
+    try:
+        return base64.b64encode(FAVICON.read_bytes()).decode("ascii")
+    except OSError:
+        return ""
+
+
+def _read_font_b64() -> str:
+    """Return the bundled font as base64, or '' if it is missing.
+
+    An empty value leaves the @font-face src unresolvable, and the template's
+    fallback stack takes over — degraded typography rather than a broken page.
+    """
+    try:
+        return base64.b64encode(FONT_WOFF2.read_bytes()).decode("ascii")
+    except OSError:
+        return ""
+
+
+def _apply_replacements(template: str, replacements: dict) -> str:
+    """Substitute placeholders, skipping the template's documentation comment.
+
+    That comment lists every placeholder by name, so a plain replace across
+    the whole file also substituted there — embedding a copy of the logo data
+    URI, and now the Chart.js bundle, into a comment no reader ever sees.
+    """
+    head, sep, body = template.partition("-->")
+    if not sep:
+        head, sep, body = "", "", template
+    for placeholder, value in replacements.items():
+        body = body.replace(placeholder, value)
+    return head + sep + body
+
+
+SUPPORTED_SOURCES = {"cloudsmith", "trivy", "grype", "snyk"}
+
+
+def is_cloudsmith_cli_format(data: dict) -> bool:
+    """Return True if the JSON looks like raw Cloudsmith CLI output."""
+    return isinstance(data.get("data"), dict) and "scans" in data["data"]
+
+
+def is_cloudsmith_repo_summary_format(data: dict) -> bool:
+    """Return True if the JSON looks like a Cloudsmith repo-level summary."""
+    d = data.get("data")
+    return isinstance(d, dict) and "packages" in d and "repository" in d and "scans" not in d
+
+
+def is_trivy_format(data: dict) -> bool:
+    """Return True if the JSON looks like Trivy JSON output."""
+    return "Results" in data and isinstance(data.get("Results"), list)
+
+
+def is_grype_format(data: dict) -> bool:
+    """Return True if the JSON looks like Grype JSON output."""
+    return "matches" in data and isinstance(data.get("matches"), list) and "descriptor" in data
+
+
+def is_snyk_format(data: dict) -> bool:
+    """Return True if the JSON looks like Snyk CLI container test output."""
+    return (
+        "vulnerabilities" in data
+        and isinstance(data.get("vulnerabilities"), list)
+        and "packageManager" in data
+        and "projectName" in data
+    )
+
+
+
+def normalize_snyk(raw: dict) -> dict:
+    """Transform Snyk CLI JSON into the internal report format."""
+    project_name = raw.get("projectName", "Unknown")
+    # projectName is typically "docker-image|nginx" — extract the image name
+    if "|" in project_name:
+        artifact_name = project_name.split("|", 1)[1]
+    else:
+        artifact_name = project_name
+
+    docker_info = raw.get("docker", {})
+    os_info = docker_info.get("os", {})
+    scan_target = os_info.get("prettyName", raw.get("platform", "Unknown"))
+    package_format = raw.get("packageManager", "Unknown")
+    path_info = raw.get("path", "")
+
+    # Deduplicate vulnerabilities by (id, name, version)
+    seen = set()
+    vulnerabilities = []
+    for v in raw.get("vulnerabilities", []):
+        vuln_id = v.get("id", "")
+        pkg_name = v.get("name", v.get("packageName", "N/A"))
+        pkg_version = v.get("version", "N/A")
+        dedup_key = (vuln_id, pkg_name, pkg_version)
+        if dedup_key in seen:
+            continue
+        seen.add(dedup_key)
+
+        # Prefer CVE identifier if available, fall back to Snyk ID
+        identifiers = v.get("identifiers", {})
+        cves = identifiers.get("CVE", [])
+        identifier = cves[0] if cves else vuln_id
+
+        # CVSS score
+        cvss = v.get("cvssScore")
+
+        # Fixed version
+        fixed_in = v.get("fixedIn", [])
+        fixed_version = ", ".join(fixed_in) if fixed_in else None
+
+        vuln = {
+            "severity": (v.get("severity") or "unknown").lower(),
+            "identifier": identifier,
+            "package": pkg_name,
+            "affected_version": pkg_version,
+            "fixed_version": fixed_version,
+            "title": v.get("title", ""),
+            "cvss": cvss,
+        }
+        vulnerabilities.append(vuln)
+
+    return {
+        "scan_date": "",
+        "repository": artifact_name,
+        "package_name": artifact_name,
+        "package_version": path_info.split(":")[-1] if ":" in path_info else "latest",
+        "package_format": package_format,
+        "scan_target": scan_target,
+        "scan_id": raw.get("projectId", "N/A"),
+        "vulnerabilities": vulnerabilities,
+    }
+
+
+def normalize_grype(raw: dict) -> dict:
+    """Transform Grype JSON into the internal report format."""
+    source = raw.get("source", {})
+    target = source.get("target", {})
+    distro = raw.get("distro", {})
+    descriptor = raw.get("descriptor", {})
+
+    artifact_name = target.get("userInput", "Unknown")
+    image_id = target.get("imageID", "")
+    tags = target.get("tags", [])
+    scan_target = tags[0] if tags else artifact_name
+
+    distro_name = distro.get("name", "")
+    distro_version = distro.get("version", "")
+    package_format = f"{distro_name} {distro_version}".strip() if distro_name else source.get("type", "Unknown")
+
+    vulnerabilities = []
+    for match in raw.get("matches", []):
+        v = match.get("vulnerability", {})
+        artifact = match.get("artifact", {})
+
+        # Extract best CVSS v3 score
+        cvss = None
+        for entry in v.get("cvss", []):
+            if isinstance(entry, dict) and entry.get("version") == "3.1":
+                metrics = entry.get("metrics", {})
+                score = metrics.get("baseScore")
+                if score is not None:
+                    if cvss is None or score > cvss:
+                        cvss = score
+
+        # Extract fixed version
+        fix = v.get("fix", {})
+        fix_versions = fix.get("versions", [])
+        fixed_version = fix_versions[0] if fix_versions else None
+
+        vuln = {
+            "severity": (v.get("severity") or "unknown").lower(),
+            "identifier": v.get("id", "N/A"),
+            "package": artifact.get("name", "N/A"),
+            "affected_version": artifact.get("version", "N/A"),
+            "fixed_version": fixed_version,
+            "title": v.get("description", "")[:120] or None,
+            "cvss": cvss,
+        }
+        vulnerabilities.append(vuln)
+
+    return {
+        "scan_date": "",
+        "repository": artifact_name,
+        "package_name": artifact_name,
+        "package_version": image_id.replace("sha256:", "")[:12] if image_id else "latest",
+        "package_format": package_format,
+        "scan_target": scan_target,
+        "scan_id": "N/A",
+        "vulnerabilities": vulnerabilities,
+    }
+
+
+def normalize_trivy(raw: dict) -> dict:
+    """Transform Trivy JSON into the internal report format."""
+    artifact_name = raw.get("ArtifactName", "Unknown")
+    artifact_type = raw.get("ArtifactType", "Unknown")
+    created_at = raw.get("CreatedAt", "")
+    scan_date = created_at[:10] if created_at else ""
+    report_id = raw.get("ReportID", "N/A")
+
+    metadata = raw.get("Metadata", {})
+    os_info = metadata.get("OS", {})
+    os_family = os_info.get("Family", "")
+    os_name = os_info.get("Name", "")
+    package_format = f"{os_family} {os_name}".strip() if os_family else artifact_type
+
+    # Collect scan targets from Results
+    targets = []
+    for result in raw.get("Results", []):
+        t = result.get("Target")
+        if t:
+            targets.append(t)
+    scan_target = ", ".join(dict.fromkeys(targets)) if targets else artifact_name
+
+    # Flatten all vulnerabilities across all Results
+    vulnerabilities = []
+    for result in raw.get("Results", []):
+        for v in result.get("Vulnerabilities", []):
+            # Extract best CVSS v3 score
+            cvss = None
+            cvss_data = v.get("CVSS", {})
+            if isinstance(cvss_data, dict):
+                for vendor_scores in cvss_data.values():
+                    if isinstance(vendor_scores, dict):
+                        score = vendor_scores.get("V3Score")
+                        if score is not None:
+                            if cvss is None or score > cvss:
+                                cvss = score
+
+            fixed_version = v.get("FixedVersion") or None
+
+            vuln = {
+                "severity": (v.get("Severity") or "unknown").lower(),
+                "identifier": v.get("VulnerabilityID", "N/A"),
+                "package": v.get("PkgName", "N/A"),
+                "affected_version": v.get("InstalledVersion", "N/A"),
+                "fixed_version": fixed_version,
+                "title": v.get("Title") or (v.get("Description", "")[:120] or None),
+                "cvss": cvss,
+            }
+            vulnerabilities.append(vuln)
+
+    return {
+        "scan_date": scan_date,
+        "repository": artifact_name,
+        "package_name": artifact_name,
+        "package_version": metadata.get("ImageID", "latest").replace("sha256:", "")[:12] if metadata.get("ImageID") else "latest",
+        "package_format": package_format,
+        "scan_target": scan_target,
+        "scan_id": report_id,
+        "vulnerabilities": vulnerabilities,
+    }
+
+
+def normalize_cloudsmith_cli(raw: dict) -> dict:
+    """Transform Cloudsmith CLI JSON into the internal report format."""
+    data = raw["data"]
+    pkg = data.get("package", {})
+
+    # Extract namespace and repository from the API URL
+    # e.g. https://api.cloudsmith.io/v1/packages/colinmoynes-test-org/java/…
+    url = pkg.get("url", "")
+    namespace, repository = "unknown", "unknown"
+    parts = url.rstrip("/").split("/")
+    # Find "packages" in the URL and grab the next two segments
+    if "packages" in parts:
+        idx = parts.index("packages")
+        if idx + 2 < len(parts):
+            namespace = parts[idx + 1]
+            repository = parts[idx + 2]
+
+    scan_date = data.get("created_at", "")[:10]  # "2025-06-09T…" → "2025-06-09"
+
+    # Determine scan target and format from scans metadata
+    scans = data.get("scans", [])
+    scan_targets = []
+    scan_types = set()
+    for scan in scans:
+        if scan.get("target"):
+            scan_targets.append(scan["target"])
+        if scan.get("type"):
+            scan_types.add(scan["type"])
+    scan_target = ", ".join(dict.fromkeys(scan_targets)) if scan_targets else "Unknown"
+    package_format = ", ".join(sorted(scan_types)) if scan_types else "Unknown"
+
+    # Flatten all scan results into a single vulnerabilities list
+    vulnerabilities = []
+    for scan in scans:
+        for result in scan.get("results", []):
+            # Extract version strings from nested objects
+            affected_ver = result.get("affected_version")
+            if isinstance(affected_ver, dict):
+                affected_version = affected_ver.get("version") or affected_ver.get("raw_version", "N/A")
+            else:
+                affected_version = str(affected_ver) if affected_ver else "N/A"
+
+            fixed_ver = result.get("fixed_version")
+            if isinstance(fixed_ver, dict):
+                fixed_version = fixed_ver.get("version") or fixed_ver.get("raw_version")
+            else:
+                fixed_version = str(fixed_ver) if fixed_ver else None
+
+            if not fixed_version:
+                fixed_version = None
+
+            # Extract CVSS score from cvss_scores
+            cvss = None
+            cvss_scores = result.get("cvss_scores")
+            if isinstance(cvss_scores, list) and cvss_scores:
+                # Use the first available score
+                first = cvss_scores[0]
+                if isinstance(first, dict):
+                    cvss = first.get("score") or first.get("base_score")
+                elif isinstance(first, (int, float)):
+                    cvss = first
+            elif isinstance(cvss_scores, (int, float)):
+                cvss = cvss_scores
+
+            vuln = {
+                "severity": result.get("severity", "unknown"),
+                "identifier": result.get("vulnerability_id", "N/A"),
+                "package": result.get("package_name", "N/A"),
+                "affected_version": affected_version,
+                "fixed_version": fixed_version,
+                "title": result.get("title") or result.get("description", "")[:120] or None,
+                "cvss": cvss,
+            }
+            vulnerabilities.append(vuln)
+
+    return {
+        "scan_date": scan_date,
+        "repository": f"{namespace}/{repository}",
+        "package_name": pkg.get("name", "Unknown"),
+        "package_version": pkg.get("version", "Unknown"),
+        "package_format": package_format,
+        "scan_target": scan_target,
+        "scan_id": data.get("identifier", "N/A"),
+        "vulnerabilities": vulnerabilities,
+    }
+
+
+def normalize_cloudsmith_repo_summary(raw: dict) -> dict:
+    """Transform Cloudsmith repo-level summary JSON into a repo summary format."""
+    data = raw["data"]
+    owner = data.get("owner", "unknown")
+    repository = data.get("repository", "unknown")
+    packages = data.get("packages", [])
+
+    # Aggregate totals
+    total_critical = 0
+    total_high = 0
+    total_medium = 0
+    total_low = 0
+    total_unknown = 0
+    status_counts = {"vulnerable": 0, "no_issues_found": 0, "no_scan": 0}
+
+    normalized_packages = []
+    for pkg in packages:
+        vulns = pkg.get("vulnerabilities", {})
+        if not isinstance(vulns, dict):
+            vulns = {}
+        critical = _as_int(vulns.get("critical"))
+        high = _as_int(vulns.get("high"))
+        medium = _as_int(vulns.get("medium"))
+        low = _as_int(vulns.get("low"))
+        unknown = _as_int(vulns.get("unknown"))
+
+        total_critical += critical
+        total_high += high
+        total_medium += medium
+        total_low += low
+        total_unknown += unknown
+
+        status = pkg.get("status", "unknown")
+        if status in status_counts:
+            status_counts[status] += 1
+
+        pkg_total = critical + high + medium + low + unknown
+
+        normalized_packages.append({
+            "package": pkg.get("package", "Unknown"),
+            "slug_perm": pkg.get("slug_perm", ""),
+            "status": status,
+            "critical": critical,
+            "high": high,
+            "medium": medium,
+            "low": low,
+            "unknown": unknown,
+            "total": pkg_total,
+        })
+
+    return {
+        "report_type": "repo_summary",
+        "owner": owner,
+        "repository": repository,
+        "total_packages": len(packages),
+        "status_counts": status_counts,
+        "total_critical": total_critical,
+        "total_high": total_high,
+        "total_medium": total_medium,
+        "total_low": total_low,
+        "total_unknown": total_unknown,
+        "total_vulnerabilities": total_critical + total_high + total_medium + total_low + total_unknown,
+        "packages": normalized_packages,
+    }
+
+
+def load_vulnerability_data(source: str) -> dict:
+    """Load vulnerability data from a JSON file or stdin (when source is '-')."""
+    if source == "-":
+        return json.load(sys.stdin)
+    with open(source, "r") as f:
+        return json.load(f)
+
+
+def validate_data(data: dict) -> list[str]:
+    """Validate the structure of the input JSON. Returns a list of warnings."""
+    warnings = []
+    if not isinstance(data, dict):
+        raise SystemExit("Error: Input JSON must be a top-level object.")
+    if "vulnerabilities" not in data:
+        raise SystemExit(
+            "Error: Input JSON is missing the 'vulnerabilities' key. "
+            "If using Cloudsmith CLI output, ensure the JSON contains a 'data' object with 'scans'."
+        )
+    if not isinstance(data["vulnerabilities"], list):
+        raise SystemExit("Error: 'vulnerabilities' must be an array.")
+
+    required_fields = {"severity", "identifier", "package"}
+    for i, vuln in enumerate(data["vulnerabilities"]):
+        if not isinstance(vuln, dict):
+            warnings.append(f"  Warning: vulnerabilities[{i}] is not an object, skipping.")
+            continue
+        missing = required_fields - vuln.keys()
+        if missing:
+            warnings.append(
+                f"  Warning: vulnerabilities[{i}] is missing field(s): {', '.join(sorted(missing))}"
+            )
+    return warnings
+
+
+def count_severities(vulnerabilities: list) -> dict:
+    """Count vulnerabilities by severity level."""
+    counts = {"critical": 0, "high": 0, "medium": 0, "low": 0, "unknown": 0}
+    for vuln in vulnerabilities:
+        severity = vuln.get("severity", "unknown").lower()
+        if severity in counts:
+            counts[severity] += 1
+        else:
+            counts["unknown"] += 1
+    return counts
+
+
+def _js_string(value: object) -> str:
+    """Encode a value as a JS string literal that is safe inside <script>.
+
+    json.dumps escapes for JavaScript but not for HTML. Scanner-supplied text
+    (CVE titles come from NVD and vendor advisory feeds) containing a literal
+    "</script>" would terminate the script element early, letting anything
+    after it parse as markup. Escaping the HTML-significant characters as
+    \\uXXXX leaves the decoded string identical while making breakout
+    impossible.
+
+    json.dumps defaults to ensure_ascii=True, so U+2028/U+2029 — legal in JSON
+    but historically line terminators in JS — are already escaped.
+    """
+    return (
+        json.dumps("" if value is None else str(value))
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+    )
+
+
+@overload
+def _as_float(value: Any, default: float) -> float: ...
+@overload
+def _as_float(value: Any, default: None = None) -> float | None: ...
+
+
+def _as_float(value: Any, default: float | None = None) -> float | None:
+    """Coerce untyped scanner data to a float, or `default` if it will not.
+
+    Scores and counts arrive from third-party JSON with no type guarantee, so
+    every numeric read goes through here rather than trusting the input. The
+    overloads let callers that supply a default treat the result as a float.
+    """
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _js_number(value: Any) -> str:
+    """Encode a value as a JS number literal, or null if it is not numeric.
+
+    Interpolating an unchecked value straight into the array would emit
+    arbitrary source rather than a number.
+    """
+    number = _as_float(value)
+    return "null" if number is None else repr(number)
+
+
+def _as_int(value: Any, default: int = 0) -> int:
+    """Coerce untyped scanner data to an int, falling back to `default`."""
+    number = _as_float(value)
+    return default if number is None else int(number)
+
+
+def _js_int(value: object, default: int = 0) -> str:
+    """Encode a value as a JS integer literal, falling back to `default`."""
+    return str(_as_int(value, default))
+
+
+# Advisory identifiers permitted in a link target. Both patterns allow only
+# [A-Za-z0-9-], so a matching identifier cannot introduce path segments.
+_CVE_RE = re.compile(r"^CVE-\d{4}-\d{4,}$", re.IGNORECASE)
+_GHSA_RE = re.compile(r"^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$", re.IGNORECASE)
+
+
+def _advisory_href(identifier: str) -> str:
+    """Return the advisory URL for a well-formed identifier, or '#'.
+
+    Identifiers are scanner-supplied. Interpolating one unvalidated let ".."
+    segments collapse the path — "GHSA-../../../evil" resolved to
+    https://github.com/evil — so a crafted identifier could aim a row's link
+    at an attacker-controlled page on a domain the reader trusts.
+
+    The scheme was never at risk: both prefixes are hardcoded https origins,
+    and anything not matching a known prefix already returned "#".
+    """
+    ident = str(identifier).strip()
+    if _CVE_RE.match(ident):
+        return f"https://nvd.nist.gov/vuln/detail/{ident}"
+    if _GHSA_RE.match(ident):
+        return f"https://github.com/advisories/{ident}"
+    return "#"
+
+
+# Scanners signal "no fix" with a missing key, an empty string, or "N/A".
+NO_FIX = (None, "", "N/A")
+
+
+def has_fix(vuln: dict) -> bool:
+    """Return True if the finding carries a fixed version.
+
+    Shared by the fixable count and the table cell, so the stat card cannot
+    disagree with the rows it summarises.
+    """
+    return vuln.get("fixed_version") not in NO_FIX
+
+
+def count_fixable(vulnerabilities: list) -> int:
+    return sum(1 for v in vulnerabilities if has_fix(v))
+
+
+def _csv_filename(package_name: str, scan_date: str) -> str:
+    """Name for the CSV a reader downloads from the report.
+
+    Package names carry registry paths, tags and digests, so they are reduced
+    to filename-safe characters — the value also lands in a download
+    attribute, where a path separator would be a directory traversal.
+    """
+    stem = re.sub(r"[^\w.-]+", "-", f"{package_name}-{scan_date}").strip("-.")
+    return f"{(stem or 'vulnly-report')[:80]}-vulnerabilities.csv"
+
+
+def build_vuln_data_js(vulnerabilities: list) -> str:
+    """Build the VULN_DATA JavaScript array for the template."""
+    def _order(vuln: dict) -> tuple:
+        """Worst first: severity, then CVSS descending, unscored last.
+
+        Matches the report's default sort, so the emitted array is already in
+        the order the table shows.
+        """
+        rank = SEVERITY_ORDER.get(str(vuln.get("severity", "unknown")).lower(), 4)
+        # Unscored findings sort last within their severity.
+        score = _as_float(vuln.get("cvss"), -1.0)
+        return (rank, -score)
+
+    sorted_vulns = sorted(vulnerabilities, key=_order)
+
+    entries = []
+    for vuln in sorted_vulns:
+        identifier = vuln.get("identifier", "N/A")
+        package = vuln.get("package", "N/A")
+        severity = vuln.get("severity", "unknown").capitalize()
+        affected_version = vuln.get("affected_version", "N/A")
+        fixed_version = vuln.get("fixed_version", None)
+        title = vuln.get("title", f"{severity} vulnerability in {package}")
+        cvss = vuln.get("cvss", None)
+
+        fixed_js = _js_string(fixed_version) if has_fix(vuln) else "null"
+
+        cvss_js = _js_number(cvss)
+
+        href = _advisory_href(identifier)
+
+        entry = (
+            f"    {{\n"
+            f"      id:       {_js_string(identifier)},\n"
+            f"      pkg:      {_js_string(package)},\n"
+            f"      title:    {_js_string(title)},\n"
+            f"      sev:      {_js_string(severity)},\n"
+            f"      cvss:     {cvss_js},\n"
+            f"      affected: {_js_string(affected_version)},\n"
+            f"      fixed:    {fixed_js},\n"
+            f"      href:     {_js_string(href)}\n"
+            f"    }}"
+        )
+        entries.append(entry)
+
+    return "[\n" + ",\n".join(entries) + "\n  ]"
+
+
+def build_pkg_data_js(packages: list) -> str:
+    """Build the PKG_DATA JavaScript array for the repo summary template."""
+    # Sort: vulnerable first, then no_issues_found, then no_scan
+    status_order = {"vulnerable": 0, "no_issues_found": 1, "no_scan": 2}
+
+    def sort_key(pkg: dict) -> tuple:
+        # `total` is untyped scanner data; negating a string would raise.
+        try:
+            total = int(pkg.get("total", 0))
+        except (TypeError, ValueError):
+            total = 0
+        return (status_order.get(pkg.get("status", ""), 3), -total)
+
+    sorted_pkgs = sorted(packages, key=sort_key)
+
+    entries = []
+    for pkg in sorted_pkgs:
+        entry = (
+            f"    {{\n"
+            f"      package:   {_js_string(pkg.get('package', 'Unknown'))},\n"
+            f"      slug_perm: {_js_string(pkg.get('slug_perm', ''))},\n"
+            f"      status:    {_js_string(pkg.get('status', 'unknown'))},\n"
+            f"      critical:  {_js_int(pkg.get('critical'))},\n"
+            f"      high:      {_js_int(pkg.get('high'))},\n"
+            f"      medium:    {_js_int(pkg.get('medium'))},\n"
+            f"      low:       {_js_int(pkg.get('low'))},\n"
+            f"      unknown:   {_js_int(pkg.get('unknown'))},\n"
+            f"      total:     {_js_int(pkg.get('total'))}\n"
+            f"    }}"
+        )
+        entries.append(entry)
+
+    return "[\n" + ",\n".join(entries) + "\n  ]"
+
+
+# Maximum custom logo dimensions (pixels) and file size (bytes)
+MAX_LOGO_WIDTH = 512
+MAX_LOGO_HEIGHT = 512
+MAX_LOGO_FILE_SIZE = 2 * 1024 * 1024  # 2 MB
+
+
+def _get_image_dimensions(path: Path) -> tuple[int, int] | None:
+    """Read width and height from a PNG or JPEG file header. Returns (w, h) or None."""
+    try:
+        data = path.read_bytes()
+        # PNG: 8-byte signature, then IHDR chunk with width (4 bytes) and height (4 bytes)
+        if data[:8] == b"\x89PNG\r\n\x1a\n":
+            w, h = struct.unpack(">II", data[16:24])
+            return (w, h)
+        # JPEG: scan for SOF0/SOF2 markers
+        if data[:2] == b"\xff\xd8":
+            i = 2
+            while i < len(data) - 9:
+                if data[i] != 0xFF:
+                    break
+                marker = data[i + 1]
+                if marker in (0xC0, 0xC2):  # SOF0, SOF2
+                    h, w = struct.unpack(">HH", data[i + 5 : i + 9])
+                    return (w, h)
+                length = struct.unpack(">H", data[i + 2 : i + 4])[0]
+                i += 2 + length
+    except Exception:
+        pass
+    return None
+
+
+def _validate_custom_logo(logo_path: Path) -> bool:
+    """Validate a custom logo's file size and dimensions. Prints warnings and returns False on failure."""
+    size = logo_path.stat().st_size
+    if size > MAX_LOGO_FILE_SIZE:
+        size_mb = size / (1024 * 1024)
+        print(
+            f"WARNING: Custom logo '{logo_path.name}' is {size_mb:.1f} MB "
+            f"(max {MAX_LOGO_FILE_SIZE // (1024 * 1024)} MB). Using default logo instead.",
+            file=sys.stderr,
+        )
+        return False
+    dims = _get_image_dimensions(logo_path)
+    if dims:
+        w, h = dims
+        if w > MAX_LOGO_WIDTH or h > MAX_LOGO_HEIGHT:
+            print(
+                f"WARNING: Custom logo '{logo_path.name}' is {w}×{h}px "
+                f"(max {MAX_LOGO_WIDTH}×{MAX_LOGO_HEIGHT}px). Using default logo instead.",
+                file=sys.stderr,
+            )
+            return False
+    return True
+
+
+def _encode_logo_data_uri(logo_path: Path) -> str:
+    """Return a data URI string for the given image file."""
+    mime_type = mimetypes.guess_type(str(logo_path))[0] or "image/png"
+    logo_data = base64.b64encode(logo_path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{logo_data}"
+
+
+def _resolve_logo_html(logo_path: Path | None) -> str:
+    """Return logo HTML markup, shared by both report generators."""
+    # The header is 68px tall, so the mark has to sit inside that.
+    if logo_path and logo_path.is_file():
+        if _validate_custom_logo(logo_path):
+            data_uri = _encode_logo_data_uri(logo_path)
+            return f'<img src="{data_uri}" alt="Logo" style="height:40px;width:auto;border-radius:9px;">'
+    # Default: the icon plus a wordmark set in the report's own font, so it
+    # recolours with the theme. The icon carries no text of its own.
+    if DEFAULT_LOGO.is_file():
+        data_uri = _encode_logo_data_uri(DEFAULT_LOGO)
+        return (
+            f'<img src="{data_uri}" alt="" style="height:36px;width:auto;">'
+            f'<span class="logo-text">Vulnly</span>'
+        )
+    return '<div class="logo-mark">V</div>'
+
+
+def _resolve_footer_logo_html() -> str:
+    """Return footer logo HTML — always uses the Vulnly logo."""
+    if DEFAULT_LOGO.is_file():
+        data_uri = _encode_logo_data_uri(DEFAULT_LOGO)
+        return f'<img src="{data_uri}" alt="" style="height:22px;width:auto;vertical-align:middle;margin-right:6px;">'
+    return ''
+
+
+def generate_repo_summary_html(data: dict, template_path: Path = REPO_SUMMARY_TEMPLATE, logo_path: Path | None = None, output_path: Path | None = None, theme: str = "dark") -> str:
+    """Generate an HTML repo summary report by populating the template."""
+    template = template_path.read_text(encoding="utf-8")
+
+    logo_html = _resolve_logo_html(logo_path)
+    footer_logo_html = _resolve_footer_logo_html()
+
+    owner = data.get("owner", "unknown")
+    repository = data.get("repository", "unknown")
+    total_packages = data.get("total_packages", 0)
+    status_counts = data.get("status_counts", {})
+    total_vulns = data.get("total_vulnerabilities", 0)
+
+    report_date = datetime.datetime.now().strftime("%-d %b %Y")
+
+    count_vulnerable = status_counts.get("vulnerable", 0)
+    count_no_issues = status_counts.get("no_issues_found", 0)
+    count_no_scan = status_counts.get("no_scan", 0)
+
+    # Findings only. The owner, repository and package total are each stated
+    # once elsewhere in the hero, and the status breakdown is in the cards
+    # below, so this states the headline result and nothing more.
+    if total_vulns and count_vulnerable:
+        hero_summary = (
+            f"<strong>{total_vulns} "
+            f"{'vulnerability was' if total_vulns == 1 else 'vulnerabilities were'}</strong> "
+            f"detected across <strong>{count_vulnerable}</strong> "
+            f"{'package' if count_vulnerable == 1 else 'packages'}."
+        )
+    elif count_no_scan and not count_vulnerable:
+        # Nothing found, but the result is only as complete as the coverage.
+        hero_summary = (
+            f"No vulnerabilities were detected. "
+            f"<strong>{count_no_scan}</strong> "
+            f"{'package has' if count_no_scan == 1 else 'packages have'} not been scanned."
+        )
+    else:
+        hero_summary = "No vulnerabilities were detected."
+
+    # Executive summary
+    exec_p1 = (
+        f"A security summary of the <strong>{html.escape(repository)}</strong> repository "
+        f"owned by <strong>{html.escape(owner)}</strong> covers "
+        f"<strong>{total_packages} packages</strong>. "
+        f"Of these, <strong>{count_vulnerable} {'package is' if count_vulnerable == 1 else 'packages are'} vulnerable</strong>, "
+        f"<strong>{count_no_issues} {'has' if count_no_issues == 1 else 'have'} no issues</strong>, "
+        f"and <strong>{count_no_scan} {'has' if count_no_scan == 1 else 'have'} not been scanned</strong>."
+    )
+    exec_p2 = (
+        f"Across all scanned packages, a total of <strong>{total_vulns} vulnerabilities</strong> "
+        f"were identified: <strong>{data.get('total_critical', 0)} Critical</strong>, "
+        f"<strong>{data.get('total_high', 0)} High</strong>, "
+        f"<strong>{data.get('total_medium', 0)} Medium</strong>, and "
+        f"<strong>{data.get('total_low', 0)} Low</strong> severity."
+    )
+
+    if count_vulnerable > 0:
+        alert_text = (
+            f"{count_vulnerable} vulnerable "
+            f"{'package requires' if count_vulnerable == 1 else 'packages require'} "
+            f"review. A total of {total_vulns} vulnerabilities were found across these packages."
+        )
+        alert_class = ""
+        alert_icon = "⚡"
+        alert_title = "Action Required:"
+    else:
+        alert_text = (
+            f"No vulnerable packages were found in this repository. "
+            f"{count_no_scan} {'package has' if count_no_scan == 1 else 'packages have'} not yet been scanned."
+        )
+        alert_class = "info"
+        alert_icon = "✓"
+        alert_title = "Repository Clean:"
+
+    replacements = {
+        "{{THEME_ATTR}}": ' data-theme="light"' if theme == "light" else "",
+        "{{OWNER}}": html.escape(owner),
+        "{{REPOSITORY}}": html.escape(repository),
+        "{{TOTAL_PACKAGES}}": str(total_packages),
+        "{{HERO_SUMMARY}}": hero_summary,
+        "{{COUNT_VULNERABLE}}": str(count_vulnerable),
+        "{{COUNT_NO_ISSUES}}": str(count_no_issues),
+        "{{COUNT_NO_SCAN}}": str(count_no_scan),
+        "{{TOTAL_VULNS}}": str(total_vulns),
+        "{{COUNT_CRITICAL}}": str(data.get("total_critical", 0)),
+        "{{COUNT_HIGH}}": str(data.get("total_high", 0)),
+        "{{COUNT_MEDIUM}}": str(data.get("total_medium", 0)),
+        "{{COUNT_LOW}}": str(data.get("total_low", 0)),
+        "{{COUNT_UNKNOWN}}": str(data.get("total_unknown", 0)),
+        "{{EXEC_SUMMARY_P1}}": exec_p1,
+        "{{EXEC_SUMMARY_P2}}": exec_p2,
+        "{{ALERT_TEXT}}": alert_text,
+        "{{ALERT_CLASS}}": alert_class,
+        "{{ALERT_ICON}}": alert_icon,
+        "{{ALERT_TITLE}}": alert_title,
+        "{{REPORT_DATE}}": html.escape(report_date),
+        "{{LOGO_HTML}}": logo_html,
+        "{{FOOTER_LOGO_HTML}}": footer_logo_html,
+        "{{CHART_JS}}": _read_chart_js(),
+        "{{FONT_WOFF2_B64}}": _read_font_b64(),
+        "{{FAVICON_B64}}": _read_favicon_b64(),
+    }
+
+    template = _apply_replacements(template, replacements)
+
+    # Replace PKG_DATA array
+    pkg_data_js = build_pkg_data_js(data.get("packages", []))
+    replacement = f"const PKG_DATA = {pkg_data_js};"
+    template = re.sub(
+        r"const PKG_DATA = \[.*?\];",
+        lambda _: replacement,
+        template,
+        count=1,
+        flags=re.DOTALL,
+    )
+
+    return template
+
+
+def generate_html(data: dict, template_path: Path = REPORT_TEMPLATE, logo_path: Path | None = None, output_path: Path | None = None, theme: str = "dark") -> str:
+    """Generate the full HTML report by populating the template."""
+    template = template_path.read_text(encoding="utf-8")
+
+    logo_html = _resolve_logo_html(logo_path)
+    footer_logo_html = _resolve_footer_logo_html()
+
+    vulnerabilities = data.get("vulnerabilities", [])
+    counts = count_severities(vulnerabilities)
+    total = len(vulnerabilities)
+
+    scan_path = data.get("repository", "Unknown")
+    pkg_name = data.get("package_name", "Unknown")
+    pkg_version = data.get("package_version", "Unknown")
+    # Snyk and Grype carry no scan timestamp, so their normalizers emit an
+    # empty string. The key is present, so a plain .get() default never fires
+    # and the empty value reached the report — fall back on falsy, not missing.
+    scan_date = data.get("scan_date") or datetime.datetime.now().strftime("%Y-%m-%d")
+
+    # Format display date (e.g. "13 Mar 2026")
+    try:
+        dt = datetime.datetime.strptime(scan_date, "%Y-%m-%d")
+        scan_date_display = dt.strftime("%-d %b %Y")
+    except ValueError:
+        scan_date_display = scan_date
+
+    report_date = datetime.datetime.now().strftime("%-d %b %Y")
+
+    # Only image/registry scanners set repository to the package name itself;
+    # for those the path adds nothing, so it is dropped rather than repeated.
+    path_is_distinct = bool(scan_path) and scan_path != pkg_name
+
+    if path_is_distinct:
+        path_clause = f"in the <strong>{html.escape(scan_path)}</strong> repository "
+        path_footer_html = f"Path: <strong>{html.escape(scan_path)}</strong> &bull;\n    "
+    else:
+        path_clause = ""
+        path_footer_html = ""
+
+    # The line beneath the report title: what was scanned, once. The separator
+    # is only emitted between two present values, so a scan with just a version
+    # does not render a leading bullet.
+    identity_parts = []
+    if path_is_distinct:
+        identity_parts.append(html.escape(scan_path))
+    if pkg_version and pkg_version != "Unknown":
+        identity_parts.append(html.escape(pkg_version))
+    hero_identity = '<span class="identity-sep">&middot;</span>'.join(identity_parts)
+
+    # Generate executive summary text
+    scan_scope = (
+        f"A security scan of the <strong>{html.escape(pkg_name)}</strong> package "
+        f"(version <strong>{html.escape(pkg_version)}</strong>) {path_clause}"
+    )
+
+    urgent = counts["critical"] + counts["high"]
+
+    if total > 0:
+        if urgent > 0:
+            exec_p1 = (
+                f"{scan_scope}"
+                f"identified a total of <strong>{total} "
+                f"{'vulnerability' if total == 1 else 'vulnerabilities'}</strong>. "
+                f"Of these, <strong>{counts['critical']} "
+                f"{'is' if counts['critical'] == 1 else 'are'} rated Critical</strong> and "
+                f"<strong>{counts['high']} "
+                f"{'is' if counts['high'] == 1 else 'are'} rated High</strong> severity."
+            )
+            exec_p2 = (
+                f"The scan also found <strong>{counts['medium']} Medium</strong> and "
+                f"<strong>{counts['low']} Low</strong> severity issues. "
+                f"Addressing Critical and High severity vulnerabilities should be prioritised "
+                f"to reduce the risk of exploitation."
+            )
+            # Name only the severities actually present, so a High-only scan
+            # does not read "0 Critical and 3 High…".
+            urgent_parts = []
+            if counts["critical"]:
+                urgent_parts.append(f"{counts['critical']} Critical")
+            if counts["high"]:
+                urgent_parts.append(f"{counts['high']} High")
+            alert_text = (
+                f"{' and '.join(urgent_parts)} severity "
+                f"{'vulnerability requires' if urgent == 1 else 'vulnerabilities require'} "
+                f"immediate review and remediation. Consult the detailed table below for "
+                f"affected packages and available fixes."
+            )
+            alert_class = ""
+            alert_icon = "⚡"
+            alert_title = "Immediate Action Required:"
+        else:
+            exec_p1 = (
+                f"{scan_scope}"
+                f"identified a total of <strong>{total} "
+                f"{'vulnerability' if total == 1 else 'vulnerabilities'}</strong>, "
+                f"<strong>none of which are rated Critical or High</strong> severity."
+            )
+            exec_p2 = (
+                f"The scan found <strong>{counts['medium']} Medium</strong> and "
+                f"<strong>{counts['low']} Low</strong> severity issues. "
+                f"These do not require immediate action, but should be reviewed and "
+                f"scheduled for remediation as part of routine maintenance."
+            )
+            alert_text = (
+                f"No Critical or High severity vulnerabilities were found. The "
+                f"{total} lower-severity {'issue' if total == 1 else 'issues'} listed below "
+                f"can be addressed as part of routine maintenance."
+            )
+            alert_class = "warn"
+            alert_icon = "ℹ"
+            alert_title = "Review Recommended:"
+
+        badge_class = ""
+        badge_text = "⚠ Vulnerabilities Detected"
+        # Findings only — the package, path, version and date are all stated
+        # once elsewhere in the hero. Scoped by affected package rather than
+        # by image layer, since scans cover Maven, npm and others too.
+        affected = len({v.get("package") for v in vulnerabilities if v.get("package")})
+        if affected == 1:
+            scope = " in 1 package"
+        elif affected > 1:
+            scope = f" across {affected} packages"
+        else:
+            scope = ""
+        hero_vuln_summary = (
+            f"<strong>{total} "
+            f"{'vulnerability was' if total == 1 else 'vulnerabilities were'}</strong> "
+            f"detected{scope}."
+        )
+    else:
+        exec_p1 = (
+            f"{scan_scope}"
+            f"identified <strong>no known vulnerabilities</strong>."
+        )
+        exec_p2 = (
+            f"No Critical, High, Medium or Low severity issues were reported by "
+            f"<strong>{html.escape(data.get('scanner_source', 'the scanner'))}</strong>. "
+            f"Re-scan when the package is updated, as new advisories are published "
+            f"against existing versions over time."
+        )
+        alert_text = (
+            f"This package is clean as of {html.escape(scan_date_display)}. "
+            f"No remediation is required — continue to monitor for newly published "
+            f"advisories affecting this version."
+        )
+        alert_class = "clean"
+        alert_icon = "✓"
+        alert_title = "No Vulnerabilities Detected:"
+        badge_class = "clean"
+        badge_text = "✓ No Vulnerabilities Detected"
+        hero_vuln_summary = "No vulnerabilities were detected."
+
+    # Replace placeholders
+    replacements = {
+        "{{THEME_ATTR}}": ' data-theme="light"' if theme == "light" else "",
+        "{{SCAN_PATH}}": html.escape(scan_path),
+        "{{HERO_IDENTITY}}": hero_identity,
+        "{{PATH_FOOTER_HTML}}": path_footer_html,
+        "{{PACKAGE_NAME}}": html.escape(pkg_name),
+        "{{PACKAGE_VERSION}}": html.escape(pkg_version),
+        "{{SCAN_DATE}}": html.escape(scan_date),
+        "{{SCAN_ID}}": html.escape(data.get("scan_id", "N/A")),
+        "{{SCANNER_SOURCE}}": html.escape(data.get("scanner_source", "Unknown")),
+        "{{REPORT_DATE}}": html.escape(report_date),
+        "{{TOTAL_VULNS}}": str(total),
+        "{{COUNT_CRITICAL}}": str(counts["critical"]),
+        "{{COUNT_HIGH}}": str(counts["high"]),
+        "{{COUNT_MEDIUM}}": str(counts["medium"]),
+        "{{COUNT_LOW}}": str(counts["low"]),
+        "{{COUNT_UNKNOWN}}": str(counts["unknown"]),
+        "{{COUNT_FIXABLE}}": str(count_fixable(vulnerabilities)),
+        "{{CSV_FILENAME}}": _csv_filename(pkg_name, scan_date),
+        "{{EXEC_SUMMARY_P1}}": exec_p1,
+        "{{EXEC_SUMMARY_P2}}": exec_p2,
+        "{{HERO_VULN_SUMMARY}}": hero_vuln_summary,
+        "{{ALERT_TEXT}}": alert_text,
+        "{{ALERT_CLASS}}": alert_class,
+        "{{ALERT_ICON}}": alert_icon,
+        "{{ALERT_TITLE}}": alert_title,
+        "{{BADGE_CLASS}}": badge_class,
+        "{{BADGE_TEXT}}": badge_text,
+        "{{LOGO_HTML}}": logo_html,
+        "{{FOOTER_LOGO_HTML}}": footer_logo_html,
+        "{{CHART_JS}}": _read_chart_js(),
+        "{{FONT_WOFF2_B64}}": _read_font_b64(),
+        "{{FAVICON_B64}}": _read_favicon_b64(),
+    }
+
+    template = _apply_replacements(template, replacements)
+
+    # Replace the example VULN_DATA array with actual data
+    vuln_data_js = build_vuln_data_js(vulnerabilities)
+    replacement = f"const VULN_DATA = {vuln_data_js};"
+    template = re.sub(
+        r"const VULN_DATA = \[.*?\];",
+        lambda _: replacement,
+        template,
+        count=1,
+        flags=re.DOTALL,
+    )
+
+    return template
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate an HTML vulnerability report from a JSON input file."
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "input",
+        help="Path to the JSON file containing vulnerability data (use '-' for stdin)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Output HTML file path (default: auto-generated from package metadata)",
+    )
+    parser.add_argument(
+        "--logo",
+        default=None,
+        help="Path to a custom logo image (embedded in the report as a data URI)",
+    )
+    parser.add_argument(
+        "--theme",
+        choices=["dark", "light"],
+        default="dark",
+        help="Report colour theme (default: dark)",
+    )
+    parser.add_argument(
+        "--source",
+        default=None,
+        help=(
+            "Scanner source format: "
+            f"{', '.join(sorted(SUPPORTED_SOURCES))} (auto-detected if omitted)"
+        ),
+    )
+    args = parser.parse_args()
+
+    if args.source and args.source.lower() not in SUPPORTED_SOURCES:
+        print(
+            f"Error: Unsupported source '{args.source}'. "
+            f"Supported sources: {', '.join(sorted(SUPPORTED_SOURCES))}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # --- Load ---------------------------------------------------------------
+    if args.input != "-" and not Path(args.input).exists():
+        print(f"Error: Input file '{args.input}' not found.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        data = load_vulnerability_data(args.input)
+    except json.JSONDecodeError as exc:
+        print(f"Error: Invalid JSON – {exc}", file=sys.stderr)
+        sys.exit(1)
+    # --- Normalize based on source ------------------------------------------
+    source = (args.source or "").lower()
+    is_repo_summary = False
+
+    # Check for repo summary format first (both explicit and auto-detect)
+    if is_cloudsmith_repo_summary_format(data):
+        is_repo_summary = True
+        source = "cloudsmith"
+        data = normalize_cloudsmith_repo_summary(data)
+    elif source == "cloudsmith":
+        if not is_cloudsmith_cli_format(data):
+            print(
+                "Error: --source cloudsmith was specified but the input does not "
+                "look like Cloudsmith CLI output (expected a top-level 'data' object "
+                "containing 'scans').",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        data = normalize_cloudsmith_cli(data)
+    elif source == "trivy":
+        if not is_trivy_format(data):
+            print(
+                "Error: --source trivy was specified but the input does not look "
+                "like Trivy JSON output (expected a top-level 'Results' array).",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        data = normalize_trivy(data)
+    elif source == "grype":
+        if not is_grype_format(data):
+            print(
+                "Error: --source grype was specified but the input does not look "
+                "like Grype JSON output (expected top-level 'matches' array and "
+                "'descriptor' object).",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        data = normalize_grype(data)
+    elif source == "snyk":
+        if not is_snyk_format(data):
+            print(
+                "Error: --source snyk was specified but the input does not look "
+                "like Snyk CLI output (expected top-level 'vulnerabilities' array, "
+                "'packageManager', and 'projectName').",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        data = normalize_snyk(data)
+    elif not source:
+        # Auto-detect
+        if is_cloudsmith_cli_format(data):
+            source = "cloudsmith"
+            data = normalize_cloudsmith_cli(data)
+        elif is_trivy_format(data):
+            source = "trivy"
+            data = normalize_trivy(data)
+        elif is_grype_format(data):
+            source = "grype"
+            data = normalize_grype(data)
+        elif is_snyk_format(data):
+            source = "snyk"
+            data = normalize_snyk(data)
+
+    data["scanner_source"] = source.capitalize() if source else "Unknown"
+
+    # --- Logo ---------------------------------------------------------------
+    logo_path = None
+    if args.logo:
+        logo_path = Path(args.logo)
+        if not logo_path.exists():
+            print(f"Error: Logo file '{args.logo}' not found.", file=sys.stderr)
+            sys.exit(1)
+
+    # --- Repo summary flow --------------------------------------------------
+    if is_repo_summary:
+        if args.output is None:
+            owner = data.get("owner", "unknown")
+            repository = data.get("repository", "unknown")
+            safe = re.sub(r'[^\w.\-]', '_', f"{owner}_{repository}_cloudsmith")
+            reports_dir = Path("reports")
+            reports_dir.mkdir(exist_ok=True)
+            args.output = str(reports_dir / f"{safe}_repo_summary_report.html")
+
+        output_path = Path(args.output)
+        report_html = generate_repo_summary_html(
+            data, template_path=REPO_SUMMARY_TEMPLATE, logo_path=logo_path,
+            output_path=output_path, theme=args.theme,
+        )
+
+        with open(args.output, "w") as f:
+            f.write(report_html)
+
+        total_pkgs = data.get("total_packages", 0)
+        status = data.get("status_counts", {})
+        total_vulns = data.get("total_vulnerabilities", 0)
+        print(f"Repo summary generated: {args.output} ({total_pkgs} packages, {total_vulns} vulnerabilities)")
+        print(
+            f"  VULNERABLE: {status.get('vulnerable', 0)}  "
+            f"NO ISSUES: {status.get('no_issues_found', 0)}  "
+            f"NOT SCANNED: {status.get('no_scan', 0)}"
+        )
+        return
+
+    # --- Validate -----------------------------------------------------------
+    warnings = validate_data(data)
+    for w in warnings:
+        print(w, file=sys.stderr)
+
+    # --- Output filename ----------------------------------------------------
+    if args.output is None:
+        repo = data.get("repository", "unknown").replace("/", "_")
+        pkg = data.get("package_name", "unknown")
+        ver = data.get("package_version", "unknown")
+        # Truncate long versions (e.g. Docker digests) to 12 chars
+        if len(ver) > 20:
+            ver = ver[:12]
+        # Sanitise for filesystem safety
+        source_tag = source if source else "unknown"
+        safe = re.sub(r'[^\w.\-]', '_', f"{repo}_{pkg}_{ver}_{source_tag}")
+        reports_dir = Path("reports")
+        reports_dir.mkdir(exist_ok=True)
+        args.output = str(reports_dir / f"{safe}_vulnerability_report.html")
+
+    # --- Generate -----------------------------------------------------------
+    output_path = Path(args.output)
+    report_html = generate_html(
+        data, template_path=REPORT_TEMPLATE, logo_path=logo_path,
+        output_path=output_path, theme=args.theme,
+    )
+
+    with open(args.output, "w") as f:
+        f.write(report_html)
+
+    # --- Terminal summary ---------------------------------------------------
+    vulnerabilities = data.get("vulnerabilities", [])
+    counts = count_severities(vulnerabilities)
+    total = len(vulnerabilities)
+    # SEVERITY_ORDER is the canonical ordering and includes `unknown`; listing
+    # the levels by hand here previously dropped it, so a scan of only
+    # unknown-severity findings reported a total and then "No vulnerabilities".
+    breakdown = "  ".join(
+        f"{sev.upper()}: {counts[sev]}"
+        for sev in sorted(SEVERITY_ORDER, key=lambda s: SEVERITY_ORDER[s])
+        if counts[sev] > 0
+    )
+    print(f"Report generated: {args.output} ({total} vulnerabilities)")
+    if breakdown:
+        print(f"  {breakdown}")
+    else:
+        print("  No vulnerabilities found.")
+
+    check_for_update()
+
+
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:(a|b|rc)(\d+))?$", re.IGNORECASE)
+# Pre-releases order before the release they lead to: 1.0.0a1 < 1.0.0b1 < 1.0.0rc1 < 1.0.0
+_PRE_ORDER = {"a": 0, "b": 1, "rc": 2}
+_RELEASE_RANK = 3
+
+
+def _version_key(version: str) -> tuple | None:
+    """Return a sortable key for a version string, or None if unrecognised."""
+    match = _VERSION_RE.match(str(version).strip())
+    if not match:
+        return None
+    major, minor, patch, pre, pre_num = match.groups()
+    if pre is None:
+        return (int(major), int(minor), int(patch), _RELEASE_RANK, 0)
+    return (int(major), int(minor), int(patch), _PRE_ORDER[pre.lower()], int(pre_num))
+
+
+UPDATE_CHECK_ENV = "VULNLY_NO_UPDATE_CHECK"
+
+
+def _update_check_enabled() -> bool:
+    """Return False when the update check should be skipped entirely.
+
+    The check costs a network round trip on every invocation, which is noise
+    in CI and unwanted on hosts with restricted egress. It is skipped when
+    opted out, and when stderr is not a terminal — the notice is written
+    there, so nobody would read it anyway.
+    """
+    if os.environ.get(UPDATE_CHECK_ENV, "").strip():
+        return False
+    try:
+        return sys.stderr.isatty()
+    except Exception:
+        return False
+
+
+def check_for_update() -> None:
+    """Check PyPI for a newer version and print a notice if available."""
+    if not _update_check_enabled():
+        return
+    try:
+        url = "https://pypi.org/pypi/vulnly/json"
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=3) as resp:
+            data = json.loads(resp.read().decode())
+        latest = data["info"]["version"]
+
+        # Comparing as strings reported an update whenever the versions merely
+        # differed, so running a build ahead of PyPI advised "upgrading" to an
+        # older release. Stay silent when either version is unrecognised rather
+        # than guess.
+        current_key = _version_key(__version__)
+        latest_key = _version_key(latest)
+        if current_key is None or latest_key is None:
+            return
+        if latest_key > current_key:
+            print(
+                f"\nUpdate available: {__version__} → {latest}  "
+                f"Run `pip install --upgrade vulnly` to update.",
+                file=sys.stderr,
+            )
+    except Exception:
+        pass  # never block the user on a failed update check
+
+
+if __name__ == "__main__":
+    main()