Metadata-Version: 2.5
Name: mcpnuke
Version: 6.22.1
Summary: MCP red teaming & security scanner — enumerate, probe, and exploit Model Context Protocol servers
Project-URL: Homepage, https://github.com/babywyrm/mcpnuke
Project-URL: Repository, https://github.com/babywyrm/mcpnuke
Project-URL: Documentation, https://github.com/babywyrm/mcpnuke/blob/main/docs/checks.md
Project-URL: Changelog, https://github.com/babywyrm/mcpnuke/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/babywyrm/mcpnuke/issues
Author: babywyrm
License-Expression: MIT
License-File: LICENSE
Keywords: ai-security,mcp,model-context-protocol,pentest,red-team,scanner,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == 'ai'
Requires-Dist: boto3>=1.35; extra == 'ai'
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: boto3>=1.35; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: pydantic>=2.9; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == 'server'
Requires-Dist: pydantic>=2.9; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'server'
Description-Content-Type: text/markdown

# mcpnuke

[![CI](https://github.com/babywyrm/mcpnuke/actions/workflows/tests.yml/badge.svg)](https://github.com/babywyrm/mcpnuke/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/mcpnuke)](https://pypi.org/project/mcpnuke/)
[![Python](https://img.shields.io/pypi/pyversions/mcpnuke)](https://pypi.org/project/mcpnuke/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**MCP Red Teaming & Security Scanner**

Security scanner for [Model Context Protocol](https://modelcontextprotocol.io)
servers. Combines **static metadata analysis** with **active behavioral
probing** — connects to MCP servers, enumerates tools/resources/prompts,
calls tools with safe payloads, and analyzes what comes back.

Works against standard MCP (SSE, Streamable HTTP), **local stdio servers**
(`npx`, `python`, etc.), non-standard tool servers (`POST /execute`), and
Kubernetes-internal MCP deployments.

Use with [DVMCP](https://github.com/harishsg993010/damn-vulnerable-MCP-server)
for training, or point at any MCP server in dev/staging/prod.

**See [CHANGELOG.md](CHANGELOG.md) for recent changes and planned work.**

---

## Contents

**On this page**

- [Install](#install)
  - [To use mcpnuke](#to-use-mcpnuke)
  - [To work on mcpnuke](#to-work-on-mcpnuke)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Security Checks](#security-checks)
- [Identity Lanes & Transports](#identity-lanes--transports)
- [CLI Reference](#cli-reference)
- [Kubernetes Deployment](#kubernetes-deployment)
- [Exit Code](#exit-code)
- [Authorized Use](#authorized-use)
- [Contributing](#contributing)
- [License](#license)

**Reference**

| Document | Contents |
|----------|----------|
| [docs/cli-reference.md](docs/cli-reference.md) | Every flag, generated from the parser |
| [docs/checks.md](docs/checks.md) | Full check inventory with severities |
| [docs/scan-modes.md](docs/scan-modes.md) | Scan modes and fast-mode scoring |
| [docs/ai-analysis.md](docs/ai-analysis.md) | Claude, Bedrock and Ollama analysis |
| [docs/lanes.md](docs/lanes.md) | Identity lanes, transports, lane-aware reporting |
| [docs/kubernetes.md](docs/kubernetes.md) | In-cluster deployment and posture checks |
| [docs/methodology.md](docs/methodology.md) | Probing methodology, risk scoring, attack chains |
| [docs/spec-surface.md](docs/spec-surface.md) | MCP 2026-08-22 roadmap: what we speak, scan, and can probe next |
| [QUICKSTART.md](QUICKSTART.md) | Recipes by goal, then the lab notes |
| [docs/ci-cd-guide.md](docs/ci-cd-guide.md) | Integrating scans into your pipeline |
| [walkthrough/README.md](walkthrough/README.md) | Guided DVMCP scan, finding by finding |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup, check-authoring recipe, test invariants |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting and authorized-use guidance |

**Ecosystem**

[agentic-sec](https://github.com/babywyrm/agentic-sec) — architecture,
walkthroughs and cross-project guides for camazotz + nullfield + mcpnuke.

**mcpnuke and [stoneburner](https://github.com/babywyrm/stoneburner) meet at
the agent.** mcpnuke scans the MCP server — whether the tools will do the
dangerous thing. stoneburner grades the model — whether the model will ask
them to. An attack chain needs both halves, so the tools complement rather
than overlap: mcpnuke's `--chain-replay` proves the server half, stoneburner's
`adversarial` / `toolcall` suites measure the model half. Neither scans the
other's layer.

---

## Install

### To use mcpnuke

**One-liner:**
```bash
curl -LsSf https://raw.githubusercontent.com/babywyrm/mcpnuke/main/install.sh | bash
```

Picks `uv tool`, `pipx` or `pip --user`, whichever you have. All three install
mcpnuke into its own environment, so its dependency pins cannot disturb the
rest of your Python. Pass `--extras all` for the optional features, or
`--dry-run` to see the plan first.

**Or install it yourself:**
```bash
uv tool install mcpnuke          # recommended
pipx install mcpnuke
pip install --user mcpnuke
```

**Verify:**
```bash
mcpnuke --doctor
```

Optional extras: `ai` (Claude analysis), `server` (the `mcpnuke-runner` HTTP
job API), `all` (everything). The scanner itself, Kubernetes checks
included, needs none of them — `uv tool install 'mcpnuke[all]'` if you want the lot.

### To work on mcpnuke

```bash
git clone https://github.com/babywyrm/mcpnuke.git && cd mcpnuke
./quickstart.sh
```

Creates a `.venv`, installs every extra including `dev`, runs the test suite
and prints usage. After that `./scan` and `uv run mcpnuke` both work with no
activation, because `uv run` finds the project venv on its own.

Manual equivalents:
```bash
uv sync --all-extras                              # uv
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[all,dev]"
```

---

## Quick Start

**New to mcpnuke?** Try the **[DVMCP Walkthrough](walkthrough/README.md)** —
a hands-on guide that scans 10 vulnerable MCP servers and explains every
finding, or run `./walkthrough/demo.sh` for the fully automated version.

```bash
# Single target
./scan --targets http://localhost:2266

# DVMCP challenges 1–10
./scan --port-range localhost:9001-9010 --verbose

# Authenticated endpoint (JWT, PAT, etc.)
./scan --targets https://api.githubcopilot.com/mcp/ --auth-token-file ./token

# OIDC auto-token (Keycloak, etc.)
./scan --targets http://localhost:9090/mcp \
  --oidc-url http://keycloak:8080/realms/myapp \
  --client-id myapp --client-secret SECRET \
  --oidc-resource http://localhost:9090/mcp

# JSON report for CI (includes proof-ranked priority_actions + impact/fix/verify,
# OWASP MCP Top 10 alignment, and an AIBOM-style inventory per target)
./scan --port-range localhost:9001-9010 --json report.json

# Suggest a NullfieldPolicy from findings (proved chains → DENY sink + HOLD sources)
./scan --targets http://localhost:8080/mcp --generate-policy fix.yaml

# Differential scan (compare to baseline)
./scan --targets http://localhost:9001 --baseline baseline.json

# Scan a local MCP server via stdin/stdout (no proxy needed)
./scan --stdio 'npx -y @modelcontextprotocol/server-everything'

# Fast scan (~2min vs ~30min) — static checks read the full catalog; probes sample the top 5
./scan --targets http://localhost:9090 --fast --verbose

# AI-powered analysis (Claude, AWS Bedrock, or local Ollama)
./scan --targets http://localhost:9002/sse --claude --verbose
./scan --targets http://localhost:9002/sse --ollama-analysis http://<ollama-host>:11434

# Run tests
uv run pytest tests/ -v
```

All `./scan` commands also work as `uv run mcpnuke` (no activation needed),
`mcpnuke` (with venv activated), or `.venv/bin/mcpnuke`.

More recipes — DPoP + token introspection + JWKS hardening, grouped findings,
parallel probes, Ollama ensembles, K8s discovery, per-lane reporting,
production safety passes — in **[QUICKSTART.md](QUICKSTART.md)**.

**Exit codes:** `0` clean at the `--fail-on` threshold, `1` findings at or
above it, `2` scan error. Full table under [Exit Code](#exit-code).

**SARIF output:** Use `--sarif results.sarif` to emit a SARIF 2.1.0 report
for GitHub Code Scanning, VS Code, and IDE integration. Findings map as:
CRITICAL/HIGH — `error`, MEDIUM — `warning`, LOW — `note`. Each result
carries the same impact, fix, and verify text as the console priority
action, and the rule help repeats it.

See [CI/CD Integration Guide](docs/ci-cd-guide.md) for GitHub Actions, GitLab CI,
and mcpnuke-runner setup.

---

## How It Works

```
1. CONNECT        Detect transport (SSE, Streamable HTTP, stdio, or custom tool server)
2. ENUMERATE      initialize → tools/list → resources/list → prompts/list
                  (or probe tool names for non-MCP /execute APIs)
3. STATIC CHECKS  Pattern-match metadata (names, descriptions, schemas)
4. PROBE          Call tools with safe payloads, read resources
5. ANALYZE        Scan responses for injection, exfil, leakage, drift
6. AGGREGATE      Detect attack chains across findings
7. REPORT         Priority actions (fix first) + console/JSON (+ optional policy)
```

### Scan Phases

The scanner runs checks in a deliberate order:

| Phase | What Happens |
|-------|-------------|
| **Static** | Pattern-match on tool names, descriptions, schemas. No server interaction beyond enumeration. |
| **Behavioral** | Light interaction: re-list tools, read resources, send invalid methods. |
| **Deep Probes** | Active tool invocation with safe payloads. Analyze responses for threats. |
| **Transport** | CORS, unauthenticated SSE, cross-origin POST. |
| **Aggregate** | Cross-reference all prior findings to detect compound threats. |
| **AI** (optional) | Claude or Ollama reads definitions, tool output, and findings, and can replay proposed chains. Requires `--claude` or `--ollama-analysis`. |

Which checks run in each phase, and under what conditions, is in
**[docs/checks.md](docs/checks.md)**.

How the probes are built, how findings are scored and chained, and how to test
all of it against DVMCP, is in **[docs/methodology.md](docs/methodology.md)**.

---

## Security Checks

mcpnuke runs 104 checks across static, behavioral, infrastructure and aggregate
phases, covering 54 of 57 threat IDs (95%) in the agentic-sec threat taxonomy.
See **[docs/checks.md](docs/checks.md)** for the full inventory with severities
and detection notes.

---

## Identity Lanes & Transports

Every lane-scoped finding carries an **identity lane** (1–5, the *who*:
human-direct → anonymous) and a **transport** (A–E, the *how*: MCP JSON-RPC
through native LLM function-calling), resolved automatically from the
agentic-sec taxonomy. `--by-lane` groups findings per lane.
`--owasp` maps them onto the OWASP MCP Top 10 (2025) alignment view.
`--coverage-report` intersects them with a live camazotz lane corpus.
`tests/owasp_lab` is the positive fixture for that report, one planted
marker per category. `tests/reference_target` is the quiet server, and
those markers stay out of it.

Full tables and reporting guide: **[docs/lanes.md](docs/lanes.md)**.

---

## CLI Reference

Every flag, its argument group, and the environment variable that backs it:
**[docs/cli-reference.md](docs/cli-reference.md)**, generated from the parser
so it cannot drift.

- Scan modes (`--fast`, `--safe-mode`, `--no-invoke`) and how `--fast` picks
  which tools to sample: **[docs/scan-modes.md](docs/scan-modes.md)**
- `--claude`, `--bedrock` and `--ollama-analysis`, and what the AI layer adds
  over the deterministic checks: **[docs/ai-analysis.md](docs/ai-analysis.md)**

---

## Kubernetes Deployment

mcpnuke also deploys as a K8s Job to scan cluster-internal MCP services and
audit the Kubernetes posture from inside. Manifests, RBAC, the in-cluster check
list and CronJob scheduling: **[docs/kubernetes.md](docs/kubernetes.md)**.

---

## Exit Code

The exit code reports the `--fail-on` threshold, not the raw finding count.
A scan that reports only LOW findings exits `0` under the default threshold.

| Code | Meaning |
|------|---------|
| **0** | Clean — nothing at or above the `--fail-on` threshold (default: `high`) |
| **1** | Findings — at least one finding at or above that threshold |
| **2** | Error — scan did not complete successfully (e.g. unreachable target, bad flags) |

`--fail-on any` exits `1` on any finding at all; `--fail-on none` always exits
`0`, for informational scans.

---

## Authorized Use

mcpnuke actively probes targets. By default it calls tools and sends
injection and SSRF payloads, which on a real server can create data or
trigger outbound requests. Multi-step chain replay (`--chain-replay`) is
off unless you ask for it.

**Only scan systems you own or have written authorization to test.**

Against anything you do not control, start with `--no-invoke` (static-only, never
calls a tool), then `--safe-mode` (skips tools classified dangerous) once you
know the blast radius. Full guidance, plus how to handle the sensitive output a
scan produces, is in **[SECURITY.md](SECURITY.md)**.

---

## Contributing

Bug reports about **detection quality — false positives and false negatives —
are the most valuable contribution**, because operator trust in the output is
what makes the tool worth running.

Setup, the check-authoring recipe, severity calibration, and the invariants the
test suite guards: **[CONTRIBUTING.md](CONTRIBUTING.md)**. Working with an AI
coding agent (Codex, Cursor, etc.)? It should read **[AGENTS.md](AGENTS.md)**
first.

To report a vulnerability *in mcpnuke itself*, use private reporting as described
in [SECURITY.md](SECURITY.md) rather than a public issue.

---

## License

[MIT](LICENSE) © babywyrm
