mcplens-scanner 0.1.0__py3-none-any.whl

mcplens/__init__.py

@@ -0,0 +1,3 @@
+"""mcplens — MCP server security scanner with runtime behavioral verification."""
+
+__version__ = "0.1.0"

mcplens/baseline.py

@@ -0,0 +1,102 @@
+"""Baseline snapshots and rug-pull diffing.
+
+A baseline pins the SHA-256 of every tool's canonical definition
+(name + description + inputSchema). Re-scanning and diffing against the
+baseline exposes silent definition changes — the 'rug pull' pattern where
+a server behaves during review and mutates afterwards.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .models import ToolInfo
+
+SNAPSHOT_VERSION = 1
+
+
+def tool_hash(tool: ToolInfo) -> str:
+    return hashlib.sha256(tool.canonical_json().encode("utf-8")).hexdigest()
+
+
+def set_hash(tools: list[ToolInfo]) -> str:
+    joined = "\n".join(f"{t.name}:{tool_hash(t)}" for t in sorted(tools, key=lambda x: x.name))
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def make_snapshot(tools: list[ToolInfo], label: str = "") -> dict[str, Any]:
+    return {
+        "mcplens_snapshot": SNAPSHOT_VERSION,
+        "created": datetime.now(timezone.utc).isoformat(),
+        "target": label,
+        "set_sha256": set_hash(tools),
+        "tools": {
+            t.name: {"sha256": tool_hash(t), "definition": t.canonical()}
+            for t in tools
+        },
+    }
+
+
+def save_snapshot(snapshot: dict[str, Any], path: str) -> None:
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(snapshot, fh, indent=2, sort_keys=True)
+        fh.write("\n")
+
+
+def load_snapshot(path: str) -> dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if data.get("mcplens_snapshot") != SNAPSHOT_VERSION:
+        raise ValueError(f"{path} is not an mcplens snapshot (version mismatch)")
+    return data
+
+
+@dataclass
+class ToolChange:
+    name: str
+    kind: str  # "added" | "removed" | "changed"
+    fields: list[str] = field(default_factory=list)  # for "changed": which fields differ
+
+
+@dataclass
+class DiffResult:
+    changes: list[ToolChange] = field(default_factory=list)
+    old_set_hash: str = ""
+    new_set_hash: str = ""
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.changes)
+
+
+def _field_diffs(old_def: dict[str, Any], new_def: dict[str, Any]) -> list[str]:
+    fields = []
+    if old_def.get("description") != new_def.get("description"):
+        fields.append("description")
+    if json.dumps(old_def.get("inputSchema") or {}, sort_keys=True) != \
+            json.dumps(new_def.get("inputSchema") or {}, sort_keys=True):
+        fields.append("inputSchema")
+    return fields
+
+
+def diff_snapshot(snapshot: dict[str, Any], current: list[ToolInfo]) -> DiffResult:
+    old_tools: dict[str, Any] = snapshot.get("tools") or {}
+    result = DiffResult(old_set_hash=snapshot.get("set_sha256", ""),
+                        new_set_hash=set_hash(current))
+    current_by_name = {t.name: t for t in current}
+
+    for name in sorted(set(old_tools) - set(current_by_name)):
+        result.changes.append(ToolChange(name=name, kind="removed"))
+    for name in sorted(set(current_by_name) - set(old_tools)):
+        result.changes.append(ToolChange(name=name, kind="added"))
+    for name in sorted(set(old_tools) & set(current_by_name)):
+        tool = current_by_name[name]
+        if old_tools[name].get("sha256") != tool_hash(tool):
+            old_def = old_tools[name].get("definition") or {}
+            fields = _field_diffs(old_def, tool.canonical())
+            result.changes.append(ToolChange(name=name, kind="changed",
+                                             fields=fields or ["definition"]))
+    return result

mcplens/cli.py

@@ -0,0 +1,157 @@
+"""mcplens command-line interface.
+
+Commands:
+  mcplens scan     --cmd "..." | --config cfg.json [--name X] | --url URL
+                   [--probes] [--format text|json]
+  mcplens baseline (same target flags) [--out mcplens-baseline.json]
+  mcplens diff     (same target flags) [--baseline mcplens-baseline.json]
+
+Exit codes: scan -> 1 if any critical finding, else 0.
+            diff -> 1 if tool definitions drifted from the baseline.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .baseline import diff_snapshot, load_snapshot, make_snapshot, save_snapshot
+from .models import ScanReport
+from .report import render_diff, render_text
+from .rules import analyze_tools
+from .transport import Target, fetch_tools
+
+
+def _add_target_args(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("target (pick one)")
+    g.add_argument("--cmd", metavar="COMMAND",
+                   help='stdio server command, e.g. --cmd "python server.py"')
+    g.add_argument("--config", metavar="PATH",
+                   help="client config JSON (mcpServers format)")
+    g.add_argument("--name", metavar="SERVER",
+                   help="server name inside --config (required if it holds several)")
+    g.add_argument("--url", metavar="URL",
+                   help="streamable HTTP MCP endpoint URL")
+
+
+def _resolve_target(args: argparse.Namespace) -> Target:
+    if getattr(args, "url", None):
+        return Target.from_url(args.url)
+    if getattr(args, "config", None):
+        return Target.from_config(args.config, args.name)
+    if getattr(args, "cmd", None):
+        return Target.from_command(args.cmd)
+    raise SystemExit("error: specify a target with --cmd, --config, or --url")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcplens",
+        description="MCP server security scanner with runtime behavioral verification.",
+    )
+    parser.add_argument("--version", action="version", version=f"mcplens {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="enumerate tools, run static rules, optionally probe behavior")
+    _add_target_args(p_scan)
+    p_scan.add_argument("--probes", action="store_true",
+                        help="run dynamic canary probes in a sandbox (stdio targets only)")
+    p_scan.add_argument("--format", choices=("text", "json"), default="text")
+
+    p_base = sub.add_parser("baseline", help="save a hash snapshot of tool definitions")
+    _add_target_args(p_base)
+    p_base.add_argument("--out", default="mcplens-baseline.json",
+                        help="snapshot file to write (default: mcplens-baseline.json)")
+
+    p_diff = sub.add_parser("diff", help="compare current tool definitions against a baseline")
+    _add_target_args(p_diff)
+    p_diff.add_argument("--baseline", default="mcplens-baseline.json",
+                        help="snapshot file to compare against (default: mcplens-baseline.json)")
+    return parser
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    target = _resolve_target(args)
+    report = ScanReport(target_label=target.label, transport=target.kind)
+
+    probe_findings = []
+    if args.probes:
+        if target.kind != "stdio":
+            print("error: --probes requires a stdio target (--cmd or --config)", file=sys.stderr)
+            return 2
+        from .probes import run_probes
+        run = run_probes(target)
+        report.tools = run.tools
+        report.probes = run.results
+        report.probes_run = True
+        probe_findings = run.findings
+    else:
+        report.tools = fetch_tools(target)
+
+    static_findings = analyze_tools(report.tools,
+                                    target_url=target.url if target.kind == "http" else "")
+    report.findings = static_findings + probe_findings
+
+    if args.format == "json":
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(render_text(report))
+    return 1 if any(f.severity == "critical" for f in report.findings) else 0
+
+
+def cmd_baseline(args: argparse.Namespace) -> int:
+    target = _resolve_target(args)
+    tools = fetch_tools(target)
+    snapshot = make_snapshot(tools, label=target.label)
+    save_snapshot(snapshot, args.out)
+    print(f"Baseline saved to {args.out}")
+    print(f"  target:    {target.label}")
+    print(f"  tools:     {len(tools)}")
+    print(f"  set hash:  {snapshot['set_sha256']}")
+    for t in tools:
+        print(f"    {t.name:<32} {snapshot['tools'][t.name]['sha256'][:16]}…")
+    return 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    target = _resolve_target(args)
+    try:
+        snapshot = load_snapshot(args.baseline)
+    except (OSError, ValueError) as exc:
+        print(f"error: cannot load baseline: {exc}", file=sys.stderr)
+        return 2
+    tools = fetch_tools(target)
+    result = diff_snapshot(snapshot, tools)
+    print(render_diff(result, target.label))
+    return 1 if result.has_changes else 0
+
+
+def _flatten(exc: BaseException) -> str:
+    """One-line message for an exception, unwrapping exception groups."""
+    if isinstance(exc, BaseExceptionGroup) and exc.exceptions:
+        return _flatten(exc.exceptions[0])
+    return str(exc) or type(exc).__name__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "scan":
+            return cmd_scan(args)
+        if args.command == "baseline":
+            return cmd_baseline(args)
+        if args.command == "diff":
+            return cmd_diff(args)
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except BaseExceptionGroup as group:  # transport/task-group failures
+        print(f"error: {_flatten(group)}", file=sys.stderr)
+        return 2
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcplens/models.py

@@ -0,0 +1,116 @@
+"""Core data structures for mcplens."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Any, Optional
+
+SEVERITIES = ("critical", "high", "medium", "low", "info")
+SEVERITY_ORDER = {name: i for i, name in enumerate(SEVERITIES)}
+SEVERITY_PENALTY = {"critical": 40, "high": 20, "medium": 8, "low": 3, "info": 1}
+
+
+@dataclass
+class ToolInfo:
+    """A single tool definition as advertised by an MCP server (tools/list)."""
+
+    name: str
+    description: str = ""
+    input_schema: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_mcp(cls, tool: Any) -> "ToolInfo":
+        schema = getattr(tool, "inputSchema", None) or \
+            getattr(tool, "input_schema", None) or {}
+        if not isinstance(schema, dict):
+            try:
+                schema = dict(schema)
+            except Exception:
+                schema = {}
+        return cls(
+            name=getattr(tool, "name", "") or "",
+            description=getattr(tool, "description", None) or "",
+            input_schema=schema,
+        )
+
+    def canonical(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+
+    def canonical_json(self) -> str:
+        return json.dumps(self.canonical(), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: str  # one of SEVERITIES
+    title: str
+    tool: Optional[str]  # tool name, or None for server-level findings
+    detail: str
+    owasp: str = ""  # OWASP MCP Top 10 mapping, e.g. "MCP05 Tool Poisoning"
+    source: str = "static"  # "static" or "probe"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ToolProbeResult:
+    tool: str
+    probed: bool
+    note: str = ""
+    declared: list[str] = field(default_factory=list)   # behaviors implied by name/description
+    observed: list[str] = field(default_factory=list)   # behaviors actually observed
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ScanReport:
+    target_label: str
+    transport: str  # "stdio" or "http"
+    tools: list[ToolInfo] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    probes: list[ToolProbeResult] = field(default_factory=list)
+    probes_run: bool = False
+
+    @property
+    def score(self) -> int:
+        score = 100
+        for f in self.findings:
+            score -= SEVERITY_PENALTY.get(f.severity, 0)
+        return max(0, score)
+
+    @property
+    def grade(self) -> str:
+        s = self.score
+        if s >= 90:
+            return "A"
+        if s >= 75:
+            return "B"
+        if s >= 60:
+            return "C"
+        if s >= 40:
+            return "D"
+        return "F"
+
+    def sorted_findings(self) -> list[Finding]:
+        return sorted(self.findings, key=lambda f: (SEVERITY_ORDER.get(f.severity, 99), f.rule_id))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target_label,
+            "transport": self.transport,
+            "grade": self.grade,
+            "score": self.score,
+            "tools": [t.canonical() for t in self.tools],
+            "findings": [f.to_dict() for f in self.sorted_findings()],
+            "probes_run": self.probes_run,
+            "probes": [p.to_dict() for p in self.probes],
+        }