mcpprobe-scanner 0.1.0__py3-none-any.whl

mcpprobe/report/terminal.py

@@ -0,0 +1,172 @@
+"""Terminal summary rendered with rich.
+
+Every string that originates from the target (tool names, descriptions,
+evidence bodies, server info) is rendered as plain :class:`rich.text.Text`
+after control characters are made visible, so a hostile server cannot inject
+rich markup or ANSI escape sequences into the operator's terminal.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from mcpprobe.checks._util import visible
+from mcpprobe.models import CheckStatus, Finding, ScanReport, Severity, Standards
+
+#: Brand severity palette (hex), also used for badges and the website.
+SEVERITY_HEX: dict[Severity, str] = {
+    Severity.CRITICAL: "#B3261E",
+    Severity.HIGH: "#C2410C",
+    Severity.MEDIUM: "#9A6200",
+    Severity.LOW: "#4A5560",
+    Severity.INFO: "#4A5560",
+}
+PASS_HEX = "#2E7D4F"
+
+_ORDER = (Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO)
+
+
+def severity_style(sev: Severity, *, badge: bool = False) -> str:
+    colour = SEVERITY_HEX[sev]
+    if badge:
+        return f"bold #FFFFFF on {colour}"
+    return f"bold {colour}" if sev in (Severity.CRITICAL, Severity.HIGH) else colour
+
+
+def standards_text(std: Standards) -> str:
+    """``MCP07:2025 (beta), ASI03, LLM03:2026, LLM06:2025`` (2026 IDs first, per OWASP guidance)."""
+    parts = [f"{m} (beta)" for m in std.mcp] + list(std.asi) + list(std.llm_2026) + list(std.llm_2025)
+    return ", ".join(parts) if parts else "spec conformance / hygiene"
+
+
+def _plain(value: object, limit: int | None = None) -> str:
+    text = visible(str(value))
+    if limit is not None and len(text) > limit:
+        text = text[: limit - 1] + "…"
+    return text
+
+
+def _finding_block(f: Finding, verbose: bool) -> Group:
+    head = Text()
+    head.append(f" {f.severity.value.upper():<8} ", style=severity_style(f.severity, badge=True))
+    head.append(f" {f.id}  ", style="bold")
+    head.append(_plain(f.title), style="bold")
+    meta = Text("    ")
+    meta.append("confidence ", style="dim")
+    meta.append(f.confidence.value)
+    if f.location:
+        meta.append("  where ", style="dim")
+        meta.append(_plain(f.location, 120))
+    lines: list[Text] = [head, meta]
+    std = Text("    standards ", style="dim")
+    std.append(standards_text(f.standards))
+    lines.append(std)
+    if verbose:
+        desc = Text("    ")
+        desc.append(_plain(f.description, 600))
+        lines.append(desc)
+    if f.evidence_excerpt:
+        ev = Text("    evidence ", style="dim")
+        ev.append(_plain(f.evidence_excerpt, 300 if not verbose else 1200), style="dim")
+        lines.append(ev)
+    fix = Text("    fix ", style=f"bold {PASS_HEX}")
+    fix.append(_plain(f.fix, 400 if not verbose else 2000))
+    lines.append(fix)
+    lines.append(Text(""))
+    return Group(*lines)
+
+
+def render(
+    report: ScanReport,
+    console: Console | None = None,
+    *,
+    show_evidence: bool = False,
+    verbose: bool = False,
+    fail_on: Severity | None = None,
+) -> None:
+    console = console or Console()
+    fp = report.fingerprint
+    header = Text()
+    header.append(f"mcpprobe {report.version}  ", style="bold")
+    header.append(_plain(report.target, 200))
+    sub: list[str] = []
+    if fp:
+        sub.append(f"transport={fp.transport}")
+        sub.append(f"revision={fp.protocol_version or 'unknown'} ({fp.flavour})")
+        sub.append("auth=required" if fp.auth_required else "auth=none")
+        name = fp.server_info.get("name") if isinstance(fp.server_info, dict) else None
+        if name:
+            sub.append(_plain(f"server={name} {fp.server_info.get('version', '')}".strip(), 60))
+    inv = report.inventory_summary
+    if inv:
+        sub.append(
+            f"tools={inv.get('tools', 0)} prompts={inv.get('prompts', 0)} resources={inv.get('resources', 0)}"
+        )
+    sub.append(f"mode={report.mode.value}")
+    console.print(Panel(header, subtitle=Text(" | ".join(sub)), subtitle_align="left"))
+
+    counts = report.counts()
+    summary = Text("Findings ")
+    for sev in _ORDER:
+        style = severity_style(sev, badge=True) if counts[sev.value] else "dim"
+        summary.append(f" {sev.value} {counts[sev.value]} ", style=style)
+        summary.append(" ")
+    console.print(summary)
+    console.print()
+
+    if report.findings:
+        for f in report.findings:
+            console.print(_finding_block(f, verbose))
+    else:
+        console.print(Text("No findings.", style=f"bold {PASS_HEX}"))
+
+    cov = Table(title="Check coverage", expand=False, show_header=True, header_style="bold")
+    cov.add_column("Check")
+    cov.add_column("Mode")
+    cov.add_column("Status")
+    cov.add_column("Findings", justify="right")
+    cov.add_column("Reason")
+    for c in report.checks:
+        if c.status == CheckStatus.RAN:
+            status = Text("pass" if not c.findings else "ran", style=PASS_HEX if not c.findings else "")
+            if c.findings:
+                worst = max((x.severity for x in c.findings), key=lambda s: s.rank)
+                status = Text(worst.value, style=severity_style(worst))
+        else:
+            status = Text(
+                c.status.value,
+                style={
+                    CheckStatus.SKIPPED: "dim",
+                    CheckStatus.NOT_IMPLEMENTED: "dim italic",
+                    CheckStatus.ERROR: f"bold {SEVERITY_HEX[Severity.CRITICAL]}",
+                }.get(c.status, ""),
+            )
+        cov.add_row(c.check_id, c.mode.value, status, str(len(c.findings)), Text(_plain(c.reason or "", 70)))
+    console.print(cov)
+
+    if report.attestations:
+        gov = Text("Attestation only (not assessable by scan): ", style="bold")
+        gov.append(", ".join(f"{a.id} {a.title}" for a in report.attestations), style="dim")
+        console.print(gov)
+
+    if report.notes and verbose:
+        console.print(Text("Notes", style="bold"))
+        for note in report.notes:
+            console.print(Text(f"  - {_plain(note, 300)}"))
+    if show_evidence:
+        console.print(
+            Text(f"{report.evidence_count} request/response pairs recorded as evidence.", style="dim")
+        )
+    if fail_on is not None:
+        top = report.max_severity()
+        if top is not None and top >= fail_on:
+            console.print(
+                Text(f"Result: FAIL (findings at or above {fail_on.value})", style=severity_style(top))
+            )
+        else:
+            console.print(
+                Text(f"Result: PASS (nothing at or above {fail_on.value})", style=f"bold {PASS_HEX}")
+            )

mcpprobe/scanner.py

@@ -0,0 +1,211 @@
+"""Scan orchestrator: transport -> opt-out -> fingerprint -> inventory -> checks -> report."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from mcpprobe import USER_AGENT, __version__
+from mcpprobe.authz import AuthorisationError, AuthorisationRecord, require_active_authorisation
+from mcpprobe.checks import Check, ScanContext, ScanOptions, select_checks
+from mcpprobe.dnsutil import TxtLookup
+from mcpprobe.governance import governance_items
+from mcpprobe.models import (
+    CheckMode,
+    CheckResult,
+    CheckStatus,
+    Fingerprint,
+    Inventory,
+    ScanReport,
+    utcnow,
+)
+from mcpprobe.policy import DEFAULT_RATE, check_opt_out, clamp_rate
+from mcpprobe.transport import (
+    EvidenceLog,
+    HttpTransport,
+    RateLimiter,
+    StdioTransport,
+    Transport,
+    TransportError,
+    ensure_url,
+    fingerprint,
+)
+
+MAX_LIST_PAGES = 10
+
+
+@dataclass(slots=True)
+class ScanConfig:
+    """Everything needed to run one scan."""
+
+    target: str
+    stdio: bool = False
+    stdio_env: Mapping[str, str] = field(default_factory=dict)
+    headers: Mapping[str, str] = field(default_factory=dict)
+    timeout: float = 15.0
+    rate: float = DEFAULT_RATE
+    options: ScanOptions = field(default_factory=ScanOptions)
+    only: Iterable[str] | None = None
+    skip: Iterable[str] | None = None
+    authorisation: AuthorisationRecord | None = None
+    user_agent: str = USER_AGENT
+    verify_tls: bool | str = True
+    #: DNS TXT resolver for the opt-out check (injected in tests).
+    txt_lookup: TxtLookup | None = None
+    #: Test-suite escape hatch for the 10 req/s ceiling. Not exposed on the CLI.
+    _unsafe_allow_any_rate: bool = False
+
+    def effective_rate(self) -> float:
+        if self._unsafe_allow_any_rate:
+            return self.rate
+        return clamp_rate(self.rate)
+
+
+def build_transport(config: ScanConfig, evidence: EvidenceLog, limiter: RateLimiter) -> Transport:
+    if config.stdio:
+        return StdioTransport(
+            config.target,
+            env=config.stdio_env,
+            timeout=config.timeout,
+            evidence=evidence,
+            limiter=limiter,
+        )
+    return HttpTransport(
+        ensure_url(config.target),
+        extra_headers=config.headers,
+        timeout=config.timeout,
+        evidence=evidence,
+        limiter=limiter,
+        verify=config.verify_tls,
+        user_agent=config.user_agent,
+    )
+
+
+async def _list_all(
+    transport: Transport, method: str, key: str
+) -> tuple[list[dict[str, Any]], str | None, Any]:
+    """Paginate a ``*/list`` method; returns (items, error, first evidence)."""
+    items: list[dict[str, Any]] = []
+    cursor: str | None = None
+    first_evidence = None
+    for _ in range(MAX_LIST_PAGES):
+        params: dict[str, Any] = {"cursor": cursor} if cursor else {}
+        resp = await transport.rpc(method, params, note=f"inventory {method}")
+        if first_evidence is None:
+            first_evidence = resp.evidence
+        if not resp.ok:
+            err = resp.rpc_error
+            text = err.get("message") if err else (resp.error_text or f"HTTP {resp.status}")
+            return items, str(text), first_evidence
+        result = resp.result or {}
+        page = result.get(key)
+        if isinstance(page, list):
+            items.extend(x for x in page if isinstance(x, dict))
+        cursor = result.get("nextCursor")
+        if not cursor:
+            break
+    return items, None, first_evidence
+
+
+async def collect_inventory(transport: Transport, fp: Fingerprint) -> Inventory:
+    inv = Inventory()
+    if fp.auth_required or fp.flavour in {"unknown", "legacy-sse"}:
+        inv.tools_error = "not listed: " + ("authentication required" if fp.auth_required else fp.flavour)
+        return inv
+    inv.tools, inv.tools_error, inv.tools_evidence = await _list_all(transport, "tools/list", "tools")
+    caps = fp.capabilities if isinstance(fp.capabilities, dict) else {}
+    # Only ask for prompts/resources when advertised (or capabilities unknown) to avoid noise.
+    if not caps or "prompts" in caps:
+        inv.prompts, inv.prompts_error, inv.prompts_evidence = await _list_all(
+            transport, "prompts/list", "prompts"
+        )
+    if not caps or "resources" in caps:
+        inv.resources, inv.resources_error, inv.resources_evidence = await _list_all(
+            transport, "resources/list", "resources"
+        )
+    return inv
+
+
+async def run_check(check: Check, ctx: ScanContext) -> CheckResult:
+    """Run one check under the gating rules and wrap the outcome."""
+    result = CheckResult(check_id=check.id, title=check.title, mode=check.mode, status=CheckStatus.RAN)
+    if not check.applies(ctx):
+        result.status = CheckStatus.SKIPPED
+        result.reason = f"not applicable to {ctx.transport.name} transport"
+        return result
+    if check.mode == CheckMode.ACTIVE:
+        try:
+            require_active_authorisation(ctx.authorisation)
+        except AuthorisationError:
+            result.status = CheckStatus.SKIPPED
+            result.reason = "requires --active and verified ownership"
+            return result
+    started = time.monotonic()
+    try:
+        result.findings = await check.run(ctx)
+    except NotImplementedError as exc:
+        result.status = CheckStatus.NOT_IMPLEMENTED
+        result.reason = str(exc)
+    except PermissionError as exc:
+        result.status = CheckStatus.SKIPPED
+        result.reason = str(exc)
+    except Exception as exc:
+        result.status = CheckStatus.ERROR
+        result.reason = f"{type(exc).__name__}: {exc}"
+    result.duration_ms = (time.monotonic() - started) * 1000
+    return result
+
+
+async def run_scan(config: ScanConfig) -> tuple[ScanReport, EvidenceLog]:
+    """Execute a full scan. Raises TransportError/OptOutError for fatal conditions."""
+    evidence = EvidenceLog()
+    try:
+        limiter = RateLimiter(rate=config.effective_rate())
+    except ValueError as exc:
+        raise TransportError(str(exc)) from exc
+    started = utcnow()
+    transport = build_transport(config, evidence, limiter)
+    options = config.options
+    if options.txt_lookup is None:
+        options.txt_lookup = config.txt_lookup
+    if config.stdio:
+        options.stdio_command = list(transport.argv)  # type: ignore[attr-defined]
+        options.stdio_env = dict(config.stdio_env)
+    report = ScanReport(
+        version=__version__,
+        target=config.target,
+        mode=options.mode,
+        started_at=started,
+        attestations=governance_items(),
+    )
+    async with transport:
+        if isinstance(transport, HttpTransport):
+            # Must be the very first thing that happens: DNS opt-out, then the
+            # well-known document, before any MCP request.
+            report.notes.extend(await check_opt_out(transport, transport.url, config.txt_lookup))
+        fp = await fingerprint(transport)
+        report.fingerprint = fp
+        if fp.flavour == "unknown" and not fp.auth_required:
+            raise TransportError(fp.error or "target did not answer any MCP protocol revision")
+        inventory = await collect_inventory(transport, fp)
+        report.inventory_summary = inventory.summary()
+        ctx = ScanContext(
+            target=transport.url if isinstance(transport, HttpTransport) else config.target,
+            transport=transport,
+            fingerprint=fp,
+            inventory=inventory,
+            evidence=evidence,
+            options=options,
+            authorisation=config.authorisation,
+        )
+        for check in select_checks(config.only, config.skip):
+            result = await run_check(check, ctx)
+            report.checks.append(result)
+            report.findings.extend(result.findings)
+        report.notes.extend(ctx.notes)
+    report.finished_at = utcnow()
+    report.evidence_count = len(evidence)
+    report.findings.sort(key=lambda f: (-f.severity.rank, f.id, f.location or ""))
+    return report, evidence

mcpprobe/transport/__init__.py

@@ -0,0 +1,34 @@
+"""MCP client transports used by the scanner."""
+
+from mcpprobe.transport.base import (
+    HANDSHAKE_VERSIONS,
+    PROTOCOL_2025_06_18,
+    PROTOCOL_2025_11_25,
+    PROTOCOL_2026_07_28,
+    VERSION_PREFERENCE,
+    RpcResponse,
+    Transport,
+    TransportError,
+)
+from mcpprobe.transport.evidence import EvidenceLog
+from mcpprobe.transport.fingerprint import fingerprint
+from mcpprobe.transport.http import HttpTransport, ensure_url
+from mcpprobe.transport.ratelimit import RateLimiter
+from mcpprobe.transport.stdio import StdioTransport
+
+__all__ = [
+    "HANDSHAKE_VERSIONS",
+    "PROTOCOL_2025_06_18",
+    "PROTOCOL_2025_11_25",
+    "PROTOCOL_2026_07_28",
+    "VERSION_PREFERENCE",
+    "EvidenceLog",
+    "HttpTransport",
+    "RateLimiter",
+    "RpcResponse",
+    "StdioTransport",
+    "Transport",
+    "TransportError",
+    "ensure_url",
+    "fingerprint",
+]

mcpprobe/transport/base.py

@@ -0,0 +1,156 @@
+"""Shared transport abstractions.
+
+The scanner deliberately does **not** use an official MCP SDK client: checks
+need to send malformed and non-conformant requests (bad ``Origin``, bogus
+protocol version header, forged session IDs, wrong-audience tokens) that a
+conformant client refuses to send. The transports here are thin and permissive.
+"""
+
+from __future__ import annotations
+
+import abc
+import itertools
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from mcpprobe.models import EvidenceRecord
+from mcpprobe.transport.evidence import EvidenceLog
+from mcpprobe.transport.ratelimit import RateLimiter
+
+#: Current (stateless) revision. ``server/discover`` replaces ``initialize``.
+PROTOCOL_2026_07_28 = "2026-07-28"
+#: Handshake-based revisions still widely deployed.
+PROTOCOL_2025_11_25 = "2025-11-25"
+PROTOCOL_2025_06_18 = "2025-06-18"
+
+#: Order in which versions are tried during fingerprinting.
+VERSION_PREFERENCE: tuple[str, ...] = (
+    PROTOCOL_2026_07_28,
+    PROTOCOL_2025_11_25,
+    PROTOCOL_2025_06_18,
+)
+
+#: Versions that use the ``initialize`` handshake rather than ``server/discover``.
+HANDSHAKE_VERSIONS: frozenset[str] = frozenset({PROTOCOL_2025_11_25, PROTOCOL_2025_06_18})
+
+#: ``_meta`` key carrying the protocol version in 2026-07-28 requests.
+META_VERSION_KEY = "io.modelcontextprotocol/protocolVersion"
+
+CLIENT_INFO: dict[str, str] = {"name": "mcpprobe", "version": "0.1.0"}
+
+
+class TransportError(Exception):
+    """Raised when the target cannot be reached or spoken to at all."""
+
+
+@dataclass(slots=True)
+class RpcResponse:
+    """Result of one JSON-RPC exchange, successful or not."""
+
+    method: str
+    status: int | None
+    headers: dict[str, str]
+    body: bytes
+    message: dict[str, Any] | None = None
+    evidence: EvidenceRecord | None = None
+    elapsed_ms: float = 0.0
+    error_text: str | None = None
+    #: All JSON-RPC messages seen in an SSE stream (the matching one is ``message``).
+    stream_messages: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def result(self) -> dict[str, Any] | None:
+        value = self.message.get("result") if self.message else None
+        return value if isinstance(value, dict) else None
+
+    @property
+    def rpc_error(self) -> dict[str, Any] | None:
+        value = self.message.get("error") if self.message else None
+        return value if isinstance(value, dict) else None
+
+    @property
+    def ok(self) -> bool:
+        """True when a JSON-RPC ``result`` came back (HTTP 2xx or stdio)."""
+        return self.result is not None and (self.status is None or 200 <= self.status < 300)
+
+    def header(self, name: str) -> str | None:
+        return self.headers.get(name.lower())
+
+
+def is_jsonrpc_error_body(body: bytes) -> bool:
+    """Whether a body parses as a JSON-RPC error object (used by conformance checks)."""
+    try:
+        data = json.loads(body.decode("utf-8", errors="replace"))
+    except (ValueError, UnicodeDecodeError):
+        return False
+    return isinstance(data, dict) and isinstance(data.get("error"), dict)
+
+
+class Transport(abc.ABC):
+    """Common interface over streamable HTTP and stdio."""
+
+    name: str = "abstract"
+
+    def __init__(self, evidence: EvidenceLog | None = None, limiter: RateLimiter | None = None) -> None:
+        self.evidence = evidence if evidence is not None else EvidenceLog()
+        self.limiter = limiter if limiter is not None else RateLimiter()
+        self._ids = itertools.count(1)
+        #: Negotiated protocol version; set by the fingerprinter.
+        self.protocol_version: str | None = None
+
+    def next_id(self) -> int:
+        return next(self._ids)
+
+    @property
+    def stateless(self) -> bool:
+        """True when speaking the 2026-07-28 stateless revision."""
+        return self.protocol_version == PROTOCOL_2026_07_28
+
+    def build_message(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        protocol_version: str | None = None,
+        msg_id: int | None = None,
+        notification: bool = False,
+    ) -> dict[str, Any]:
+        """Build a JSON-RPC message, adding the 2026-07-28 ``_meta`` version when needed."""
+        version = protocol_version or self.protocol_version
+        body: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if not notification:
+            body["id"] = msg_id if msg_id is not None else self.next_id()
+        p: dict[str, Any] = dict(params or {})
+        if version == PROTOCOL_2026_07_28:
+            meta = dict(p.get("_meta") or {})
+            meta.setdefault(META_VERSION_KEY, version)
+            p["_meta"] = meta
+        if p or not notification:
+            body["params"] = p
+        return body
+
+    @abc.abstractmethod
+    async def rpc(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        note: str | None = None,
+        **kwargs: Any,
+    ) -> RpcResponse:
+        """Send a request and wait for its response."""
+
+    @abc.abstractmethod
+    async def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        """Send a notification (no response expected)."""
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        """Release connections or processes."""
+
+    async def __aenter__(self) -> Transport:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()