@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-tools/clis/maggie_security_deps.py

@@ -0,0 +1,560 @@
+#!/usr/bin/env python3
+"""``maggie security deps`` — docs/maggie-security/02-dependencies-supply-chain-prd.md section 6.1.
+
+Two parts, one findings set:
+
+1. Lockfiles and manifests of every ecosystem: the pinned osv-scanner binary
+   when it is installed (``scan source -r PATH --format json``, offline with
+   the mirrored DB), otherwise Maggie's native engine (the inventory parsers
+   plus OSV ``querybatch``, the same path ``vuln-watch`` uses).
+2. JavaScript copied into the site (``dist/``, ``public/``, theme and plugin
+   folders): libraries found by retire.js extractors and matched against
+   retire.js's own vulnerability repository (``jsrepository-v4.json``,
+   Apache-2.0, cached daily), which covers libraries that have no npm
+   advisory; OSV npm adds the rest.
+
+The CI gate uses ``--ci`` (SARIF, ``--fail-on high``, dev dependencies included).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import tempfile
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_intel as intel
+import maggie_security_inventory as inventory
+import maggie_security_versions as versions
+
+RETIRE_SEVERITY = {"critical": "critical", "high": "high", "medium": "medium", "low": "low", "none": "info"}
+
+
+def project_stack(ctx: core.Context) -> dict:
+    inv = inventory.Inventory(ctx.project, ctx.site, core.detect_site_type(ctx.project))
+    inv.scan_project()
+    stack = inv.stack([], [])
+    stack["runtimes"] = [r for r in stack["runtimes"] if r.get("source") not in ("runtime-inventory",)]
+    ctx.run["inputs"]["lockfiles"] = sorted({s["path"] for s in stack["sources"]})
+    ctx.run["inputs"]["parse_problems"] = inv.problems
+    return stack
+
+
+# --------------------------------------------------------------------------- osv-scanner binary
+
+
+def osv_scanner(ctx: core.Context, stack_site: str) -> list[dict] | None:
+    args = ["scan", "source", "-r", str(ctx.project), "--format", "json"]
+    env = {}
+    db = ctx.state.path("db", "osv")
+    if ctx.args.offline:
+        if not db.is_dir():
+            ctx.degrade("osv-scanner", "offline needs the mirrored OSV database in .maggie/security/db/osv (feeds mirror)")
+            return None
+        args.append("--offline-vulnerabilities")
+        env["OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY"] = str(db)
+    proc = core.run_tool("osv-scanner", args, ctx.lock, cwd=ctx.project, env=env)
+    if proc.returncode == 128:
+        ctx.run["inputs"]["osv_scanner"] = "no packages found"
+        return []
+    if proc.returncode not in (0, 1):
+        ctx.degrade("osv-scanner", core.clean_excerpt(proc.stderr.decode(errors="replace"), 200))
+        return None
+    spec = ctx.lock["tools"]["osv-scanner"]
+    ctx.run["tools"].append({"name": "osv-scanner", "version": spec["version"], "sha256": None})
+    return osv_scanner_to_findings(json.loads(proc.stdout.decode() or "{}"), ctx, stack_site)
+
+
+def osv_scanner_to_findings(data: dict, ctx: core.Context, site: str) -> list[dict]:
+    """Adapter for osv-scanner --format json (PRD 02 section 7.1)."""
+    stack = {"site": {"id": site}, "hosts": []}
+    findings = []
+    for result in data.get("results") or []:
+        source = (result.get("source") or {}).get("path") or ""
+        try:
+            rel = Path(source).resolve().relative_to(ctx.project).as_posix()
+        except ValueError:
+            rel = Path(source).name
+        for package in result.get("packages") or []:
+            pkg = package.get("package") or {}
+            groups = package.get("dependency_groups") or package.get("depGroups") or pkg.get("depGroups") or []  # osv-scanner 2.x: dependency_groups
+            comp = {"ecosystem": pkg.get("ecosystem", ""), "name": pkg.get("name", ""), "version": pkg.get("version", ""),
+                    "purl": core.make_purl(pkg.get("ecosystem", ""), pkg.get("name", ""), pkg.get("version", "")),
+                    "scope": "dev" if "dev" in groups else "runtime", "direct": None, "location": rel}
+            max_severity = {i: g.get("max_severity") for g in package.get("groups") or [] for i in g.get("ids") or []}
+            for record in package.get("vulnerabilities") or []:
+                finding = intel.osv_component_finding(ctx, stack, comp, record, "deps")
+                if not finding:
+                    continue
+                finding.pop("_how", None)
+                finding["source"]["tool"] = "osv-scanner"
+                score = max_severity.get(record.get("id"))
+                if not finding.get("cvss") and score not in (None, ""):
+                    try:
+                        finding["cvss"] = {"version": "3.1", "score": float(score), "vector": ""}
+                        finding["severity"], finding["severity_source"] = core.severity_from_cvss(float(score)), "cvss"
+                        finding["priority"] = core.compute_priority(finding)
+                    except ValueError:
+                        pass
+                findings.append(finding)
+    return findings
+
+
+# --------------------------------------------------------------------------- retire.js repository (native)
+
+
+def retire_repo(ctx: core.Context) -> dict | None:
+    return ctx.cache.get_json("retire-jsrepo", core.SOURCES["retire-jsrepo"]["url"], ttl="24h")
+
+
+def in_retire_range(version: str, vuln: dict) -> bool:
+    low = vuln.get("atOrAbove")
+    high = vuln.get("below")
+    if low and versions.compare("npm", version, low) < 0:
+        return False
+    if high and versions.compare("npm", version, high) >= 0:
+        return False
+    return bool(low or high)
+
+
+def retire_findings(ctx: core.Context, stack: dict, repo: dict) -> list[dict]:
+    npm_to_lib = {}
+    for lib, spec in repo.items():
+        npm_to_lib[(spec.get("npmname") or lib).lower()] = lib
+        npm_to_lib[lib.lower()] = lib
+    findings = []
+    for comp in stack.get("components") or []:
+        if not str(comp.get("location") or "").endswith(".js"):
+            continue
+        lib = npm_to_lib.get(comp["name"].lower())
+        if not lib:
+            continue
+        for vuln in repo[lib].get("vulnerabilities") or []:
+            if not in_retire_range(comp["version"], vuln):
+                continue
+            ids = vuln.get("identifiers") or {}
+            cves = ids.get("CVE") or []
+            aliases = cves + [i for i in [ids.get("githubID"), ids.get("issue"), ids.get("bug")] if i] + ([ids["retid"]] if ids.get("retid") else [])
+            primary = cves[0] if cves else (ids.get("githubID") or f"retire-{lib}-{vuln.get('below') or vuln.get('atOrAbove')}")
+            fixed = [vuln["below"]] if vuln.get("below") else []
+            summary = ids.get("summary") or (aliases[0] if aliases else "known vulnerability")
+            findings.append(core.make_finding(
+                kind="vulnerability", command="deps", primary_id=primary, site=ctx.site, title=f"{comp['name']} {comp['version']}: {intel.short(summary, 120)}",
+                severity=RETIRE_SEVERITY.get(str(vuln.get("severity", "")).lower(), "medium"), severity_source="tool", confidence="confirmed",
+                aliases=aliases or [primary], cwe_ids=[c for c in vuln.get("cwe") or [] if re.match(r"^CWE-\d+$", c)], asvs_ids=["V15.2.1"],
+                affected={"purl": comp.get("purl"), "ecosystem": "npm", "name": comp["name"], "version": comp["version"], "component_type": "js-bundle",
+                          "direct": True, "scope": "runtime"},
+                fix={"fixed_versions": fixed, "recommended": fixed[0] if fixed else None, "available": bool(fixed)},
+                target={"path": comp["location"]}, evidence=[{"path": comp["location"], "excerpt": f"{comp['name']} {comp['version']}"}],
+                tool="retire.js-repository", feed="retire-jsrepo", fetched_at=core.iso(),
+                remediation={"summary": f"Replace the copied {comp['name']} with {fixed[0]} or later." if fixed else f"Remove or replace {comp['name']}.",
+                             "steps": [f"Swap {comp['location']} for {comp['name']} {fixed[0]}+ (or install it from npm and bundle it)"] if fixed else [],
+                             "snippets": [], "references": (vuln.get("info") or [])[:4], "cheat_sheet": None},
+                untrusted={"summary": intel.short(summary, 300)}))
+    return findings
+
+
+# --------------------------------------------------------------------------- command
+
+
+def deps(ctx: core.Context):
+    args = ctx.args
+    if args.ci:
+        args.include_dev = True
+    stack = project_stack(ctx)
+    findings: list[dict] = []
+    engine = args.engine
+    if engine == "auto":
+        engine = "osv-scanner" if core.resolve_tool("osv-scanner", ctx.lock)[2] == "pinned" else "native"
+    covered: set[str] = set()
+    if not args.bundles_only:
+        lock_stack = dict(stack, components=[c for c in stack["components"] if not str(c.get("location") or "").endswith(".js")])
+        if engine == "osv-scanner":
+            found = osv_scanner(ctx, ctx.site)
+            ok = found is not None
+            findings += found or []
+        else:
+            ctx.run["tools"].append({"name": "maggie-osv-native", "version": core.maggie_version(), "sha256": None})
+            found, ok = intel.match_osv(ctx, dict(lock_stack, runtimes=[]), "deps")
+            findings += found
+        if ok:
+            covered |= intel._locators(dict(lock_stack, runtimes=[]), True)
+    if not args.lockfiles_only:
+        bundle_stack = dict(stack, components=[c for c in stack["components"] if str(c.get("location") or "").endswith(".js")])
+        if bundle_stack["components"]:
+            found, ok = intel.match_osv(ctx, dict(bundle_stack, runtimes=[]), "deps")
+            for finding in found:
+                finding["affected"]["component_type"] = "js-bundle"
+            findings += found
+            repo = retire_repo(ctx)
+            if repo:
+                findings += retire_findings(ctx, bundle_stack, repo)
+            if ok and repo:
+                covered |= intel._locators(dict(bundle_stack, runtimes=[]), True)
+    if not args.include_dev:
+        findings = [f for f in findings if (f.get("affected") or {}).get("scope") != "dev"]
+    stack_for_kev = {"hosts": []}
+    intel.apply_kev(findings, intel.load_kev(ctx), stack_for_kev)
+    intel.join_epss(ctx, findings)
+    ctx.run["inputs"].update({"engine": engine, "include_dev": bool(args.include_dev)})
+    return ctx.finish(findings, covered=covered)
+
+
+# --------------------------------------------------------------------------- sbom
+
+
+def sbom(ctx: core.Context) -> dict:
+    """CycloneDX 1.5 JSON: syft when installed (or for --image), else built from Maggie's inventory."""
+    args = ctx.args
+    name = args.name or ctx.site
+    out_dir = ctx.state.path("sbom")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    target = out_dir / f"{name}-{core.iso()[:10]}.cdx.json"
+    engine = args.engine
+    if engine == "auto":
+        engine = "syft" if (args.image or core.resolve_tool("syft", ctx.lock)[1] is not None) else "native"
+    if engine == "syft":
+        source = args.image if args.image else f"dir:{ctx.project}"
+        proc = core.run_tool("syft", [source, "-o", f"cyclonedx-json={target}", "-q"], ctx.lock, timeout=1800)
+        if proc.returncode != 0 or not target.is_file():
+            raise core.DegradedError(f"syft failed: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 200)}")
+    else:
+        stack = project_stack(ctx)
+        components = []
+        for comp in stack["components"]:
+            entry = {"type": "library", "name": comp["name"], "version": comp["version"], "bom-ref": comp.get("purl") or f"{comp['ecosystem']}:{comp['name']}@{comp['version']}",
+                     "properties": [{"name": "maggie:ecosystem", "value": comp["ecosystem"]}, {"name": "maggie:location", "value": str(comp.get("location") or "")},
+                                    {"name": "maggie:scope", "value": comp.get("scope") or "runtime"}]}
+            if comp.get("purl"):
+                entry["purl"] = comp["purl"]
+            components.append(entry)
+        wp = stack.get("wordpress") or {}
+        for kind, items in (("plugin", wp.get("plugins") or []), ("theme", wp.get("themes") or [])):
+            for item in items:
+                components.append({"type": "library", "name": item["slug"], "version": item.get("version") or "", "bom-ref": f"wordpress-{kind}:{item['slug']}",
+                                   "purl": f"pkg:wordpress/{item['slug']}@{item.get('version') or ''}", "properties": [{"name": "maggie:wordpress", "value": kind}]})
+        for runtime in stack.get("runtimes") or []:
+            components.append({"type": "platform" if runtime["name"] in intel.OS_RUNTIMES else "application", "name": runtime["name"],
+                               "version": runtime["version"], "bom-ref": f"runtime:{runtime['name']}@{runtime['version']}"})
+        bom = {"bomFormat": "CycloneDX", "specVersion": "1.5", "serialNumber": f"urn:uuid:{_uuid(name)}", "version": 1,
+               "metadata": {"timestamp": core.iso(), "tools": {"components": [{"type": "application", "name": "maggie-security", "version": core.maggie_version()}]},
+                            "component": {"type": "application", "name": name, "bom-ref": f"site:{name}"}},
+               "components": components}
+        core.write_json(target, bom)
+    kept = sorted(out_dir.glob(f"{name}-*.cdx.json"))
+    for old in kept[:-10]:
+        old.unlink()
+    data = core.read_json(target)
+    return {"schema": "maggie-security-sbom-result.v1", "path": str(target), "engine": engine, "components": len(data.get("components") or []),
+            "format": f"CycloneDX {data.get('specVersion')}"}
+
+
+def _uuid(seed: str) -> str:
+    digest = core.sha256_bytes(f"{seed}{core.iso()}".encode())
+    return f"{digest[:8]}-{digest[8:12]}-4{digest[13:16]}-a{digest[17:20]}-{digest[20:32]}"
+
+
+# --------------------------------------------------------------------------- image (trivy + dockle)
+
+
+TRIVY_SEVERITY = {"CRITICAL": "critical", "HIGH": "high", "MEDIUM": "medium", "LOW": "low", "UNKNOWN": "info"}
+DOCKLE_SEVERITY = {"FATAL": "high", "WARN": "medium", "INFO": "low", "SKIP": "info", "PASS": "info"}
+
+
+def trivy_to_findings(ctx: core.Context, data: dict, ref: str) -> list[dict]:
+    findings = []
+    os_meta = (data.get("Metadata") or {}).get("OS") or {}
+    if os_meta.get("EOSL"):
+        findings.append(core.make_finding(
+            kind="eol", command="image", primary_id=f"eol-image-os-{os_meta.get('Family')}", site=ctx.site,
+            title=f"The image's base OS {os_meta.get('Family')} {os_meta.get('Name')} no longer gets security fixes", severity="high",
+            severity_source="tool", confidence="confirmed", asvs_ids=["V15.2.1"],
+            affected={"purl": None, "ecosystem": None, "name": str(os_meta.get("Family")), "version": str(os_meta.get("Name")), "component_type": "os",
+                      "direct": True, "scope": "os"}, target={"image": ref}, tool="trivy",
+            remediation={"summary": "Rebuild on a supported base image (e.g. a current alpine/debian tag).", "steps": [], "snippets": [], "references": [],
+                         "cheat_sheet": None}))
+    for result in data.get("Results") or []:
+        for vuln in result.get("Vulnerabilities") or []:
+            purl = (vuln.get("PkgIdentifier") or {}).get("PURL")
+            fixed = [v.strip() for v in str(vuln.get("FixedVersion") or "").split(",") if v.strip()]
+            cvss = None
+            for source in (vuln.get("CVSS") or {}).values():
+                if source.get("V3Score"):
+                    cvss = {"version": "3.1", "score": float(source["V3Score"]), "vector": source.get("V3Vector") or ""}
+                    break
+            findings.append(core.make_finding(
+                kind="vulnerability", command="image", primary_id=vuln.get("VulnerabilityID"), site=ctx.site,
+                title=f"{vuln.get('PkgName')} {vuln.get('InstalledVersion')}: {intel.short(vuln.get('Title') or vuln.get('VulnerabilityID'), 120)}",
+                severity=TRIVY_SEVERITY.get(str(vuln.get("Severity")).upper(), "info") if not cvss else core.severity_from_cvss(cvss["score"]),
+                severity_source="cvss" if cvss else "tool", cvss=cvss, confidence="confirmed", aliases=[vuln.get("VulnerabilityID")],
+                cwe_ids=[c for c in vuln.get("CweIDs") or [] if str(c).startswith("CWE-")], asvs_ids=["V15.2.1"],
+                affected={"purl": purl.split("?")[0] if purl else None, "ecosystem": result.get("Type"), "name": vuln.get("PkgName"),
+                          "version": vuln.get("InstalledVersion"), "component_type": "image", "direct": None, "scope": "os" if result.get("Class") == "os-pkgs" else "runtime"},
+                fix={"fixed_versions": fixed, "recommended": fixed[0] if fixed else None, "available": bool(fixed)},
+                target={"image": ref, "path": result.get("Target")}, tool="trivy", rule_id=vuln.get("VulnerabilityID"),
+                remediation={"summary": f"Update {vuln.get('PkgName')} to {fixed[0]} (rebuild the image)." if fixed else "No fix yet; consider another base image.",
+                             "steps": [], "snippets": [], "references": [vuln["PrimaryURL"]] if vuln.get("PrimaryURL") else [], "cheat_sheet": None},
+                untrusted={"description": intel.short(vuln.get("Description"), 400)} if vuln.get("Description") else None))
+        for secret in result.get("Secrets") or []:
+            findings.append(core.make_finding(
+                kind="secret", command="image", primary_id=str(secret.get("RuleID")), site=ctx.site,
+                title=f"A secret ({secret.get('Title') or secret.get('RuleID')}) is baked into the image at {result.get('Target')}", severity="high",
+                severity_source="tool", confidence="likely", asvs_ids=["V13.3.1"], target={"image": ref, "path": result.get("Target")}, tool="trivy",
+                evidence=[{"path": str(result.get("Target")), "line": secret.get("StartLine")}],  # the Match line holds the value: dropped
+                remediation={"summary": "Rotate it, remove it from the image build, and pass it at run time.", "steps": [], "snippets": [], "references": [],
+                             "cheat_sheet": None}))
+        for misconfig in result.get("Misconfigurations") or []:
+            if misconfig.get("Status") == "PASS":
+                continue
+            findings.append(core.make_finding(
+                kind="misconfiguration", command="image", primary_id=str(misconfig.get("ID") or misconfig.get("AVDID")), site=ctx.site,
+                title=intel.short(misconfig.get("Title") or misconfig.get("ID"), 200), severity=TRIVY_SEVERITY.get(str(misconfig.get("Severity")).upper(), "low"),
+                severity_source="tool", confidence="likely", target={"image": ref, "path": result.get("Target")}, tool="trivy",
+                remediation={"summary": intel.short(misconfig.get("Resolution") or "", 300), "steps": [], "snippets": [], "references": [], "cheat_sheet": None}))
+    return findings
+
+
+def dockle_to_findings(ctx: core.Context, data: dict, ref: str) -> list[dict]:
+    findings = []
+    for detail in data.get("details") or []:
+        level = str(detail.get("level", "")).upper()
+        if level in ("PASS", "SKIP"):
+            continue
+        alerts = [core.mask_query(re.sub(r"(?i)((?:password|secret|token|key)[^=\s]*=)\S+", r"\1***", a)) for a in detail.get("alerts") or []]
+        findings.append(core.make_finding(
+            kind="misconfiguration", command="image", primary_id=str(detail.get("code")), site=ctx.site, title=f"{detail.get('code')}: {detail.get('title')}",
+            severity=DOCKLE_SEVERITY.get(level, "low"), severity_source="tool", confidence="likely", target={"image": ref}, tool="dockle",
+            evidence=[{"path": ref, "excerpt": core.clean_excerpt(a, 200)} for a in alerts[:3]],
+            remediation={"summary": str(detail.get("title")), "steps": [], "snippets": [],
+                         "references": [f"https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#{str(detail.get('code')).lower()}"], "cheat_sheet": None}))
+    return findings
+
+
+def image(ctx: core.Context):
+    args = ctx.args
+    ref = args.ref
+    findings: list[dict] = []
+    if args.trivy_json:
+        findings += trivy_to_findings(ctx, core.read_json(Path(args.trivy_json)), ref)
+    else:
+        db = ctx.state.path("db", "trivy")
+        argv = ["image", "--scanners", "vuln,secret,misconfig", "--format", "json", "--cache-dir", str(db), "--exit-on-eol", "0"]
+        if args.offline:
+            argv += ["--skip-db-update", "--skip-java-db-update", "--offline-scan"]
+        argv.append(ref)
+        proc = core.run_tool("trivy", argv, ctx.lock, timeout=1800)
+        if proc.returncode not in (0, 1) or not proc.stdout:
+            raise core.DegradedError(f"trivy failed: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 200)}")
+        findings += trivy_to_findings(ctx, json.loads(proc.stdout.decode()), ref)
+        ctx.run["tools"].append({"name": "trivy", "version": ctx.lock["tools"]["trivy"]["version"], "sha256": None})
+    if args.dockle_json:
+        findings += dockle_to_findings(ctx, core.read_json(Path(args.dockle_json)), ref)
+    elif not args.trivy_json and core.resolve_tool("dockle", ctx.lock)[1] is not None:
+        proc = core.run_tool("dockle", ["--format", "json", "--exit-code", "0", ref], ctx.lock, timeout=900)
+        if proc.stdout:
+            findings += dockle_to_findings(ctx, json.loads(proc.stdout.decode()), ref)
+    if args.ignore_unfixed:
+        findings = [f for f in findings if f["kind"] != "vulnerability" or (f.get("fix") or {}).get("available")]
+    intel.apply_kev(findings, intel.load_kev(ctx), {"hosts": []})
+    return ctx.finish(findings, covered=[f"image:{ref}"])
+
+
+# --------------------------------------------------------------------------- preinstall (vet a package before installing it)
+
+
+POPULAR_NPM = ["react", "react-dom", "lodash", "express", "axios", "next", "vue", "typescript", "webpack", "vite", "astro", "eslint", "prettier", "jest",
+               "moment", "dayjs", "chalk", "commander", "dotenv", "debug", "uuid", "request", "body-parser", "cors", "jsonwebtoken", "bcrypt", "mongoose",
+               "mysql2", "pg", "redis", "sharp", "nodemon", "ts-node", "zod", "yup", "tailwindcss", "postcss", "autoprefixer", "babel-core", "@babel/core",
+               "rxjs", "underscore", "async", "bluebird", "socket.io", "ws", "node-fetch", "cross-env", "rimraf", "glob", "minimist", "yargs", "colors",
+               "electron", "puppeteer", "playwright", "cheerio", "nodemailer", "stripe", "openai", "@anthropic-ai/sdk", "prisma", "@prisma/client",
+               "sequelize", "knex", "passport", "helmet", "morgan", "multer", "date-fns", "classnames", "styled-components", "graphql", "apollo-server"]
+core.SOURCES.setdefault("npm-registry", {"hosts": ["registry.npmjs.org"], "ttl": "6h", "url": "https://registry.npmjs.org/{name}"})
+core.SOURCES.setdefault("scorecard", {"hosts": ["api.scorecard.dev"], "ttl": "7d", "url": "https://api.scorecard.dev/projects/github.com/{owner}/{repo}"})
+
+
+def edit_distance(a: str, b: str) -> int:
+    """Optimal string alignment distance: a swap of two neighbouring letters counts as one edit (lodash/lodahs)."""
+    rows = [[0] * (len(b) + 1) for _ in range(len(a) + 1)]
+    for i in range(len(a) + 1):
+        rows[i][0] = i
+    for j in range(len(b) + 1):
+        rows[0][j] = j
+    for i in range(1, len(a) + 1):
+        for j in range(1, len(b) + 1):
+            cost = a[i - 1] != b[j - 1]
+            rows[i][j] = min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost)
+            if i > 1 and j > 1 and a[i - 1] == b[j - 2] and a[i - 2] == b[j - 1]:
+                rows[i][j] = min(rows[i][j], rows[i - 2][j - 2] + 1)
+    return rows[-1][-1]
+
+
+def typosquat_of(name: str) -> str | None:
+    bare = name.split("/")[-1].lower()
+    if name in POPULAR_NPM:
+        return None
+    for popular in POPULAR_NPM:
+        target = popular.split("/")[-1]
+        if bare != target and len(target) >= 4 and (edit_distance(bare, target) == 1 or bare.replace("-", "") == target.replace("-", "")
+                                                     or bare in (target + "js", target + "-js", "node-" + target)):
+            return popular
+    return None
+
+
+def preinstall(ctx: core.Context) -> dict:
+    args = ctx.args
+    verdicts = []
+    for spec in args.packages:
+        name, _, version = spec.rpartition("@") if spec.rfind("@") > 0 else (spec, "", "")
+        meta = ctx.cache.get_json("npm-registry", f"https://registry.npmjs.org/{name.replace('/', '%2F')}", ttl="6h")
+        reasons_block, reasons_warn, info = [], [], {}
+        if meta is None:
+            verdicts.append({"package": spec, "verdict": "unknown", "block": [], "warn": ["npm registry did not answer or the package does not exist"]})
+            continue
+        version = version or (meta.get("dist-tags") or {}).get("latest")
+        manifest = (meta.get("versions") or {}).get(version)
+        if not manifest:
+            verdicts.append({"package": spec, "verdict": "block", "block": [f"version {version} does not exist"], "warn": []})
+            continue
+        times = meta.get("time") or {}
+        created = times.get("created")
+        published = times.get(version)
+        now = core.utcnow()
+        age_days = (now - core.parse_time(created)).days if created else None
+        version_hours = (now - core.parse_time(published)).total_seconds() / 3600 if published else None
+        scripts = {k: v for k, v in (manifest.get("scripts") or {}).items() if k in ("preinstall", "install", "postinstall", "prepare")}
+        info.update({"version": version, "package_age_days": age_days, "version_age_hours": round(version_hours or 0, 1),
+                     "maintainers": len(meta.get("maintainers") or []), "install_scripts": sorted(scripts), "license": manifest.get("license")})
+        squat = typosquat_of(name)
+        if squat:
+            reasons_block.append(f"name looks like a typo of the popular package {squat}")
+        if scripts and age_days is not None and age_days < 30:
+            reasons_block.append(f"runs install scripts ({', '.join(sorted(scripts))}) and the package is only {age_days} days old")
+        elif scripts:
+            reasons_warn.append(f"runs install scripts: {', '.join(sorted(scripts))}")
+        if age_days is not None and age_days < 30:
+            reasons_warn.append(f"the package is only {age_days} days old")
+        if version_hours is not None and version_hours < 72:
+            hours = round(version_hours)
+            reasons_warn.append(f"this version was published {hours} hour{'s' if hours != 1 else ''} ago (wait 3 days for new releases, or pin the previous one)")
+        if manifest.get("deprecated"):
+            reasons_warn.append(f"deprecated: {core.clean_excerpt(str(manifest['deprecated']), 120)}")
+        stack = {"site": {"id": ctx.site}, "hosts": [], "runtimes": [],
+                 "components": [{"purl": core.make_purl("npm", name, version), "ecosystem": "npm", "name": name, "version": version, "scope": "runtime",
+                                 "direct": True, "location": "preinstall"}]}
+        found, ok = intel.match_osv(ctx, stack, "preinstall")
+        for finding in found:
+            if finding["kind"] == "malicious-package":
+                reasons_block.append(f"known malicious package ({finding['source']['rule_id']})")
+            elif finding["severity"] in ("critical", "high") and not (finding.get("fix") or {}).get("available"):
+                reasons_block.append(f"{finding['aliases'][0]}: {finding['severity']} with no fixed version")
+            else:
+                reasons_warn.append(f"{finding['aliases'][0]} ({finding['severity']}); fixed in {(finding.get('fix') or {}).get('recommended')}")
+        repo = str((manifest.get("repository") or {}).get("url") if isinstance(manifest.get("repository"), dict) else manifest.get("repository") or "")
+        match = re.search(r"github\.com[/:]([^/]+)/([^/.#]+)", repo)
+        if match and not args.no_scorecard:
+            score = ctx.cache.get_json("scorecard", f"https://api.scorecard.dev/projects/github.com/{match.group(1)}/{match.group(2)}", ttl="7d")
+            if score and score.get("score") is not None:
+                info["scorecard"] = score["score"]
+                if float(score["score"]) < 4.0:
+                    reasons_warn.append(f"OpenSSF Scorecard {score['score']} (below 4)")
+        if args.threshold == "strict":
+            reasons_block, reasons_warn = reasons_block + reasons_warn, []
+        verdict = "block" if reasons_block else "warn" if reasons_warn else "allow"
+        if not ok and verdict == "allow":
+            verdict = "unknown"
+        verdicts.append({"package": f"{name}@{version}", "verdict": verdict, "block": reasons_block, "warn": reasons_warn, "facts": info,
+                         "next": f"npm install {name}@{version} --save-exact" if verdict in ("allow", "warn") else None})
+    worst = "block" if any(v["verdict"] == "block" for v in verdicts) else "unknown" if any(v["verdict"] == "unknown" for v in verdicts) else         "warn" if any(v["verdict"] == "warn" for v in verdicts) else "allow"
+    return {"schema": "maggie-security-preinstall.v1", "verdict": worst, "packages": verdicts,
+            "note": "Maggie never installs anything; run the `next` command yourself if you accept the verdict.",
+            "exit_code": {"block": core.EXIT_FINDINGS, "unknown": core.EXIT_DEGRADED}.get(worst, core.EXIT_OK)}
+
+
+# --------------------------------------------------------------------------- exposure-check (known malicious packages already installed)
+
+
+def exposure_check(ctx: core.Context):
+    args = ctx.args
+    roots = [Path(r) for r in (args.root or [str(ctx.project)])]
+    components = []
+    for root in roots:
+        if not root.is_dir():
+            raise core.UsageError(f"not a folder: {root}")
+        inv = inventory.Inventory(root, ctx.site, "unknown")
+        inv.scan_project()
+        for lock in root.rglob("node_modules/.package-lock.json") if args.deep else []:
+            inv.safe(inv.parse_package_lock_json, lock)
+        components += [c for c in inv.stack([], [])["components"]]
+    catalogs = []
+    catalog_dir = Path(args.catalog_dir) if args.catalog_dir else ctx.state.path("db", "exposure")
+    for path in sorted(catalog_dir.glob("*.json")) if catalog_dir.is_dir() else []:
+        try:
+            catalogs.append(core.read_json(path))
+        except core.UsageError:
+            ctx.degrade("exposure-catalog", f"{path.name} is not valid JSON")
+    findings = []
+    for catalog in catalogs:
+        for entry in catalog.get("entries") or []:
+            for comp in components:
+                if comp["name"] == entry.get("name") and comp["ecosystem"].lower() == str(entry.get("ecosystem", comp["ecosystem"])).lower()                         and entry.get("version") in ("*", comp["version"]):
+                    findings.append(core.make_finding(
+                        kind="malicious-package", command="exposure-check", primary_id=str(entry.get("id") or f"catalog-{entry['name']}"), site=ctx.site,
+                        title=f"{comp['name']} {comp['version']} is on the incident catalog ({catalog.get('name') or 'local'})", severity="critical",
+                        severity_source="maggie", confidence="confirmed",
+                        affected={"purl": comp.get("purl"), "ecosystem": comp["ecosystem"], "name": comp["name"], "version": comp["version"],
+                                  "component_type": "library", "direct": comp.get("direct"), "scope": comp.get("scope")},
+                        target={"path": comp.get("location")}, remediation={"summary": "Remove it, rotate credentials on machines that installed it, and check how it got in.",
+                                                                           "steps": [], "snippets": [], "references": [], "cheat_sheet": None}))
+    stack = {"site": {"id": ctx.site}, "hosts": [], "runtimes": [], "components": components}
+    found, ok = intel.match_osv(ctx, stack, "exposure-check")
+    findings += [f for f in found if f["kind"] == "malicious-package"]
+    ctx.run["inputs"].update({"roots": [str(r) for r in roots], "components": len(components), "catalogs": len(catalogs)})
+    return ctx.finish(findings, covered=["*"] if ok else [])
+
+
+def configure(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--engine", choices=["auto", "osv-scanner", "native"], default="auto",
+                   help="auto: the pinned osv-scanner if installed, else Maggie's native OSV engine")
+    p.add_argument("--lockfiles-only", action="store_true")
+    p.add_argument("--bundles-only", action="store_true")
+    p.add_argument("--include-dev", action="store_true", help="report dev dependencies too (always on with --ci)")
+    p.add_argument("--no-epss", action="store_true")
+
+
+def _sbom(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--image", help="image reference (needs syft)")
+    p.add_argument("--name")
+    p.add_argument("--engine", choices=["auto", "syft", "native"], default="auto")
+
+
+def _image(p: argparse.ArgumentParser) -> None:
+    p.add_argument("ref")
+    p.add_argument("--ignore-unfixed", action="store_true")
+    p.add_argument("--trivy-json", help="parse a saved trivy JSON report instead of running trivy")
+    p.add_argument("--dockle-json", help="parse a saved dockle JSON report")
+
+
+def _preinstall(p: argparse.ArgumentParser) -> None:
+    p.add_argument("packages", nargs="+", help="npm package names, optionally @version")
+    p.add_argument("--threshold", choices=["default", "strict"], default="default")
+    p.add_argument("--no-scorecard", action="store_true")
+    p.add_argument("--no-epss", action="store_true")
+
+
+def _exposure(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--root", action="append", help="folder to check (default the project); repeatable")
+    p.add_argument("--deep", action="store_true", help="also read node_modules/.package-lock.json files")
+    p.add_argument("--catalog-dir", help="folder of incident catalogs (default .maggie/security/db/exposure)")
+    p.add_argument("--no-epss", action="store_true")
+
+
+COMMANDS = [core.Command("deps", "known vulnerabilities in dependencies (every lockfile ecosystem) and in JavaScript copied into the site",
+                         ["osv-api", "retire-jsrepo", "kev", "epss"], configure, deps),
+            core.Command("sbom", "CycloneDX SBOM of the project (or an image with syft)", [], _sbom, sbom, findings=False),
+            core.Command("image", "container image vulnerabilities, secrets and best practices (trivy + dockle)", ["kev", "github-releases"], _image, image),
+            core.Command("preinstall", "vet an npm package before installing it (age, install scripts, typosquats, malware, vulnerabilities, Scorecard)",
+                         ["npm-registry", "osv-api", "scorecard", "kev", "epss"], _preinstall, preinstall, findings=False),
+            core.Command("exposure-check", "known malicious packages already installed (OSV MAL- records and incident catalogs)", ["osv-api", "kev"],
+                         _exposure, exposure_check)]