mcpprobe-scanner 0.1.0__py3-none-any.whl

mcpprobe/__init__.py

@@ -0,0 +1,21 @@
+"""mcpprobe: a security scanner for Model Context Protocol (MCP) servers.
+
+The package is organised as follows:
+
+- :mod:`mcpprobe.transport` -- a deliberately low-level MCP client (streamable
+  HTTP and stdio) that can send malformed or non-conformant requests and
+  records every exchange as evidence.
+- :mod:`mcpprobe.checks` -- the plugin framework and the individual checks.
+- :mod:`mcpprobe.authz` -- the hard authorisation gate for active mode.
+- :mod:`mcpprobe.report` -- JSON, SARIF 2.1.0 and terminal reporters.
+- :mod:`mcpprobe.scanner` -- the orchestrator tying everything together.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+POLICY_URL = "https://mcpprobe.tech/scanning-policy"
+USER_AGENT = f"mcpprobe/{__version__} (+{POLICY_URL})"
+
+__all__ = ["POLICY_URL", "USER_AGENT", "__version__"]

mcpprobe/action.py

@@ -0,0 +1,69 @@
+"""Entry point for the Docker container GitHub Action (``action.yml``).
+
+GitHub passes action inputs as ``INPUT_<NAME>`` environment variables (name
+upper-cased, hyphens kept). This module turns them into a CLI invocation,
+always writes SARIF, records outputs in ``$GITHUB_OUTPUT`` and exits with the
+scanner's exit code (0 clean, 1 findings at or above ``fail-on``, 2 error).
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from mcpprobe.cli import EXIT_ERROR, main
+
+
+def _input(env: Mapping[str, str], name: str, default: str = "") -> str:
+    return env.get(f"INPUT_{name.upper()}", default).strip()
+
+
+def build_argv(env: Mapping[str, str]) -> list[str]:
+    """Translate action inputs into ``mcpprobe scan`` arguments."""
+    target = _input(env, "target")
+    if not target:
+        raise ValueError("input 'target' is required")
+    argv = ["scan", target]
+    argv += ["--fail-on", _input(env, "fail-on", "high") or "high"]
+    argv += ["--rate", _input(env, "rate", "5") or "5"]
+    argv += ["--sarif", _input(env, "sarif-output", "mcpprobe.sarif") or "mcpprobe.sarif"]
+    if json_out := _input(env, "json-output"):
+        argv += ["--json", json_out]
+    if loc := _input(env, "sarif-location"):
+        argv += ["--sarif-location", loc]
+    if baseline := _input(env, "baseline"):
+        argv += ["--baseline", baseline]
+    for line in _input(env, "headers").splitlines():
+        if line.strip():
+            argv += ["--header", line.strip()]
+    if extra := _input(env, "extra-args"):
+        argv += shlex.split(extra)
+    return argv
+
+
+def run(env: Mapping[str, str] | None = None) -> int:
+    env = os.environ if env is None else env
+    try:
+        argv = build_argv(env)
+    except ValueError as exc:
+        print(f"::error::{exc}", file=sys.stderr)
+        return EXIT_ERROR
+    code = EXIT_ERROR
+    try:
+        main(argv)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else EXIT_ERROR
+    out = env.get("GITHUB_OUTPUT")
+    if out:
+        sarif = argv[argv.index("--sarif") + 1]
+        with Path(out).open("a", encoding="utf-8") as fh:
+            fh.write(f"sarif-file={sarif}\n")
+            fh.write(f"exit-code={code}\n")
+    return code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(run())

mcpprobe/authz.py

@@ -0,0 +1,313 @@
+"""Authorisation gate for active mode.
+
+Active checks call tools or send probe payloads, so they are allowed only when:
+
+1. the operator states who authorised the scan (``--authorised-by``) and the
+   agreed scope (``--scope``), **and**
+2. ownership verification passes:
+
+   * ``dns-txt``: a TXT record ``mcpprobe-verification=<token>`` exists at
+     ``_mcpprobe.<host>``. The token is generated locally with
+     ``mcpprobe token <host>`` and stored under the user's config directory, or
+     supplied with ``--token``.
+   * ``local``: only for stdio targets, which the operator runs on their own
+     machine.
+
+Every active scan writes an authorisation record JSON next to the report. The
+record is the evidence that the scan was authorised (who, what, which proof,
+when, with which limits). Passive mode never consults this module, but the
+ownership rule in README.md applies to every mode.
+
+This is a gate in code, not policy: :func:`authorise` raises
+:class:`AuthorisationError` and the scanner refuses to run active checks
+without a verified record.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import ipaddress
+import json
+import os
+import secrets
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from mcpprobe import __version__
+from mcpprobe.dnsutil import DnsLookupError, TxtLookup, default_txt_lookup, record_name
+from mcpprobe.models import CheckMode, utcnow
+
+TXT_PREFIX = "mcpprobe-verification="
+VERIFY_METHODS = ("dns-txt", "local")
+
+
+class AuthorisationError(Exception):
+    """Raised when active mode is requested without a valid authorisation."""
+
+
+class VerificationResult(BaseModel):
+    method: str
+    verified: bool
+    detail: str
+    evidence: dict[str, Any] = Field(default_factory=dict)
+
+
+class AuthorisationRecord(BaseModel):
+    """Written next to the report for every active scan."""
+
+    timestamp: str
+    scanner_version: str = __version__
+    target: str
+    transport: str
+    mode: CheckMode
+    authorised_by: str | None
+    scope: str | None
+    operator_reference: str | None = None
+    verification: VerificationResult
+    excluded_tools: list[str] = Field(default_factory=list)
+    rate_cap_rps: float
+    max_concurrent_tool_calls: int = 1
+    token_fingerprint: str | None = Field(
+        default=None, description="sha256 prefix of the verification token, never the token itself"
+    )
+
+    @property
+    def verified(self) -> bool:
+        return self.verification.verified
+
+
+# ----------------------------------------------------------------------------- tokens
+def generate_token() -> str:
+    """32 random bytes, base32 lower-case without padding (52 chars)."""
+    return base64.b32encode(secrets.token_bytes(32)).decode("ascii").rstrip("=").lower()
+
+
+def token_store_path() -> Path:
+    override = os.environ.get("MCPPROBE_TOKEN_STORE")
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "mcpprobe" / "verification-tokens.json"
+
+
+def _load_store(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text("utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_token(host: str, token: str, path: Path | None = None) -> Path:
+    path = path or token_store_path()
+    store = _load_store(path)
+    store[host.lower()] = {"token": token, "created_at": utcnow().isoformat()}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(store, indent=2, sort_keys=True), "utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:  # pragma: no cover - platform dependent
+        pass
+    return path
+
+
+def load_token(host: str, path: Path | None = None) -> str | None:
+    entry = _load_store(path or token_store_path()).get(host.lower())
+    token = entry.get("token") if isinstance(entry, dict) else None
+    return token if isinstance(token, str) else None
+
+
+def token_fingerprint(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+
+
+def expected_txt_record(token: str) -> str:
+    return TXT_PREFIX + token
+
+
+# ------------------------------------------------------------------------- verifiers
+def verify_dns_txt(host: str, token: str, lookup: TxtLookup | None = None) -> VerificationResult:
+    """Check for ``mcpprobe-verification=<token>`` at ``_mcpprobe.<host>``."""
+    if not host:
+        return VerificationResult(method="dns-txt", verified=False, detail="target has no host name")
+    if _is_ip_literal(host):
+        return VerificationResult(
+            method="dns-txt",
+            verified=False,
+            detail=f"{host} is an IP address; DNS TXT verification needs a host name you control",
+        )
+    resolver = lookup or default_txt_lookup
+    expected = expected_txt_record(token)
+    name = record_name(host)
+    try:
+        records = [r.strip().strip('"') for r in resolver(name)]
+    except DnsLookupError as exc:
+        raise AuthorisationError(str(exc)) from exc
+    # Keep only our own records in the snapshot; other TXT data is not ours to store.
+    ours = [r for r in records if r.startswith(TXT_PREFIX)]
+    snapshot = {"name": name, "records": ours, "checked_at": utcnow().isoformat()}
+    if expected in records:
+        return VerificationResult(
+            method="dns-txt", verified=True, detail=f"TXT record found at {name}", evidence=snapshot
+        )
+    return VerificationResult(
+        method="dns-txt",
+        verified=False,
+        detail=f"no TXT record {TXT_PREFIX}<token> matching the saved token found at {name}",
+        evidence=snapshot,
+    )
+
+
+def _is_ip_literal(host: str) -> bool:
+    try:
+        ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return False
+    return True
+
+
+def verify_local(transport: str) -> VerificationResult:
+    if transport != "stdio":
+        return VerificationResult(
+            method="local",
+            verified=False,
+            detail="'local' verification is only valid for stdio targets the operator runs themselves",
+        )
+    return VerificationResult(
+        method="local",
+        verified=True,
+        detail="stdio package executed locally by the operator",
+        evidence={"checked_at": utcnow().isoformat()},
+    )
+
+
+# ------------------------------------------------------------------------------ gate
+def authorise(
+    *,
+    target: str,
+    transport: str,
+    host: str,
+    active: bool,
+    authorised_by: str | None,
+    scope: str | None,
+    verify_method: str | None,
+    token: str | None = None,
+    excluded_tools: Iterable[str] = (),
+    rate_cap_rps: float,
+    reference: str | None = None,
+    lookup: TxtLookup | None = None,
+    token_store: Path | None = None,
+) -> AuthorisationRecord:
+    """Build the authorisation record; raise :class:`AuthorisationError` if active mode is not allowed.
+
+    For passive mode the function still returns a record (unverified, for the
+    report), but never raises.
+    """
+    mode = CheckMode.ACTIVE if active else CheckMode.PASSIVE
+    fingerprint: str | None = None
+    if not active:
+        verification = VerificationResult(
+            method="none", verified=False, detail="passive mode; no verification"
+        )
+        return _record(
+            target,
+            transport,
+            mode,
+            authorised_by,
+            scope,
+            reference,
+            verification,
+            excluded_tools,
+            rate_cap_rps,
+            None,
+        )
+
+    missing = [name for name, value in (("--authorised-by", authorised_by), ("--scope", scope)) if not value]
+    if missing:
+        raise AuthorisationError("active mode requires " + " and ".join(missing))
+    if verify_method not in VERIFY_METHODS:
+        raise AuthorisationError(
+            f"active mode requires --verify {{{'|'.join(VERIFY_METHODS)}}} (got {verify_method!r})"
+        )
+    if verify_method == "local":
+        verification = verify_local(transport)
+    else:
+        token = token or load_token(host, token_store)
+        if not token:
+            raise AuthorisationError(
+                f"no verification token for {host}; run 'mcpprobe token {host}' and publish the TXT record, "
+                "or pass --token"
+            )
+        fingerprint = token_fingerprint(token)
+        verification = verify_dns_txt(host, token, lookup)
+    if not verification.verified:
+        raise AuthorisationError(f"ownership verification failed: {verification.detail}")
+    return _record(
+        target,
+        transport,
+        mode,
+        authorised_by,
+        scope,
+        reference,
+        verification,
+        excluded_tools,
+        rate_cap_rps,
+        fingerprint,
+    )
+
+
+def _record(
+    target: str,
+    transport: str,
+    mode: CheckMode,
+    authorised_by: str | None,
+    scope: str | None,
+    reference: str | None,
+    verification: VerificationResult,
+    excluded_tools: Iterable[str],
+    rate_cap_rps: float,
+    fingerprint: str | None,
+) -> AuthorisationRecord:
+    return AuthorisationRecord(
+        timestamp=utcnow().isoformat(),
+        target=target,
+        transport=transport,
+        mode=mode,
+        authorised_by=authorised_by,
+        scope=scope,
+        operator_reference=reference,
+        verification=verification,
+        excluded_tools=sorted(set(excluded_tools)),
+        rate_cap_rps=rate_cap_rps,
+        token_fingerprint=fingerprint,
+    )
+
+
+def record_path_for(report_path: str | os.PathLike[str] | None) -> Path:
+    """``<report>.authorisation.json`` next to the report, or a timestamped file in cwd."""
+    if report_path:
+        p = Path(report_path)
+        return p.with_name(p.stem + ".authorisation.json")
+    stamp = utcnow().strftime("%Y%m%dT%H%M%SZ")
+    return Path(f"mcpprobe-authorisation-{stamp}.json")
+
+
+def write_record(record: AuthorisationRecord, report_path: str | os.PathLike[str] | None) -> Path:
+    path = record_path_for(report_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(record.model_dump_json(indent=2), "utf-8")
+    return path
+
+
+def require_active_authorisation(record: AuthorisationRecord | None) -> AuthorisationRecord:
+    """Second gate used by the orchestrator right before running active checks."""
+    if record is None or record.mode != CheckMode.ACTIVE or not record.verified:
+        raise AuthorisationError("active checks refused: no verified authorisation record")
+    return record

mcpprobe/catalogue.py

@@ -0,0 +1,125 @@
+"""Generate the public checks catalogue (CHECKS.md) from check metadata.
+
+``mcpprobe checks --format markdown`` prints the same text, and a test asserts
+that the committed CHECKS.md matches, so the documentation cannot drift from
+the code.
+"""
+
+from __future__ import annotations
+
+from mcpprobe import __version__
+from mcpprobe.checks import ALL_CHECKS, Check
+from mcpprobe.governance import GOVERNANCE_ITEMS
+from mcpprobe.models import CheckMode, Standards
+
+
+def _std(std: Standards) -> str:
+    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 "MCP spec conformance / hygiene (no OWASP item)"
+
+
+def _transports(cls: type[Check]) -> str:
+    return ", ".join(sorted(cls.applies_to))
+
+
+def _section(cls: type[Check]) -> list[str]:
+    status = "implemented" if cls.mode == CheckMode.PASSIVE else "stub (gated, not implemented)"
+    return [
+        f"### {cls.id} - {cls.title}",
+        "",
+        "| | |",
+        "|---|---|",
+        f"| Mode | {cls.mode.value} ({status}) |",
+        f"| Default severity | {cls.severity.value} |",
+        f"| Transports | {_transports(cls)} |",
+        f"| Standards | {_std(cls.standards)} |",
+        f"| Evidence | {cls.evidence_type or '-'} |",
+        "",
+        cls.description,
+        "",
+        f"**False positives.** {cls.false_positive_notes or 'None known.'}",
+        "",
+        f"**Fix.** {cls.fix or '-'}",
+        "",
+    ]
+
+
+def checks_markdown() -> str:
+    lines: list[str] = [
+        "# mcpprobe checks catalogue",
+        "",
+        f"Generated from the check metadata of mcpprobe {__version__} "
+        "(`mcpprobe checks --format markdown`). Do not edit by hand.",
+        "",
+        "Standards: OWASP MCP Top 10 (IDs `MCP0x:2025`, still a beta list, so shown with `(beta)`), "
+        "OWASP Top 10 for Agentic Applications (`ASI0x`), OWASP Top 10 for LLM Applications 2026 "
+        "(`LLM0x:2026`, primary) and 2025 (`LLM0x:2025`, kept for one release cycle). Severities are "
+        "defaults; a check can raise or lower the severity of an individual finding (for example "
+        "loopback-only servers are reported one level lower), and heuristic checks never rate a "
+        "finding Critical on their own.",
+        "",
+        "Passive checks send only what a normal MCP client would send plus a few benign malformed "
+        "requests. They never call a tool. Active checks are listed so coverage is reported honestly; "
+        "in this release they are stubs that run only behind the authorisation gate and report "
+        "`not_implemented`.",
+        "",
+        "## Summary",
+        "",
+        "| ID | Mode | Default severity | Title | Standards |",
+        "|---|---|---|---|---|",
+    ]
+    for cls in ALL_CHECKS:
+        lines.append(
+            f"| [{cls.id}](#{cls.id.lower()}---{_anchor(cls.title)}) | {cls.mode.value} | "
+            f"{cls.severity.value} | {cls.title} | {_std(cls.standards)} |"
+        )
+    for item in GOVERNANCE_ITEMS:
+        lines.append(f"| {item.id} | attestation | - | {item.title} | {_std(item.standards)} |")
+    lines += ["", "## Passive checks", ""]
+    for cls in ALL_CHECKS:
+        if cls.mode == CheckMode.PASSIVE:
+            lines += _section(cls)
+    lines += [
+        "## Active checks (stubs)",
+        "",
+        "Rules of engagement for when these are implemented: non-destructive, non-persistent "
+        "canaries only; tools excluded with `--exclude-tool` or annotated `destructiveHint: true` are "
+        "never called; at most one concurrent tool call; every payload is recorded as evidence; the "
+        "scan stops on the first sign of an unintended side effect.",
+        "",
+    ]
+    for cls in ALL_CHECKS:
+        if cls.mode == CheckMode.ACTIVE:
+            lines += _section(cls)
+    lines += [
+        "## Governance items (attestation only)",
+        "",
+        "These cannot be assessed by an automated black-box scan. Every report lists them as "
+        "`attestation-only` with the checklist below; mcpprobe never marks them passed or failed.",
+        "",
+    ]
+    for item in GOVERNANCE_ITEMS:
+        lines += [
+            f"### {item.id} - {item.title}",
+            "",
+            f"Standards: {_std(item.standards)}",
+            "",
+            item.reason,
+            "",
+        ]
+        lines += [f"- [ ] {c}" for c in item.checklist]
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _anchor(title: str) -> str:
+    out = []
+    for ch in title.lower():
+        if ch.isalnum() or ch in "-_":
+            out.append(ch)
+        elif ch == " ":
+            out.append("-")
+    return "".join(out)
+
+
+__all__ = ["checks_markdown"]

mcpprobe/checks/__init__.py

@@ -0,0 +1,100 @@
+"""Check registry.
+
+``ALL_CHECKS`` lists every check class in execution order. Passive checks run
+by default; active ones are stubs gated behind the authorisation record.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from mcpprobe.checks.active_stubs import ACTIVE_STUBS
+from mcpprobe.checks.auth import (
+    Auth01NoAuthentication,
+    Auth02MissingProtectedResourceMetadata,
+    Auth03AuthorizationServerMetadata,
+    Auth04TokenAudienceAndPassthrough,
+)
+from mcpprobe.checks.base import (
+    ActiveCheck,
+    Check,
+    JudgeFn,
+    JudgeVerdict,
+    ScanContext,
+    ScanOptions,
+)
+from mcpprobe.checks.baseline import Meta02RugPullBaseline
+from mcpprobe.checks.metadata import (
+    Meta03DangerousCapabilitySurface,
+    Meta04SchemaHygiene,
+    Meta05SecretsInMetadata,
+)
+from mcpprobe.checks.poisoning import Meta01ToolDescriptionPoisoning
+from mcpprobe.checks.robustness import Dos01UnboundedConsumption, Err01VerboseErrors
+from mcpprobe.checks.transport_conformance import (
+    Trans01OriginValidation,
+    Trans02ProtocolVersionHandling,
+    Trans03SessionIdQuality,
+    Trans04DeprecatedTransport,
+    Trans05TlsAndHeaders,
+)
+
+PASSIVE_CHECKS: list[type[Check]] = [
+    Auth01NoAuthentication,
+    Auth02MissingProtectedResourceMetadata,
+    Auth03AuthorizationServerMetadata,
+    Auth04TokenAudienceAndPassthrough,
+    Trans01OriginValidation,
+    Trans02ProtocolVersionHandling,
+    Trans03SessionIdQuality,
+    Trans04DeprecatedTransport,
+    Trans05TlsAndHeaders,
+    Meta01ToolDescriptionPoisoning,
+    Meta02RugPullBaseline,
+    Meta03DangerousCapabilitySurface,
+    Meta04SchemaHygiene,
+    Meta05SecretsInMetadata,
+    Err01VerboseErrors,
+    Dos01UnboundedConsumption,
+]
+
+ALL_CHECKS: list[type[Check]] = [*PASSIVE_CHECKS, *ACTIVE_STUBS]
+
+_BY_ID: dict[str, type[Check]] = {c.id: c for c in ALL_CHECKS}
+
+
+def get_check(check_id: str) -> type[Check]:
+    try:
+        return _BY_ID[check_id.upper()]
+    except KeyError as exc:
+        raise KeyError(f"unknown check id: {check_id}") from exc
+
+
+def select_checks(only: Iterable[str] | None = None, skip: Iterable[str] | None = None) -> list[Check]:
+    """Instantiate checks, honouring ``--only`` / ``--skip`` lists."""
+    only_set = {s.upper() for s in only} if only else None
+    skip_set = {s.upper() for s in skip} if skip else set()
+    for cid in (only_set or set()) | skip_set:
+        get_check(cid)  # raise on typos
+    out: list[Check] = []
+    for cls in ALL_CHECKS:
+        if only_set is not None and cls.id not in only_set:
+            continue
+        if cls.id in skip_set:
+            continue
+        out.append(cls())
+    return out
+
+
+__all__ = [
+    "ALL_CHECKS",
+    "PASSIVE_CHECKS",
+    "ActiveCheck",
+    "Check",
+    "JudgeFn",
+    "JudgeVerdict",
+    "ScanContext",
+    "ScanOptions",
+    "get_check",
+    "select_checks",
+]