mcppt 1.0.0__py3-none-any.whl

mcppt/cli.py

@@ -0,0 +1,243 @@
+"""MCPPT CLI — entry point for `mcppt` command."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .core import configure, mcp_init, rpc
+
+CHECKS = [
+    "enum", "auth", "idor", "injection", "schema", "ssrf", "publish",
+    "rate", "stored", "scope", "replay", "context_overflow", "poison_all",
+    "tenant", "session", "rug_pull",
+    "headers", "error_disclosure", "tool_poisoning", "resources",
+    "cmd_injection", "path_traversal", "jwt_audit", "oauth_discovery",
+    "secret_scan", "tool_shadowing",
+    "sampling", "schema_leak",
+]
+
+EPILOG = """
+commands:
+  scan        Run all/selected security checks with live TUI
+  list        Enumerate tools and parameter schemas
+  call        Call a single tool with custom JSON args
+  shell       Launch interactive REPL (default when run with no args)
+  serve-mcp   Expose MCPTROTTER itself as an MCP server
+
+examples:
+  mcppt                                               <- interactive shell
+  mcppt scan --url https://target.com/mcp --token eyJ...
+  mcppt scan --url https://target.com/mcp --token t1 --token2 t2 --checks idor,scope
+  mcppt scan --url https://target.com/mcp --no-verify --output report.md
+  mcppt scan --url https://target.com/mcp --proxy http://127.0.0.1:8080 --checks all
+  mcppt list --url https://target.com/mcp --token eyJ...
+  mcppt call --url https://target.com/mcp --token eyJ... --tool get_user --args '{"id":1}'
+  mcppt serve-mcp --port 8899
+"""
+
+
+# ── scan ──────────────────────────────────────────────────────────────────────
+
+def cmd_scan(args: argparse.Namespace) -> None:
+    from .checks import ScanState, run_scan, ALL_CHECKS
+    from .tui import run_tui
+    from .report import save_json, save_markdown
+
+    configure(no_verify=args.no_verify, proxy=args.proxy or None)
+
+    checks = [c.strip() for c in args.checks.split(",")]
+    run_all = "all" in checks
+    total = len(ALL_CHECKS) if run_all else len([c for c in checks if c in ALL_CHECKS])
+
+    state = ScanState(
+        url=args.url,
+        token=args.token or None,
+        token2=args.token2 or None,
+        checks_total=total,
+    )
+
+    run_tui(state, run_scan, state, checks)
+
+    if args.output:
+        p = (
+            save_markdown(state, args.output)
+            if args.output.endswith(".md")
+            else save_json(state, args.output)
+        )
+        print(f"\n  Report saved → {p}")
+
+
+# ── list ──────────────────────────────────────────────────────────────────────
+
+def cmd_list(args: argparse.Namespace) -> None:
+    from rich import box
+    from rich.console import Console
+    from rich.table import Table
+
+    configure(no_verify=args.no_verify, proxy=args.proxy or None)
+    console = Console()
+
+    mcp_init(args.url, args.token or None)
+    r = rpc(args.url, "tools/list", {}, token=args.token or None)
+    if r["status"] != 200:
+        console.print(f"[red]tools/list failed: HTTP {r['status']}[/]")
+        sys.exit(1)
+
+    tools = r["body"].get("result", {}).get("tools", [])
+    if not tools:
+        console.print("[yellow]No tools returned.[/]")
+        return
+
+    console.print(f"\n[bold]{len(tools)} tools on [cyan]{args.url}[/][/]\n")
+    for t in tools:
+        name = t.get("name", "?")
+        desc = t.get("description", "").split("\n")[0][:80]
+        props = t.get("inputSchema", {}).get("properties", {})
+        required = t.get("inputSchema", {}).get("required", [])
+
+        console.print(f"[bold cyan]{name}[/]  [dim]{desc}[/]")
+        if props:
+            tbl = Table(show_header=True, box=box.SIMPLE, header_style="bold dim", padding=(0, 1))
+            tbl.add_column("Field")
+            tbl.add_column("Type")
+            tbl.add_column("Req", width=4)
+            tbl.add_column("Description")
+            for field, meta in props.items():
+                req = "[red]*[/]" if field in required else ""
+                tbl.add_row(
+                    field,
+                    meta.get("type", "any"),
+                    req,
+                    meta.get("description", "")[:70],
+                )
+            console.print(tbl)
+        console.print()
+
+
+# ── call ──────────────────────────────────────────────────────────────────────
+
+def cmd_call(args: argparse.Namespace) -> None:
+    from rich.console import Console
+
+    configure(no_verify=args.no_verify, proxy=args.proxy or None)
+    console = Console()
+
+    try:
+        tool_args = json.loads(args.args)
+    except json.JSONDecodeError as e:
+        console.print(f"[red]Invalid JSON args: {e}[/]")
+        sys.exit(1)
+
+    mcp_init(args.url, args.token or None)
+    console.print(f"\nCalling [cyan]{args.tool}[/] on [cyan]{args.url}[/]...")
+    r = rpc(
+        args.url,
+        "tools/call",
+        {"name": args.tool, "arguments": tool_args},
+        token=args.token or None,
+    )
+    status_style = "green" if r["status"] == 200 else "red"
+    console.print(f"[{status_style}]HTTP {r['status']}[/]")
+
+    body = r["body"]
+    result = body.get("result", {})
+    content = result.get("content", [])
+    if content:
+        for item in content:
+            if item.get("type") == "text":
+                try:
+                    console.print_json(json.dumps(json.loads(item["text"])))
+                except Exception:
+                    console.print(item["text"])
+    elif "error" in body:
+        console.print(f"[red]Error:[/] {body['error']}")
+    else:
+        console.print_json(json.dumps(body))
+
+
+# ── arg parsing ───────────────────────────────────────────────────────────────
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--url",       required=True,  help="MCP server endpoint URL")
+    p.add_argument("--token",     default=None,   help="Bearer token (primary)")
+    p.add_argument("--no-verify", action="store_true", help="Skip SSL certificate verification")
+    p.add_argument("--proxy",     default=None,   help="Proxy URL  e.g. http://127.0.0.1:8080")
+
+
+def _ensure_utf8() -> None:
+    """Reconfigure stdout/stderr to UTF-8 on Windows so Rich box-drawing chars encode."""
+    import sys
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def cmd_shell(_args=None) -> None:
+    from .shell import launch_shell
+    launch_shell()
+
+
+def cmd_serve_mcp(args: argparse.Namespace) -> None:
+    from .server import serve
+    serve(port=args.port)
+
+
+def main() -> None:
+    _ensure_utf8()
+    parser = argparse.ArgumentParser(
+        prog="mcppt",
+        description="MCPTROTTER v2.3 — MCP Pentest Tool  |  28 automated security checks",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=EPILOG,
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # scan
+    p_scan = sub.add_parser("scan", help="Run security scan (live TUI)")
+    _add_common(p_scan)
+    p_scan.add_argument("--token2",  default=None, help="Second user token (IDOR/scope/tenant checks)")
+    p_scan.add_argument("--checks",  default="all",
+                        help=f"Comma-separated checks or 'all'.  Options: {','.join(CHECKS)}")
+    p_scan.add_argument("--output",  default=None,
+                        help="Save report to file  (report.json  or  report.md)")
+
+    # list
+    p_list = sub.add_parser("list", help="Enumerate tools and schemas")
+    _add_common(p_list)
+
+    # call
+    p_call = sub.add_parser("call", help="Call a single tool")
+    _add_common(p_call)
+    p_call.add_argument("--tool", required=True, help="Tool name to call")
+    p_call.add_argument("--args", default="{}", help="JSON arguments  (default: {})")
+
+    # shell
+    sub.add_parser("shell", help="Launch interactive REPL (gobuster/ffuf-style)")
+
+    # serve-mcp
+    p_serve = sub.add_parser("serve-mcp", help="Expose MCPTROTTER as an MCP server")
+    p_serve.add_argument("--port", type=int, default=8899, help="Port to listen on (default: 8899)")
+
+    args = parser.parse_args()
+
+    # default: no subcommand → launch interactive shell
+    if not args.command:
+        cmd_shell()
+        return
+
+    dispatch = {
+        "scan":      cmd_scan,
+        "list":      cmd_list,
+        "call":      cmd_call,
+        "shell":     cmd_shell,
+        "serve-mcp": cmd_serve_mcp,
+    }
+    dispatch[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

mcppt/core.py

@@ -0,0 +1,169 @@
+"""Low-level JSON-RPC transport for MCP Streamable HTTP servers."""
+from __future__ import annotations
+
+import base64
+import json
+import ssl
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+_SESSION_ID: Optional[str] = None
+_SSL_CTX: Optional[ssl.SSLContext] = None
+_PROXY_HANDLER: Any = None
+
+
+def configure(no_verify: bool = False, proxy: Optional[str] = None) -> None:
+    global _SSL_CTX, _PROXY_HANDLER
+    if no_verify:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        _SSL_CTX = ctx
+    else:
+        _SSL_CTX = None
+    _PROXY_HANDLER = (
+        urllib.request.ProxyHandler({"http": proxy, "https": proxy}) if proxy else None
+    )
+
+
+def reset_session() -> None:
+    global _SESSION_ID
+    _SESSION_ID = None
+
+
+def get_session_id() -> Optional[str]:
+    return _SESSION_ID
+
+
+def set_session_id(sid: Optional[str]) -> None:
+    global _SESSION_ID
+    _SESSION_ID = sid
+
+
+def rpc(
+    url: str,
+    method: str,
+    params: dict,
+    token: Optional[str] = None,
+    req_id: int = 1,
+) -> dict:
+    global _SESSION_ID
+    payload = json.dumps(
+        {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}
+    ).encode()
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    if _SESSION_ID:
+        headers["mcp-session-id"] = _SESSION_ID
+
+    try:
+        req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+        if _PROXY_HANDLER:
+            extra = (
+                urllib.request.HTTPSHandler(context=_SSL_CTX)
+                if _SSL_CTX
+                else urllib.request.HTTPSHandler()
+            )
+            opener = urllib.request.build_opener(_PROXY_HANDLER, extra)
+        elif _SSL_CTX:
+            opener = urllib.request.build_opener(
+                urllib.request.HTTPSHandler(context=_SSL_CTX)
+            )
+        else:
+            opener = urllib.request.build_opener()
+
+        with opener.open(req, timeout=15) as resp:
+            sid = resp.headers.get("mcp-session-id")
+            if sid and not _SESSION_ID:
+                _SESSION_ID = sid
+            return {
+                "status": resp.status,
+                "body": _parse_sse(resp.read().decode(errors="replace")),
+            }
+    except urllib.error.HTTPError as e:
+        try:
+            body = _parse_sse(e.read().decode(errors="replace"))
+        except Exception:
+            body = {"raw": str(e)}
+        return {"status": e.code, "body": body}
+    except Exception as e:
+        return {"status": 0, "body": {"error": str(e)}}
+
+
+def _parse_sse(raw: str) -> dict:
+    raw = raw.strip()
+    if not raw:
+        return {"error": "Empty response"}
+    data_lines = [
+        line[5:].strip() for line in raw.splitlines() if line.startswith("data:")
+    ]
+    if data_lines:
+        try:
+            return json.loads("\n".join(data_lines))
+        except Exception:
+            return {"raw_sse": "\n".join(data_lines)}
+    try:
+        return json.loads(raw)
+    except Exception:
+        return {"raw": raw[:500]}
+
+
+def mcp_init(url: str, token: Optional[str]) -> bool:
+    reset_session()
+    r = rpc(
+        url,
+        "initialize",
+        {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "mcppt", "version": "2.0"},
+        },
+        token=token,
+    )
+    if r["status"] == 200 and "result" in r["body"]:
+        rpc(url, "notifications/initialized", {}, token=token, req_id=2)
+        return True
+    return False
+
+
+def decode_jwt(token: str) -> dict:
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return {}
+        padded = parts[1] + "=" * (4 - len(parts[1]) % 4)
+        return json.loads(
+            base64.urlsafe_b64decode(padded).decode("utf-8", errors="replace")
+        )
+    except Exception:
+        return {}
+
+
+def jsonrpc_succeeded(body: dict) -> bool:
+    """True if the response indicates actual tool execution, not an auth rejection."""
+    if "result" not in body:
+        return False
+    content_text = "".join(
+        i.get("text", "").lower() for i in body["result"].get("content", [])
+    )
+    AUTH_KEYWORDS = [
+        "unauthorized", "forbidden", "401", "403", "access denied",
+        "not authenticated", "invalid token", "token expired",
+    ]
+    return not any(k in content_text for k in AUTH_KEYWORDS)
+
+
+def is_auth_error(body: dict) -> bool:
+    err = body.get("error", {})
+    code = err.get("code", 0)
+    msg = str(err.get("message", "")).lower()
+    AUTH_KEYWORDS = [
+        "unauthorized", "forbidden", "authentication",
+        "not authenticated", "invalid token", "access denied",
+    ]
+    return code in (401, 403) or any(k in msg for k in AUTH_KEYWORDS)

mcppt/report.py

@@ -0,0 +1,105 @@
+"""Generate JSON and Markdown reports from a completed ScanState."""
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from .checks import ScanState
+
+SEV_ICON = {"CRITICAL": "[CRIT]", "HIGH": "[HIGH]", "MEDIUM": "[MED]", "LOW": "[LOW]"}
+
+
+def save_json(state: ScanState, path: str) -> Path:
+    out = Path(path)
+    data = {
+        "tool": "MCPPT",
+        "version": "2.0.0",
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "target": state.url,
+        "elapsed_seconds": round(state.elapsed, 1),
+        "summary": {
+            sev: sum(1 for f in state.findings if f.severity == sev)
+            for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW")
+        },
+        "findings": [
+            {
+                "check": f.check,
+                "severity": f.severity,
+                "title": f.title,
+                "detail": f.detail,
+            }
+            for f in state.findings
+        ],
+    }
+    out.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return out
+
+
+def save_markdown(state: ScanState, path: str) -> Path:
+    out = Path(path)
+    ts = datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC")
+
+    lines = [
+        "# MCPPT Security Scan Report",
+        "",
+        f"**Target:** `{state.url}`  ",
+        f"**Date:** {ts}  ",
+        f"**Duration:** {state.elapsed:.1f}s  ",
+        "",
+        "## Summary",
+        "",
+        "| Severity | Count |",
+        "| --- | --- |",
+    ]
+    for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+        count = sum(1 for f in state.findings if f.severity == sev)
+        lines.append(f"| {SEV_ICON[sev]} {sev} | {count} |")
+
+    lines += ["", "## Findings", ""]
+
+    if not state.findings:
+        lines.append("_No findings detected — all checks passed._")
+    else:
+        for i, f in enumerate(state.findings, 1):
+            icon = SEV_ICON.get(f.severity, "⚪")
+            lines += [
+                f"### {i}. {icon} [{f.severity}] {f.title}",
+                "",
+                f"**Check:** `{f.check}`  ",
+                f"**Severity:** {f.severity}  ",
+                "",
+                f.detail,
+                "",
+                "---",
+                "",
+            ]
+
+    lines += [
+        "## Remediation Reference",
+        "",
+        "| Check | Risk | Fix |",
+        "| --- | --- | --- |",
+        "| `enum` | Info disclosure | Require auth on `tools/list` |",
+        "| `auth` | Auth bypass | Validate Bearer token server-side on every tool call |",
+        "| `idor` | Data exposure | Scope resource access to the authenticated user |",
+        "| `injection` | Prompt injection | Sanitise/escape all user-supplied strings before returning to LLM |",
+        "| `schema` | Input validation | Enforce strict type validation at the MCP server layer |",
+        "| `ssrf` | SSRF | Block RFC-1918/link-local URLs; use allowlist for external fetches |",
+        "| `publish` | Unconfirmed action | Enforce confirmation gate in MCP layer, not only in agent prompt |",
+        "| `rate` | DoS | Add rate limiting per token/IP |",
+        "| `stored` | Stored injection | Escape stored content before returning in tool responses |",
+        "| `scope` | Privilege escalation | Enforce token scopes server-side per tool |",
+        "| `replay` | Replay | Add per-request nonce or timestamp window validation |",
+        "| `context_overflow` | Context hijack | Enforce max field length at ingestion |",
+        "| `poison_all` | Injection | Sanitise every response field, not just primary content |",
+        "| `tenant` | Data leak | Scope cache keys and storage to tenant/user ID |",
+        "| `session` | Session hijack | Use CSPRNG ≥128-bit entropy for session IDs (UUID v4) |",
+        "| `rug_pull` | Supply chain | Pin tool versions; alert on description changes |",
+        "",
+        "---",
+        "_Generated by [MCPPT](https://github.com/gurudeepmallam-cmd/mcppt) v2.0_",
+    ]
+
+    out.write_text("\n".join(lines), encoding="utf-8")
+    return out