mcpnuke 6.22.0__tar.gz

mcpnuke-6.22.0/.cursor/rules/mcpnuke-checks.mdc

@@ -0,0 +1,68 @@
+---
+description: Conventions for mcpnuke check modules and pattern files
+globs: mcpnuke/checks/**/*.py,mcpnuke/patterns/**/*.py
+alwaysApply: false
+---
+
+# Check Module Conventions
+
+## Static Check Template
+
+```python
+"""One-line description of what this check detects."""
+
+import re
+from mcpnuke.core.models import TargetResult
+from mcpnuke.checks.base import time_check
+from mcpnuke.patterns.rules import YOUR_PATTERNS
+
+
+def check_your_check(result: TargetResult) -> None:
+    with time_check("your_check", result):
+        for tool in result.tools:
+            name: str = tool.get("name", "")
+            desc: str = tool.get("description", "")
+            combined: str = f"{name} {desc} {tool.get('inputSchema', {})}"
+            for pat in YOUR_PATTERNS:
+                if re.search(pat, combined, re.IGNORECASE):
+                    result.add("your_check", "SEVERITY", f"Title '{name}'", f"Detail: {pat}", evidence=combined[:300])
+                    break
+```
+
+## Behavioral Check Template
+
+`session` is typed with `MCPSessionProtocol` from
+`mcpnuke.core.transports.base`. Rely only on what it declares — `call`,
+`notify`, `close`, `wait_ready`, `protocol_mode`. For anything HTTP-specific
+(`post_raw`), gate on `hasattr(session, "post_raw")`, because stdio has no
+header layer.
+
+```python
+def check_your_check(
+    session: MCPSessionProtocol,
+    result: TargetResult,
+    probe_opts: dict | None = None,
+) -> None:
+    opts: dict = probe_opts or {}
+    _log = opts.get("_log", lambda msg: None)
+    cache: dict = opts.get("_response_cache", {})
+    with time_check("your_check", result):
+        for tool in result.tools:
+            name: str = tool.get("name", "")
+            text: str | None = cache.get(name)
+            if text is None:
+                args = _build_safe_args(tool)
+                resp = _call_tool(session, name, args)
+                text = _response_text(resp)
+            if text:
+                # Analyze response
+                pass
+```
+
+## Wiring Checklist
+
+1. Import in `checks/__init__.py`
+2. Call in correct phase (static / behavioral / deep probe)
+3. Add attack chains to `core/constants.py` if applicable
+4. Add to README scan phases table
+5. Add to CHANGELOG

mcpnuke-6.22.0/.cursor/rules/mcpnuke-development.mdc

@@ -0,0 +1,87 @@
+---
+description: Core mcpnuke development standards and superpowers workflow integration
+alwaysApply: true
+---
+
+# mcpnuke Development Standards
+
+## Project Identity
+
+mcpnuke is an MCP red teaming and security scanner. Version 6.22.0. Python 3.11+.
+Package manager: `uv`. Test runner: `uv run pytest tests/ -v`.
+
+## Superpowers Workflow (mandatory)
+
+All development on mcpnuke follows the superpowers skills framework:
+
+1. **brainstorming** before any new feature, check, or transport
+2. **writing-plans** before multi-step implementation work
+3. **test-driven-development** for all check modules and pattern changes — RED-GREEN-REFACTOR, no exceptions
+4. **systematic-debugging** for any test failure or scan anomaly — form hypothesis before changing code
+5. **verification-before-completion** before claiming anything is done — run `uv run pytest tests/ -v` and confirm output
+6. **requesting-code-review** after completing a feature branch
+
+## Code Conventions
+
+- Strong typing throughout: use `dict`, `list`, `frozenset`, `int`, `str` type hints on all functions
+- Module-level constants: `UPPER_SNAKE_CASE`, typed explicitly (e.g. `_NAME_MULTIPLIER: int = 3`)
+- Check functions signature: `check_name(result: TargetResult)` for static, `check_name(session: MCPSessionProtocol, result: TargetResult, probe_opts: dict | None = None)` for behavioral
+- Credential regexes belong in `patterns/credentials.py` only, in the tier that matches their false-positive risk — never in `rules.py`, `probes.py`, or a check module
+- Every check wrapped in `with time_check("check_name", result):`
+- Findings via `result.add(check_name, severity, title, detail, evidence=...)`
+- Severity levels: CRITICAL, HIGH, MEDIUM, LOW
+
+## Testing Requirements
+
+- Every new check needs a dedicated `tests/test_<check_name>.py`
+- Minimum 3 tests per check: positive detection, clean/negative, timing recorded
+- Use `conftest.py` fixtures: `result_with_tools([{...}])`
+- Full suite must pass before any commit: 0 failed. Do not cite a hardcoded pass count.
+- Also green before committing: `ruff check .` at zero, `mypy mcpnuke/` at or below the CI ceiling. The whole package enforces `disallow_untyped_defs`
+- DVMCP live tests gated behind `DVMCP_LIVE=1`
+
+## Architecture Quick Reference
+
+```
+mcpnuke/checks/__init__.py       — orchestrator, _pick_security_relevant, run_all_checks
+mcpnuke/checks/<name>.py         — individual check modules
+mcpnuke/checks/base.py           — time_check, tool_text (shared searchable surface)
+mcpnuke/patterns/rules.py        — static regex pattern sets
+mcpnuke/patterns/probes.py       — behavioral probe payloads and response analysis
+mcpnuke/patterns/credentials.py  — the only credential regexes, tiered by FP risk
+mcpnuke/core/session.py          — transport detection; re-exports the session classes
+mcpnuke/core/transports/base.py  — MCPSessionProtocol, HTTPCapableSession
+mcpnuke/core/transports/<name>.py — sse, http, toolserver, stdio sessions
+mcpnuke/core/protocol.py         — legacy vs stateless framing (2026-07-28 spec)
+mcpnuke/core/enumerator.py       — protocol negotiation and server enumeration
+mcpnuke/core/models.py           — Finding, TargetResult dataclasses
+mcpnuke/core/constants.py        — severity weights, attack chain patterns
+mcpnuke/scanner.py               — parallel scan orchestration
+mcpnuke/__main__.py              — CLI entry point
+mcpnuke/cli_steps.py             — scan-path helpers: auth, AI backend, k8s, report
+mcpnuke/subcommands.py           — --doctor, --lab-coverage, `mcpnuke diff`; exit codes
+```
+
+## Invariants Guarded by Tests
+
+These exist because each one broke once. Do not route around them:
+
+- `tests/test_credential_patterns.py` — every consumer of the credential tiers
+  detects the same set. Add new secrets to the corpus.
+- `tests/test_injection_patterns.py` — one shared injection marker set, no
+  private copies.
+- `tests/test_session_protocol.py` — all four transports satisfy the Protocol,
+  and stdio never gains `post_raw`.
+- `tests/test_check_progress.py` — the progress denominator is derived from the
+  check inventory, never hardcoded.
+- `tests/test_docs_current.py` — README, checks, scan modes, and the roadmap
+  glance counts match the registry. Stated check counts are not handwritten.
+
+## Project-Specific Skills
+
+Use mcpnuke skills for domain-specific tasks:
+- `mcpnuke-add-check` — end-to-end new security check
+- `mcpnuke-add-patterns` — new regex detection patterns
+- `mcpnuke-add-transport` — new transport type
+- `mcpnuke-extend-dvmcp` — new DVMCP challenge tests
+- `mcpnuke-run-tests` — run and interpret test suite

mcpnuke-6.22.0/.cursor/rules/mcpnuke-tests.mdc

@@ -0,0 +1,58 @@
+---
+description: Test conventions for mcpnuke — enforces TDD workflow
+globs: tests/**/*.py
+alwaysApply: false
+---
+
+# mcpnuke Test Conventions
+
+## TDD Workflow (superpowers: test-driven-development)
+
+1. **RED** — Write the failing test first. Run it. Watch it fail.
+2. **GREEN** — Write the minimal code to make it pass. Run it. Watch it pass.
+3. **REFACTOR** — Clean up. Run tests again. Still green.
+
+Never write implementation before the test exists.
+
+## Test Structure
+
+```python
+"""Tests for <check_name>."""
+from mcpnuke.core.models import TargetResult
+from mcpnuke.checks.<module> import check_<name>
+
+
+def test_<name>_positive(result_with_tools):
+    r = result_with_tools([{"name": "vuln_tool", "description": "...", "inputSchema": {}}])
+    check_<name>(r)
+    assert any(f.check == "<name>" for f in r.findings)
+
+
+def test_<name>_clean(result_with_tools):
+    r = result_with_tools([{"name": "safe_tool", "description": "Nothing here", "inputSchema": {}}])
+    check_<name>(r)
+    assert not any(f.check == "<name>" for f in r.findings)
+
+
+def test_<name>_timing(result_with_tools):
+    r = result_with_tools([{"name": "x", "description": "y", "inputSchema": {}}])
+    check_<name>(r)
+    assert "<name>" in r.timings
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests/ -v              # Full suite
+uv run pytest tests/test_foo.py -v   # Single file
+uv run pytest tests/ -v -x           # Stop on first failure
+```
+
+## Verification (superpowers: verification-before-completion)
+
+Before claiming work is done, run and confirm:
+- `uv run pytest tests/ -v` — 0 failed. Do not cite a hardcoded pass count.
+- `uv run ruff check .` — zero findings, and `uv run mypy mcpnuke/` at or below
+  the ceiling in `.github/workflows/tests.yml`
+- No import errors or deprecation warnings
+- New tests cover positive, negative, and timing

mcpnuke-6.22.0/.cursor/skills/mcpnuke-add-check/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: mcpnuke-add-check
+description: >-
+  Create a new mcpnuke security check module end-to-end: pattern file,
+  check function, wire into run_all_checks, add tests, update changelog.
+  Use when adding a new security check to mcpnuke.
+---
+
+# Add a New mcpnuke Check
+
+## Gather Info
+
+1. **Check name** — snake_case (e.g. `jwt_audience`, `ssrf_probe`)
+2. **Check type** — static (metadata only) or behavioral (calls tools)
+3. **What it detects** — one sentence
+4. **Severity** — CRITICAL / HIGH / MEDIUM / LOW
+5. **Taxonomy ID** — MCP-T## from the playbook (if applicable)
+
+## File Locations
+
+```
+mcpnuke/
+├── patterns/rules.py          # Static regex patterns
+├── patterns/probes.py         # Behavioral probe payloads
+├── checks/
+│   ├── __init__.py            # run_all_checks() — wire new check here
+│   ├── your_check.py          # New check module
+│   └── base.py                # time_check helper
+├── core/constants.py          # ATTACK_CHAIN_PATTERNS — add chains here
+tests/
+├── test_your_check.py         # Unit tests
+├── test_dvmcp.py              # DVMCP integration tests
+```
+
+## Step-by-Step
+
+### 1. Add patterns (if static check)
+
+Edit `mcpnuke/patterns/rules.py`:
+
+```python
+YOUR_CHECK_PATTERNS = [
+    r"pattern_one",
+    r"pattern_two",
+]
+```
+
+### 2. Create the check module
+
+Create `mcpnuke/checks/your_check.py`:
+
+```python
+"""Description of what this check detects."""
+
+import re
+
+from mcpnuke.core.models import TargetResult
+from mcpnuke.checks.base import time_check
+from mcpnuke.patterns.rules import YOUR_CHECK_PATTERNS
+
+
+def check_your_check(result: TargetResult):
+    with time_check("your_check", result):
+        for tool in result.tools:
+            name = tool.get("name", "")
+            combined = (
+                name + " "
+                + tool.get("description", "")
+                + " " + str(tool.get("inputSchema", {}))
+            )
+            for pat in YOUR_CHECK_PATTERNS:
+                if re.search(pat, combined, re.IGNORECASE):
+                    result.add(
+                        "your_check",
+                        "SEVERITY",
+                        f"Finding title for tool '{name}'",
+                        f"Detail: {pat}",
+                        evidence=combined[:300],
+                    )
+                    break
+```
+
+For **behavioral checks**, accept `session` and `probe_opts`:
+
+```python
+def check_your_check(session, result: TargetResult, probe_opts: dict | None = None):
+    opts = probe_opts or {}
+    with time_check("your_check", result):
+        # Call tools, analyze responses
+        pass
+```
+
+### 3. Wire into run_all_checks
+
+Edit `mcpnuke/checks/__init__.py`:
+
+1. Add import at top:
+```python
+from mcpnuke.checks.your_check import check_your_check
+```
+
+2. Add call in appropriate phase:
+   - **Static checks** section (always run)
+   - **Behavioral checks** section (gated on `not no_invoke`)
+   - **Deep probes** section (gated on `not no_invoke`, accept `probe_opts`)
+
+### 4. Add attack chain patterns (if applicable)
+
+Edit `mcpnuke/core/constants.py`, add to `ATTACK_CHAIN_PATTERNS`:
+
+```python
+("your_check", "code_execution"),
+("input_sanitization", "your_check"),
+```
+
+### 5. Write tests
+
+Create `tests/test_your_check.py`:
+
+```python
+"""Tests for your_check."""
+
+import pytest
+from mcpnuke.core.models import TargetResult
+from mcpnuke.checks.your_check import check_your_check
+
+
+def test_your_check_positive(result_with_tools):
+    r = result_with_tools([{
+        "name": "vuln_tool",
+        "description": "Description that matches pattern",
+        "inputSchema": {},
+    }])
+    check_your_check(r)
+    assert any(f.check == "your_check" for f in r.findings)
+
+
+def test_your_check_clean(result_with_tools):
+    r = result_with_tools([{
+        "name": "safe_tool",
+        "description": "Nothing suspicious here",
+        "inputSchema": {},
+    }])
+    check_your_check(r)
+    assert not any(f.check == "your_check" for f in r.findings)
+
+
+def test_your_check_timing(result_with_tools):
+    r = result_with_tools([{"name": "x", "description": "y", "inputSchema": {}}])
+    check_your_check(r)
+    assert "your_check" in r.timings
+```
+
+### 6. Run tests
+
+```bash
+uv run pytest tests/test_your_check.py tests/test_checks_integration.py -v
+```
+
+### 7. Update CHANGELOG.md
+
+Add under `[Unreleased]` → `### Added`.
+
+## Workflow Integration
+
+This skill works with superpowers:
+- **test-driven-development** — write tests (step 5) BEFORE the check module (step 2). RED first.
+- **verification-before-completion** — run full suite before claiming done.
+- **systematic-debugging** — if tests fail, form hypothesis before changing code.
+
+## Checklist
+
+- [ ] Patterns added to `rules.py` or `probes.py`
+- [ ] Tests written FIRST and failing (TDD RED phase)
+- [ ] Check module created in `checks/` (TDD GREEN phase)
+- [ ] Imported and called in `checks/__init__.py`
+- [ ] Attack chains added to `constants.py` (if applicable)
+- [ ] Full test suite passing: `uv run pytest tests/ -v`
+- [ ] CHANGELOG updated

mcpnuke-6.22.0/.cursor/skills/mcpnuke-add-patterns/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: mcpnuke-add-patterns
+description: >-
+  Add new regex detection patterns to mcpnuke's pattern libraries with
+  test coverage. Use when adding new patterns to rules.py or probes.py,
+  or when extending detection for a vulnerability class.
+---
+
+# Add mcpnuke Patterns
+
+## Pattern Files
+
+| File | Purpose | Used By |
+|------|---------|---------|
+| `mcpnuke/patterns/rules.py` | Static regex for metadata analysis | Static checks (injection, permissions, theft, etc.) |
+| `mcpnuke/patterns/probes.py` | Probe payloads and response analysis | Behavioral checks (tool_probes, resource_poisoning) |
+
+## Adding Static Patterns
+
+### 1. Define the pattern list in `rules.py`
+
+```python
+YOUR_PATTERNS = [
+    r"pattern_one",
+    r"pattern_two",
+]
+```
+
+Pattern guidelines:
+- Use raw strings (`r"..."`)
+- Case-insensitive matching is done by the caller (`re.IGNORECASE`)
+- Use `\s+` for whitespace, `\b` for word boundaries
+- Use `.{0,30}` for bounded wildcards (not `.*`)
+- Test each pattern against both positive and negative examples
+
+### 2. Add tests in `tests/test_patterns.py`
+
+```python
+def test_your_patterns_match():
+    text = "String that should match"
+    matches = [p for p in YOUR_PATTERNS if re.search(p, text, re.IGNORECASE)]
+    assert len(matches) >= 1
+
+
+def test_your_patterns_no_false_positive():
+    text = "Normal safe string"
+    matches = [p for p in YOUR_PATTERNS if re.search(p, text, re.IGNORECASE)]
+    assert len(matches) == 0
+```
+
+### 3. Run tests (TDD: write tests FIRST, then patterns)
+
+Follow superpowers test-driven-development: write the test assertions before
+adding patterns to `rules.py`. Watch them fail (RED), then add patterns (GREEN).
+
+```bash
+uv run pytest tests/test_patterns.py -v
+```
+
+## Adding Probe Payloads
+
+### In `probes.py`
+
+Injection probes (sent to tools):
+```python
+YOUR_PROBES = [
+    f"payload_with_{CANARY}",
+    "payload_two",
+]
+```
+
+Response analysis patterns (checked in tool output):
+```python
+YOUR_RESPONSE_PATTERNS = [
+    r"pattern_to_find_in_responses",
+]
+```
+
+Rules:
+- Probes should be **safe** — they test for vuln without causing damage
+- Use the `CANARY` string (`MCP_PROBE_8f4c2a`) to detect reflection
+- Response patterns use the same regex conventions as `rules.py`
+
+## Existing Pattern Sets (reference)
+
+| Name | Count | Purpose |
+|------|-------|---------|
+| `INJECTION_PATTERNS` | 19 | Prompt injection in metadata |
+| `POISON_PATTERNS` | 11 | Hidden instructions, exfil hints |
+| `DANGEROUS_TOOL_PATTERNS` | 8 categories | Dangerous capabilities |
+| `TOKEN_THEFT_PATTERNS` | 10 | Credential exfiltration |
+| `CODE_EXEC_PATTERNS` | 9 | Code execution indicators |
+| `RATE_LIMIT_PATTERNS` | 5 | Missing rate limiting |
+| `PROMPT_LEAKAGE_PATTERNS` | 8 | Prompt exposure |
+| `SUPPLY_CHAIN_PATTERNS` | 9 | Dynamic package install |
+| `RAC_PATTERNS` | 6 categories | Remote access |
+| `RESPONSE_INJECTION_PATTERNS` | 11 | Injection in tool responses |
+| `ERROR_LEAKAGE_PATTERNS` | 9 | Info disclosure in errors |
+| `CREDENTIAL_CONTENT_PATTERNS` | 11 | Actual secrets in content |

mcpnuke-6.22.0/.cursor/skills/mcpnuke-add-transport/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mcpnuke-add-transport
+description: >-
+  Add a new transport type to mcpnuke alongside SSE, HTTP, and ToolServer.
+  Use when adding support for a new MCP transport protocol like DPoP, mTLS,
+  or a custom gateway.
+---
+
+# Add a New mcpnuke Transport
+
+## Current Transport Architecture
+
+```
+detect_transport(url)
+  ├── SSE probe → MCPSession
+  ├── HTTP POST probe → HTTPSession
+  ├── SSE+POST combos → MCPSession
+  └── ToolServer probe → ToolServerSession
+```
+
+All session types implement the same interface:
+- `wait_ready(timeout) → bool`
+- `call(method, params, timeout, retries) → dict | None`
+- `notify(method, params)`
+- `close()`
+- Properties: `base`, `sse_url`, `post_url`
+
+## Steps to Add a Transport
+
+### 1. Create the session class
+
+In a new module `mcpnuke/core/transports/<name>.py`, add the class, and
+re-export it from `mcpnuke/core/session.py`:
+
+```python
+class YourSession:
+    def __init__(self, base, post_url, timeout=25.0, **kwargs):
+        self.base = base
+        self.sse_url = ""
+        self.post_url = post_url
+        self.timeout = timeout
+        # Your transport-specific setup
+
+    def wait_ready(self, timeout=10.0) -> bool:
+        return True
+
+    def call(self, method, params=None, timeout=None, retries=2) -> dict | None:
+        # Translate MCP JSON-RPC calls to your transport
+        pass
+
+    def notify(self, method, params=None):
+        pass
+
+    def close(self):
+        pass
+```
+
+### 2. Add detection logic
+
+Create a detector function:
+
+```python
+def _detect_your_transport(base, hint, timeout, auth_token, **kwargs):
+    # Probe for your transport
+    # Return YourSession if detected, None otherwise
+    pass
+```
+
+### 3. Wire into detect_transport
+
+Add your detector as a fallback in `detect_transport()`, after existing transports:
+
+```python
+# After ToolServer detection
+your_session = _detect_your_transport(base, hint, ...)
+if your_session:
+    return your_session
+```
+
+### 4. Add CLI flags (if needed)
+
+In `mcpnuke/cli.py`, add arguments:
+
+```python
+p.add_argument("--your-flag", help="...")
+```
+
+Thread through `__main__.py` → `scanner.py` → `detect_transport()`.
+
+### 5. Add verbose logging
+
+Use the `log` callable in `detect_transport`:
+
+```python
+if verbose:
+    _log(f"  [dim]Trying YourTransport detection...[/dim]")
+```
+
+### 6. Update scanner labels
+
+In `mcpnuke/scanner.py` `scan_target()`, add label detection:
+
+```python
+if isinstance(session, YourSession):
+    transport_label = "YourTransport"
+```
+
+### 7. Test
+
+Add transport detection tests to `tests/test_cli.py` or a new test file.
+
+## Reference: Existing Transports
+
+| Transport | Class | Detection Method |
+|-----------|-------|-----------------|
+| SSE | `MCPSession` | GET returns `text/event-stream` |
+| HTTP | `HTTPSession` | POST initialize returns JSON-RPC |
+| ToolServer | `ToolServerSession` | POST `/execute` returns tool response |