@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-tools/clis/maggie_security_standards.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Standards (docs/maggie-security/09-risk-report-standards-prd.md): ``checklist`` and ``threat-model``.
+
+- ``checklist`` lays the site's findings over OWASP ASVS 5.0. The requirement
+  text is read from OWASP's own CSV at run time (cached 30 days; CC BY-SA 4.0,
+  attributed in the output) rather than packaged. A requirement is ``pass``
+  only when a command that positively checks it (Maggie's coverage map) ran in
+  the last 30 days without degrading and left no open finding; ``fail`` when an
+  open finding names it; ``unknown`` when a checker exists but has not run;
+  ``manual`` when no Maggie command checks it; ``not-applicable`` for the
+  profile. It never claims compliance.
+- ``threat-model`` writes an OWASP Threat Dragon v2 model with a STRIDE diagram
+  of the site's elements and, optionally, open findings as threats.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+from pathlib import Path
+
+import maggie_security_core as core
+
+ASVS_URL = "https://raw.githubusercontent.com/OWASP/ASVS/master/5.0/docs_en/OWASP_Application_Security_Verification_Standard_5.0.0_en.csv"
+core.SOURCES.setdefault("asvs", {"hosts": ["raw.githubusercontent.com"], "ttl": "30d", "url": ASVS_URL})
+ATTRIBUTION = "OWASP Application Security Verification Standard 5.0.0, OWASP Foundation, CC BY-SA 4.0 (requirement text unchanged)."
+
+
+def data_dir() -> Path:
+    for base in (core.ROOT / "skills", core.ROOT / "bundled-skills"):
+        path = base / "maggie-security" / "data"
+        if path.is_dir():
+            return path
+    raise core.UsageError("maggie-security data folder not found")
+
+
+def load_asvs(ctx: core.Context) -> list[dict]:
+    body = ctx.cache.get("asvs", ASVS_URL, ttl="30d")
+    if body is None:
+        raise core.DegradedError("could not read the ASVS 5.0 requirements (OWASP CSV); try again online once, it is cached for 30 days")
+    rows = list(csv.DictReader(io.StringIO(body.decode("utf-8-sig"))))
+    if not rows or "req_id" not in rows[0]:
+        raise core.DegradedError("the ASVS CSV has an unexpected shape")
+    return [{"id": r["req_id"], "level": int(r["L"]), "chapter": r["chapter_id"], "chapter_name": r["chapter_name"],
+             "section": r["section_id"], "section_name": r["section_name"], "text": r["req_description"]} for r in rows]
+
+
+def latest_runs(state: core.State, days: int = 30) -> dict[str, dict]:
+    floor = core.utcnow() - core.parse_duration(f"{days}d")
+    out: dict[str, dict] = {}
+    runs = state.path("runs")
+    for path in sorted(runs.glob("*.json")) if runs.is_dir() else []:
+        try:
+            doc = json.loads(path.read_text(encoding="utf-8"))
+        except ValueError:
+            continue
+        if core.parse_time(doc["run"]["finished_at"]) >= floor:
+            out[doc["run"]["command"]] = doc
+    return out
+
+
+def checklist(ctx: core.Context) -> dict:
+    args = ctx.args
+    mapping = core.read_json(data_dir() / "asvs-map.json")
+    stack_path = ctx.state.path("inventory", "stack.json")
+    profile = args.profile or (core.read_json(stack_path)["site"].get("type") if stack_path.is_file() else core.detect_site_type(ctx.project))
+    if profile not in mapping["profiles"]:
+        profile = "node-app" if profile in ("unknown",) else profile
+    if profile not in mapping["profiles"]:
+        raise core.UsageError(f"--profile must be one of {', '.join(mapping['profiles'])}")
+    rules = mapping["profiles"][profile]
+    requirements = [r for r in load_asvs(ctx) if r["level"] <= args.level]
+    runs = latest_runs(ctx.state)
+    ledger = core.Ledger(ctx.state.path("ledger.jsonl"))
+    history = ledger.history()
+    open_by_asvs: dict[str, list[dict]] = {}
+    for doc in runs.values():
+        for finding in doc.get("findings") or []:
+            status = core.Ledger.derive(history[finding["id"]])["status"] if finding["id"] in history else finding["status"]
+            if status in ("new", "open"):
+                for asvs in finding.get("asvs_ids") or []:
+                    open_by_asvs.setdefault(asvs, []).append(finding)
+    checkers: dict[str, list[str]] = {}
+    for command, ids in mapping["coverage"].items():
+        for asvs in ids:
+            checkers.setdefault(asvs, []).append(command)
+    items = []
+    for req in requirements:
+        applicable = req["chapter"] in rules["chapters"] and req["section"] not in rules["exclude_sections"]
+        commands = checkers.get(req["id"], [])
+        ran = [c for c in commands if c in runs and not runs[c]["run"].get("degraded")]
+        if not applicable:
+            state = "not-applicable"
+        elif req["id"] in open_by_asvs:
+            state = "fail"
+        elif ran:
+            state = "pass"
+        elif commands:
+            state = "unknown"
+        else:
+            state = "manual"
+        items.append({"id": req["id"], "level": req["level"], "section": f"{req['section']} {req['section_name']}", "state": state,
+                      "checked_by": commands, "evidence": [f["id"] for f in open_by_asvs.get(req["id"], [])][:10] if state == "fail" else
+                      [runs[c]["run"]["id"] for c in ran][:3], "text": req["text"],
+                      "next": (f"run maggie security {commands[0]}" if state == "unknown" else None)})
+    counts = {s: sum(1 for i in items if i["state"] == s) for s in ("pass", "fail", "unknown", "manual", "not-applicable")}
+    result = {"schema": "maggie-security-checklist.v1", "standard": "ASVS 5.0.0", "level": args.level, "profile": profile,
+              "total": len(items), "checked": counts["pass"] + counts["fail"], **counts, "attribution": ATTRIBUTION,
+              "note": "A checklist of what Maggie could verify automatically; it is not a compliance statement.", "items": items}
+    if args.format == "md":
+        result["markdown"] = checklist_markdown(result)
+    if args.fail_on and counts["fail"]:
+        result["exit_code"] = core.EXIT_FINDINGS
+    return result
+
+
+def checklist_markdown(result: dict) -> str:
+    lines = [f"# ASVS 5.0 Level {result['level']} checklist — {result['profile']}", "",
+             f"{result['checked']} of {result['total']} requirements checked automatically · {result['pass']} passing · {result['fail']} failing · "
+             f"{result['unknown']} not run yet · {result['manual']} need a person · {result['not-applicable']} not applicable", "",
+             "| Requirement | Level | State | Checked by |", "|---|---|---|---|"]
+    for item in result["items"]:
+        if item["state"] == "not-applicable":
+            continue
+        lines.append(f"| {item['id']} {item['section']} | L{item['level']} | {item['state']} | {', '.join(item['checked_by']) or '—'} |")
+    lines += ["", result["note"], "", result["attribution"]]
+    return "\n".join(lines) + "\n"
+
+
+# --------------------------------------------------------------------------- threat model (OWASP Threat Dragon v2)
+
+
+def threat_model(ctx: core.Context) -> dict:
+    args = ctx.args
+    stack_path = ctx.state.path("inventory", "stack.json")
+    stack = core.read_json(stack_path) if stack_path.is_file() else {"site": {"id": ctx.site, "type": core.detect_site_type(ctx.project)},
+                                                                     "runtimes": [], "hosts": []}
+    profile = args.profile or stack["site"].get("type") or "static"
+    runtimes = {r["name"] for r in stack.get("runtimes") or []}
+    databases = sorted(runtimes & {"mysql", "mariadb", "postgresql", "redis", "mongodb", "memcached", "elasticsearch"})
+    cells: list[dict] = []
+    threats_by_cell: dict[str, list[dict]] = {}
+
+    def element(cid: str, shape: str, name: str, x: int, y: int, description: str, threats: list[dict]) -> None:
+        cells.append({"id": cid, "shape": shape, "position": {"x": x, "y": y}, "size": {"width": 160, "height": 80},
+                      "data": {"type": f"tm.{ {'actor': 'Actor', 'process': 'Process', 'store': 'Store'}[shape]}", "name": name,
+                               "description": description, "outOfScope": False, "hasOpenThreats": bool(threats), "threats": threats}})
+        threats_by_cell[cid] = threats
+
+    def threat(title: str, kind: str, severity: str, mitigation: str, description: str = "") -> dict:
+        return {"title": title, "type": kind, "status": "Open", "severity": severity, "description": description, "mitigation": mitigation,
+                "modelType": "STRIDE"}
+
+    element("visitor", "actor", "Visitor / attacker", 40, 160, "Anyone on the internet", [])
+    web_threats = [threat("Spoofed or stolen admin session", "Spoofing", "High", "Secure, HttpOnly, SameSite cookies; MFA for admins"),
+                   threat("Script injection in pages", "Tampering", "High", "Output encoding, CSP, code-scan rules"),
+                   threat("Brute force on login", "Denial of service", "Medium", "Rate limits (protect-plan), fail2ban/CrowdSec"),
+                   threat("Version and error disclosure", "Information disclosure", "Low", "server_tokens off, generic error pages")]
+    if profile == "wordpress":
+        web_threats.append(threat("Vulnerable plugin or theme", "Elevation of privilege", "High", "wp-check daily, remove unused plugins"))
+    element("web", "process", f"{stack['site'].get('id')} ({profile})", 320, 160, "Web server and application", web_threats)
+    if databases:
+        element("db", "store", ", ".join(databases), 620, 80, "Data stores", [
+            threat("Database reachable from the internet", "Information disclosure", "High", "Bind to 127.0.0.1; host-quick hq-ports"),
+            threat("SQL injection", "Tampering", "High", "Prepared statements; code-scan maggie.php.sql-concat")])
+    element("secrets", "store", "Secrets and configuration", 620, 260, ".env, API keys, wp-config.php", [
+        threat("Secret leaked in code or build output", "Information disclosure", "High", "secrets gate before deploy; rotate first")])
+    if args.include_findings:
+        for doc in latest_runs(ctx.state).values():
+            for finding in doc.get("findings") or []:
+                if finding["status"] in ("new", "open") and finding["priority"] in ("p0", "p1", "p2"):
+                    target = "db" if (finding.get("affected") or {}).get("name") in databases and databases else \
+                        "secrets" if finding["kind"] == "secret" else "web"
+                    threats_by_cell[target].append(threat(finding["title"][:120], "Tampering" if finding["kind"] != "secret" else "Information disclosure",
+                                                          {"p0": "High", "p1": "High", "p2": "Medium"}[finding["priority"]],
+                                                          (finding.get("remediation") or {}).get("summary") or "", f"Maggie finding {finding['id']}"))
+    for cell in cells:
+        cell["data"]["threats"] = threats_by_cell[cell["id"]]
+        cell["data"]["hasOpenThreats"] = bool(threats_by_cell[cell["id"]])
+    flows = [("visitor", "web", "HTTPS requests")] + ([("web", "db", "queries")] if databases else []) + [("web", "secrets", "reads config")]
+    for index, (src, dst, label) in enumerate(flows):
+        cells.append({"id": f"flow-{index}", "shape": "flow", "source": {"cell": src}, "target": {"cell": dst},
+                      "data": {"type": "tm.Flow", "name": label, "isEncrypted": src == "visitor", "outOfScope": False, "threats": []}})
+    cells.append({"id": "boundary-0", "shape": "trust-boundary-curve", "source": {"x": 230, "y": 40}, "target": {"x": 230, "y": 320},
+                  "data": {"type": "tm.Boundary", "name": "Internet / server"}})
+    model = {"version": "2.3.0", "summary": {"title": f"{stack['site'].get('id')} threat model", "owner": "", "description":
+             "Draft generated by maggie security threat-model from the stack inventory; review and edit in OWASP Threat Dragon.", "id": 0},
+             "detail": {"contributors": [], "diagrams": [{"id": 0, "title": "Main", "diagramType": "STRIDE", "version": "2.3.0", "cells": cells}],
+                        "diagramTop": 1, "reviewer": "", "threatTop": sum(len(t) for t in threats_by_cell.values())}}
+    out = Path(args.out) if args.out else ctx.state.path("reports", "threat-model.json")
+    core.write_json(out, model)
+    return {"schema": "maggie-security-threat-model-result.v1", "path": str(out), "elements": len([c for c in cells if c["shape"] != "flow"]),
+            "threats": model["detail"]["threatTop"], "open_in": "https://www.threatdragon.com/ (Open an existing model)"}
+
+
+def _checklist(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--profile", choices=["static", "wordpress", "node-app", "php-app", "python-app", "java-app", "workers", "astro"])
+    p.add_argument("--level", type=int, choices=[1, 2, 3], default=1)
+
+
+def _threat(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--profile", choices=["static", "wordpress", "node-app", "php-app", "python-app", "java-app"])
+    p.add_argument("--include-findings", action="store_true")
+    p.add_argument("--out")
+
+
+COMMANDS = [
+    core.Command("checklist", "OWASP ASVS 5.0 checklist filled from your findings (what passed, failed, was not checked, or needs a person)",
+                 ["asvs"], _checklist, checklist, findings=False),
+    core.Command("threat-model", "draft an OWASP Threat Dragon model (STRIDE) from the stack and open findings", [], _threat, threat_model,
+                 findings=False),
+]

package/bundled-tools/clis/maggie_security_versions.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""Version ordering and range evaluation for every stack the security watch covers.
+
+Standard library only. Ecosystems:
+
+- SemVer (npm, crates.io, Go modules, Node core, Hex, Pub): precedence after
+  osv.dev ``osv/semver_index.py`` (Apache-2.0, Google LLC): coerce, then
+  compare core numerically and pre-release identifiers per SemVer 2.0 rule 11.
+- npm ranges (``^ ~ x * >= < || hyphen``) for Node core ``vulnerable`` /
+  ``patched`` and package.json engines.
+- Generic dotted versions with qualifiers (PyPI, Maven, NuGet, RubyGems,
+  Packagist, WordPress, nginx, PHP, databases, endoflife.date cycles):
+  numeric segments compare numerically; ``dev < alpha < beta < milestone <
+  rc < (release) < sp/post/patch`` as Maven and PEP 440 order them.
+- Debian/Ubuntu dpkg ordering (epoch, upstream, revision; ``~`` sorts first)
+  for OS packages.
+- OSV ``affected[].ranges[].events`` and CVE JSON 5 ``versions[]`` evaluation.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+from typing import Iterable
+
+SEMVER_ECOSYSTEMS = {"npm", "crates.io", "go", "hex", "pub", "node", "semver", "bun"}
+DPKG_ECOSYSTEMS = {"debian", "ubuntu", "deb"}
+
+# --------------------------------------------------------------------------- semver
+
+_SEMVER = re.compile(r"^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$")
+
+
+def parse_semver(version: str) -> tuple[int, int, int, tuple] | None:
+    """Coerce like osv.dev semver_index.coerce: leading v, missing minor/patch -> 0."""
+    match = _SEMVER.match(version.strip())
+    if not match:
+        return None
+    major, minor, patch, pre = match.groups()
+    pre_parts: tuple = ()
+    if pre:
+        pre_parts = tuple((0, int(p), "") if p.isdecimal() else (1, 0, p) for p in pre.split("."))
+    return int(major), int(minor or 0), int(patch or 0), pre_parts
+
+
+def compare_semver(a: str, b: str) -> int:
+    pa, pb = parse_semver(a), parse_semver(b)
+    if pa is None or pb is None:
+        return compare_generic(a, b)
+    if pa[:3] != pb[:3]:
+        return -1 if pa[:3] < pb[:3] else 1
+    # A pre-release has lower precedence than the release (rule 11.3).
+    if pa[3] == pb[3]:
+        return 0
+    if not pa[3]:
+        return 1
+    if not pb[3]:
+        return -1
+    return -1 if pa[3] < pb[3] else 1
+
+
+# --------------------------------------------------------------------------- generic
+
+_QUALIFIERS = {"dev": -6, "snapshot": -5, "a": -4, "alpha": -4, "b": -3, "beta": -3, "m": -2, "milestone": -2,
+               "c": -1, "rc": -1, "cr": -1, "pre": -1, "preview": -1, "": 0, "ga": 0, "final": 0, "release": 0,
+               "stable": 0, "p": 1, "pl": 1, "patch": 1, "post": 1, "sp": 1, "r": 1}
+_TOKEN = re.compile(r"(\d+|[A-Za-z]+)")
+
+
+def _generic_tokens(version: str) -> list[tuple[int, int, str]]:
+    text = version.strip().lower()
+    text = re.sub(r"^v(?=\d)", "", text)
+    text = text.split("+", 1)[0]
+    if "!" in text:  # PEP 440 epoch
+        epoch, _, text = text.partition("!")
+        prefix = [(2, int(epoch) if epoch.isdigit() else 0, "")]
+    else:
+        prefix = [(2, 0, "")]
+    tokens = []
+    for raw in _TOKEN.findall(text):
+        if raw.isdigit():
+            tokens.append((2, int(raw), ""))
+        else:
+            rank = _QUALIFIERS.get(raw)
+            tokens.append((1, rank, "") if rank is not None else (0, 0, raw))
+    # Trailing zeros of the numeric release part and release markers do not
+    # change the version: 1.0 == 1.0.0 == 1.0-final, and 1.0-rc1 == 1-rc1.
+    split = next((i for i, t in enumerate(tokens) if t[0] != 2), len(tokens))
+    release, suffix = tokens[:split], tokens[split:]
+    while release and release[-1] == (2, 0, "") and len(release) > 1:
+        release.pop()
+    while suffix and suffix[-1] in ((2, 0, ""), (1, 0, "")):
+        suffix.pop()
+    if suffix and suffix[0] == (1, 0, ""):
+        suffix = suffix[1:]
+    return prefix + release + suffix
+
+
+def compare_generic(a: str, b: str) -> int:
+    ta, tb = _generic_tokens(a), _generic_tokens(b)
+    for index in range(max(len(ta), len(tb))):
+        xa = ta[index] if index < len(ta) else None
+        xb = tb[index] if index < len(tb) else None
+        if xa == xb:
+            continue
+        # A missing token is a release; a following number is newer, a qualifier decides itself.
+        if xa is None:
+            return -1 if xb[0] == 2 or (xb[0] == 1 and xb[1] > 0) else 1
+        if xb is None:
+            return 1 if xa[0] == 2 or (xa[0] == 1 and xa[1] > 0) else -1
+        key_a = (xa[0] == 2, xa[1] if xa[0] != 0 else 0, xa[2])
+        key_b = (xb[0] == 2, xb[1] if xb[0] != 0 else 0, xb[2])
+        if xa[0] == 1 and xb[0] == 1:
+            return -1 if xa[1] < xb[1] else 1
+        if xa[0] == 0 and xb[0] == 0:
+            return -1 if xa[2] < xb[2] else 1
+        if xa[0] != xb[0]:
+            # number > named qualifier > unknown word, except post-release qualifiers outrank nothing else
+            order = {2: 2, 1: 1, 0: 0}
+            if xa[0] == 1 and xb[0] == 0:
+                return 1
+            if xa[0] == 0 and xb[0] == 1:
+                return -1
+            return -1 if order[xa[0]] < order[xb[0]] else 1
+        return -1 if key_a < key_b else 1
+    return 0
+
+
+# --------------------------------------------------------------------------- dpkg
+
+
+def _dpkg_order(char: str) -> int:
+    if char == "~":
+        return -1
+    if char.isdigit():
+        return 0
+    if char.isalpha():
+        return ord(char)
+    return ord(char) + 256
+
+
+def _dpkg_part(a: str, b: str) -> int:
+    ia = ib = 0
+    while ia < len(a) or ib < len(b):
+        first_diff = 0
+        while (ia < len(a) and not a[ia].isdigit()) or (ib < len(b) and not b[ib].isdigit()):
+            ca = _dpkg_order(a[ia]) if ia < len(a) and not a[ia].isdigit() else 0
+            cb = _dpkg_order(b[ib]) if ib < len(b) and not b[ib].isdigit() else 0
+            if ca != cb:
+                return -1 if ca < cb else 1
+            ia += 1
+            ib += 1
+        while ia < len(a) and a[ia] == "0":
+            ia += 1
+        while ib < len(b) and b[ib] == "0":
+            ib += 1
+        while ia < len(a) and a[ia].isdigit() and ib < len(b) and b[ib].isdigit():
+            if not first_diff:
+                first_diff = ord(a[ia]) - ord(b[ib])
+            ia += 1
+            ib += 1
+        if ia < len(a) and a[ia].isdigit():
+            return 1
+        if ib < len(b) and b[ib].isdigit():
+            return -1
+        if first_diff:
+            return -1 if first_diff < 0 else 1
+    return 0
+
+
+def _dpkg_split(version: str) -> tuple[int, str, str]:
+    epoch = 0
+    if ":" in version:
+        head, version = version.split(":", 1)
+        epoch = int(head) if head.isdigit() else 0
+    upstream, _, revision = version.rpartition("-") if "-" in version else (version, "", "0")
+    return epoch, upstream or version, revision or "0"
+
+
+def compare_dpkg(a: str, b: str) -> int:
+    ea, ua, ra = _dpkg_split(a.strip())
+    eb, ub, rb = _dpkg_split(b.strip())
+    if ea != eb:
+        return -1 if ea < eb else 1
+    return _dpkg_part(ua, ub) or _dpkg_part(ra, rb)
+
+
+# --------------------------------------------------------------------------- dispatch
+
+
+def compare(ecosystem: str | None, a: str, b: str) -> int:
+    eco = (ecosystem or "").split(":", 1)[0].strip().lower()
+    if eco in DPKG_ECOSYSTEMS:
+        return compare_dpkg(a, b)
+    if eco in SEMVER_ECOSYSTEMS and parse_semver(a) and parse_semver(b):
+        return compare_semver(a, b)
+    return compare_generic(a, b)
+
+
+def sort_key(ecosystem: str | None):
+    return functools.cmp_to_key(lambda x, y: compare(ecosystem, x, y))
+
+
+def cycle_of(version: str, parts: int = 2) -> str:
+    numbers = re.findall(r"\d+", version.split("+", 1)[0])
+    return ".".join(numbers[:parts]) if numbers else version
+
+
+# --------------------------------------------------------------------------- npm ranges
+
+
+def _expand_partial(op: str, version: str) -> list[tuple[str, str]]:
+    raw = version.strip().lstrip("v=")
+    parts = raw.split("-", 1)[0].split(".")
+    wild = [p in ("x", "X", "*", "") for p in parts] + [True] * (3 - len(parts))
+    nums = [int(p) if p.isdigit() else 0 for p in parts] + [0] * (3 - len(parts))
+    pre = "-" + raw.split("-", 1)[1] if "-" in raw else ""
+    if raw in ("", "*", "x", "X"):
+        return [(">=", "0.0.0")]
+    if op == "^":
+        if wild[1]:
+            return [(">=", f"{nums[0]}.0.0{pre}"), ("<", f"{nums[0] + 1}.0.0-0")]
+        if nums[0] > 0:
+            return [(">=", f"{nums[0]}.{nums[1]}.{nums[2]}{pre}"), ("<", f"{nums[0] + 1}.0.0-0")]
+        if nums[1] > 0 or wild[2]:
+            return [(">=", f"0.{nums[1]}.{nums[2]}{pre}"), ("<", f"0.{nums[1] + 1}.0-0")]
+        return [(">=", f"0.0.{nums[2]}{pre}"), ("<", f"0.0.{nums[2] + 1}-0")]
+    if op == "~":
+        if wild[1]:
+            return [(">=", f"{nums[0]}.0.0{pre}"), ("<", f"{nums[0] + 1}.0.0-0")]
+        return [(">=", f"{nums[0]}.{nums[1]}.{nums[2]}{pre}"), ("<", f"{nums[0]}.{nums[1] + 1}.0-0")]
+    if wild[0]:
+        return [(">=", "0.0.0")]
+    if wild[1] or wild[2]:
+        low = f"{nums[0]}.{nums[1] if not wild[1] else 0}.0"
+        high = f"{nums[0] + 1}.0.0-0" if wild[1] else f"{nums[0]}.{nums[1] + 1}.0-0"
+        if op in ("", "="):
+            return [(">=", low), ("<", high)]
+        if op == ">":
+            return [(">=", high)]
+        if op == "<=":
+            return [("<", high)]
+        if op == ">=":
+            return [(">=", low)]
+        if op == "<":
+            return [("<", low)]
+    return [(op or "=", f"{nums[0]}.{nums[1]}.{nums[2]}{pre}")]
+
+
+def _comparators(clause: str) -> list[tuple[str, str]]:
+    clause = clause.strip()
+    hyphen = re.match(r"^(\S+)\s+-\s+(\S+)$", clause)
+    if hyphen:
+        low = _expand_partial(">=", hyphen.group(1))
+        high_raw = hyphen.group(2)
+        parts = high_raw.split(".")
+        high = _expand_partial("<=", high_raw) if len(parts) < 3 or any(p in ("x", "X", "*") for p in parts) else [("<=", high_raw)]
+        return low + high
+    out: list[tuple[str, str]] = []
+    for token in re.findall(r"(\^|~>?|>=|<=|>|<|=)?\s*([^\s<>=^~]+)", clause):
+        op, version = token
+        out.extend(_expand_partial(op.replace("~>", "~"), version))
+    return out or [(">=", "0.0.0")]
+
+
+def satisfies(version: str, range_text: str) -> bool:
+    """npm semver range check (no include-prerelease)."""
+    if parse_semver(version) is None:
+        return False
+    for clause in (range_text or "").split("||"):
+        comps = _comparators(clause)
+        ok = True
+        for op, bound in comps:
+            c = compare_semver(version, bound)
+            if (op == ">=" and c < 0) or (op == ">" and c <= 0) or (op == "<" and c >= 0) or (op == "<=" and c > 0) or (op == "=" and c != 0):
+                ok = False
+                break
+        if ok:
+            # Pre-release versions only match a clause that names the same [major, minor, patch] tuple with a pre-release.
+            pv = parse_semver(version)
+            if pv and pv[3] and not any(parse_semver(b) and parse_semver(b)[3] and parse_semver(b)[:3] == pv[:3] and not b.endswith("-0") for _, b in comps):
+                continue
+            return True
+    return False
+
+
+def lowest_satisfying(candidates: Iterable[str], range_text: str) -> str | None:
+    matching = [v for v in candidates if satisfies(v, range_text)]
+    return min(matching, key=sort_key("npm")) if matching else None
+
+
+# --------------------------------------------------------------------------- OSV and CVE ranges
+
+
+def osv_affected(version: str, affected: dict, ecosystem: str | None = None) -> tuple[bool, list[str], str]:
+    """Return (affected, fixed versions, how) for one OSV ``affected[]`` entry.
+
+    ``how`` is ``versions`` (exact list), ``range`` (SEMVER/ECOSYSTEM events) or
+    ``none``. GIT ranges are ignored (no commit information here).
+    """
+    eco = ecosystem or (affected.get("package") or {}).get("ecosystem")
+    fixed_all: list[str] = []
+    hit = False
+    how = "none"
+    if version in (affected.get("versions") or []):
+        hit, how = True, "versions"
+    for rng in affected.get("ranges") or []:
+        if rng.get("type") not in ("SEMVER", "ECOSYSTEM"):
+            continue
+        rng_eco = "semver" if rng.get("type") == "SEMVER" else eco
+        events = rng.get("events") or []
+        fixed_all += [e["fixed"] for e in events if "fixed" in e]
+        state = False
+        for event in sorted(events, key=lambda e: _event_key(e, rng_eco)):
+            if "introduced" in event:
+                intro = event["introduced"]
+                if intro == "0" or compare(rng_eco, version, intro) >= 0:
+                    state = True
+            elif "fixed" in event:
+                if compare(rng_eco, version, event["fixed"]) >= 0:
+                    state = False
+            elif "last_affected" in event:
+                if compare(rng_eco, version, event["last_affected"]) > 0:
+                    state = False
+            elif "limit" in event:
+                if compare(rng_eco, version, event["limit"]) >= 0:
+                    state = False
+        if state:
+            hit, how = True, how if how == "versions" else "range"
+    return hit, sorted(set(fixed_all), key=sort_key(eco)), how
+
+
+def _event_key(event: dict, ecosystem: str | None):
+    value = next(iter(v for k, v in event.items() if k in ("introduced", "fixed", "last_affected", "limit")), "0")
+    if value == "0":
+        return (0, sort_key(ecosystem)("0"))
+    return (1, sort_key(ecosystem)(value))
+
+
+def cve_versions_affected(version: str, versions: list[dict], default_status: str = "unknown",
+                          ecosystem: str | None = None) -> tuple[bool | None, list[str]]:
+    """Evaluate CVE JSON 5 ``affected[].versions[]``; returns (affected or None if unknown, fix bounds)."""
+    fixes: list[str] = [str(e["lessThan"]) for e in versions or [] if e.get("lessThan") and e.get("lessThan") != "*"]
+    result: bool | None = None
+    for entry in versions or []:
+        status = entry.get("status", default_status)
+        start = str(entry.get("version", "")).strip()
+        less = entry.get("lessThan")
+        less_eq = entry.get("lessThanOrEqual")
+        if less or less_eq:
+            lower_ok = start in ("", "0", "*", "n/a", "unspecified") or compare(ecosystem, version, start) >= 0
+            if less in ("*",):
+                upper_ok = True
+            elif less:
+                upper_ok = compare(ecosystem, version, str(less)) < 0
+            else:
+                upper_ok = less_eq == "*" or compare(ecosystem, version, str(less_eq)) <= 0
+            if lower_ok and upper_ok:
+                result = status == "affected"
+                if result:
+                    return True, sorted(set(fixes), key=sort_key(ecosystem))
+        elif start and start not in ("*", "n/a", "unspecified", "0"):
+            if compare(ecosystem, version, start) == 0:
+                result = status == "affected"
+                if result:
+                    return True, fixes
+    if result is None and default_status == "affected" and not versions:
+        return None, fixes
+    return result, sorted(set(fixes), key=sort_key(ecosystem))
+
+
+def recommended_fix(version: str, fixed: Iterable[str], ecosystem: str | None = None) -> str | None:
+    """Smallest fixed version above the current one, preferring the same major.minor line."""
+    newer = sorted((f for f in fixed if compare(ecosystem, f, version) > 0), key=sort_key(ecosystem))
+    if not newer:
+        return None
+    line = cycle_of(version)
+    same_line = [f for f in newer if cycle_of(f) == line]
+    major = cycle_of(version, 1)
+    same_major = [f for f in newer if cycle_of(f, 1) == major]
+    return (same_line or same_major or newer)[0]