mcpprobe-scanner 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. mcpprobe/__init__.py +1 -1
  2. mcpprobe/action.py +113 -6
  3. mcpprobe/chains.py +103 -0
  4. mcpprobe/checks/__init__.py +19 -0
  5. mcpprobe/checks/auth.py +301 -48
  6. mcpprobe/checks/base.py +66 -1
  7. mcpprobe/checks/baseline.py +33 -2
  8. mcpprobe/checks/capability.py +186 -2
  9. mcpprobe/checks/metadata.py +279 -93
  10. mcpprobe/checks/poisoning.py +181 -36
  11. mcpprobe/checks/proof.py +163 -0
  12. mcpprobe/checks/protocol_2026.py +749 -0
  13. mcpprobe/checks/robustness.py +124 -8
  14. mcpprobe/checks/tool_surface.py +339 -0
  15. mcpprobe/checks/transport_conformance.py +295 -77
  16. mcpprobe/cli.py +50 -0
  17. mcpprobe/environment.py +51 -0
  18. mcpprobe/judges/__init__.py +31 -0
  19. mcpprobe/judges/hf.py +125 -0
  20. mcpprobe/models.py +120 -3
  21. mcpprobe/readiness.py +341 -0
  22. mcpprobe/report/json_report.py +7 -0
  23. mcpprobe/report/sarif.py +21 -3
  24. mcpprobe/report/terminal.py +52 -3
  25. mcpprobe/scanner.py +179 -10
  26. mcpprobe/transport/base.py +25 -1
  27. mcpprobe/transport/evidence.py +21 -45
  28. mcpprobe/transport/fingerprint.py +7 -8
  29. mcpprobe/transport/http.py +112 -2
  30. {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/METADATA +66 -12
  31. mcpprobe_scanner-0.3.0.dist-info/RECORD +48 -0
  32. mcpprobe_scanner-0.3.0.dist-info/licenses/LICENSE +201 -0
  33. mcpprobe_scanner-0.3.0.dist-info/licenses/NOTICE +8 -0
  34. mcpprobe_scanner-0.1.0.dist-info/RECORD +0 -39
  35. mcpprobe_scanner-0.1.0.dist-info/licenses/LICENSE +0 -21
  36. {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/WHEEL +0 -0
  37. {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/entry_points.txt +0 -0
mcpprobe/__init__.py CHANGED
@@ -13,7 +13,7 @@ The package is organised as follows:
13
13
 
14
14
  from __future__ import annotations
15
15
 
16
- __version__ = "0.1.0"
16
+ __version__ = "0.3.0"
17
17
 
18
18
  POLICY_URL = "https://mcpprobe.tech/scanning-policy"
19
19
  USER_AGENT = f"mcpprobe/{__version__} (+{POLICY_URL})"
mcpprobe/action.py CHANGED
@@ -2,19 +2,40 @@
2
2
 
3
3
  GitHub passes action inputs as ``INPUT_<NAME>`` environment variables (name
4
4
  upper-cased, hyphens kept). This module turns them into a CLI invocation,
5
- always writes SARIF, records outputs in ``$GITHUB_OUTPUT`` and exits with the
6
- scanner's exit code (0 clean, 1 findings at or above ``fail-on``, 2 error).
5
+ always writes SARIF, records outputs in ``$GITHUB_OUTPUT``, writes a job
6
+ summary to ``$GITHUB_STEP_SUMMARY``, emits one workflow annotation that names
7
+ the outcome, and exits with the scanner's exit code:
8
+
9
+ - 0 clean (no finding at or above ``fail-on``)
10
+ - 1 findings at or above ``fail-on``
11
+ - 2 error (unreachable target, bad input, opt-out, authorisation refused)
12
+ - 3 the target answered but is not an MCP server (wrong URL or path)
13
+
14
+ For exit codes 2 and 3 the SARIF file contains no results. Uploading it to
15
+ code scanning would close every open alert for the category, so workflows
16
+ should upload only when ``result`` is ``clean`` or ``findings``.
7
17
  """
8
18
 
9
19
  from __future__ import annotations
10
20
 
21
+ import json
11
22
  import os
12
23
  import shlex
13
24
  import sys
14
25
  from collections.abc import Mapping
15
26
  from pathlib import Path
27
+ from typing import Any
16
28
 
17
- from mcpprobe.cli import EXIT_ERROR, main
29
+ from mcpprobe.cli import EXIT_CLEAN, EXIT_ERROR, EXIT_FINDINGS, EXIT_NOT_MCP, main
30
+
31
+ #: ``result`` output value for each exit code.
32
+ RESULTS: dict[int, str] = {
33
+ EXIT_CLEAN: "clean",
34
+ EXIT_FINDINGS: "findings",
35
+ EXIT_ERROR: "error",
36
+ EXIT_NOT_MCP: "not-mcp",
37
+ }
38
+ _SEVERITIES = ("critical", "high", "medium", "low", "info")
18
39
 
19
40
 
20
41
  def _input(env: Mapping[str, str], name: str, default: str = "") -> str:
@@ -44,24 +65,110 @@ def build_argv(env: Mapping[str, str]) -> list[str]:
44
65
  return argv
45
66
 
46
67
 
68
+ def _escape(text: str) -> str:
69
+ """Escape a workflow-command message (``%``, CR and LF must be encoded)."""
70
+ return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
71
+
72
+
73
+ def _escape_property(text: str) -> str:
74
+ """Escape a workflow-command property value (also ``:`` and ``,``)."""
75
+ return _escape(text).replace(":", "%3A").replace(",", "%2C")
76
+
77
+
78
+ def sarif_counts(path: Path) -> dict[str, int]:
79
+ """Count SARIF results per mcpprobe severity (empty when the file is missing or unreadable)."""
80
+ counts = dict.fromkeys(_SEVERITIES, 0)
81
+ try:
82
+ data: Any = json.loads(path.read_text(encoding="utf-8"))
83
+ for run in data.get("runs", []):
84
+ for result in run.get("results", []):
85
+ sev = str(result.get("properties", {}).get("severity", "info"))
86
+ counts[sev if sev in counts else "info"] += 1
87
+ except (OSError, ValueError, AttributeError):
88
+ return {}
89
+ return counts
90
+
91
+
92
+ def describe(code: int, target: str, fail_on: str, counts: Mapping[str, int]) -> tuple[str, str, str]:
93
+ """Return (annotation level, title, message) for an exit code."""
94
+ total = sum(counts.values())
95
+ breakdown = ", ".join(f"{counts[s]} {s}" for s in _SEVERITIES if counts.get(s))
96
+ if code == EXIT_CLEAN:
97
+ found = f" ({breakdown} below the threshold)" if breakdown else ""
98
+ return "notice", "mcpprobe: passed", f"No finding at or above '{fail_on}' on {target}{found}."
99
+ if code == EXIT_FINDINGS:
100
+ return (
101
+ "error",
102
+ "mcpprobe: findings",
103
+ f"{total} finding(s) on {target} ({breakdown}); at least one is at or above '{fail_on}'. "
104
+ "See the job summary or the code scanning alerts.",
105
+ )
106
+ if code == EXIT_NOT_MCP:
107
+ return (
108
+ "error",
109
+ "mcpprobe: not an MCP server",
110
+ f"{target} answered, but not as an MCP server, so nothing was checked and nothing passed. "
111
+ "Check the URL and path (Streamable HTTP endpoints are usually /mcp) and that the "
112
+ "deployment is up. Do not upload this SARIF: it has no results and would close open alerts.",
113
+ )
114
+ return (
115
+ "error",
116
+ "mcpprobe: scan error",
117
+ f"The scan of {target} did not complete (exit {code}): the target was unreachable, an input "
118
+ "was invalid, the target opted out, or authorisation was refused. See the step log.",
119
+ )
120
+
121
+
122
+ def _summary(code: int, target: str, fail_on: str, counts: Mapping[str, int], message: str) -> str:
123
+ lines = [
124
+ "## mcpprobe MCP security scan",
125
+ "",
126
+ f"**Target:** `{target}` ",
127
+ f"**Result:** {RESULTS.get(code, 'error')} (exit {code}, fail-on `{fail_on}`)",
128
+ "",
129
+ message,
130
+ "",
131
+ ]
132
+ if code in (EXIT_CLEAN, EXIT_FINDINGS) and counts:
133
+ lines += ["| Severity | Findings |", "|---|---|"]
134
+ lines += [f"| {s} | {counts[s]} |" for s in _SEVERITIES]
135
+ lines.append("")
136
+ lines.append(
137
+ "Docs: https://mcpprobe.tech · checks: https://github.com/mcpprobe-dev/mcpprobe/blob/main/CHECKS.md"
138
+ )
139
+ return "\n".join(lines) + "\n"
140
+
141
+
47
142
  def run(env: Mapping[str, str] | None = None) -> int:
48
143
  env = os.environ if env is None else env
49
144
  try:
50
145
  argv = build_argv(env)
51
146
  except ValueError as exc:
52
- print(f"::error::{exc}", file=sys.stderr)
147
+ print(
148
+ f"::error title={_escape_property('mcpprobe: bad input')}::{_escape(str(exc))}", file=sys.stderr
149
+ )
53
150
  return EXIT_ERROR
54
151
  code = EXIT_ERROR
55
152
  try:
56
153
  main(argv)
57
154
  except SystemExit as exc:
58
155
  code = exc.code if isinstance(exc.code, int) else EXIT_ERROR
156
+ target = argv[1]
157
+ fail_on = argv[argv.index("--fail-on") + 1]
158
+ sarif = argv[argv.index("--sarif") + 1]
159
+ counts = sarif_counts(Path(sarif))
160
+ level, title, message = describe(code, target, fail_on, counts)
161
+ print(f"::{level} title={_escape_property(title)}::{_escape(message)}", file=sys.stderr)
59
162
  out = env.get("GITHUB_OUTPUT")
60
163
  if out:
61
- sarif = argv[argv.index("--sarif") + 1]
62
164
  with Path(out).open("a", encoding="utf-8") as fh:
63
- fh.write(f"sarif-file={sarif}\n")
165
+ fh.write(f"sarif-file={sarif if Path(sarif).exists() else ''}\n")
64
166
  fh.write(f"exit-code={code}\n")
167
+ fh.write(f"result={RESULTS.get(code, 'error')}\n")
168
+ summary = env.get("GITHUB_STEP_SUMMARY")
169
+ if summary:
170
+ with Path(summary).open("a", encoding="utf-8") as fh:
171
+ fh.write(_summary(code, target, fail_on, counts, message))
65
172
  return code
66
173
 
67
174
 
mcpprobe/chains.py ADDED
@@ -0,0 +1,103 @@
1
+ """Attack chains: findings that together form one attack path.
2
+
3
+ A chain is emitted only when every constituent finding is present in the
4
+ report; it never adds evidence of its own and never upgrades a finding.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import TYPE_CHECKING
10
+
11
+ from mcpprobe.models import Chain, Finding, ScanReport, Severity
12
+
13
+ if TYPE_CHECKING:
14
+ from mcpprobe.checks.base import ScanContext
15
+
16
+ EXEC = "arbitrary_command_execution"
17
+ FILE_READ = "arbitrary_file_read"
18
+ FILE_WRITE = "arbitrary_file_write"
19
+
20
+
21
+ def _first(findings: list[Finding], check_id: str) -> Finding | None:
22
+ return next((f for f in findings if f.id == check_id), None)
23
+
24
+
25
+ def _dangerous_tools(findings: list[Finding]) -> dict[str, list[str]]:
26
+ """``{tool: [capability, ...]}`` from META-03's arbitrary-capability finding."""
27
+ out: dict[str, list[str]] = {}
28
+ for f in findings:
29
+ if f.id != "META-03":
30
+ continue
31
+ caps = f.details.get("arbitrary")
32
+ if isinstance(caps, dict):
33
+ for tool, kinds in caps.items():
34
+ if isinstance(kinds, list):
35
+ out.setdefault(str(tool), []).extend(str(k) for k in kinds)
36
+ return out
37
+
38
+
39
+ def _poisoned_tools(findings: list[Finding], candidates: set[str]) -> list[str]:
40
+ hits: list[str] = []
41
+ for f in findings:
42
+ if f.id == "META-01" and f.severity >= Severity.MEDIUM:
43
+ hits.extend(t for t in f.affected if t in candidates and t not in hits)
44
+ return hits
45
+
46
+
47
+ def build_chains(report: ScanReport, ctx: ScanContext) -> list[Chain]:
48
+ findings = report.findings
49
+ chains: list[Chain] = []
50
+ auth01 = _first(findings, "AUTH-01")
51
+ dangerous = _dangerous_tools(findings)
52
+ if auth01 is None or not dangerous:
53
+ return chains
54
+ exec_tools = sorted(t for t, k in dangerous.items() if EXEC in k)
55
+ file_tools = sorted(t for t, k in dangerous.items() if FILE_READ in k or FILE_WRITE in k)
56
+ poisoned = _poisoned_tools(findings, set(dangerous))
57
+ ids = ["AUTH-01", "META-03"] + (["META-01"] if poisoned else [])
58
+ if exec_tools:
59
+ what = "remote code execution"
60
+ tools_text = ", ".join(exec_tools + [t for t in file_tools if t not in exec_tools])
61
+ else:
62
+ what = "arbitrary file access"
63
+ tools_text = ", ".join(file_tools)
64
+ title = f"Unauthenticated {what}" + (" steered by a poisoned description" if poisoned else "")
65
+ narrative = (
66
+ f"Anyone who can reach {ctx.target} can call {tools_text} without credentials (AUTH-01). "
67
+ f"The advertised capability of {'these tools' if len(dangerous) > 1 else 'this tool'} is "
68
+ + "; ".join(
69
+ f"{t}: {', '.join(k.replace('_', ' ') for k in sorted(set(v)))}"
70
+ for t, v in sorted(dangerous.items())
71
+ )
72
+ + " (META-03)."
73
+ )
74
+ if poisoned:
75
+ narrative += (
76
+ f" The description of {', '.join(poisoned)} also tells the model to call it and hand over "
77
+ "context (META-01), so a connected AI client can be steered into the same path without "
78
+ "the attacker ever touching the endpoint."
79
+ )
80
+ narrative += (
81
+ " Fix the chain by removing or sandboxing the tool first; adding authentication alone "
82
+ "leaves it open to every authenticated or prompt-injected client."
83
+ )
84
+ chains.append(
85
+ Chain(id="CHAIN-01", title=title, severity=Severity.CRITICAL, finding_ids=ids, narrative=narrative)
86
+ )
87
+
88
+ trans01 = _first(findings, "TRANS-01")
89
+ if trans01 is not None and not ctx.environment.public and ctx.is_http:
90
+ chains.append(
91
+ Chain(
92
+ id="CHAIN-02",
93
+ title="Browser-driven access to a local server's dangerous tools (DNS rebinding)",
94
+ severity=Severity.HIGH,
95
+ finding_ids=["TRANS-01", "AUTH-01", "META-03"],
96
+ narrative=(
97
+ f"The server at {ctx.target} runs on a local or private address, accepts foreign "
98
+ "Origin headers (TRANS-01) and needs no credentials (AUTH-01). A web page the user "
99
+ f"visits can use DNS rebinding to reach it and call {tools_text} (META-03)."
100
+ ),
101
+ )
102
+ )
103
+ return chains
@@ -20,6 +20,7 @@ from mcpprobe.checks.base import (
20
20
  Check,
21
21
  JudgeFn,
22
22
  JudgeVerdict,
23
+ NotApplicable,
23
24
  ScanContext,
24
25
  ScanOptions,
25
26
  )
@@ -30,7 +31,16 @@ from mcpprobe.checks.metadata import (
30
31
  Meta05SecretsInMetadata,
31
32
  )
32
33
  from mcpprobe.checks.poisoning import Meta01ToolDescriptionPoisoning
34
+ from mcpprobe.checks.protocol_2026 import (
35
+ Auth05IssuerIdentification,
36
+ Auth06DynamicClientRegistration,
37
+ Trans06ServerDiscover,
38
+ Trans07UnadvertisedVersionAccepted,
39
+ Trans08HeaderBodyMismatch,
40
+ Trans09CachingHints,
41
+ )
33
42
  from mcpprobe.checks.robustness import Dos01UnboundedConsumption, Err01VerboseErrors
43
+ from mcpprobe.checks.tool_surface import Meta06ToolAnnotationLint, Meta07ToxicFlow
34
44
  from mcpprobe.checks.transport_conformance import (
35
45
  Trans01OriginValidation,
36
46
  Trans02ProtocolVersionHandling,
@@ -44,16 +54,24 @@ PASSIVE_CHECKS: list[type[Check]] = [
44
54
  Auth02MissingProtectedResourceMetadata,
45
55
  Auth03AuthorizationServerMetadata,
46
56
  Auth04TokenAudienceAndPassthrough,
57
+ Auth05IssuerIdentification,
58
+ Auth06DynamicClientRegistration,
47
59
  Trans01OriginValidation,
48
60
  Trans02ProtocolVersionHandling,
49
61
  Trans03SessionIdQuality,
50
62
  Trans04DeprecatedTransport,
51
63
  Trans05TlsAndHeaders,
64
+ Trans06ServerDiscover,
65
+ Trans07UnadvertisedVersionAccepted,
66
+ Trans08HeaderBodyMismatch,
67
+ Trans09CachingHints,
52
68
  Meta01ToolDescriptionPoisoning,
53
69
  Meta02RugPullBaseline,
54
70
  Meta03DangerousCapabilitySurface,
55
71
  Meta04SchemaHygiene,
56
72
  Meta05SecretsInMetadata,
73
+ Meta06ToolAnnotationLint,
74
+ Meta07ToxicFlow,
57
75
  Err01VerboseErrors,
58
76
  Dos01UnboundedConsumption,
59
77
  ]
@@ -93,6 +111,7 @@ __all__ = [
93
111
  "Check",
94
112
  "JudgeFn",
95
113
  "JudgeVerdict",
114
+ "NotApplicable",
96
115
  "ScanContext",
97
116
  "ScanOptions",
98
117
  "get_check",