mcpnuke 6.22.0__py3-none-any.whl

mcpnuke/__init__.py

@@ -0,0 +1,14 @@
+"""
+mcpnuke — MCP Red Teaming & Security Scanner
+
+Security auditing for Model Context Protocol servers. Enumerates tools,
+probes for injection and poisoning, detects rug pulls, and audits
+Kubernetes MCP deployments.
+
+Usage:
+    mcpnuke --targets http://localhost:9090
+    mcpnuke --port-range localhost:9001-9010 --verbose
+    python -m mcpnuke --targets http://localhost:9090
+"""
+
+__version__ = "6.22.0"

mcpnuke/__main__.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""
+mcpnuke — MCP Red Teaming & Security Scanner
+
+Usage:
+    mcpnuke --targets http://localhost:9090
+    mcpnuke --port-range localhost:9001-9010 --verbose
+    mcpnuke --targets http://target:9090 --auth-token $TOKEN --json report.json
+    mcpnuke --stdio 'npx -y @modelcontextprotocol/server-everything'
+    mcpnuke --targets http://target:9090 --fast --group-findings
+"""
+
+import sys
+import time
+from datetime import datetime
+
+from rich.console import Console
+from rich.panel import Panel
+
+from mcpnuke import __version__
+from mcpnuke.cli import build_url_list, parse_args
+from mcpnuke.cli_steps import (
+    _apply_baseline,
+    _base_probe_opts,
+    _k8s_setup,
+    _print_mode_notices,
+    _print_scan_panel,
+    _report,
+    _resolve_auth,
+    _should_fail,
+    _start_oast,
+    _validate_ai_backend,
+    _watch_lanes,
+)
+from mcpnuke.core.auth import parse_header_kv_pairs
+from mcpnuke.core.models import TargetResult
+from mcpnuke.core.trust import parse_trust_sets
+from mcpnuke.diff import (
+    load_baseline,
+    save_baseline,
+)
+from mcpnuke.patterns.credentials import redact_credentials
+from mcpnuke.scanner import run_parallel, scan_stdio_target, scan_target
+from mcpnuke.subcommands import (
+    EXIT_CLEAN,
+    EXIT_ERROR,
+    EXIT_FINDINGS,
+    _run_diff_subcommand,
+    _run_doctor,
+    _run_lab_coverage,
+)
+
+
+def _main_inner() -> None:
+    # Handle `mcpnuke diff a.json b.json` before full arg parse
+    if len(sys.argv) >= 2 and sys.argv[1] == "diff":
+        _run_diff_subcommand(sys.argv[2:])
+        return
+
+    args = parse_args()
+    console = Console(no_color=args.no_color, force_terminal=not args.no_color)
+    from mcpnuke.core.llm import configure_bedrock
+    configure_bedrock(enabled=False)
+    try:
+        extra_headers = parse_header_kv_pairs(getattr(args, "header", None))
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(EXIT_ERROR)
+    if args.dpop_proof:
+        extra_headers["DPoP"] = args.dpop_proof
+
+    if args.doctor:
+        _run_doctor(console)
+        sys.exit(EXIT_CLEAN)
+
+    if getattr(args, "lab_coverage", None):
+        _run_lab_coverage(args.lab_coverage, console, getattr(args, "json_out", None))
+        sys.exit(EXIT_CLEAN)
+
+    _validate_ai_backend(args)
+
+    deterministic_mode: bool = bool(getattr(args, "deterministic", False))
+    effective_probe_workers: int = args.probe_workers
+    effective_phase2_workers: int = args.claude_phase2_workers
+    if deterministic_mode:
+        effective_probe_workers = 1
+        effective_phase2_workers = 1
+
+    # --stdio mode: scan a local server via stdin/stdout, then exit
+    if args.stdio:
+        probe_opts = _base_probe_opts(
+            args,
+            extra_headers=extra_headers,
+            probe_workers=effective_probe_workers,
+            phase2_workers=effective_phase2_workers,
+            deterministic=deterministic_mode,
+        )
+
+        panel_lines = [
+            f"[bold cyan]mcpnuke v{__version__}[/bold cyan]  [dim]MCP Red Teaming & Security Scanner[/dim]",
+            "Mode    : stdio",
+            f"Command : {args.stdio}",
+            f"Fast    : {args.fast}",
+            f"Workers : {effective_probe_workers} probe thread(s)",
+            f"Started : {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        ]
+        if deterministic_mode:
+            panel_lines.append("Deterministic: True")
+        console.print(Panel("\n".join(panel_lines), title="mcpnuke", border_style="cyan"))
+
+        result = scan_stdio_target(
+            args.stdio,
+            timeout=args.timeout,
+            verbose=args.verbose,
+            probe_opts=probe_opts,
+        )
+        _report(args, [result], console)
+        if _should_fail(result.findings, getattr(args, "fail_on", "high")):
+            sys.exit(EXIT_FINDINGS)
+        sys.exit(EXIT_CLEAN)
+
+    inference_only = (
+        getattr(args, "inference_host", None)
+        and not args.targets
+        and not args.targets_file
+        and not getattr(args, "public_targets", False)
+        and not args.port_range
+    )
+    if inference_only or (
+        args.k8s_discover
+        and not args.targets
+        and not args.targets_file
+        and not getattr(args, "public_targets", False)
+        and not args.port_range
+    ):
+        urls = []
+    else:
+        urls = build_url_list(args)
+
+    try:
+        trust_sets = parse_trust_sets(getattr(args, "trust_set", None), targets=urls)
+    except ValueError as exc:
+        console.print(f"  [red]✗[/red] {exc}")
+        sys.exit(EXIT_ERROR)
+
+    auth_token, auth_context_summary = _resolve_auth(args, urls, extra_headers, console)
+
+    baseline = {}
+    if args.baseline:
+        baseline = load_baseline(args.baseline)
+        if not baseline:
+            console.print(f"[yellow]Baseline empty or not found: {args.baseline}[/yellow]")
+
+    _print_scan_panel(
+        args,
+        urls,
+        auth_token=auth_token,
+        auth_context_summary=auth_context_summary,
+        extra_headers=extra_headers,
+        probe_workers=effective_probe_workers,
+        phase2_workers=effective_phase2_workers,
+        deterministic=deterministic_mode,
+        console=console,
+    )
+
+    profile_data = None
+    if getattr(args, "profile", None):
+        from mcpnuke.profile import load_profile
+        try:
+            profile_data = load_profile(args.profile)
+            console.print(f"  [green]Profile loaded:[/green] {profile_data.name} ({len(profile_data.tools)} tools)")
+        except (FileNotFoundError, ValueError) as exc:
+            console.print(f"  [red]Profile error:[/red] {exc}")
+
+    probe_opts = {
+        **_base_probe_opts(
+            args,
+            extra_headers=extra_headers,
+            probe_workers=effective_probe_workers,
+            phase2_workers=effective_phase2_workers,
+            deterministic=deterministic_mode,
+        ),
+        "trust_sets": [sorted(group) for group in trust_sets],
+        "target_count": len(urls),
+        "auth_context_summary": auth_context_summary,
+        "profile": profile_data,
+    }
+
+    oast_listener = _start_oast(args, console)
+    if oast_listener is not None:
+        probe_opts["oast"] = oast_listener
+
+    _print_mode_notices(args, deterministic_mode, console)
+
+    _k8s_setup(args, urls, console)
+
+    if not urls and inference_only:
+        from mcpnuke.checks.inference_backend import check_inference_backend, check_model_integrity
+        t0 = time.time()
+        result = TargetResult(url=probe_opts["inference_host"])
+        result.transport = "inference-only"
+        check_inference_backend(result, probe_opts=probe_opts)
+        if probe_opts.get("inference_baseline") or probe_opts.get("save_inference_baseline"):
+            check_model_integrity(result, probe_opts=probe_opts)
+        result.timings["total"] = time.time() - t0
+        results = [result]
+        _report(args, results, console)
+        if probe_opts.get("save_inference_baseline"):
+            console.print(f"\n  [green]✓[/green] Inference baseline saved to {probe_opts['save_inference_baseline']}")
+        from mcpnuke.k8s.scanner import GLOBAL_K8S_FINDINGS
+        if _should_fail(result.findings + GLOBAL_K8S_FINDINGS, getattr(args, "fail_on", "high")):
+            sys.exit(EXIT_FINDINGS)
+        sys.exit(EXIT_CLEAN)
+
+    if not urls:
+        from mcpnuke.k8s.scanner import GLOBAL_K8S_FINDINGS
+        if GLOBAL_K8S_FINDINGS:
+            console.print(f"\n[bold]── K8s-Only Report ({len(GLOBAL_K8S_FINDINGS)} findings) ──[/bold]")
+            _report(args, [], console)
+            if _should_fail(GLOBAL_K8S_FINDINGS, getattr(args, "fail_on", "high")):
+                sys.exit(EXIT_FINDINGS)
+            sys.exit(EXIT_CLEAN)
+        console.print("[red]No targets specified and K8s discovery found nothing.[/red]")
+        sys.exit(EXIT_ERROR)
+
+    if len(urls) == 1:
+        results = [
+            scan_target(
+                urls[0],
+                [],
+                timeout=args.timeout,
+                verbose=args.verbose,
+                auth_token=auth_token,
+                probe_opts=probe_opts,
+            )
+        ]
+    else:
+        results = run_parallel(
+            urls,
+            timeout=args.timeout,
+            workers=args.workers,
+            verbose=args.verbose,
+            auth_token=auth_token,
+            probe_opts=probe_opts,
+        )
+
+    _apply_baseline(args, results, baseline, console)
+
+    _report(args, results, console)
+    if args.save_baseline:
+        save_baseline(results, args.save_baseline, console=console)
+
+    if getattr(args, "watch", None):
+        _watch_lanes(args, results, urls, auth_token, probe_opts, baseline, console)
+        return
+
+    from mcpnuke.k8s.scanner import GLOBAL_K8S_FINDINGS
+    all_findings = [f for r in results for f in r.findings] + GLOBAL_K8S_FINDINGS
+    if _should_fail(all_findings, getattr(args, "fail_on", "high")):
+        sys.exit(EXIT_FINDINGS)
+
+
+def main() -> None:
+    try:
+        _main_inner()
+    except Exception as exc:
+        print(f"mcpnuke: {type(exc).__name__}: {redact_credentials(str(exc))}", file=sys.stderr)
+        sys.exit(EXIT_ERROR)
+
+
+if __name__ == "__main__":
+    main()

mcpnuke/_docsgen.py

@@ -0,0 +1,297 @@
+"""Paths to the reference documents, and the renderer for the generated ones.
+
+Two kinds of document are named here and only one of them is generated.
+
+The CLI reference is derived from the argparse parser rather than maintained by
+hand, because the hand-maintained copy drifted 14 flags behind before anyone
+noticed. tests/test_docs_current.py fails the build if the committed output
+stops matching the parser.
+
+docs/checks.md is the other kind: hand-written, because a check's severity and
+what it detects cannot be derived from its source. Its path lives here so that
+the test guarding it can reference one place where doc paths are declared,
+which is the only thing the two have in common.
+
+DANGER: main() must never write CHECKS_PATH. Adding it there for symmetry with
+CLI_REFERENCE_PATH would overwrite a document nothing can regenerate, and would
+do it silently, on a command whose whole contract is "safe to re-run".
+test_generator_never_writes_the_hand_written_doc fails if main() so much as
+names it.
+
+Regenerate: uv run python -m mcpnuke._docsgen
+
+Never import this module from runtime code. REPO_ROOT walks up from __file__
+to find a checkout, which is meaningless in an installed wheel — the package
+ships whole, so this file is present but its paths point nowhere useful. It is
+a build-time tool that happens to live inside the package so it can import the
+parsers it documents.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+from pathlib import Path
+from typing import TypeGuard
+
+from mcpnuke.cli import build_parser
+from mcpnuke.subcommands import _build_diff_parser
+
+REPO_ROOT: Path = Path(__file__).resolve().parent.parent
+CLI_REFERENCE_PATH: Path = REPO_ROOT / "docs" / "cli-reference.md"
+
+# Hand-written, unlike the CLI reference: severity and detection prose cannot be
+# derived from source. Named here so the completeness test that guards it does
+# not have to rebuild a repo-root path of its own. Read-only to this module —
+# see the warning in the module docstring before using it anywhere that writes.
+CHECKS_PATH: Path = REPO_ROOT / "docs" / "checks.md"
+
+# Read as text, not imported: the association between an env var and the flag
+# it backs exists only in the source, since argparse keeps the resolved value
+# and throws the variable name away.
+CLI_SOURCE_PATH: Path = Path(__file__).resolve().parent / "cli.py"
+
+BANNER: str = (
+    "<!-- GENERATED FILE — do not edit by hand.\n"
+    "     Regenerate: uv run python -m mcpnuke._docsgen\n"
+    "     Source: mcpnuke/cli.py -->"
+)
+
+# argparse's own groups. "options" holds only -h/--help after the flags were
+# split into named groups, so rendering it would emit a stub section.
+_SKIP_TITLES: frozenset[str] = frozenset({"positional arguments", "options"})
+
+ENV_HEADING: str = "Environment Variables"
+DIFF_HEADING: str = "Subcommand: `mcpnuke diff`"
+
+# The only prose in the generated document. Everything factual — every option,
+# positional and variable name — comes from a parser or from the source.
+_DIFF_PROSE: str = (
+    "Compares two saved scan reports. `diff` is dispatched off `sys.argv` "
+    "before the main parser runs, so it takes its own arguments and none of "
+    "the options above."
+)
+_DIFF_EXIT_NOTE: str = (
+    "Exits 1 when the newer report contains findings the baseline did not, "
+    "so it can gate a CI job."
+)
+_ENV_PROSE: str = (
+    "Each variable supplies the default for one flag; passing the flag wins. "
+    "Only names are listed here — a value is a credential."
+)
+
+
+def _is_environ_get(node: ast.AST) -> TypeGuard[ast.Call]:
+    """True for an `os.environ.get(...)` call node."""
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "get"
+        and getattr(node.func.value, "attr", "") == "environ"
+        and bool(node.args)
+    )
+
+
+def _module_string_constants(tree: ast.Module) -> dict[str, str]:
+    """Module-level `NAME = "literal"` bindings, for resolving indirection.
+
+    `--auth-token` reads `os.environ.get(AUTH_TOKEN_ENV)`. A literal-only walk
+    finds 13 of the 14 variables and drops MCP_AUTH_TOKEN, the one most worth
+    documenting.
+    """
+    return {
+        target.id: node.value.value
+        for node in tree.body
+        if isinstance(node, ast.Assign)
+        and isinstance(node.value, ast.Constant)
+        and isinstance(node.value.value, str)
+        for target in node.targets
+        if isinstance(target, ast.Name)
+    }
+
+
+def _environ_name(node: ast.AST, constants: dict[str, str]) -> str | None:
+    """The variable name an `os.environ.get(...)` call reads, if it is static."""
+    if not _is_environ_get(node):
+        return None
+    key = node.args[0]
+    if isinstance(key, ast.Constant) and isinstance(key.value, str):
+        return key.value
+    if isinstance(key, ast.Name):
+        return constants.get(key.id)
+    return None
+
+
+def _parse_cli_source() -> tuple[ast.Module, dict[str, str]]:
+    tree = ast.parse(CLI_SOURCE_PATH.read_text())
+    return tree, _module_string_constants(tree)
+
+
+def count_environ_reads() -> int:
+    """How many `os.environ.get(...)` calls cli.py makes with a static name.
+
+    Exists so a test can assert the flag association below loses none of them;
+    a silent drop would put a variable back in the undocumented pile.
+    """
+    tree, constants = _parse_cli_source()
+    return len({
+        name
+        for node in ast.walk(tree)
+        if (name := _environ_name(node, constants)) is not None
+    })
+
+
+def env_var_flag_pairs() -> list[tuple[str, str]]:
+    """Every env var cli.py reads, paired with the flag whose default it sets.
+
+    Walks `add_argument` calls and takes the first string positional as the
+    flag, so the pairing comes from the source rather than a list someone has
+    to remember to update.
+    """
+    tree, constants = _parse_cli_source()
+    pairs: set[tuple[str, str]] = set()
+    for node in ast.walk(tree):
+        if not (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "add_argument"
+        ):
+            continue
+        flag = next(
+            (
+                arg.value
+                for arg in node.args
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str)
+            ),
+            None,
+        )
+        if flag is None:
+            continue
+        for inner in ast.walk(node):
+            name = _environ_name(inner, constants)
+            if name is not None:
+                pairs.add((name, flag))
+    return sorted(pairs)
+
+
+def _help_text(action: argparse.Action) -> str:
+    """The help string as `--help` shows it, without expanding any values.
+
+    argparse %-formats help strings before printing, so a literal percent is
+    written `%%` in the source. Undoing that escape here keeps the doc matching
+    `--help`. Note this is *not* argparse's `_expand_help`: that would also
+    substitute `%(default)s`, and fourteen defaults come from `os.environ.get`,
+    several of them secrets. Nothing here ever reads a default.
+    """
+    return (action.help or "").replace("%%", "%")
+
+
+def _cell(text: str) -> str:
+    """Collapse whitespace and escape pipes so a table row survives markdown."""
+    return " ".join(text.split()).replace("|", "\\|")
+
+
+def _row(formatter: argparse.HelpFormatter, action: argparse.Action) -> str:
+    """One table row: the invocation exactly as --help prints it, plus help."""
+    invocation = formatter._format_action_invocation(action)
+    return f"| `{_cell(invocation)}` | {_cell(_help_text(action))} |"
+
+
+def _table(header: str) -> list[str]:
+    return [f"| {header} | Description |", "|---|---|"]
+
+
+def _render_flag_groups(parser: argparse.ArgumentParser) -> list[str]:
+    """One section per curated argument group, in declaration order."""
+    formatter = parser._get_formatter()
+    lines: list[str] = []
+    for group in parser._action_groups:
+        if group.title in _SKIP_TITLES:
+            continue
+        actions = [
+            a
+            for a in group._group_actions
+            if a.help != argparse.SUPPRESS and a.option_strings
+        ]
+        if not actions:
+            continue
+        lines += [f"## {group.title}", "", *_table("Option")]
+        lines += [_row(formatter, a) for a in actions]
+        lines.append("")
+    return lines
+
+
+def _render_env_vars() -> list[str]:
+    return [
+        f"## {ENV_HEADING}",
+        "",
+        _ENV_PROSE,
+        "",
+        "| Variable | Flag |",
+        "|---|---|",
+        *(f"| `{var}` | `{flag}` |" for var, flag in env_var_flag_pairs()),
+        "",
+    ]
+
+
+def _render_diff_subcommand(parser: argparse.ArgumentParser) -> list[str]:
+    """The `diff` section, tables generated, prose hand-written.
+
+    Rendered separately because `diff` has positionals, which the main
+    renderer filters out rather than loosening its own filter for one section.
+    """
+    formatter = parser._get_formatter()
+    actions = [
+        a
+        for a in parser._actions
+        if a.help != argparse.SUPPRESS and "--help" not in a.option_strings
+    ]
+    return [
+        f"## {DIFF_HEADING}",
+        "",
+        _DIFF_PROSE,
+        "",
+        "```bash",
+        "mcpnuke diff OLD.json NEW.json",
+        "```",
+        "",
+        *_table("Argument"),
+        *(_row(formatter, a) for a in actions),
+        "",
+        _DIFF_EXIT_NOTE,
+    ]
+
+
+def render_cli_reference(
+    parser: argparse.ArgumentParser,
+    diff_parser: argparse.ArgumentParser | None = None,
+) -> str:
+    """Render the full CLI reference as markdown.
+
+    Only invocations and help text are emitted. Fourteen flags default to
+    `os.environ.get(...)`, several of them secrets, so a defaults column would
+    bake the generating machine's credentials into a committed file.
+    """
+    lines: list[str] = [
+        BANNER,
+        "",
+        "# CLI Reference",
+        "",
+        "Every option `mcpnuke` accepts, grouped as `--help` groups them.",
+        "Generated from the parser, so it cannot fall behind the code.",
+        "",
+        *_render_flag_groups(parser),
+        *_render_env_vars(),
+        *_render_diff_subcommand(diff_parser or _build_diff_parser()),
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main() -> None:
+    CLI_REFERENCE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CLI_REFERENCE_PATH.write_text(render_cli_reference(build_parser()))
+    print(f"wrote {CLI_REFERENCE_PATH.relative_to(REPO_ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

mcpnuke/_runner_entry.py

@@ -0,0 +1,55 @@
+"""Console-script shim for ``mcpnuke-runner``.
+
+The runner needs the optional ``server`` extra (fastapi, uvicorn, pydantic),
+but its console script is installed by the base package. Pointing the script
+straight at ``mcpnuke.server.app:run`` meant a plain ``pip install mcpnuke``
+followed by ``mcpnuke-runner`` printed a ModuleNotFoundError traceback.
+
+This module sits deliberately *outside* ``mcpnuke.server``: that package's
+``__init__`` imports pydantic through ``models``, so any handler written
+inside it would need the very dependency it is trying to report on.
+
+Nothing here may import the server package at module level.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+# The distribution names that make up the `server` extra. A missing import
+# outside this set is a real bug in the server package, and is re-raised
+# rather than reported as a missing extra.
+_SERVER_EXTRA_MODULES: frozenset[str] = frozenset({"fastapi", "uvicorn", "pydantic"})
+
+_EXIT_MISSING_EXTRA: int = 2
+
+
+def _load_run() -> Callable[[], None]:
+    """Import the real entry point. Kept separate so tests can replace it."""
+    from mcpnuke.server.app import run
+
+    return run
+
+
+def main() -> None:
+    try:
+        run = _load_run()
+    except ImportError as exc:
+        missing = (getattr(exc, "name", "") or "").split(".")[0]
+        if missing not in _SERVER_EXTRA_MODULES:
+            raise
+        sys.stderr.write(
+            f"mcpnuke-runner needs the 'server' extra, and {missing} is not installed.\n"
+            "\n"
+            "  uv tool install 'mcpnuke[server]'\n"
+            "  pip install 'mcpnuke[server]'\n"
+            "\n"
+            "The scanner itself does not need it — plain 'mcpnuke' works without.\n"
+        )
+        raise SystemExit(_EXIT_MISSING_EXTRA) from None
+    run()
+
+
+if __name__ == "__main__":
+    main()