Metadata-Version: 2.4
Name: mcpsweep
Version: 0.2.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

# a full URL, and a target list from a file
mcpsweep http://10.10.0.31:8090/mcp/api
mcpsweep -iL targets.txt --exclude 10.10.0.5

# authenticated scan (servers that require a token)
mcpsweep 10.10.0.31 --ports 8090 --bearer "$TOKEN"
mcpsweep 10.10.0.31 --ports 8090 -H "X-Api-Key: abc123"

# reports: JSON, Markdown, SARIF (GitHub code-scanning), self-contained HTML
mcpsweep 10.10.0.31 --ports 8090 --format json  -o report.json
mcpsweep 10.10.0.31 --ports 8090 --format md    -o report.md
mcpsweep 10.10.0.31 --ports 8090 --format sarif -o report.sarif
mcpsweep 10.10.0.31 --ports 8090 --format html  -o report.html

# CI gates: only show high+, fail the build on any critical
mcpsweep 10.10.0.31 --ports 8090 --severity high --fail-on critical

# drift detection between two JSON scans (continuous posture monitoring)
mcpsweep diff yesterday.json today.json --fail-on-drift
```

### Key options

| Flag | Purpose |
|---|---|
| `--target-file`/`-iL` | read targets from a file (one per line, `#` comments) |
| `--exclude` | comma-separated hosts to skip |
| `--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` |
| `--header`/`-H`, `--bearer` | custom header(s) / bearer token for authenticated scans |
| `--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` |
| `--severity` | only report endpoints at/above a level |
| `--fail-on` | exit `2` if any endpoint is at/above a level (CI gate) |
| `--format`/`-f` | `text` (default), `json`, `md`, `sarif`, `html` |
| `--concurrency`/`-c` | parallel probes (default 16) |

Exit codes: `0` found (or clean), `1` nothing found, `2` `--fail-on` threshold hit,
`3` drift found (`diff --fail-on-drift`).

### Drift detection

```bash
mcpsweep 10.10.0.31 --ports 8090 -f json -o baseline.json   # week 1
mcpsweep 10.10.0.31 --ports 8090 -f json -o current.json    # week 2
mcpsweep diff baseline.json current.json
```

Reports **new / removed servers and tools**, **newly-poisoned** descriptions, and
**risk-level changes** — turning point-in-time scans into continuous monitoring.

> **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`, …
- **Prompt injection / poisoning** in tool descriptions **and** server
  `instructions`, prompt templates, and resource listings ("ignore previous
  instructions", "silently", "password_hash", …).
- **Injection surface**: high-impact tools (`sql`/`rce`/…) that accept a
  **free-form string** parameter.
- **HTTP fingerprint**: `Server` / `X-Powered-By` headers, and server names that
  hint at an elevated or untrusted purpose.

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
