sniffmcp-cli 0.4.1__py3-none-any.whl

sniffmcp/fleet.py

@@ -0,0 +1,182 @@
+"""Fleet scanning: audit every MCP server a user has installed, in one pass.
+
+Config sources:
+  - Claude Desktop: claude_desktop_config.json  ({"mcpServers": {...}})
+  - Claude Code:    ~/.claude.json  (user-scope "mcpServers" and per-project
+                    "projects.<path>.mcpServers"), plus ./.mcp.json
+  - Cursor:         ~/.cursor/mcp.json
+  - Windsurf:       ~/.codeium/windsurf/mcp_config.json
+  - Any JSON file with an "mcpServers" object, or a bare {name: config} map
+
+Scanning a stdio entry runs its command, exactly as your client does on
+startup. Per-server failures never abort the fleet scan — one dead server must
+not hide the other fourteen.
+"""
+from __future__ import annotations
+import asyncio, json, os
+from pathlib import Path
+
+from .client import ConnectError
+from .engine import scan
+from .models import Finding
+from .report import to_json_report, gate
+
+CONFIG_CANDIDATES = [
+    ("claude-desktop", "~/Library/Application Support/Claude/claude_desktop_config.json"),
+    ("claude-desktop", "~/.config/Claude/claude_desktop_config.json"),
+    ("claude-desktop", "~/AppData/Roaming/Claude/claude_desktop_config.json"),
+    ("cursor",         "~/.cursor/mcp.json"),
+    ("claude-code",    "~/.claude.json"),
+    ("claude-code",    "./.mcp.json"),
+    ("windsurf",       "~/.codeium/windsurf/mcp_config.json"),
+]
+
+
+def discover_config_paths() -> list[str]:
+    found = []
+    for _label, p in CONFIG_CANDIDATES:
+        pp = Path(os.path.expanduser(p)).resolve()
+        if pp.exists() and str(pp) not in found:
+            found.append(str(pp))
+    return found
+
+
+def _servers_in(block) -> dict[str, dict]:
+    if not isinstance(block, dict):
+        return {}
+    return {name: cfg for name, cfg in block.items()
+            if isinstance(cfg, dict) and ("command" in cfg or "url" in cfg)}
+
+
+def load_servers(path: str) -> dict[str, dict]:
+    raw = json.loads(Path(path).read_text())
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path}: not a JSON object")
+    servers = _servers_in(raw.get("mcpServers")) if "mcpServers" in raw else {}
+    # Claude Code keeps project-scoped servers under projects.<path>.mcpServers
+    for proj, block in (raw.get("projects") or {}).items():
+        for name, cfg in _servers_in((block or {}).get("mcpServers")).items():
+            servers.setdefault(f"{name} ({Path(proj).name})", cfg)
+    if not servers and "mcpServers" not in raw and "projects" not in raw:
+        servers = _servers_in(raw)   # bare {name: config} map
+    return servers
+
+
+async def scan_one(name: str, config: dict, fail_on: str = "high", launch: bool = True) -> dict:
+    try:
+        report, manifest = await scan(config, launch=launch)
+    except ConnectError as e:
+        return {"name": name, "target": config.get("url") or config.get("command", "?"),
+                "status": "error", "error": str(e)}
+    out = to_json_report(report.target, report.score, report.grade, report.findings, report.manifest_hash)
+    out.update(name=name, transport=report.transport, status="ok", tool_count=report.tool_count,
+               tool_names=[t.get("name") for t in manifest.get("tools", [])],
+               gate=gate(report.findings, fail_on))
+    return out
+
+
+def tool_collisions(results: list[dict]) -> list[Finding]:
+    """The same tool name exposed by two servers: the agent picks one, and a
+    malicious server can shadow a trusted one this way."""
+    owners: dict[str, list[str]] = {}
+    for r in results:
+        for t in r.get("tool_names") or []:
+            owners.setdefault(t, []).append(r["name"])
+    return [Finding("FLEET-01", "medium", f"Tool name '{t}' exposed by {len(s)} servers", ", ".join(s),
+                    "Remove one, or check which server your client actually routes this name to.", tool_name=t)
+            for t, s in sorted(owners.items()) if len(s) > 1]
+
+
+async def scan_fleet(paths: list[str] | None = None, fail_on: str = "high", launch: bool = True) -> dict:
+    if not paths:
+        paths = discover_config_paths()
+    if not paths:
+        raise ValueError("no config files found; pass paths explicitly")
+
+    servers: dict[str, dict] = {}
+    sources: dict[str, str] = {}
+    warnings = []
+    for p in paths:
+        try:
+            for name, cfg in load_servers(p).items():
+                servers.setdefault(name, cfg)   # first definition wins
+                sources.setdefault(name, p)
+        except Exception as e:
+            warnings.append(f"skipping {p}: {e}")
+
+    sem = asyncio.Semaphore(4)  # don't fork-bomb the user's machine
+    async def bounded(name, cfg):
+        async with sem:
+            r = await scan_one(name, cfg, fail_on, launch)
+            r["source"] = sources.get(name, "")
+            return r
+    results = await asyncio.gather(*[bounded(n, c) for n, c in servers.items()])
+    # Parallel cold starts (several `npx -y` downloads at once) can time out on a
+    # first run. Retry those one at a time; the package cache is warm by now.
+    for i, r in enumerate(results):
+        if r["status"] == "error" and "timed out" in r["error"] and "command" in servers[r["name"]]:
+            retry = await scan_one(r["name"], servers[r["name"]], fail_on, launch)
+            retry["source"] = r["source"]
+            results[i] = retry
+
+    ok = [r for r in results if r["status"] == "ok"]
+    errs = [r for r in results if r["status"] == "error"]
+    scores = [r["score"] for r in ok]
+    # one injection pattern across several servers is a bigger story than isolated lows
+    freq: dict[str, int] = {}
+    for r in ok:
+        for cid in {f["check_id"] for f in r["findings"] if not f.get("suppressed")
+                    and f["severity"] in ("critical", "high")}:
+            freq[cid] = freq.get(cid, 0) + 1
+    collisions = tool_collisions(ok)
+
+    summary = {
+        "scanned": len(ok), "failed": len(errs), "total": len(results),
+        "avg_score": round(sum(scores) / len(scores), 1) if scores else None,
+        "grade_distribution": {g: sum(1 for r in ok if r["grade"] == g) for g in "ABCDF"},
+        "servers_at_or_below_C": [r["name"] for r in ok if r["grade"] in ("C", "D", "F")],
+        "high_or_critical_by_check": dict(sorted(freq.items(), key=lambda kv: -kv[1])),
+        "tool_name_collisions": [{"tool": f.tool_name, "servers": f.evidence} for f in collisions],
+        "worst": sorted(((r["name"], r["score"]) for r in ok), key=lambda x: x[1])[:5],
+        # exit contract: 1 = findings at/above threshold, 3 = some servers not analysed, 0 = clean
+        "gate": 1 if any(r.get("gate") == 1 for r in ok) else (3 if errs else 0),
+        "warnings": warnings,
+    }
+    return {"summary": summary, "servers": results, "fail_on": fail_on}
+
+
+def fleet_console(fleet: dict) -> None:
+    s = fleet["summary"]
+    print(f"\nFLEET: {s['scanned']}/{s['total']} servers scanned ({s['failed']} unreachable)")
+    print(f"avg score {s['avg_score']}  grades {s['grade_distribution']}")
+    for r in sorted((r for r in fleet["servers"] if r["status"] == "ok"), key=lambda r: r["score"]):
+        flagged = [f for f in r["findings"] if f["severity"] in ("critical", "high") and not f.get("suppressed")]
+        print(f"  {r['score']:3}/100 {r['grade']}  {r['name']}  ({r['tool_count']} tools)")
+        for f in flagged[:5]:
+            print(f"           [{f['severity']}] {f['title']}")
+    for c in s["tool_name_collisions"]:
+        print(f"  [collision] tool '{c['tool']}' in: {c['servers']}")
+    for r in fleet["servers"]:
+        if r["status"] == "error":
+            print(f"  [error] {r['name']}: {r['error'][:200]}")
+    for w in s["warnings"]:
+        print(f"  [warning] {w}")
+
+
+def fleet_markdown(fleet: dict, title: str = "sniffmcp") -> str:
+    """Compact Markdown for a CI job summary."""
+    s = fleet["summary"]
+    L = [f"### {title}", "",
+         f"{s['scanned']}/{s['total']} MCP servers analysed"
+         + (f", {s['failed']} not reachable" if s["failed"] else "") + "", "",
+         "| server | grade | high / critical findings |", "|---|---|---|"]
+    for r in sorted(fleet["servers"], key=lambda r: r.get("score", -1)):
+        if r["status"] != "ok":
+            L.append(f"| `{r['name']}` | – | not analysed: {r['error'][:80]} |")
+            continue
+        bad = [f"{f['check_id']} {f['title']}" for f in r["findings"]
+               if f["severity"] in ("critical", "high") and not f.get("suppressed")]
+        L.append(f"| `{r['name']}` | {r['grade']} ({r['score']}) | {'<br>'.join(bad[:4]) or '—'} |")
+    for c in s["tool_name_collisions"]:
+        L.append(f"\nTool name `{c['tool']}` is exposed by several servers: {c['servers']}")
+    return "\n".join(L)

sniffmcp/injection.py

@@ -0,0 +1,183 @@
+"""Injection analysis for text the model reads: tool descriptions, parameter
+descriptions inside inputSchema, prompt descriptions, server instructions.
+
+Calibrated for precision over recall. A rule earns a place here only if it
+rarely fires on legitimate servers ("Send the message to a channel" and a docs
+URL are normal; "do not tell the user" is not). Every rule is run against the
+benign corpus in tests/ before it ships.
+"""
+from __future__ import annotations
+import re
+from .models import Finding
+
+# (label, severity, regex). Order is irrelevant; each rule fires at most once per text.
+RULES: list[tuple[str, str, re.Pattern]] = [
+    ("instruction override", "critical", re.compile(
+        r"(?i)\b(ignore|disregard|forget|override)\s+(all\s+|any\s+)?(the\s+|your\s+)?(previous|prior|above|earlier|preceding|other|system)\s+"
+        r"(instructions?|prompts?|messages?|rules?|guidelines?)")),
+    # "you are now a PLAYER in the game" / "Where you are now" are normal; jailbreak framings are not
+    ("role reassignment", "high", re.compile(
+        r"(?i)\b(you are now (in )?(dan|developer mode|jailbroken|unrestricted|no longer bound)"
+        r"|your new (instructions|role) (is|are)|act as the system)\b")),
+    # Self-referential hiding only. Real servers say "never tell the user the UETR alone is
+    # enough" (accuracy) and "do not show this wallet ID to the user" (UX); neither hides
+    # what the agent is doing. "Don't tell the user about this step" does.
+    ("concealment from user", "critical", re.compile(
+        r"(?i)(\b(do not|don't|never|must not)\s+(tell|inform|notify|alert)\s+the\s+user"
+        r"(\s*([.,;:)!]|$)|\s+(about\s+(this|it|these|that)|that\s+you|what\s+you|you\s+(are|have|did|will)))"
+        r"|\b(do not|don't|never)\s+(tell|mention|reveal|disclose)\s+(this|it|these)(\s+\w+)?\s+(to\s+)?the\s+user"
+        r"|\b(do not|don't|never)\s+(show|reveal|disclose|mention)\s+(this|these|the)\s+instructions?\b"
+        r"|\binstructions?\s+(is|are)\s+for\s+you\s+only"
+        r"|\b(do not|don't|never)\s+(mention|reveal|disclose)\s+that\s+you\b"
+        r"|without\s+(telling|informing|notifying|alerting)\s+the\s+user"
+        r"|hide\s+(this|it)\s+from\s+the\s+user\b(?!'s)"
+        r"|the\s+user\s+(must|should)\s+(not|never)\s+(know|see|be told))")),
+    # Medium alone (setup docs name config files; SSH *public* keys are meant to be shared).
+    # Combined with another indicator it compounds to critical.
+    ("sensitive file target", "medium", re.compile(
+        r"(?i)(~/\.ssh/(?!\S*\.pub\b)|\bid_(rsa|ed25519|ecdsa)\b(?!\.pub)|\.aws/credentials|\.kube/config"
+        r"|\.bash_history|\.zsh_history|\.git-credentials|\.docker/config\.json|/etc/shadow"
+        r"|\.(cursor|vscode)/mcp\.json|claude_desktop_config\.json|\.claude\.json)")),
+    # paired tags only: "<system>:<id>" placeholders and "[Admin]" labels are common (seen in the wild)
+    ("fake privileged tag", "high", re.compile(
+        r"(?is)<\s*(important|system|instructions?)\s*>.{3,}?<\s*/\s*\1\s*>|\[\s*system\s*\]\s*[:\-]")),
+    ("cross-tool instruction", "medium", re.compile(
+        r"(?i)\b(before|after|when|whenever)\s+(using|calling|invoking|running)\s+(any|every|all|other|another)\s+tools?\b")),
+    # needs a data object; "send them to https://…/signup" (users) and "POST it to <own API>" are normal
+    ("exfiltration directive", "high", re.compile(
+        r"(?i)\b(send|post|upload|forward|transmit|exfiltrate)\s+(everything|all\s+(files|data|keys|secrets|messages|history)"
+        r"|(the|their|its|all|any|your)\s+(\w+\s+)?(contents?|conversation|chat\s+history|history|keys?|api\s+keys?"
+        r"|tokens?|credentials?|secrets?|passwords?|env\w*|\.env))\b(?:[^.\n]|\.(?=\S)){0,60}?\sto\s+"
+        r"(https?://|[\w.+-]+@[\w-]+\.)")),
+    ("encoded payload", "high", re.compile(r"[A-Za-z0-9+/]{120,}={0,2}")),
+    # Text telling the agent to persist something into its *own* configuration (skills, rules,
+    # CLAUDE.md / AGENTS.md). It outlives the session and the server. Seen in the wild: 7 of
+    # 10,409 registry servers on 2026-10-09 (mostly skill/memory features). Needs an explicit
+    # target ("write X to/into/in <config>"); mentions and URL paths like /agents.md don't count.
+    ("writes into agent config", "medium", re.compile(
+        r"(?is)\b(write|save|create|append|add|put|install|copy|store)\b[^.]{0,100}?(\b(to|into|in|at)\b|[:(])[^.]{0,30}?"
+        r"(~/\.claude/(skills|commands|agents)|\.claude/(skills|commands|agents)|\.cursor/rules|\.cursorrules|\.windsurfrules"
+        r"|\.codex/|~/\.gemini/|(?<![/\w])(?-i:CLAUDE\.md|AGENTS\.md|GEMINI\.md))")),
+    # ...and the dangerous version: fetching or running code into that config.
+    ("installs code into agent config", "high", re.compile(
+        r"(?is)(~/\.claude/(skills|commands|agents)|\.claude/(skills|commands|agents)|\.cursor/rules|\.codex/)\S*"
+        r".{0,200}?\b(curl|wget|npm\s+install|pnpm\s+(add|install)|pip\s+install|git\s+clone|bash\s|sh\s+-c|node\s+\S+\.m?js)"
+        r"|\b(curl|wget|git\s+clone)\b.{0,200}?(~/\.claude/(skills|commands|agents)|\.cursor/rules|\.codex/)")),
+]
+
+# A rule that matches a *mention* (a security tool listing "ignore previous instructions"
+# as a pattern it detects, or "never allow X to override system rules") is not an attack.
+MENTION_BEFORE = re.compile(
+    r"(?i)([\"'“‘(/`]\s*$|\b(never|not|don't|do not)\s+(allow|let)\b[^.]{0,40}$"
+    r"|\b(detect|detects|flag|flags|block|blocks|catch|catches|against|patterns?|phrases?|phrasing|such as|e\.g\.|like|attempts?\s+to)\b[^.]{0,60}$)")
+MENTION_RULES = {"instruction override", "role reassignment"}
+
+
+def looks_encoded(s: str) -> bool:
+    """Base64 payloads mix cases and digits with few slashes; hex strings, slash-separated
+    word lists and long identifiers don't."""
+    if re.fullmatch(r"[0-9a-fA-F]+", s) or s.count("/") > len(s) / 25:
+        return False
+    return bool(re.search(r"[a-z]", s) and re.search(r"[A-Z]", s) and re.search(r"[0-9]", s))
+
+
+# Invisible / direction-control characters have no business in text a model reads:
+# zero-width, bidi overrides, and Unicode tag characters (ASCII smuggling).
+HIDDEN_CHARS = re.compile("[​-‏‪-‮⁠-⁤⁦-⁩\U000e0000-\U000e007f]")
+
+JOINER_SCRIPTS = re.compile("[\u0600-\u06ff\u0750-\u077f\u0900-\u0dff\U0001f300-\U0001faff]")
+LONG_DESCRIPTION = 2500
+
+
+def _counts(label: str, text: str, m: re.Match) -> bool:
+    if label == "encoded payload":
+        return looks_encoded(m.group(0))
+    if label in MENTION_RULES:
+        return not MENTION_BEFORE.search(text[max(0, m.start() - 80):m.start()])
+    return True
+
+
+def scan_text(text: str) -> list[tuple[str, str, str]]:
+    """Return [(label, severity, snippet)] for one piece of model-visible text."""
+    if not text:
+        return []
+    hits = []
+    for label, sev, rx in RULES:
+        m = next((m for m in rx.finditer(text) if _counts(label, text, m)), None)
+        if m:
+            a, b = max(0, m.start() - 30), min(len(text), m.end() + 30)
+            hits.append((label, sev, text[a:b].replace("\n", " ")))
+    hidden = HIDDEN_CHARS.findall(text)
+    if hidden and JOINER_SCRIPTS.search(text):
+        # ZWNJ/ZWJ are ordinary in Persian, Arabic, Indic scripts and emoji sequences
+        hidden = [c for c in hidden if c not in "\u200c\u200d"]
+    if hidden:
+        codes = sorted({f"U+{ord(c):04X}" for c in hidden})
+        hits.append(("hidden unicode characters", "critical", f"{len(hidden)} chars: {', '.join(codes[:6])}"))
+    # Independent indicators in one text compound: a fake <IMPORTANT> tag on its own
+    # might be sloppy docs, but a tag plus a credential path is an attack.
+    serious = {label for label, sev, _ in hits if sev in ("critical", "high") or label == "sensitive file target"}
+    if len(serious) >= 2 and not any(sev == "critical" for _, sev, _ in hits):
+        hits.append(("multiple injection indicators", "critical", ", ".join(sorted(serious))))
+    return hits
+
+
+def schema_texts(schema: dict, path: str = "") -> list[tuple[str, str]]:
+    """Every description/title/default/enum string nested in a JSON schema."""
+    out = []
+    if not isinstance(schema, dict):
+        return out
+    for key in ("description", "title"):
+        if isinstance(schema.get(key), str):
+            out.append((f"{path or 'schema'}.{key}", schema[key]))
+    if isinstance(schema.get("default"), str):
+        out.append((f"{path or 'schema'}.default", schema["default"]))
+    for name, sub in (schema.get("properties") or {}).items():
+        out.extend(schema_texts(sub, f"{path}.{name}" if path else name))
+    for key in ("items", "additionalProperties"):
+        if isinstance(schema.get(key), dict):
+            out.extend(schema_texts(schema[key], f"{path}[]" if path else "[]"))
+    for key in ("anyOf", "oneOf", "allOf"):
+        for i, sub in enumerate(schema.get(key) or []):
+            out.extend(schema_texts(sub, f"{path}<{key}{i}>"))
+    return out
+
+
+def tool_texts(tool: dict) -> list[tuple[str, str]]:
+    """(location, text) for every model-visible string on a tool."""
+    out = [("description", tool.get("description") or "")]
+    if tool.get("title"):
+        out.append(("title", tool["title"]))
+    out.extend(schema_texts(tool.get("inputSchema") or {}))
+    return out
+
+
+def analyze_descriptions(tools: list[dict], llm_hook=None) -> list[Finding]:
+    """Heuristic pass over every tool (INJ-HEUR), plus an optional second opinion
+    (INJ-LLM). llm_hook: (name, description) -> ("clean"|"suspicious", reason)."""
+    findings = []
+    for t in tools or []:
+        name = t.get("name")
+        for where, text in tool_texts(t):
+            for label, sev, snippet in scan_text(text):
+                findings.append(Finding(
+                    "INJ-HEUR", sev, f"Injection indicator in tool '{name}': {label}",
+                    f"{where}: …{snippet}…",
+                    "Text in tool metadata is read by the model as instructions. Do not install, "
+                    "or pin and review the server source before trusting it.",
+                    tool_name=name))
+        desc = t.get("description") or ""
+        if len(desc) > LONG_DESCRIPTION:
+            findings.append(Finding(
+                "INJ-HEUR", "info", f"Very long description on '{name}' ({len(desc)} chars)",
+                "Long descriptions cost context on every turn and make hidden instructions easier to bury.",
+                "Review the full text once.", tool_name=name))
+        if llm_hook:
+            try:
+                verdict, reason = llm_hook(name, desc)
+            except Exception as e:
+                verdict, reason = "error", str(e)
+            if verdict == "suspicious":
+                findings.append(Finding("INJ-LLM", "medium", f"LLM flagged description of '{name}'",
+                                        reason, "Review this description manually.", tool_name=name))
+    return findings

sniffmcp/models.py

@@ -0,0 +1,53 @@
+"""Core data types shared by checks, scoring, reports and the watcher."""
+from __future__ import annotations
+import hashlib, json, time
+from dataclasses import dataclass, field, asdict
+
+
+@dataclass
+class Finding:
+    check_id: str
+    severity: str                 # critical | high | medium | low | info
+    title: str
+    evidence: str = ""
+    remediation: str = ""
+    tool_name: str | None = None
+    kind: str = ""                # for drift findings: breaking | risky | benign
+    suppressed: bool = False
+
+
+@dataclass
+class ScanReport:
+    target: str
+    transport: str
+    score: int
+    grade: str
+    findings: list[Finding]
+    manifest_hash: str
+    tool_count: int
+    scanned_at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["findings"] = [asdict(f) for f in self.findings]
+        return d
+
+
+def _tool_key(t: dict) -> dict:
+    return {"name": t.get("name"), "description": t.get("description") or "",
+            "inputSchema": t.get("inputSchema") or {}, "annotations": t.get("annotations") or {}}
+
+
+def canonical_manifest_hash(tools, resources=None, prompts=None) -> str:
+    """SHA-256 over everything the agent sees: tool names, descriptions, input
+    schemas (parameter descriptions are an injection surface too), annotations,
+    resources and prompts. Order-independent."""
+    blob = {
+        "tools": sorted((_tool_key(t) for t in tools or []), key=lambda t: t["name"] or ""),
+        "resources": sorted(({"uri": str(r.get("uri", "")), "name": r.get("name"),
+                              "description": r.get("description") or ""}
+                             for r in resources or []), key=lambda r: r["uri"]),
+        "prompts": sorted(({"name": p.get("name"), "description": p.get("description") or ""}
+                           for p in prompts or []), key=lambda p: p["name"] or ""),
+    }
+    return hashlib.sha256(json.dumps(blob, sort_keys=True).encode()).hexdigest()

sniffmcp/osv.py

@@ -0,0 +1,132 @@
+"""Known-malware and known-vulnerability lookups via OSV.dev (free, public, no key).
+
+OSV aggregates the OpenSSF malicious-packages feed (IDs "MAL-…") and vulnerability
+databases (GHSA, PYSEC, CVE aliases). We use:
+  POST /v1/querybatch   up to 1000 (package, version) queries per call -> vuln IDs
+  GET  /v1/vulns/{id}   summary, aliases, severity for each ID we need to show
+
+Checks run *before* a stdio server is spawned: a scanner must not execute a package
+that is already known to be malware in order to find out it is malicious.
+Set SNIFFMCP_OFFLINE=1 to skip all lookups.
+"""
+from __future__ import annotations
+import asyncio, os, re
+
+import httpx2
+
+from . import __version__
+from .models import Finding
+
+API = "https://api.osv.dev/v1"
+ECOSYSTEM = {"npm": "npm", "pypi": "PyPI"}
+BATCH = 1000
+UA = {"User-Agent": f"sniffmcp/{__version__}"}
+GHSA_SEVERITY = {"CRITICAL": "high", "HIGH": "high", "MODERATE": "medium", "MEDIUM": "medium", "LOW": "low"}
+
+
+def offline() -> bool:
+    return os.environ.get("SNIFFMCP_OFFLINE") == "1"
+
+
+def split_spec(ecosystem: str, spec: str) -> tuple[str, str | None]:
+    """'@scope/pkg@1.2.3' -> ('@scope/pkg', '1.2.3'); 'pkg==1.0' / 'pkg[extra]@1.0' -> ('pkg', '1.0')."""
+    if ecosystem == "npm":
+        at = spec.rfind("@")
+        if at > 0:
+            ver = spec[at + 1:]
+            return spec[:at], (ver if re.match(r"^v?\d+\.\d+\.\d+", ver) else None)
+        return spec, None
+    m = re.match(r"^([A-Za-z0-9._-]+)(\[[^\]]*\])?\s*(?:==|@)\s*v?([\w.+-]+)$", spec)
+    if m:
+        return m.group(1), m.group(3)
+    return re.sub(r"\[.*\]$", "", spec.strip()), None
+
+
+async def latest_version(http, ecosystem: str, name: str) -> str | None:
+    """What an unpinned `npx pkg` / `uvx pkg` would run today."""
+    try:
+        if ecosystem == "npm":
+            r = await http.get(f"https://registry.npmjs.org/{name.replace('/', '%2F')}",
+                               headers={"Accept": "application/vnd.npm.install-v1+json"})
+            return (r.json().get("dist-tags") or {}).get("latest") if r.status_code == 200 else None
+        r = await http.get(f"https://pypi.org/pypi/{name}/json")
+        return (r.json().get("info") or {}).get("version") if r.status_code == 200 else None
+    except Exception:
+        return None
+
+
+async def query_batch(http, queries: list[tuple[str, str, str | None]]) -> list[list[str]]:
+    """[(ecosystem, name, version|None)] -> [[vuln ids]] in the same order."""
+    out: list[list[str]] = []
+    for i in range(0, len(queries), BATCH):
+        chunk = queries[i:i + BATCH]
+        body = {"queries": [{"package": {"name": n, "ecosystem": ECOSYSTEM[e]}, **({"version": v} if v else {})}
+                            for e, n, v in chunk]}
+        r = await http.post(f"{API}/querybatch", json=body)
+        r.raise_for_status()
+        out.extend([[v["id"] for v in (res.get("vulns") or [])] for res in r.json().get("results", [])])
+    return out
+
+
+async def details(http, ids, concurrency: int = 10) -> dict[str, dict]:
+    sem, out = asyncio.Semaphore(concurrency), {}
+
+    async def one(vid):
+        async with sem:
+            try:
+                r = await http.get(f"{API}/vulns/{vid}")
+                out[vid] = r.json() if r.status_code == 200 else {"id": vid}
+            except Exception:
+                out[vid] = {"id": vid}
+    await asyncio.gather(*(one(v) for v in set(ids)))
+    return out
+
+
+def severity(vuln: dict) -> str:
+    if vuln.get("id", "").startswith("MAL-"):
+        return "critical"
+    ghsa = str((vuln.get("database_specific") or {}).get("severity", "")).upper()
+    return GHSA_SEVERITY.get(ghsa, "medium")
+
+
+def describe(vuln: dict) -> str:
+    aliases = [a for a in vuln.get("aliases") or [] if a.startswith("CVE-")]
+    return " ".join(filter(None, [vuln.get("id"), f"({', '.join(aliases[:2])})" if aliases else "",
+                                  "—", (vuln.get("summary") or "no summary")[:160]]))
+
+
+async def advisories_for_spec(ecosystem: str, spec: str) -> list[Finding]:
+    """Findings for one package spec as it would be launched (pinned, or today's latest)."""
+    name, version = split_spec(ecosystem, spec)
+    pinned = version is not None
+    try:
+        async with httpx2.AsyncClient(timeout=20, headers=UA) as http:
+            version = version or await latest_version(http, ecosystem, name)
+            at_version, any_version = await query_batch(http, [(ecosystem, name, version), (ecosystem, name, None)])
+            info = await details(http, at_version + [i for i in any_version if i.startswith("MAL-")])
+    except Exception as e:
+        return [Finding("SM-12", "info", "OSV lookup failed; package not checked for advisories",
+                        f"{type(e).__name__}: {e}"[:200], "Retry online, or check https://osv.dev manually.")]
+    where = f"{name}@{version}" if version else name
+    note = "" if pinned else " (unpinned: this is today's latest, which is what npx/uvx would run)"
+    out = []
+    for vid in at_version:
+        v = info.get(vid, {"id": vid})
+        if vid.startswith("MAL-"):
+            out.append(Finding("SM-11", "critical", f"Known malicious package: {where}", describe(v) + note,
+                               "Remove this server now. If it ever ran, rotate every credential it could reach.",
+                               kind="malware"))
+        else:
+            out.append(Finding("SM-12", severity(v), f"Known vulnerability in {where}", describe(v) + note,
+                               "Upgrade to a fixed version (see the advisory).", kind="vulnerability"))
+    other_mal = [i for i in any_version if i.startswith("MAL-") and i not in at_version]
+    if other_mal:
+        out.append(Finding("SM-11", "high", f"Other versions of {name} are known malware",
+                           ", ".join(describe(info.get(i, {"id": i})) for i in other_mal[:2]),
+                           "The package or its account was compromised before. Pin a version you have verified.",
+                           kind="malware"))
+    return out
+
+
+def blocks_launch(findings: list[Finding]) -> bool:
+    return any(f.check_id == "SM-11" and f.severity == "critical" for f in findings)