mcp-warden-cli 1.0.0__py3-none-any.whl

mcp_warden/__init__.py

@@ -0,0 +1,25 @@
+"""mcp-warden — CI-first MCP supply-chain integrity gate.
+
+mcp-warden pins and verifies the *declared* tool/resource/prompt surface of an
+MCP server (the ``(name, description, inputSchema)`` metadata returned by
+``tools/list`` / ``resources/list`` / ``prompts/list``), then fails CI when that
+surface drifts from an approved baseline. It operates on **definitions**, never
+on runtime tool behavior or tool results. See ``docs/THREAT_MODEL.md``.
+"""
+
+__version__ = "1.0.0"
+#: Lock schema version. Bumped 2 → 3 for #29 (in-document ``$ref`` resolution in
+#: ``schema_diff.extract_skeleton``). Following refs changes the skeleton of any
+#: ref-using tool → its ``entry_digest`` and the ``overall_digest`` (which embeds
+#: ``schema_version``, lockfile.py:167). The bump makes that digest change a
+#: declared schema-format migration rather than a silent surface change; drift.py
+#: emits an additive ``schema-version-migrated`` advisory alongside (never in
+#: place of) the ``unapproved-change`` finding so re-attestation is required.
+SCHEMA_VERSION = 3
+#: Provenance-block version (#19). Lives INSIDE the ``pin`` block, OUTSIDE the
+#: ``overall_digest`` payload, so it can evolve for #16/#23 without changing any
+#: server's digest. Deliberately distinct from ``SCHEMA_VERSION`` (which is in
+#: the digest payload — bumping that would falsely trip drift on v2 baselines).
+PROVENANCE_VERSION = 1
+
+__all__ = ["__version__", "SCHEMA_VERSION", "PROVENANCE_VERSION"]

mcp_warden/capture.py

@@ -0,0 +1,197 @@
+"""MCP stdio capture client.
+
+Spawns the target MCP server **over stdio as an argv array, never via a shell**
+(WARDEN_LOCK_SCHEMA.md §10.4), runs ``initialize`` + ``tools/list`` +
+``resources/list`` + ``prompts/list``, and captures the declared surface.
+
+A server that hangs, crashes, or exits nonzero must produce a clear
+``CaptureError``, not a traceback.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import anyio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from .models import (
+    CapturedPrompt,
+    CapturedResource,
+    CapturedSurface,
+    CapturedTool,
+)
+
+logger = logging.getLogger("mcp_warden.capture")
+
+#: Hard wall-clock timeout for the entire capture handshake (seconds).
+DEFAULT_TIMEOUT_S = 30.0
+
+
+class CaptureError(Exception):
+    """Raised when the MCP server cannot be captured cleanly.
+
+    Carries a human-readable message suitable for CLI display; never a raw
+    traceback from the child process.
+    """
+
+
+def _model_dump(obj: Any) -> dict[str, Any]:
+    """Best-effort dict view of an MCP SDK model across pydantic versions."""
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()  # pydantic v2
+    if hasattr(obj, "dict"):
+        return obj.dict()  # pydantic v1 fallback
+    return dict(obj)
+
+
+async def _capture_async(command: str, args: list[str], timeout_s: float) -> CapturedSurface:
+    """Inner async capture; wrapped with a timeout by :func:`capture_surface`."""
+    # StdioServerParameters passes command+args as an argv array to the OS; the
+    # MCP SDK does NOT spawn through a shell. This is the §10.4 guarantee.
+    params = StdioServerParameters(command=command, args=list(args))
+
+    async with stdio_client(params) as (read_stream, write_stream):
+        async with ClientSession(read_stream, write_stream) as session:
+            init_result = await session.initialize()
+            protocol_version = str(getattr(init_result, "protocolVersion", "") or "")
+
+            tools = await _list_tools(session)
+            resources = await _list_resources(session)
+            prompts = await _list_prompts(session)
+
+    return CapturedSurface(
+        command=command,
+        args=list(args),
+        protocol_version=protocol_version,
+        tools=tools,
+        resources=resources,
+        prompts=prompts,
+    )
+
+
+async def _list_tools(session: ClientSession) -> list[CapturedTool]:
+    """Run ``tools/list`` and normalize results. Empty list if unsupported."""
+    try:
+        result = await session.list_tools()
+    except Exception as exc:  # server may not declare the tools capability
+        logger.info("tools/list unavailable: %s", exc)
+        return []
+    out: list[CapturedTool] = []
+    for tool in getattr(result, "tools", []) or []:
+        data = _model_dump(tool)
+        out.append(
+            CapturedTool(
+                name=str(data.get("name", "")),
+                description=data.get("description"),
+                input_schema=data.get("inputSchema"),
+            )
+        )
+    return out
+
+
+async def _list_resources(session: ClientSession) -> list[CapturedResource]:
+    """Run ``resources/list`` and normalize results. Empty list if unsupported."""
+    try:
+        result = await session.list_resources()
+    except Exception as exc:
+        logger.info("resources/list unavailable: %s", exc)
+        return []
+    out: list[CapturedResource] = []
+    for res in getattr(result, "resources", []) or []:
+        data = _model_dump(res)
+        out.append(
+            CapturedResource(
+                uri=str(data.get("uri", "")),
+                name=data.get("name"),
+                description=data.get("description"),
+                mime_type=data.get("mimeType"),
+            )
+        )
+    return out
+
+
+async def _list_prompts(session: ClientSession) -> list[CapturedPrompt]:
+    """Run ``prompts/list`` and normalize results. Empty list if unsupported."""
+    try:
+        result = await session.list_prompts()
+    except Exception as exc:
+        logger.info("prompts/list unavailable: %s", exc)
+        return []
+    out: list[CapturedPrompt] = []
+    for prompt in getattr(result, "prompts", []) or []:
+        data = _model_dump(prompt)
+        arguments = data.get("arguments")
+        norm_args: list[dict[str, Any]] | None = None
+        if isinstance(arguments, list):
+            norm_args = [a if isinstance(a, dict) else _model_dump(a) for a in arguments]
+        out.append(
+            CapturedPrompt(
+                name=str(data.get("name", "")),
+                description=data.get("description"),
+                arguments=norm_args,
+            )
+        )
+    return out
+
+
+async def capture_surface(
+    command: str,
+    args: list[str],
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+) -> CapturedSurface:
+    """Spawn an MCP server over stdio and capture its declared surface.
+
+    Args:
+        command: ``argv[0]`` of the server launch (no shell expansion performed).
+        args: Remaining argv, order preserved.
+        timeout_s: Wall-clock timeout for the whole handshake.
+
+    Returns:
+        The :class:`CapturedSurface` with tools/resources/prompts.
+
+    Raises:
+        CaptureError: If the server hangs (timeout), crashes, exits nonzero, or
+            the MCP handshake fails. The message is CLI-safe.
+    """
+    logger.debug("spawning MCP server: command=%r args=%r", command, args)
+    try:
+        with anyio.fail_after(timeout_s):
+            return await _capture_async(command, args, timeout_s)
+    except TimeoutError as exc:
+        raise CaptureError(
+            f"MCP server '{command}' did not complete the handshake within {timeout_s:.0f}s "
+            f"(it may be hung or waiting on input)."
+        ) from exc
+    except CaptureError:
+        raise
+    except FileNotFoundError as exc:
+        raise CaptureError(f"MCP server command not found: '{command}' ({exc}).") from exc
+    except Exception as exc:
+        # Covers nonzero exit, broken pipe, protocol error, decode failure, etc.
+        raise CaptureError(
+            f"Failed to capture MCP server '{command}': {type(exc).__name__}: {exc}"
+        ) from exc
+
+
+def capture_surface_sync(
+    command: str,
+    args: list[str],
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+) -> CapturedSurface:
+    """Synchronous wrapper around :func:`capture_surface` for the CLI.
+
+    Args:
+        command: ``argv[0]`` of the server launch.
+        args: Remaining argv.
+        timeout_s: Wall-clock timeout.
+
+    Returns:
+        The captured surface.
+
+    Raises:
+        CaptureError: On any capture failure (see :func:`capture_surface`).
+    """
+    return anyio.run(capture_surface, command, args, timeout_s)

mcp_warden/check_core.py

@@ -0,0 +1,98 @@
+"""Shared check core: the single source of truth for the ``check`` verdict.
+
+Both ``cli.py:check`` and the pre-commit wrapper (``precommit.py``) call
+:func:`run_check` so a local hook and CI can never disagree on a drift verdict
+(issue: "a hook that disagrees with CI is worse than no hook").
+
+The sequence here mirrors what ``check`` has always done:
+``read_lock`` -> ``capture_surface_sync`` -> ``run_checks`` -> ``build_lock``
+(an in-memory CURRENT lock, never persisted) -> ``compute_drift``.
+
+# INTERNAL STABILITY NOTE: the pre-commit wrapper (precommit.py) depends on this
+# function's signature and exception contract (CaptureError for spawn/timeout
+# failures; FileNotFoundError / ValueError for a missing/invalid lock). Do not
+# change either without updating precommit.py.
+#
+# DETERMINISM: this shared verdict path MUST stay free of environment-dependent
+# behavior (cwd-, time-, locale-, or env-var-conditioned branches). The local
+# pre-commit hook and CI both reach the drift verdict through this exact code, so
+# any non-deterministic branch here would let a local hook verdict diverge from
+# CI — the precise failure ("a hook that disagrees with CI") this module exists
+# to prevent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .capture import capture_surface_sync
+from .checks import run_checks
+from .drift import DriftItem, compute_drift
+from .lockfile import build_lock, read_lock
+from .models import Finding
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """The full result of a check run, for callers that need more than drift.
+
+    ``findings`` are the static-check findings on the current surface (needed by
+    the CLI's SARIF/JSON emitters); ``drift`` is the verdict set.
+    """
+
+    findings: list[Finding]
+    drift: list[DriftItem]
+
+
+def run_check_full(
+    command: str,
+    args: list[str],
+    lock_path: Path,
+    timeout_s: float,
+) -> CheckResult:
+    """Run the full check verdict path: read lock -> capture -> checks -> drift.
+
+    This is the single source of truth for the ``check`` verdict. ``cli.py:check``
+    calls it (and uses ``findings`` for SARIF/JSON output); the pre-commit wrapper
+    calls the thinner :func:`run_check` which discards ``findings``.
+
+    Args:
+        command: The MCP server launch command (argv[0]).
+        args: The remaining server launch argv.
+        lock_path: Path to the baseline ``warden.lock``.
+        timeout_s: Capture timeout in seconds.
+
+    Returns:
+        A :class:`CheckResult` (``drift`` empty == clean).
+
+    Raises:
+        FileNotFoundError: The lock file does not exist.
+        ValueError: The lock file is invalid JSON or fails schema validation.
+        CaptureError: The server could not be spawned or did not respond in time.
+    """
+    baseline = read_lock(lock_path)
+    surface = capture_surface_sync(command, args, timeout_s=timeout_s)
+    findings = run_checks(surface)
+    # build_lock constructs an IN-MEMORY current lock for diffing only; it is
+    # never written to disk on the check path.
+    current = build_lock(surface, findings)
+    drift = compute_drift(baseline, current)
+    return CheckResult(findings=findings, drift=drift)
+
+
+def run_check(
+    command: str,
+    args: list[str],
+    lock_path: Path,
+    timeout_s: float,
+) -> list[DriftItem]:
+    """Run the check path and return only the drift set (verdict).
+
+    Convenience wrapper over :func:`run_check_full` for callers (the pre-commit
+    hook) that only need the drift verdict and never the static findings.
+
+    Raises:
+        FileNotFoundError, ValueError, CaptureError: see :func:`run_check_full`.
+    """
+    return run_check_full(command, args, lock_path, timeout_s).drift

mcp_warden/checks.py

@@ -0,0 +1,163 @@
+"""Static-check engine orchestrator (CHECKS.md).
+
+Runs the full ``WRD-*`` catalog over a captured surface:
+  - capability checks ``WRD-CAP-*`` (via the shared tokenizer),
+  - secret checks ``WRD-SEC-*`` (checks_secret),
+  - supply-chain checks ``WRD-SUP-*`` (checks_supply),
+  - robustness ``WRD-SCHEMA-MALFORMED``.
+
+Findings are returned sorted by ``(target, rule_id)`` for deterministic output
+(CHECKS.md §5.1). CUT items (fuzzy/NLP, result scanning, etc.) are NOT here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .checks_secret import scan_field
+from .checks_supply import check_launch_command
+from .models import CapturedSurface, Finding
+from .tokenizer import capability_evidence, derive_capabilities
+
+# Capability flag -> (rule_id, severity) per CHECKS.md §4.1.
+_CAP_RULES: dict[str, tuple[str, str]] = {
+    "shell-exec": ("WRD-CAP-SHELL", "critical"),
+    "fs-write": ("WRD-CAP-FS-WRITE", "high"),
+    "fs-read": ("WRD-CAP-FS-READ", "medium"),
+    "http-request": ("WRD-CAP-HTTP", "high"),
+    "sql-query": ("WRD-CAP-SQL", "high"),
+}
+
+
+def _string_values_from_schema(schema: dict[str, Any]) -> list[str]:
+    """Collect string ``default``/``enum``/``examples`` values from a JSON Schema.
+
+    Recurses nested schemas (``properties``, ``items``, ``$defs``, etc.). Property
+    *keys* are intentionally NOT scanned (CHECKS.md §4.2 — a key named ``api_key``
+    is not a leak).
+
+    Args:
+        schema: A JSON Schema fragment.
+
+    Returns:
+        Flat list of candidate string values to run secret scans over.
+    """
+    out: list[str] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if isinstance(node.get("default"), str):
+                out.append(node["default"])
+            enum = node.get("enum")
+            if isinstance(enum, list):
+                out.extend(v for v in enum if isinstance(v, str))
+            examples = node.get("examples")
+            if isinstance(examples, list):
+                out.extend(v for v in examples if isinstance(v, str))
+            for key, val in node.items():
+                if key in ("default", "enum", "examples"):
+                    continue
+                walk(val)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(schema)
+    return out
+
+
+def _schema_is_malformed(schema: Any) -> bool:
+    """Return True if an inputSchema is present but not analyzable (not an object)."""
+    return schema is not None and not isinstance(schema, dict)
+
+
+def run_checks(surface: CapturedSurface) -> list[Finding]:
+    """Run the full static-check catalog over a captured surface.
+
+    Args:
+        surface: The captured declared surface.
+
+    Returns:
+        Deterministically sorted (by ``target``, then ``rule_id``) list of
+        findings. Secret snippets are redacted by the scanners.
+    """
+    findings: list[Finding] = []
+
+    # --- Launch / supply-chain (target = launch/command) ---
+    findings.extend(check_launch_command(surface.command, surface.args))
+    for arg in (surface.command, *surface.args):
+        findings.extend(scan_field(arg, "launch/command"))
+
+    # --- Tools ---
+    for tool in surface.tools:
+        target = f"tools/{tool.name}"
+
+        if _schema_is_malformed(tool.input_schema):
+            findings.append(
+                Finding(
+                    rule_id="WRD-SCHEMA-MALFORMED",
+                    severity="low",
+                    target=target,
+                    message="inputSchema is present but not a JSON object; capability analysis skipped",
+                    snippet=f"inputSchema type={type(tool.input_schema).__name__}",
+                )
+            )
+            schema_obj: dict[str, Any] | None = None
+        else:
+            schema_obj = tool.input_schema
+
+        # Capability checks via the shared tokenizer.
+        for flag in derive_capabilities(tool.name, schema_obj):
+            rule_id, severity = _CAP_RULES[flag]
+            evidence = capability_evidence(tool.name, schema_obj, flag)
+            findings.append(
+                Finding(
+                    rule_id=rule_id,
+                    severity=severity,
+                    target=target,
+                    message=f"Tool derives capability '{flag}' ({evidence})",
+                    snippet=evidence,
+                )
+            )
+
+        # Secret checks on name, description, and schema string values.
+        findings.extend(scan_field(tool.name, target))
+        if tool.description:
+            findings.extend(scan_field(tool.description, target))
+        if isinstance(schema_obj, dict):
+            for sval in _string_values_from_schema(schema_obj):
+                findings.extend(scan_field(sval, target))
+
+    # --- Resources ---
+    for res in surface.resources:
+        target = f"resources/{res.uri}"
+        for field in (res.uri, res.name, res.description):
+            if field:
+                findings.extend(scan_field(field, target))
+
+    # --- Prompts ---
+    for prompt in surface.prompts:
+        target = f"prompts/{prompt.name}"
+        findings.extend(scan_field(prompt.name, target))
+        if prompt.description:
+            findings.extend(scan_field(prompt.description, target))
+
+    return _dedupe_and_sort(findings)
+
+
+def _dedupe_and_sort(findings: list[Finding]) -> list[Finding]:
+    """Collapse duplicate (rule_id, target, snippet) and sort by (target, rule_id).
+
+    CHECKS.md §5.1/§5.2: one finding per (rule_id, target, match-location);
+    emitted sorted by ``(target, rule_id)``.
+    """
+    seen: set[tuple[str, str, str]] = set()
+    unique: list[Finding] = []
+    for f in findings:
+        key = (f.rule_id, f.target, f.snippet)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(f)
+    unique.sort(key=lambda f: (f.target, f.rule_id, f.snippet))
+    return unique

mcp_warden/checks_secret.py

@@ -0,0 +1,129 @@
+"""Secret-leakage checks (MCP-SECRET) — ``WRD-SEC-*`` (CHECKS.md §4.2).
+
+Deterministic regex + entropy heuristics over the declared surface's string
+fields. Snippets are ALWAYS redacted (CHECKS.md §8.2).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+
+from .models import Finding
+from .redact import redact_secret
+
+# --- Vendor patterns (CHECKS.md §4.2; case-sensitive unless noted) -----------
+
+_VENDOR_PATTERNS: list[tuple[str, str, re.Pattern[str]]] = [
+    ("WRD-SEC-OPENAI", "critical", re.compile(r"\bsk-[A-Za-z0-9]{20,}\b")),
+    # GitHub: ghp_ (36) plus gho_/ghu_/ghs_/ghr_ OAuth/app tokens.
+    ("WRD-SEC-GITHUB", "critical", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36}\b")),
+    ("WRD-SEC-AWS-AKID", "critical", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("WRD-SEC-SLACK", "critical", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")),
+    (
+        "WRD-SEC-PRIVKEY",
+        "critical",
+        re.compile(r"-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----"),
+    ),
+    (
+        "WRD-SEC-JWT",
+        "high",
+        re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b"),
+    ),
+]
+
+#: Entropy candidate token pattern (CHECKS.md §4.2).
+_ENTROPY_TOKEN = re.compile(r"[A-Za-z0-9+/_=-]{20,}")
+
+#: Splitter for the entropy pass: whitespace + chars outside the candidate set.
+_ENTROPY_SPLIT = re.compile(r"[^A-Za-z0-9+/_=.-]+")
+
+ENTROPY_THRESHOLD = 4.0
+ENTROPY_MIN_LEN = 24
+ALNUM_DOMINANCE = 0.80
+
+
+def shannon_entropy(token: str) -> float:
+    """Compute Shannon entropy (bits/char) over a token's character distribution.
+
+    ``H = -Σ p_i log2 p_i``.
+
+    Args:
+        token: The candidate string.
+
+    Returns:
+        Entropy in bits per character; ``0.0`` for an empty string.
+    """
+    if not token:
+        return 0.0
+    counts = Counter(token)
+    n = len(token)
+    return -sum((c / n) * math.log2(c / n) for c in counts.values())
+
+
+def _alnum_ratio(token: str) -> float:
+    """Fraction of characters in ``[A-Za-z0-9]``."""
+    if not token:
+        return 0.0
+    alnum = sum(1 for ch in token if ch.isalnum() and ch.isascii())
+    return alnum / len(token)
+
+
+def scan_field(value: str, target: str) -> list[Finding]:
+    """Scan one string field for secret patterns; return redacted findings.
+
+    Applies the vendor patterns first, then the entropy heuristic de-duped
+    against any token already matched by a vendor rule.
+
+    Args:
+        value: The string field content to scan.
+        target: The finding target, e.g. ``"tools/<name>"`` or ``"launch/command"``.
+
+    Returns:
+        A list of :class:`Finding` with redacted snippets. May be empty.
+    """
+    if not value:
+        return []
+
+    findings: list[Finding] = []
+    matched_spans: set[str] = set()
+
+    # 1) Explicit vendor patterns.
+    for rule_id, severity, pattern in _VENDOR_PATTERNS:
+        for m in pattern.finditer(value):
+            raw = m.group(0)
+            matched_spans.add(raw)
+            findings.append(
+                Finding(
+                    rule_id=rule_id,
+                    severity=severity,
+                    target=target,
+                    message=f"{rule_id}: possible secret in field",
+                    snippet=redact_secret(raw),
+                )
+            )
+
+    # 2) Entropy heuristic, de-duped against vendor matches.
+    for token in _ENTROPY_SPLIT.split(value):
+        if len(token) < ENTROPY_MIN_LEN:
+            continue
+        if not _ENTROPY_TOKEN.fullmatch(token):
+            continue
+        if any(token in span or span in token for span in matched_spans):
+            continue  # already covered by a vendor rule
+        if _alnum_ratio(token) < ALNUM_DOMINANCE:
+            continue
+        if shannon_entropy(token) >= ENTROPY_THRESHOLD:
+            findings.append(
+                Finding(
+                    rule_id="WRD-SEC-ENTROPY",
+                    severity="high",
+                    target=target,
+                    message="WRD-SEC-ENTROPY: high-entropy token (possible secret)",
+                    snippet=redact_secret(token),
+                )
+            )
+            matched_spans.add(token)
+
+    return findings