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.
- mcpprobe/__init__.py +1 -1
- mcpprobe/action.py +113 -6
- mcpprobe/chains.py +103 -0
- mcpprobe/checks/__init__.py +19 -0
- mcpprobe/checks/auth.py +301 -48
- mcpprobe/checks/base.py +66 -1
- mcpprobe/checks/baseline.py +33 -2
- mcpprobe/checks/capability.py +186 -2
- mcpprobe/checks/metadata.py +279 -93
- mcpprobe/checks/poisoning.py +181 -36
- mcpprobe/checks/proof.py +163 -0
- mcpprobe/checks/protocol_2026.py +749 -0
- mcpprobe/checks/robustness.py +124 -8
- mcpprobe/checks/tool_surface.py +339 -0
- mcpprobe/checks/transport_conformance.py +295 -77
- mcpprobe/cli.py +50 -0
- mcpprobe/environment.py +51 -0
- mcpprobe/judges/__init__.py +31 -0
- mcpprobe/judges/hf.py +125 -0
- mcpprobe/models.py +120 -3
- mcpprobe/readiness.py +341 -0
- mcpprobe/report/json_report.py +7 -0
- mcpprobe/report/sarif.py +21 -3
- mcpprobe/report/terminal.py +52 -3
- mcpprobe/scanner.py +179 -10
- mcpprobe/transport/base.py +25 -1
- mcpprobe/transport/evidence.py +21 -45
- mcpprobe/transport/fingerprint.py +7 -8
- mcpprobe/transport/http.py +112 -2
- {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/METADATA +66 -12
- mcpprobe_scanner-0.3.0.dist-info/RECORD +48 -0
- mcpprobe_scanner-0.3.0.dist-info/licenses/LICENSE +201 -0
- mcpprobe_scanner-0.3.0.dist-info/licenses/NOTICE +8 -0
- mcpprobe_scanner-0.1.0.dist-info/RECORD +0 -39
- mcpprobe_scanner-0.1.0.dist-info/licenses/LICENSE +0 -21
- {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/WHEEL +0 -0
- {mcpprobe_scanner-0.1.0.dist-info → mcpprobe_scanner-0.3.0.dist-info}/entry_points.txt +0 -0
mcpprobe/__init__.py
CHANGED
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
|
|
6
|
-
|
|
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(
|
|
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
|
mcpprobe/checks/__init__.py
CHANGED
|
@@ -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",
|