mcpsweep 0.1.0__tar.gz

mcpsweep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcpsweep contributors
+
+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.

mcpsweep-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mcpsweep
+Version: 0.1.0
+Summary: Discovery and fingerprinting scanner for MCP-over-HTTP servers (tool enumeration + risk heuristics).
+Author: mcpsweep contributors
+License: MIT
+Project-URL: Homepage, https://github.com/krishnareddypadala/mcpsweep
+Project-URL: Issues, https://github.com/krishnareddypadala/mcpsweep/issues
+Keywords: mcp,model-context-protocol,security,scanner,discovery,recon,llm,appsec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Internet
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcpsweep
+
+A small, dependency-free **discovery and fingerprinting scanner for MCP-over-HTTP
+servers**. It finds Model Context Protocol endpoints on a host or network,
+performs the JSON-RPC `initialize` handshake to fingerprint each one, enumerates
+its **tools / resources / prompts**, and flags risky or **poisoned** tools.
+
+It is strictly **read-only** — it performs the handshake and `*/list` calls only,
+and never invokes a tool (`tools/call`).
+
+> **Authorized use only.** Scan hosts you own or are explicitly permitted to test.
+
+## Why
+
+MCP servers are easy to spin up and often ship with no authentication, over-broad
+tools (arbitrary SQL, shell, money movement), or instructions hidden inside a
+tool's *description* (tool poisoning). `mcpsweep` helps you inventory that surface
+— including **shadow** servers nobody registered — and see the risk at a glance.
+
+## Install
+
+```bash
+pip install mcpsweep
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/krishnareddypadala/mcpsweep && cd mcpsweep
+pip install .
+```
+
+## Usage
+
+```bash
+# scan one host on a known port
+mcpsweep 10.10.0.31 --ports 8090
+
+# route everything through Burp for inspection
+mcpsweep 10.10.0.31 --ports 8090 --proxy http://127.0.0.1:8080
+
+# sweep a subnet and a port range, also list resources/prompts
+mcpsweep 10.10.0.0/28 --ports 8000-9100 --full
+
+# machine-readable output
+mcpsweep 10.10.0.31 --ports 8090 --format json -o report.json
+mcpsweep 10.10.0.31 --ports 8090 --format md   -o report.md
+```
+
+### Key options
+
+| Flag | Purpose |
+|---|---|
+| `--ports` | ports/ranges, e.g. `8090,8000,9000-9010` |
+| `--paths` | URL paths to probe (defaults cover `/mcp`, `/mcp/api`, `/sse`, …) |
+| `--scheme` | `http`, `https`, or `both` |
+| `--proxy` | send all traffic via a proxy (e.g. Burp on `127.0.0.1:8080`) |
+| `--insecure`/`-k` | skip TLS verification |
+| `--full` | also enumerate `resources/list` and `prompts/list` |
+| `--format`/`-f` | `text` (default), `json`, `md` |
+| `--concurrency`/`-c` | parallel probes (default 16) |
+
+Exit code is `0` when at least one endpoint is found, `1` otherwise.
+
+> **Windows / Git Bash note:** Git Bash (MSYS) rewrites arguments that look like
+> Unix paths, so `--paths /mcp/api` becomes a Windows path before the tool sees
+> it. Either omit `--paths` (the built-in defaults are unaffected), prefix the
+> command with `MSYS_NO_PATHCONV=1`, or run from PowerShell / `cmd`.
+
+## What it detects
+
+- **Live MCP endpoints** across many candidate paths/ports, via the `initialize`
+  handshake (Streamable-HTTP and SSE-framed responses).
+- **Server fingerprint**: name, version, protocol, capabilities, instructions.
+- **No authentication**: `initialize` that succeeds with no credentials.
+- **Auth-gated endpoints**: `401/403` with an MCP/`WWW-Authenticate` signature.
+- **Risky tools**: name/description heuristics tag `rce`, `sql`, `money`,
+  `destructive`, `write`, `secret`, `pii`, `filesystem`, …
+- **Tool poisoning**: descriptions containing hidden instructions to the model
+  ("ignore previous instructions", "silently", "password_hash", …).
+
+A per-endpoint **risk score** rolls these up into `low / medium / high / critical`.
+
+## Library use
+
+```python
+from mcpsweep import scan
+
+for ep in scan(["10.10.0.31"], ports=[8090], proxy="http://127.0.0.1:8080"):
+    print(ep.url, ep.server_name, ep.risk_level)
+    for t in ep.tools:
+        print("  ", t.name, t.tags, "POISONED" if t.poisoned else "")
+```
+
+## License
+
+MIT

mcpsweep-0.1.0/README.md

@@ -0,0 +1,97 @@
+# mcpsweep
+
+A small, dependency-free **discovery and fingerprinting scanner for MCP-over-HTTP
+servers**. It finds Model Context Protocol endpoints on a host or network,
+performs the JSON-RPC `initialize` handshake to fingerprint each one, enumerates
+its **tools / resources / prompts**, and flags risky or **poisoned** tools.
+
+It is strictly **read-only** — it performs the handshake and `*/list` calls only,
+and never invokes a tool (`tools/call`).
+
+> **Authorized use only.** Scan hosts you own or are explicitly permitted to test.
+
+## Why
+
+MCP servers are easy to spin up and often ship with no authentication, over-broad
+tools (arbitrary SQL, shell, money movement), or instructions hidden inside a
+tool's *description* (tool poisoning). `mcpsweep` helps you inventory that surface
+— including **shadow** servers nobody registered — and see the risk at a glance.
+
+## Install
+
+```bash
+pip install mcpsweep
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/krishnareddypadala/mcpsweep && cd mcpsweep
+pip install .
+```
+
+## Usage
+
+```bash
+# scan one host on a known port
+mcpsweep 10.10.0.31 --ports 8090
+
+# route everything through Burp for inspection
+mcpsweep 10.10.0.31 --ports 8090 --proxy http://127.0.0.1:8080
+
+# sweep a subnet and a port range, also list resources/prompts
+mcpsweep 10.10.0.0/28 --ports 8000-9100 --full
+
+# machine-readable output
+mcpsweep 10.10.0.31 --ports 8090 --format json -o report.json
+mcpsweep 10.10.0.31 --ports 8090 --format md   -o report.md
+```
+
+### Key options
+
+| Flag | Purpose |
+|---|---|
+| `--ports` | ports/ranges, e.g. `8090,8000,9000-9010` |
+| `--paths` | URL paths to probe (defaults cover `/mcp`, `/mcp/api`, `/sse`, …) |
+| `--scheme` | `http`, `https`, or `both` |
+| `--proxy` | send all traffic via a proxy (e.g. Burp on `127.0.0.1:8080`) |
+| `--insecure`/`-k` | skip TLS verification |
+| `--full` | also enumerate `resources/list` and `prompts/list` |
+| `--format`/`-f` | `text` (default), `json`, `md` |
+| `--concurrency`/`-c` | parallel probes (default 16) |
+
+Exit code is `0` when at least one endpoint is found, `1` otherwise.
+
+> **Windows / Git Bash note:** Git Bash (MSYS) rewrites arguments that look like
+> Unix paths, so `--paths /mcp/api` becomes a Windows path before the tool sees
+> it. Either omit `--paths` (the built-in defaults are unaffected), prefix the
+> command with `MSYS_NO_PATHCONV=1`, or run from PowerShell / `cmd`.
+
+## What it detects
+
+- **Live MCP endpoints** across many candidate paths/ports, via the `initialize`
+  handshake (Streamable-HTTP and SSE-framed responses).
+- **Server fingerprint**: name, version, protocol, capabilities, instructions.
+- **No authentication**: `initialize` that succeeds with no credentials.
+- **Auth-gated endpoints**: `401/403` with an MCP/`WWW-Authenticate` signature.
+- **Risky tools**: name/description heuristics tag `rce`, `sql`, `money`,
+  `destructive`, `write`, `secret`, `pii`, `filesystem`, …
+- **Tool poisoning**: descriptions containing hidden instructions to the model
+  ("ignore previous instructions", "silently", "password_hash", …).
+
+A per-endpoint **risk score** rolls these up into `low / medium / high / critical`.
+
+## Library use
+
+```python
+from mcpsweep import scan
+
+for ep in scan(["10.10.0.31"], ports=[8090], proxy="http://127.0.0.1:8080"):
+    print(ep.url, ep.server_name, ep.risk_level)
+    for t in ep.tools:
+        print("  ", t.name, t.tags, "POISONED" if t.poisoned else "")
+```
+
+## License
+
+MIT

mcpsweep-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcpsweep"
+version = "0.1.0"
+description = "Discovery and fingerprinting scanner for MCP-over-HTTP servers (tool enumeration + risk heuristics)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "mcpsweep contributors" }]
+keywords = ["mcp", "model-context-protocol", "security", "scanner", "discovery", "recon", "llm", "appsec"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Security",
+    "Topic :: Internet",
+]
+dependencies = []  # stdlib only
+
+[project.urls]
+Homepage = "https://github.com/krishnareddypadala/mcpsweep"
+Issues = "https://github.com/krishnareddypadala/mcpsweep/issues"
+
+[project.scripts]
+mcpsweep = "mcpsweep.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mcpsweep-0.1.0/setup.cfg

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

mcpsweep-0.1.0/src/mcpsweep/__init__.py

@@ -0,0 +1,6 @@
+"""mcpsweep — an MCP-over-HTTP discovery and fingerprinting scanner."""
+__version__ = "0.1.0"
+
+from .scanner import scan, probe, enumerate_endpoint, MCPEndpoint, ToolInfo  # noqa: F401
+
+__all__ = ["scan", "probe", "enumerate_endpoint", "MCPEndpoint", "ToolInfo", "__version__"]

mcpsweep-0.1.0/src/mcpsweep/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcpsweep-0.1.0/src/mcpsweep/cli.py

@@ -0,0 +1,202 @@
+"""Command-line interface for mcpsweep."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .scanner import (
+    DEFAULT_PATHS, DEFAULT_PORTS, MCPEndpoint, parse_ports, scan,
+)
+
+# --- color -------------------------------------------------------------------
+
+class C:
+    HEAD = "\033[1;36m"; OK = "\033[1;32m"; WARN = "\033[1;33m"
+    CRIT = "\033[1;31m"; DIM = "\033[0;90m"; BOLD = "\033[1m"; Z = "\033[0m"
+
+    @classmethod
+    def disable(cls):
+        for k in ("HEAD", "OK", "WARN", "CRIT", "DIM", "BOLD", "Z"):
+            setattr(cls, k, "")
+
+
+LEVEL_COLOR = {"critical": C.CRIT, "high": C.WARN, "medium": C.WARN, "low": C.DIM, "info": C.DIM}
+
+
+# --- renderers ---------------------------------------------------------------
+
+def render_console(endpoints, elapsed):
+    out = []
+    for ep in endpoints:
+        col = LEVEL_COLOR.get(ep.risk_level, "")
+        out.append(f"\n{C.OK}[MCP]{C.Z} {C.BOLD}{ep.url}{C.Z}  "
+                   f"{col}{ep.risk_level.upper()}{C.Z} (score {ep.risk_score})")
+        if ep.auth_required:
+            out.append(f"    {C.DIM}server  :{C.Z} (authentication required — not enumerated)")
+        else:
+            out.append(f"    {C.DIM}server  :{C.Z} {ep.server_name}  v{ep.server_version}  "
+                       f"proto={ep.protocol}  transport={ep.transport}")
+            if ep.capabilities:
+                out.append(f"    {C.DIM}caps    :{C.Z} {', '.join(ep.capabilities)}")
+            if ep.session_id:
+                out.append(f"    {C.DIM}session :{C.Z} {ep.session_id} "
+                           f"{C.DIM}(correlator, not auth){C.Z}")
+            if ep.instructions:
+                snippet = ep.instructions[:160] + ("…" if len(ep.instructions) > 160 else "")
+                out.append(f"    {C.DIM}notes   :{C.Z} {snippet}")
+            out.append(f"    {C.DIM}tools   :{C.Z} {len(ep.tools)}")
+            for t in ep.tools:
+                tagstr = f" {C.DIM}[{','.join(t.tags)}]{C.Z}" if t.tags else ""
+                flag = f"  {C.CRIT}<-- DESCRIPTION LOOKS POISONED{C.Z}" if t.poisoned else ""
+                out.append(f"      - {t.name}{tagstr}{flag}")
+            if ep.resources:
+                out.append(f"    {C.DIM}resources:{C.Z} {len(ep.resources)} "
+                           f"({', '.join(ep.resources[:5])})")
+            if ep.prompts:
+                out.append(f"    {C.DIM}prompts :{C.Z} {len(ep.prompts)} "
+                           f"({', '.join(ep.prompts[:5])})")
+        for f in ep.findings:
+            mark = C.CRIT if ("poison" in f.lower() or "high-impact" in f.lower()) else C.WARN
+            if "requires authentication" in f.lower():
+                mark = C.OK
+            out.append(f"    {mark}![{C.Z} {f}")
+    crit = sum(1 for e in endpoints if e.risk_level == "critical")
+    out.append(f"\n{C.HEAD}== {len(endpoints)} endpoint(s) in {elapsed:.1f}s "
+               f"({crit} critical) =={C.Z}")
+    return "\n".join(out)
+
+
+def render_json(endpoints, elapsed, scope):
+    return json.dumps({
+        "tool": "mcpsweep", "version": __version__,
+        "scope": scope, "elapsed_s": round(elapsed, 2),
+        "endpoint_count": len(endpoints),
+        "endpoints": [e.to_dict() for e in endpoints],
+    }, indent=2)
+
+
+def render_markdown(endpoints, elapsed, scope):
+    L = [f"# MCP discovery report", "",
+         f"- **scope:** `{scope}`",
+         f"- **endpoints found:** {len(endpoints)}",
+         f"- **scan time:** {elapsed:.1f}s", "",
+         "| Endpoint | Server | Risk | Tools | Notable |",
+         "|---|---|---|---|---|"]
+    for ep in endpoints:
+        notable = []
+        if ep.auth_required:
+            notable.append("auth required")
+        if any(t.poisoned for t in ep.tools):
+            notable.append("poisoned tool desc")
+        dangerous = sorted({tag for t in ep.tools for tag in t.tags
+                            if tag in ("rce", "sql", "money", "destructive", "secret")})
+        notable.extend(dangerous)
+        L.append(f"| `{ep.url}` | {ep.server_name} v{ep.server_version} | "
+                 f"{ep.risk_level} ({ep.risk_score}) | {len(ep.tools)} | "
+                 f"{', '.join(notable) or '—'} |")
+    L.append("")
+    for ep in endpoints:
+        if ep.auth_required:
+            continue
+        L.append(f"## {ep.url}")
+        L.append(f"*{ep.server_name} v{ep.server_version} · proto {ep.protocol} · "
+                 f"{ep.transport} · risk {ep.risk_level} ({ep.risk_score})*")
+        L.append("")
+        for f in ep.findings:
+            L.append(f"- {f}")
+        if ep.tools:
+            L.append("")
+            L.append("| Tool | Risk tags | Poisoned |")
+            L.append("|---|---|---|")
+            for t in ep.tools:
+                L.append(f"| `{t.name}` | {', '.join(t.tags) or '—'} | "
+                         f"{'⚠️ yes' if t.poisoned else 'no'} |")
+        L.append("")
+    return "\n".join(L)
+
+
+# --- entrypoint --------------------------------------------------------------
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="mcpsweep",
+        description="Discover and fingerprint MCP-over-HTTP servers, enumerate their "
+                    "tools, and flag risky or poisoned ones. Read-only (never calls a tool).",
+        epilog="example: mcpsweep 10.10.0.31 --ports 8090 --proxy http://127.0.0.1:8080",
+    )
+    p.add_argument("targets", nargs="+", help="host(s) or CIDR block(s), e.g. 10.10.0.31 or 10.10.0.0/28")
+    p.add_argument("--ports", default=",".join(map(str, DEFAULT_PORTS)),
+                   help="ports/ranges, e.g. '8090,8000,9000-9010' (default: common MCP ports)")
+    p.add_argument("--paths", default=",".join(DEFAULT_PATHS),
+                   help="comma-separated URL paths to probe")
+    p.add_argument("--scheme", choices=["http", "https", "both"], default="http")
+    p.add_argument("--proxy", help="route all traffic through a proxy, e.g. http://127.0.0.1:8080 (Burp)")
+    p.add_argument("--insecure", "-k", action="store_true", help="skip TLS verification (for https)")
+    p.add_argument("--timeout", type=float, default=8.0, help="per-request timeout seconds (default 8)")
+    p.add_argument("--concurrency", "-c", type=int, default=16, help="parallel probes (default 16)")
+    p.add_argument("--full", action="store_true", help="also enumerate resources and prompts")
+    p.add_argument("--format", "-f", choices=["text", "json", "md"], default="text")
+    p.add_argument("--output", "-o", help="write report to a file instead of stdout")
+    p.add_argument("--no-color", action="store_true", help="disable ANSI color")
+    p.add_argument("--quiet", "-q", action="store_true", help="suppress live progress")
+    p.add_argument("--version", "-V", action="version", version=f"mcpsweep {__version__}")
+    return p
+
+
+def main(argv=None):
+    import time
+    args = build_parser().parse_args(argv)
+
+    if args.no_color or args.format != "text" or not sys.stdout.isatty():
+        C.disable()
+
+    ports = parse_ports(args.ports)
+    paths = [p if p.startswith("/") else "/" + p for p in args.paths.split(",") if p.strip()]
+    schemes = ("http", "https") if args.scheme == "both" else (args.scheme,)
+    scope = f"{','.join(args.targets)} ports={args.ports} scheme={args.scheme}"
+
+    if not args.quiet and args.format == "text":
+        print(f"{C.HEAD}mcpsweep {__version__}{C.Z}  targets={','.join(args.targets)}  "
+              f"ports={len(ports)}  paths={len(paths)}  "
+              f"proxy={args.proxy or 'off'}", file=sys.stderr)
+
+    def live(ep: MCPEndpoint):
+        if not args.quiet and args.format == "text":
+            tag = LEVEL_COLOR.get(ep.risk_level, "")
+            print(f"  {C.OK}found{C.Z} {ep.url}  "
+                  f"{tag}{ep.risk_level}{C.Z}  ({len(ep.tools)} tools)", file=sys.stderr)
+
+    t0 = time.time()
+    try:
+        endpoints = scan(
+            args.targets, ports, paths, schemes,
+            proxy=args.proxy, timeout=args.timeout, concurrency=args.concurrency,
+            insecure=args.insecure, full=args.full, on_found=live,
+        )
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+    elapsed = time.time() - t0
+
+    if args.format == "json":
+        report = render_json(endpoints, elapsed, scope)
+    elif args.format == "md":
+        report = render_markdown(endpoints, elapsed, scope)
+    else:
+        report = render_console(endpoints, elapsed)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(report + "\n")
+        print(f"wrote {args.output} ({len(endpoints)} endpoints)", file=sys.stderr)
+    else:
+        print(report)
+
+    return 0 if endpoints else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcpsweep-0.1.0/src/mcpsweep/scanner.py

@@ -0,0 +1,387 @@
+"""Core discovery + fingerprinting logic for mcpsweep.
+
+Stdlib only. Speaks MCP's Streamable-HTTP JSON-RPC transport (and parses
+SSE-framed responses), performs the ``initialize`` handshake to confirm and
+fingerprint an endpoint, then enumerates tools / resources / prompts and scores
+them with lightweight risk heuristics.
+
+The scanner is strictly read-only: it never calls ``tools/call``.
+"""
+from __future__ import annotations
+
+import ipaddress
+import json
+import re
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from typing import Optional
+
+PROTOCOL_VERSION = "2024-11-05"
+
+DEFAULT_PORTS = [8090, 8000, 8080, 3000, 5000, 8888, 9000, 9099]
+DEFAULT_PATHS = [
+    "/mcp", "/mcp/", "/mcp/api", "/mcp/db", "/mcp/http", "/mcp/v1",
+    "/sse", "/mcp/sse", "/api/mcp", "/message", "/messages",
+    "/rpc", "/jsonrpc", "/tools", "/internal/mcp",
+]
+
+# --- risk heuristics ---------------------------------------------------------
+
+#: substrings in a tool description that suggest an embedded instruction to the
+#: model (tool poisoning / prompt injection hidden in metadata)
+POISON_RE = re.compile(
+    r"(ignore\s+(all|previous|prior)|disregard\s+(all|previous)|"
+    r"do not (mention|tell|inform|reveal this)|without (telling|informing|mentioning)|"
+    r"silently|exfiltrat|password_hash|secret[_-]?key|api[_-]?key|"
+    r"internal note for the (assistant|ai|llm|model)|you must also call|"
+    r"before (answering|responding)[^.]{0,40}call)",
+    re.I,
+)
+
+#: keyword -> risk tag; matched against tool name and description
+RISK_KEYWORDS = {
+    "sql": "sql", "query": "query", "database": "db",
+    "shell": "rce", "command": "rce", "exec": "rce", "eval": "rce", "bash": "rce",
+    "run": "exec", "spawn": "rce", "subprocess": "rce",
+    "transfer": "money", "payment": "money", "wire": "money", "withdraw": "money",
+    "delete": "destructive", "drop": "destructive", "remove": "destructive",
+    "truncate": "destructive", "write": "write", "update": "write",
+    "create": "write", "insert": "write", "modify": "write", "activate": "state-change",
+    "password": "secret", "secret": "secret", "token": "secret",
+    "credential": "secret", "apikey": "secret", "env": "secret", "private": "secret",
+    "customer": "pii", "account": "pii", "balance": "pii", "profile": "pii",
+    "ssn": "pii", "email": "pii",
+    "file": "filesystem", "path": "filesystem", "read": "read",
+    "fetch": "network", "http": "network", "url": "network", "request": "network",
+}
+
+#: tags that materially raise risk (used for scoring)
+DANGEROUS_TAGS = {
+    "sql", "rce", "exec", "money", "destructive", "write", "state-change",
+    "secret", "pii", "filesystem",
+}
+
+
+@dataclass
+class ToolInfo:
+    name: str
+    description: str = ""
+    tags: list = field(default_factory=list)
+    poisoned: bool = False
+
+
+@dataclass
+class MCPEndpoint:
+    url: str
+    host: str
+    port: int
+    path: str
+    scheme: str
+    transport: str = "streamable-http"
+    server_name: str = "?"
+    server_version: str = "?"
+    protocol: str = "?"
+    capabilities: list = field(default_factory=list)
+    instructions: str = ""
+    session_id: Optional[str] = None
+    auth_required: bool = False
+    tools: list = field(default_factory=list)          # list[ToolInfo]
+    resources: list = field(default_factory=list)      # list[str]
+    prompts: list = field(default_factory=list)        # list[str]
+    risk_score: int = 0
+    risk_level: str = "info"
+    findings: list = field(default_factory=list)       # list[str]
+
+    def to_dict(self) -> dict:
+        d = self.__dict__.copy()
+        d["tools"] = [t.__dict__ for t in self.tools]
+        return d
+
+
+# --- low-level transport -----------------------------------------------------
+
+def _build_opener(proxy: Optional[str], insecure: bool):
+    handlers = []
+    if proxy:
+        handlers.append(urllib.request.ProxyHandler({"http": proxy, "https": proxy}))
+    if insecure:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        handlers.append(urllib.request.HTTPSHandler(context=ctx))
+    return urllib.request.build_opener(*handlers)
+
+
+def _parse_body(raw: str, content_type: str):
+    """Return a parsed JSON object from a plain-JSON or SSE-framed body."""
+    ct = (content_type or "").lower()
+    if "text/event-stream" in ct or raw.lstrip().startswith("event:") or "\ndata:" in raw:
+        # concatenate all `data:` payloads and try to parse the last JSON object
+        chunks = [ln[5:].strip() for ln in raw.splitlines() if ln.startswith("data:")]
+        for chunk in reversed(chunks):
+            try:
+                return json.loads(chunk)
+            except Exception:
+                continue
+    try:
+        return json.loads(raw)
+    except Exception:
+        m = re.search(r"\{.*\}", raw, re.S)
+        if m:
+            try:
+                return json.loads(m.group(0))
+            except Exception:
+                return None
+    return None
+
+
+def _rpc(url, payload, proxy=None, timeout=8.0, session=None, insecure=False):
+    """POST a JSON-RPC message. Returns (body_obj_or_None, session_id, status)."""
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(url, data=data, method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/json, text/event-stream")
+    if session:
+        req.add_header("MCP-Session-Id", session)
+    opener = _build_opener(proxy, insecure)
+    try:
+        with opener.open(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+            sid = resp.headers.get("MCP-Session-Id")
+            body = _parse_body(raw, resp.headers.get("Content-Type", ""))
+            return body, sid, getattr(resp, "status", 200)
+    except urllib.error.HTTPError as e:
+        raw = ""
+        try:
+            raw = e.read().decode("utf-8", "replace")
+        except Exception:
+            pass
+        body = _parse_body(raw, e.headers.get("Content-Type", "") if e.headers else "")
+        # surface auth challenges to the caller
+        www = e.headers.get("WWW-Authenticate", "") if e.headers else ""
+        return {"__httperror__": e.code, "__www__": www, "body": body}, None, e.code
+
+
+# --- handshake + enumeration -------------------------------------------------
+
+def _init_payload():
+    return {
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "mcpsweep", "version": "0.1.0"},
+        },
+    }
+
+
+def _is_transient(ex):
+    """True for connection resets / timeouts worth retrying (not a closed port)."""
+    reason = getattr(ex, "reason", ex)
+    if isinstance(reason, (ConnectionResetError, TimeoutError, socket.timeout)):
+        return True
+    if isinstance(reason, ConnectionRefusedError):
+        return False
+    if isinstance(reason, OSError) and getattr(reason, "winerror", None) in (10053, 10054, 10060):
+        return True
+    return False
+
+
+def probe(host, port, path, scheme="http", proxy=None, timeout=8.0, insecure=False, retries=2):
+    """Try one host:port+path. Returns an MCPEndpoint or None.
+
+    Retries the handshake on transient connection errors (resets/timeouts) so a
+    momentary blip under concurrent load doesn't drop a live endpoint.
+    """
+    url = f"{scheme}://{host}:{port}{path}"
+    body = sid = None
+    for attempt in range(retries + 1):
+        try:
+            body, sid, status = _rpc(url, _init_payload(), proxy, timeout, insecure=insecure)
+            break
+        except Exception as ex:
+            if attempt < retries and _is_transient(ex):
+                time.sleep(0.15 * (attempt + 1))
+                continue
+            return None
+    if body is None:
+        return None
+
+    # auth-gated MCP endpoint?
+    if isinstance(body, dict) and body.get("__httperror__") in (401, 403):
+        inner = body.get("body")
+        looks_mcp = bool(body.get("__www__")) or (
+            isinstance(inner, dict) and ("jsonrpc" in inner or "error" in inner)
+        )
+        if looks_mcp:
+            ep = MCPEndpoint(url=url, host=host, port=port, path=path, scheme=scheme,
+                             auth_required=True, server_name="(auth required)")
+            ep.findings.append("endpoint requires authentication (good)")
+            return ep
+        return None
+
+    if not isinstance(body, dict):
+        return None
+    result = body.get("result")
+    if not isinstance(result, dict) or "protocolVersion" not in result:
+        return None
+
+    si = result.get("serverInfo", {}) or {}
+    caps = list((result.get("capabilities") or {}).keys())
+    ep = MCPEndpoint(
+        url=url, host=host, port=port, path=path, scheme=scheme,
+        transport="sse" if "sse" in path else "streamable-http",
+        server_name=si.get("name", "?"), server_version=si.get("version", "?"),
+        protocol=result.get("protocolVersion", "?"), capabilities=caps,
+        instructions=(result.get("instructions") or "").replace("\n", " ").strip(),
+        session_id=sid,
+    )
+    # unauthenticated init succeeded -> no auth in front of this server
+    ep.findings.append("initialize succeeded without credentials (no authentication)")
+    return ep
+
+
+def _notify_initialized(url, sid, proxy, timeout, insecure):
+    try:
+        _rpc(url, {"jsonrpc": "2.0", "method": "notifications/initialized"},
+             proxy, timeout, session=sid, insecure=insecure)
+    except Exception:
+        pass
+
+
+def _list(url, method, key, sid, proxy, timeout, insecure, retries=2):
+    body = None
+    for attempt in range(retries + 1):
+        try:
+            body, _, _ = _rpc(url, {"jsonrpc": "2.0", "id": 2, "method": method, "params": {}},
+                              proxy, timeout, session=sid, insecure=insecure)
+            break
+        except Exception as ex:
+            if attempt < retries and _is_transient(ex):
+                time.sleep(0.15 * (attempt + 1))
+                continue
+            return []
+    if isinstance(body, dict):
+        return (body.get("result") or {}).get(key, []) or []
+    return []
+
+
+def enumerate_endpoint(ep: MCPEndpoint, proxy=None, timeout=8.0, insecure=False, full=False):
+    """Populate tools (and, with full=True, resources/prompts) + risk scoring."""
+    if ep.auth_required:
+        ep.risk_level = "info"
+        return ep
+    _notify_initialized(ep.url, ep.session_id, proxy, timeout, insecure)
+
+    raw_tools = _list(ep.url, "tools/list", "tools", ep.session_id, proxy, timeout, insecure)
+    for t in raw_tools:
+        name = t.get("name", "")
+        desc = t.get("description", "") or ""
+        blob = (name + " " + desc).lower()
+        tags = sorted({tag for kw, tag in RISK_KEYWORDS.items() if kw in blob})
+        poisoned = bool(POISON_RE.search(desc))
+        ep.tools.append(ToolInfo(name=name, description=desc, tags=tags, poisoned=poisoned))
+
+    if full:
+        ep.resources = [r.get("uri", r.get("name", "?"))
+                        for r in _list(ep.url, "resources/list", "resources",
+                                       ep.session_id, proxy, timeout, insecure)]
+        ep.prompts = [p.get("name", "?")
+                      for p in _list(ep.url, "prompts/list", "prompts",
+                                     ep.session_id, proxy, timeout, insecure)]
+
+    _score(ep)
+    return ep
+
+
+def _score(ep: MCPEndpoint):
+    score = 0
+    if not ep.auth_required:
+        score += 20  # unauthenticated surface
+    poisoned = [t for t in ep.tools if t.poisoned]
+    for t in ep.tools:
+        score += 6 * len(set(t.tags) & DANGEROUS_TAGS)
+        if t.poisoned:
+            score += 25
+    if poisoned:
+        ep.findings.append(f"{len(poisoned)} tool description(s) look POISONED: "
+                           + ", ".join(t.name for t in poisoned))
+    dangerous = [t for t in ep.tools if set(t.tags) & {"rce", "sql", "money", "destructive"}]
+    if dangerous:
+        ep.findings.append("high-impact tools exposed: "
+                           + ", ".join(t.name for t in dangerous))
+    ep.risk_score = score
+    ep.risk_level = ("critical" if score >= 60 else "high" if score >= 35
+                     else "medium" if score >= 15 else "low")
+
+
+# --- target expansion + orchestration ---------------------------------------
+
+def expand_targets(targets):
+    """Expand hostnames and CIDR blocks into a flat list of host strings."""
+    out = []
+    for t in targets:
+        t = t.strip()
+        if not t:
+            continue
+        try:
+            net = ipaddress.ip_network(t, strict=False)
+            if net.num_addresses > 1:
+                out.extend(str(ip) for ip in net.hosts())
+                continue
+        except ValueError:
+            pass
+        out.append(t)
+    # de-dup, preserve order
+    seen, uniq = set(), []
+    for h in out:
+        if h not in seen:
+            seen.add(h); uniq.append(h)
+    return uniq
+
+
+def parse_ports(spec):
+    """'8000,8090,9000-9010' -> sorted unique int list."""
+    ports = set()
+    for part in str(spec).split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            a, b = part.split("-", 1)
+            ports.update(range(int(a), int(b) + 1))
+        else:
+            ports.add(int(part))
+    return sorted(p for p in ports if 0 < p < 65536)
+
+
+def scan(targets, ports, paths=None, schemes=("http",), proxy=None,
+         timeout=8.0, concurrency=16, insecure=False, full=False, on_found=None):
+    """Sweep every host x port x path x scheme. Returns list[MCPEndpoint].
+
+    ``on_found(ep)`` is called as each endpoint is confirmed (for live output).
+    """
+    paths = paths or DEFAULT_PATHS
+    hosts = expand_targets(targets)
+    jobs = [(h, p, path, sc)
+            for h in hosts for p in ports for path in paths for sc in schemes]
+
+    found = []
+    with ThreadPoolExecutor(max_workers=concurrency) as pool:
+        futs = {pool.submit(probe, h, p, path, sc, proxy, timeout, insecure): (h, p, path, sc)
+                for (h, p, path, sc) in jobs}
+        for fut in as_completed(futs):
+            ep = fut.result()
+            if ep is None:
+                continue
+            enumerate_endpoint(ep, proxy, timeout, insecure, full)
+            found.append(ep)
+            if on_found:
+                on_found(ep)
+    found.sort(key=lambda e: (-e.risk_score, e.host, e.port, e.path))
+    return found

mcpsweep-0.1.0/src/mcpsweep.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mcpsweep
+Version: 0.1.0
+Summary: Discovery and fingerprinting scanner for MCP-over-HTTP servers (tool enumeration + risk heuristics).
+Author: mcpsweep contributors
+License: MIT
+Project-URL: Homepage, https://github.com/krishnareddypadala/mcpsweep
+Project-URL: Issues, https://github.com/krishnareddypadala/mcpsweep/issues
+Keywords: mcp,model-context-protocol,security,scanner,discovery,recon,llm,appsec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Internet
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcpsweep
+
+A small, dependency-free **discovery and fingerprinting scanner for MCP-over-HTTP
+servers**. It finds Model Context Protocol endpoints on a host or network,
+performs the JSON-RPC `initialize` handshake to fingerprint each one, enumerates
+its **tools / resources / prompts**, and flags risky or **poisoned** tools.
+
+It is strictly **read-only** — it performs the handshake and `*/list` calls only,
+and never invokes a tool (`tools/call`).
+
+> **Authorized use only.** Scan hosts you own or are explicitly permitted to test.
+
+## Why
+
+MCP servers are easy to spin up and often ship with no authentication, over-broad
+tools (arbitrary SQL, shell, money movement), or instructions hidden inside a
+tool's *description* (tool poisoning). `mcpsweep` helps you inventory that surface
+— including **shadow** servers nobody registered — and see the risk at a glance.
+
+## Install
+
+```bash
+pip install mcpsweep
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/krishnareddypadala/mcpsweep && cd mcpsweep
+pip install .
+```
+
+## Usage
+
+```bash
+# scan one host on a known port
+mcpsweep 10.10.0.31 --ports 8090
+
+# route everything through Burp for inspection
+mcpsweep 10.10.0.31 --ports 8090 --proxy http://127.0.0.1:8080
+
+# sweep a subnet and a port range, also list resources/prompts
+mcpsweep 10.10.0.0/28 --ports 8000-9100 --full
+
+# machine-readable output
+mcpsweep 10.10.0.31 --ports 8090 --format json -o report.json
+mcpsweep 10.10.0.31 --ports 8090 --format md   -o report.md
+```
+
+### Key options
+
+| Flag | Purpose |
+|---|---|
+| `--ports` | ports/ranges, e.g. `8090,8000,9000-9010` |
+| `--paths` | URL paths to probe (defaults cover `/mcp`, `/mcp/api`, `/sse`, …) |
+| `--scheme` | `http`, `https`, or `both` |
+| `--proxy` | send all traffic via a proxy (e.g. Burp on `127.0.0.1:8080`) |
+| `--insecure`/`-k` | skip TLS verification |
+| `--full` | also enumerate `resources/list` and `prompts/list` |
+| `--format`/`-f` | `text` (default), `json`, `md` |
+| `--concurrency`/`-c` | parallel probes (default 16) |
+
+Exit code is `0` when at least one endpoint is found, `1` otherwise.
+
+> **Windows / Git Bash note:** Git Bash (MSYS) rewrites arguments that look like
+> Unix paths, so `--paths /mcp/api` becomes a Windows path before the tool sees
+> it. Either omit `--paths` (the built-in defaults are unaffected), prefix the
+> command with `MSYS_NO_PATHCONV=1`, or run from PowerShell / `cmd`.
+
+## What it detects
+
+- **Live MCP endpoints** across many candidate paths/ports, via the `initialize`
+  handshake (Streamable-HTTP and SSE-framed responses).
+- **Server fingerprint**: name, version, protocol, capabilities, instructions.
+- **No authentication**: `initialize` that succeeds with no credentials.
+- **Auth-gated endpoints**: `401/403` with an MCP/`WWW-Authenticate` signature.
+- **Risky tools**: name/description heuristics tag `rce`, `sql`, `money`,
+  `destructive`, `write`, `secret`, `pii`, `filesystem`, …
+- **Tool poisoning**: descriptions containing hidden instructions to the model
+  ("ignore previous instructions", "silently", "password_hash", …).
+
+A per-endpoint **risk score** rolls these up into `low / medium / high / critical`.
+
+## Library use
+
+```python
+from mcpsweep import scan
+
+for ep in scan(["10.10.0.31"], ports=[8090], proxy="http://127.0.0.1:8080"):
+    print(ep.url, ep.server_name, ep.risk_level)
+    for t in ep.tools:
+        print("  ", t.name, t.tags, "POISONED" if t.poisoned else "")
+```
+
+## License
+
+MIT

mcpsweep-0.1.0/src/mcpsweep.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/mcpsweep/__init__.py
+src/mcpsweep/__main__.py
+src/mcpsweep/cli.py
+src/mcpsweep/scanner.py
+src/mcpsweep.egg-info/PKG-INFO
+src/mcpsweep.egg-info/SOURCES.txt
+src/mcpsweep.egg-info/dependency_links.txt
+src/mcpsweep.egg-info/entry_points.txt
+src/mcpsweep.egg-info/top_level.txt

mcpsweep-0.1.0/src/mcpsweep.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcpsweep-0.1.0/src/mcpsweep.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcpsweep = mcpsweep.cli:main

mcpsweep-0.1.0/src/mcpsweep.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcpsweep