mcplens-scanner 0.1.0__tar.gz

mcplens_scanner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karmendra Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcplens_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: mcplens-scanner
+Version: 0.1.0
+Summary: MCP server security scanner with runtime behavioral verification — checks that tools actually do what their descriptions claim.
+Author: Karmendra Pandey
+License: MIT
+Project-URL: Homepage, https://github.com/karmendra8386/mcplens
+Project-URL: Repository, https://github.com/karmendra8386/mcplens
+Keywords: mcp,model-context-protocol,security,scanner,ai-agents,tool-poisoning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# mcplens
+
+**An MCP server security scanner that doesn't just read what a server claims — it tests what the server actually does.**
+
+Static scanners for the Model Context Protocol (MCP) read tool descriptions and configs. That's table stakes, and mcplens does it too. But a tool description is a *claim*, and the worst MCP attacks — tool poisoning, rug pulls, confused-deputy tools — are lies told in exactly those claims.
+
+mcplens adds **runtime behavioral verification**:
+
+- It launches the server in a sandbox whose `HOME` is stocked with **canary credential files** (a fake `~/.ssh/id_rsa`, fake AWS credentials — each with a unique token).
+- It invokes every tool once with safe, schema-derived benign inputs.
+- It watches what actually happens: canary tokens leaking into responses, writes to the filesystem from "read-only" tools, network requests the description never mentions.
+- Every probed tool gets a **declared-vs-observed report card**.
+
+And because servers change after you approve them, mcplens **baselines** tool definitions with SHA-256 hashes and **diffs** them later — the rug-pull watch.
+
+Maintained by **Karmendra Pandey**. MIT licensed.
+
+## Install
+
+```bash
+pip install mcplens-scanner        # (PyPI release pending; for now install from source)
+git clone https://github.com/karmendra8386/mcplens && cd mcplens
+pip install -e .
+```
+
+Requires Python 3.10+ and the official `mcp` Python SDK (installed automatically).
+
+## Usage
+
+### Scan a server (static rules)
+
+```bash
+# stdio server by command
+mcplens scan --cmd "python my_server.py"
+
+# from a client config (Claude Desktop / mcpServers format)
+mcplens scan --config ~/.config/claude/claude_desktop_config.json --name my-server
+
+# remote streamable-HTTP server
+mcplens scan --url https://example.com/mcp
+```
+
+### Scan with behavioral probes (stdio servers)
+
+```bash
+mcplens scan --probes --cmd "python my_server.py"
+```
+
+Probes run the server with `HOME` and the working directory pointed at a throwaway sandbox. Your real files are never touched, probes never pass destructive payloads, tools with free-form command parameters are never exercised, and destructive-looking tools are skipped and reported as *not probed*.
+
+Machine-readable output:
+
+```bash
+mcplens scan --probes --format json --cmd "python my_server.py"
+```
+
+Exit code is `1` when any critical finding is present, `0` otherwise — CI-friendly.
+
+### Baseline & rug-pull diff
+
+```bash
+mcplens baseline --cmd "python my_server.py"          # writes mcplens-baseline.json
+# ...later, after the server updates...
+mcplens diff --cmd "python my_server.py"              # exit 1 if definitions drifted
+```
+
+The baseline stores the SHA-256 of every tool's canonical definition (name + description + input schema) plus a whole-set hash. `diff` reports added, removed, and changed tools, with the changed fields named.
+
+## What it catches
+
+Sample output against the deliberately vulnerable fixture in `fixtures/`:
+
+```
+Findings: 5 (critical 4, high 1, medium 0, low 0, info 0)
+  [CRITICAL] MCPL001 (static) add: Instruction injection in tool description
+  [CRITICAL] MCPL003 (static) add: Tool description references sensitive files
+  [CRITICAL] MCPL101 (probe) get_system_info: Tool returned canary credential contents
+  [CRITICAL] MCPL103 (probe) get_system_info: Read-only-claimed tool modified the filesystem
+  [HIGH    ] MCPL005 (static) run_command: Unconstrained shell/command parameter
+
+Behavioral probes (declared vs observed):
+  - get_system_info: declared [read-only access] | observed [returned a response;
+      returned contents of canary file(s): .ssh/id_rsa;
+      filesystem changes: home/.mcplens_was_here]
+
+Grade: F  (score 0/100)
+```
+
+Note what happened there: `get_system_info` looks *clean* to static analysis — its description is a lie, and only running it exposes the lie. That gap is why mcplens exists.
+
+## Rule catalog
+
+Static rules (see [docs/rule-catalog.md](docs/rule-catalog.md)):
+
+| ID | Severity | Check | OWASP MCP Top 10 |
+|---|---|---|---|
+| MCPL001 | critical | Instruction injection in tool description | MCP05 Tool Poisoning |
+| MCPL002 | high | Hidden / bidirectional Unicode in tool definition | MCP05 Tool Poisoning |
+| MCPL003 | critical | Description references sensitive files (`~/.ssh`, `.env`, …) | MCP05 Tool Poisoning |
+| MCPL004 | medium | Look-alike tool names (possible shadowing) | MCP05 Tool Poisoning |
+| MCPL005 | high | Unconstrained shell/command parameter | MCP04 Command Injection |
+| MCPL006 | medium | Parameter with no type constraint | MCP09 Protocol & Transport |
+| MCPL007 | medium | Schema allows arbitrary additional properties | MCP06 Privilege Escalation |
+| MCPL008 | medium | Read-only-sounding tool describes write/exec behavior | MCP06 Privilege Escalation |
+| MCPL009 | low | Excessive tool count (> 50) | MCP02 Context Over-Sharing |
+| MCPL010 | high | Duplicate tool names | MCP05 Tool Poisoning |
+| MCPL011 | medium | Description claims broad data access | MCP02 Context Over-Sharing |
+| MCPL012 | low | Unusually long description (> 2000 chars) | MCP05 Tool Poisoning |
+| MCPL013 | medium | Server reached over plaintext HTTP | MCP09 Protocol & Transport |
+| MCPL014 | medium | Tool accepts a secret as a plain parameter | MCP01 Token Mismanagement |
+| MCPL015 | low | Tool has no description | MCP08 Audit Logging |
+
+Behavioral probe findings:
+
+| ID | Severity | Check | OWASP MCP Top 10 |
+|---|---|---|---|
+| MCPL101 | critical | Tool returned canary credential contents | MCP02 Context Over-Sharing |
+| MCPL102 | high | Tool modified the filesystem without declaring it | MCP06 Privilege Escalation |
+| MCPL103 | critical | Read-only-claimed tool modified the filesystem | MCP06 Privilege Escalation |
+| MCPL104 | high | Tool made an undeclared network request | MCP02 Context Over-Sharing |
+| MCPL105 | low | Tool errored under benign probe input | MCP08 Audit Logging |
+
+Each server is graded **A–F** from its findings (critical −40, high −20, medium −8, low −3).
+
+## How the probes work
+
+1. **Sandbox.** A temp directory becomes the server's `HOME` and working directory. It contains canary files: `.ssh/id_rsa`, `.aws/credentials`, `canary_note.txt`, `Documents/finances.txt` — each holding a unique `MCPLENS-CANARY-…` token.
+2. **Argument derivation.** For each tool, arguments are derived from its input schema: strings get harmless placeholders, URL parameters get the URL of a local one-shot HTTP listener, integers get `1`, and so on. Tools whose names suggest destructive operations, and tools with free-form command parameters, are never invoked.
+3. **Observation.** The sandbox filesystem is hashed before and after *each* invocation, so writes are attributed to the exact tool that made them. Responses are searched for canary tokens. Listener hits reveal network egress, which is only a finding when the description doesn't declare network use.
+4. **Report card.** Each tool's inferred *declared* behaviors (from its name and description) are printed next to what was *observed*.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+The test suite runs against two fixture servers in `fixtures/`: `benign_server.py` (honest tools — must stay clean) and `vulnerable_server.py` (a poisoned description, a behaviorally lying "read-only" tool, and a raw shell tool — **test fixture only, never deploy it**).
+
+## Roadmap
+
+- **v0.2** — SARIF output for CI dashboards; schema-fuzzing probes (boundary/malformed inputs); probing of remote HTTP servers in an isolated environment.
+- **Research** — a registry-scale behavioral study: run mcplens against the most popular public MCP servers and publish how many tools do more than their descriptions claim ("Do MCP Tools Do What They Say?").
+- Signed tool-definition registries and continuous rug-pull monitoring.
+
+## Responsible use
+
+mcplens' probes are benign canaries meant for servers you own or are authorized to test. Pointing any scanner at third-party servers beyond their public tool interface is out of scope.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Author and maintainer: Karmendra Pandey.

mcplens_scanner-0.1.0/README.md

@@ -0,0 +1,153 @@
+# mcplens
+
+**An MCP server security scanner that doesn't just read what a server claims — it tests what the server actually does.**
+
+Static scanners for the Model Context Protocol (MCP) read tool descriptions and configs. That's table stakes, and mcplens does it too. But a tool description is a *claim*, and the worst MCP attacks — tool poisoning, rug pulls, confused-deputy tools — are lies told in exactly those claims.
+
+mcplens adds **runtime behavioral verification**:
+
+- It launches the server in a sandbox whose `HOME` is stocked with **canary credential files** (a fake `~/.ssh/id_rsa`, fake AWS credentials — each with a unique token).
+- It invokes every tool once with safe, schema-derived benign inputs.
+- It watches what actually happens: canary tokens leaking into responses, writes to the filesystem from "read-only" tools, network requests the description never mentions.
+- Every probed tool gets a **declared-vs-observed report card**.
+
+And because servers change after you approve them, mcplens **baselines** tool definitions with SHA-256 hashes and **diffs** them later — the rug-pull watch.
+
+Maintained by **Karmendra Pandey**. MIT licensed.
+
+## Install
+
+```bash
+pip install mcplens-scanner        # (PyPI release pending; for now install from source)
+git clone https://github.com/karmendra8386/mcplens && cd mcplens
+pip install -e .
+```
+
+Requires Python 3.10+ and the official `mcp` Python SDK (installed automatically).
+
+## Usage
+
+### Scan a server (static rules)
+
+```bash
+# stdio server by command
+mcplens scan --cmd "python my_server.py"
+
+# from a client config (Claude Desktop / mcpServers format)
+mcplens scan --config ~/.config/claude/claude_desktop_config.json --name my-server
+
+# remote streamable-HTTP server
+mcplens scan --url https://example.com/mcp
+```
+
+### Scan with behavioral probes (stdio servers)
+
+```bash
+mcplens scan --probes --cmd "python my_server.py"
+```
+
+Probes run the server with `HOME` and the working directory pointed at a throwaway sandbox. Your real files are never touched, probes never pass destructive payloads, tools with free-form command parameters are never exercised, and destructive-looking tools are skipped and reported as *not probed*.
+
+Machine-readable output:
+
+```bash
+mcplens scan --probes --format json --cmd "python my_server.py"
+```
+
+Exit code is `1` when any critical finding is present, `0` otherwise — CI-friendly.
+
+### Baseline & rug-pull diff
+
+```bash
+mcplens baseline --cmd "python my_server.py"          # writes mcplens-baseline.json
+# ...later, after the server updates...
+mcplens diff --cmd "python my_server.py"              # exit 1 if definitions drifted
+```
+
+The baseline stores the SHA-256 of every tool's canonical definition (name + description + input schema) plus a whole-set hash. `diff` reports added, removed, and changed tools, with the changed fields named.
+
+## What it catches
+
+Sample output against the deliberately vulnerable fixture in `fixtures/`:
+
+```
+Findings: 5 (critical 4, high 1, medium 0, low 0, info 0)
+  [CRITICAL] MCPL001 (static) add: Instruction injection in tool description
+  [CRITICAL] MCPL003 (static) add: Tool description references sensitive files
+  [CRITICAL] MCPL101 (probe) get_system_info: Tool returned canary credential contents
+  [CRITICAL] MCPL103 (probe) get_system_info: Read-only-claimed tool modified the filesystem
+  [HIGH    ] MCPL005 (static) run_command: Unconstrained shell/command parameter
+
+Behavioral probes (declared vs observed):
+  - get_system_info: declared [read-only access] | observed [returned a response;
+      returned contents of canary file(s): .ssh/id_rsa;
+      filesystem changes: home/.mcplens_was_here]
+
+Grade: F  (score 0/100)
+```
+
+Note what happened there: `get_system_info` looks *clean* to static analysis — its description is a lie, and only running it exposes the lie. That gap is why mcplens exists.
+
+## Rule catalog
+
+Static rules (see [docs/rule-catalog.md](docs/rule-catalog.md)):
+
+| ID | Severity | Check | OWASP MCP Top 10 |
+|---|---|---|---|
+| MCPL001 | critical | Instruction injection in tool description | MCP05 Tool Poisoning |
+| MCPL002 | high | Hidden / bidirectional Unicode in tool definition | MCP05 Tool Poisoning |
+| MCPL003 | critical | Description references sensitive files (`~/.ssh`, `.env`, …) | MCP05 Tool Poisoning |
+| MCPL004 | medium | Look-alike tool names (possible shadowing) | MCP05 Tool Poisoning |
+| MCPL005 | high | Unconstrained shell/command parameter | MCP04 Command Injection |
+| MCPL006 | medium | Parameter with no type constraint | MCP09 Protocol & Transport |
+| MCPL007 | medium | Schema allows arbitrary additional properties | MCP06 Privilege Escalation |
+| MCPL008 | medium | Read-only-sounding tool describes write/exec behavior | MCP06 Privilege Escalation |
+| MCPL009 | low | Excessive tool count (> 50) | MCP02 Context Over-Sharing |
+| MCPL010 | high | Duplicate tool names | MCP05 Tool Poisoning |
+| MCPL011 | medium | Description claims broad data access | MCP02 Context Over-Sharing |
+| MCPL012 | low | Unusually long description (> 2000 chars) | MCP05 Tool Poisoning |
+| MCPL013 | medium | Server reached over plaintext HTTP | MCP09 Protocol & Transport |
+| MCPL014 | medium | Tool accepts a secret as a plain parameter | MCP01 Token Mismanagement |
+| MCPL015 | low | Tool has no description | MCP08 Audit Logging |
+
+Behavioral probe findings:
+
+| ID | Severity | Check | OWASP MCP Top 10 |
+|---|---|---|---|
+| MCPL101 | critical | Tool returned canary credential contents | MCP02 Context Over-Sharing |
+| MCPL102 | high | Tool modified the filesystem without declaring it | MCP06 Privilege Escalation |
+| MCPL103 | critical | Read-only-claimed tool modified the filesystem | MCP06 Privilege Escalation |
+| MCPL104 | high | Tool made an undeclared network request | MCP02 Context Over-Sharing |
+| MCPL105 | low | Tool errored under benign probe input | MCP08 Audit Logging |
+
+Each server is graded **A–F** from its findings (critical −40, high −20, medium −8, low −3).
+
+## How the probes work
+
+1. **Sandbox.** A temp directory becomes the server's `HOME` and working directory. It contains canary files: `.ssh/id_rsa`, `.aws/credentials`, `canary_note.txt`, `Documents/finances.txt` — each holding a unique `MCPLENS-CANARY-…` token.
+2. **Argument derivation.** For each tool, arguments are derived from its input schema: strings get harmless placeholders, URL parameters get the URL of a local one-shot HTTP listener, integers get `1`, and so on. Tools whose names suggest destructive operations, and tools with free-form command parameters, are never invoked.
+3. **Observation.** The sandbox filesystem is hashed before and after *each* invocation, so writes are attributed to the exact tool that made them. Responses are searched for canary tokens. Listener hits reveal network egress, which is only a finding when the description doesn't declare network use.
+4. **Report card.** Each tool's inferred *declared* behaviors (from its name and description) are printed next to what was *observed*.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+The test suite runs against two fixture servers in `fixtures/`: `benign_server.py` (honest tools — must stay clean) and `vulnerable_server.py` (a poisoned description, a behaviorally lying "read-only" tool, and a raw shell tool — **test fixture only, never deploy it**).
+
+## Roadmap
+
+- **v0.2** — SARIF output for CI dashboards; schema-fuzzing probes (boundary/malformed inputs); probing of remote HTTP servers in an isolated environment.
+- **Research** — a registry-scale behavioral study: run mcplens against the most popular public MCP servers and publish how many tools do more than their descriptions claim ("Do MCP Tools Do What They Say?").
+- Signed tool-definition registries and continuous rug-pull monitoring.
+
+## Responsible use
+
+mcplens' probes are benign canaries meant for servers you own or are authorized to test. Pointing any scanner at third-party servers beyond their public tool interface is out of scope.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Author and maintainer: Karmendra Pandey.

mcplens_scanner-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcplens-scanner"
+version = "0.1.0"
+description = "MCP server security scanner with runtime behavioral verification — checks that tools actually do what their descriptions claim."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Karmendra Pandey" }]
+keywords = ["mcp", "model-context-protocol", "security", "scanner", "ai-agents", "tool-poisoning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = ["mcp>=2.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+mcplens = "mcplens.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/karmendra8386/mcplens"
+Repository = "https://github.com/karmendra8386/mcplens"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcplens_scanner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcplens_scanner-0.1.0/src/mcplens/__init__.py

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

mcplens_scanner-0.1.0/src/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_scanner-0.1.0/src/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())