mcp-supply-audit 0.1.0__tar.gz

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 (48) hide show
  1. mcp_supply_audit-0.1.0/LICENSE +21 -0
  2. mcp_supply_audit-0.1.0/PKG-INFO +142 -0
  3. mcp_supply_audit-0.1.0/README.md +121 -0
  4. mcp_supply_audit-0.1.0/pyproject.toml +51 -0
  5. mcp_supply_audit-0.1.0/pyproject.toml.orig +46 -0
  6. mcp_supply_audit-0.1.0/src/mcp_supply_audit/__init__.py +6 -0
  7. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/__init__.py +1 -0
  8. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/_http.py +507 -0
  9. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/npm.py +100 -0
  10. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/osv.py +205 -0
  11. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/pypi.py +159 -0
  12. mcp_supply_audit-0.1.0/src/mcp_supply_audit/clients/registry.py +119 -0
  13. mcp_supply_audit-0.1.0/src/mcp_supply_audit/config_scan.py +310 -0
  14. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/config_env_risky.yaml +45 -0
  15. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/config_runners.yaml +98 -0
  16. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/config_shells.yaml +56 -0
  17. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/confusables.yaml +22 -0
  18. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/pk001_advisory_id_prefixes.yaml +13 -0
  19. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/platform_namespaces.yaml +22 -0
  20. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/reference_names.json +56122 -0
  21. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/rg011_credential_params.yaml +26 -0
  22. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td002_instruction_phrases.yaml +37 -0
  23. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td003_cross_references.yaml +19 -0
  24. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td004_exfiltration.yaml +31 -0
  25. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td005_encoded_blobs.yaml +6 -0
  26. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td006_description_length.yaml +4 -0
  27. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/td007_param_names.yaml +19 -0
  28. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/typosquat_affixes.yaml +18 -0
  29. mcp_supply_audit-0.1.0/src/mcp_supply_audit/data/url_redact_params.yaml +27 -0
  30. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/__init__.py +1 -0
  31. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/config_rules.py +994 -0
  32. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/package_rules.py +340 -0
  33. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/registry.py +46 -0
  34. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/registry_rules.py +803 -0
  35. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/tool_defs.py +719 -0
  36. mcp_supply_audit-0.1.0/src/mcp_supply_audit/detectors/typosquat.py +667 -0
  37. mcp_supply_audit-0.1.0/src/mcp_supply_audit/errors.py +17 -0
  38. mcp_supply_audit-0.1.0/src/mcp_supply_audit/findings.py +429 -0
  39. mcp_supply_audit-0.1.0/src/mcp_supply_audit/hidden_chars.py +85 -0
  40. mcp_supply_audit-0.1.0/src/mcp_supply_audit/owasp.py +28 -0
  41. mcp_supply_audit-0.1.0/src/mcp_supply_audit/package_audit.py +330 -0
  42. mcp_supply_audit-0.1.0/src/mcp_supply_audit/registry_audit.py +231 -0
  43. mcp_supply_audit-0.1.0/src/mcp_supply_audit/sanitize.py +108 -0
  44. mcp_supply_audit-0.1.0/src/mcp_supply_audit/secrets.py +135 -0
  45. mcp_supply_audit-0.1.0/src/mcp_supply_audit/server.py +297 -0
  46. mcp_supply_audit-0.1.0/src/mcp_supply_audit/server_audit.py +368 -0
  47. mcp_supply_audit-0.1.0/src/mcp_supply_audit/typosquat_check.py +416 -0
  48. mcp_supply_audit-0.1.0/src/mcp_supply_audit/validation.py +229 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kim Mawla
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,142 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-supply-audit
3
+ Version: 0.1.0
4
+ Summary: An MCP server that audits other MCP servers as software artifacts: registry listings, packages, configs, and tool definitions. Static checks only. It never runs the code it inspects.
5
+ Keywords: mcp,model-context-protocol,supply-chain,security,static-analysis
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3 :: Only
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Topic :: Security
14
+ Requires-Dist: fastmcp>=4.1.5
15
+ Requires-Dist: httpx>=0.28.1
16
+ Requires-Dist: pyyaml>=6.0.3
17
+ Requires-Python: >=3.12
18
+ Project-URL: Repository, https://github.com/kimmawla/mcp-supply-audit
19
+ Project-URL: Issues, https://github.com/kimmawla/mcp-supply-audit/issues
20
+ Description-Content-Type: text/markdown
21
+
22
+ # mcp-supply-audit
23
+
24
+ <!-- mcp-name: io.github.kimmawla/mcp-supply-audit -->
25
+
26
+ > Audits MCP servers as software artifacts: registry entries, packages, configs, tool definitions.
27
+
28
+ An MCP server. Static checks only. It never runs the code it inspects.
29
+
30
+ **Status: pre-release, in development.** Not yet published. Nothing here is a security guarantee.
31
+
32
+ ## Why this exists
33
+ Most MCP security scanners focus on tool descriptions. This project looks at the server as a
34
+ supply-chain artifact: does the registry entry match its package and repo, is the name close to a
35
+ popular one, what do the package version's own metadata and advisories say, and what does the
36
+ config you are about to copy actually do.
37
+
38
+ ## What works today
39
+ Six tools, served over stdio by a FastMCP server ([tool surface](docs/tool-surface.md)). All are
40
+ read-only and take names or pasted text, never a path.
41
+
42
+ - `audit_server`: runs the checks below that apply to one server (a registry name, or a package
43
+ name plus `pypi`/`npm`) concurrently under a 30 s deadline, and returns one merged report. A check
44
+ that fails or times out is listed as skipped; the rest of the report still returns.
45
+ - `audit_registry_entry`: an MCP Registry entry's repository consistency with its packages, owner
46
+ match, package and version existence, ownership markers, status, and remote URLs (as text).
47
+ - `audit_package`: one PyPI or npm package version's OSV.dev advisories, yanked or deprecated
48
+ state, install scripts (npm only), provenance, publish recency (PyPI only) and declared repository.
49
+ - `check_typosquat`: whether a name is close to one in a dated reference list (curated PyPI and
50
+ npm names; for registry names, also names crawled from the MCP Registry).
51
+ - `scan_mcp_config`: an MCP client config's servers, for unpinned runners, plain-http remotes,
52
+ hardcoded secrets, shell wrappers, broad paths, non-registry sources and risky env.
53
+ - `scan_tool_definitions`: checks a `tools/list` snapshot for hidden Unicode, instruction-like
54
+ phrasing, cross-tool references, exfiltration phrasing, encoded blobs, and other indicators.
55
+
56
+ Outbound requests go only to registry.modelcontextprotocol.io, pypi.org, registry.npmjs.org and
57
+ api.osv.dev.
58
+
59
+ ## Quick start
60
+ Not on PyPI yet: these commands work once the package is published. Until then, run it
61
+ [from a source checkout](#from-a-source-checkout).
62
+
63
+ For Claude Code, with [uv](https://docs.astral.sh/uv/):
64
+
65
+ ```bash
66
+ claude mcp add mcp-supply-audit -- uvx mcp-supply-audit
67
+ ```
68
+
69
+ Pinned to one version (uvx's `package@version` form):
70
+
71
+ ```bash
72
+ claude mcp add mcp-supply-audit -- uvx mcp-supply-audit@0.1.0
73
+ ```
74
+
75
+ `scan_mcp_config` flags the first form in the configs it scans (CF001, unpinned package runner).
76
+
77
+ ### From a source checkout
78
+ Run it from a checkout of this repository with [uv](https://docs.astral.sh/uv/):
79
+
80
+ ```bash
81
+ cd mcp-supply-audit
82
+ uv sync
83
+ ```
84
+
85
+ Then point an MCP client at the `mcp-supply-audit` console script in that checkout. For Claude
86
+ Code:
87
+
88
+ ```bash
89
+ claude mcp add mcp-supply-audit -- uv --directory /path/to/mcp-supply-audit run mcp-supply-audit
90
+ ```
91
+
92
+ For clients configured with JSON (e.g. Claude Desktop's `mcpServers`):
93
+
94
+ ```json
95
+ {
96
+ "mcpServers": {
97
+ "mcp-supply-audit": {
98
+ "command": "uv",
99
+ "args": ["--directory", "/path/to/mcp-supply-audit", "run", "mcp-supply-audit"]
100
+ }
101
+ }
102
+ }
103
+ ```
104
+
105
+ Then ask, for example, "Is the MCP server `<namespace>/<name>` safe to install?" and the client
106
+ can call `audit_server`. Read the report's skipped checks: a report with no findings is not proof
107
+ of safety.
108
+
109
+ ## Design principles
110
+ - **Never executes a scan target.** Static analysis and metadata only. No tool accepts a filesystem path.
111
+ - **Hostile input by default.** Text from a target is sanitized, capped, and returned only as quoted
112
+ evidence under `untrusted_text`. Hidden characters are shown as visible `\uXXXX` escapes.
113
+ - **Deterministic rules, no LLM in detection.** Results are reproducible and unit-tested.
114
+ - **Findings are indicators, not verdicts.** Every report lists which checks ran and which were
115
+ skipped, and states that no findings is not proof of safety.
116
+ - **Mapped to the OWASP MCP Top 10** (beta, v0.1), by ID.
117
+
118
+ ## Limits
119
+ Static checks cannot see runtime behavior. Audit and telemetry gaps, shadow servers, and context
120
+ over-sharing are outside what this tool can detect.
121
+
122
+ Per-check limits: [registry checks](docs/known-limits-registry.md),
123
+ [package checks](docs/rules-package.md#known-limits),
124
+ [typosquat checks](docs/rules-typosquat.md#known-limits-quoted-by-the-readme),
125
+ [config checks](docs/known-limits-config.md).
126
+
127
+ ## Evaluation
128
+ No benchmark has been run yet.
129
+
130
+ ## Development
131
+ ```bash
132
+ uv sync
133
+ uv run pytest -q
134
+ uv run ruff check
135
+ uv run ruff format --check
136
+ ```
137
+
138
+ ## Security
139
+ To report a vulnerability in this project, see [SECURITY.md](SECURITY.md).
140
+
141
+ ## License
142
+ MIT
@@ -0,0 +1,121 @@
1
+ # mcp-supply-audit
2
+
3
+ <!-- mcp-name: io.github.kimmawla/mcp-supply-audit -->
4
+
5
+ > Audits MCP servers as software artifacts: registry entries, packages, configs, tool definitions.
6
+
7
+ An MCP server. Static checks only. It never runs the code it inspects.
8
+
9
+ **Status: pre-release, in development.** Not yet published. Nothing here is a security guarantee.
10
+
11
+ ## Why this exists
12
+ Most MCP security scanners focus on tool descriptions. This project looks at the server as a
13
+ supply-chain artifact: does the registry entry match its package and repo, is the name close to a
14
+ popular one, what do the package version's own metadata and advisories say, and what does the
15
+ config you are about to copy actually do.
16
+
17
+ ## What works today
18
+ Six tools, served over stdio by a FastMCP server ([tool surface](docs/tool-surface.md)). All are
19
+ read-only and take names or pasted text, never a path.
20
+
21
+ - `audit_server`: runs the checks below that apply to one server (a registry name, or a package
22
+ name plus `pypi`/`npm`) concurrently under a 30 s deadline, and returns one merged report. A check
23
+ that fails or times out is listed as skipped; the rest of the report still returns.
24
+ - `audit_registry_entry`: an MCP Registry entry's repository consistency with its packages, owner
25
+ match, package and version existence, ownership markers, status, and remote URLs (as text).
26
+ - `audit_package`: one PyPI or npm package version's OSV.dev advisories, yanked or deprecated
27
+ state, install scripts (npm only), provenance, publish recency (PyPI only) and declared repository.
28
+ - `check_typosquat`: whether a name is close to one in a dated reference list (curated PyPI and
29
+ npm names; for registry names, also names crawled from the MCP Registry).
30
+ - `scan_mcp_config`: an MCP client config's servers, for unpinned runners, plain-http remotes,
31
+ hardcoded secrets, shell wrappers, broad paths, non-registry sources and risky env.
32
+ - `scan_tool_definitions`: checks a `tools/list` snapshot for hidden Unicode, instruction-like
33
+ phrasing, cross-tool references, exfiltration phrasing, encoded blobs, and other indicators.
34
+
35
+ Outbound requests go only to registry.modelcontextprotocol.io, pypi.org, registry.npmjs.org and
36
+ api.osv.dev.
37
+
38
+ ## Quick start
39
+ Not on PyPI yet: these commands work once the package is published. Until then, run it
40
+ [from a source checkout](#from-a-source-checkout).
41
+
42
+ For Claude Code, with [uv](https://docs.astral.sh/uv/):
43
+
44
+ ```bash
45
+ claude mcp add mcp-supply-audit -- uvx mcp-supply-audit
46
+ ```
47
+
48
+ Pinned to one version (uvx's `package@version` form):
49
+
50
+ ```bash
51
+ claude mcp add mcp-supply-audit -- uvx mcp-supply-audit@0.1.0
52
+ ```
53
+
54
+ `scan_mcp_config` flags the first form in the configs it scans (CF001, unpinned package runner).
55
+
56
+ ### From a source checkout
57
+ Run it from a checkout of this repository with [uv](https://docs.astral.sh/uv/):
58
+
59
+ ```bash
60
+ cd mcp-supply-audit
61
+ uv sync
62
+ ```
63
+
64
+ Then point an MCP client at the `mcp-supply-audit` console script in that checkout. For Claude
65
+ Code:
66
+
67
+ ```bash
68
+ claude mcp add mcp-supply-audit -- uv --directory /path/to/mcp-supply-audit run mcp-supply-audit
69
+ ```
70
+
71
+ For clients configured with JSON (e.g. Claude Desktop's `mcpServers`):
72
+
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "mcp-supply-audit": {
77
+ "command": "uv",
78
+ "args": ["--directory", "/path/to/mcp-supply-audit", "run", "mcp-supply-audit"]
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ Then ask, for example, "Is the MCP server `<namespace>/<name>` safe to install?" and the client
85
+ can call `audit_server`. Read the report's skipped checks: a report with no findings is not proof
86
+ of safety.
87
+
88
+ ## Design principles
89
+ - **Never executes a scan target.** Static analysis and metadata only. No tool accepts a filesystem path.
90
+ - **Hostile input by default.** Text from a target is sanitized, capped, and returned only as quoted
91
+ evidence under `untrusted_text`. Hidden characters are shown as visible `\uXXXX` escapes.
92
+ - **Deterministic rules, no LLM in detection.** Results are reproducible and unit-tested.
93
+ - **Findings are indicators, not verdicts.** Every report lists which checks ran and which were
94
+ skipped, and states that no findings is not proof of safety.
95
+ - **Mapped to the OWASP MCP Top 10** (beta, v0.1), by ID.
96
+
97
+ ## Limits
98
+ Static checks cannot see runtime behavior. Audit and telemetry gaps, shadow servers, and context
99
+ over-sharing are outside what this tool can detect.
100
+
101
+ Per-check limits: [registry checks](docs/known-limits-registry.md),
102
+ [package checks](docs/rules-package.md#known-limits),
103
+ [typosquat checks](docs/rules-typosquat.md#known-limits-quoted-by-the-readme),
104
+ [config checks](docs/known-limits-config.md).
105
+
106
+ ## Evaluation
107
+ No benchmark has been run yet.
108
+
109
+ ## Development
110
+ ```bash
111
+ uv sync
112
+ uv run pytest -q
113
+ uv run ruff check
114
+ uv run ruff format --check
115
+ ```
116
+
117
+ ## Security
118
+ To report a vulnerability in this project, see [SECURITY.md](SECURITY.md).
119
+
120
+ ## License
121
+ MIT
@@ -0,0 +1,51 @@
1
+ [project]
2
+ name = "mcp-supply-audit"
3
+ version = "0.1.0"
4
+ description = "An MCP server that audits other MCP servers as software artifacts: registry listings, packages, configs, and tool definitions. Static checks only. It never runs the code it inspects."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ keywords = [
10
+ "mcp",
11
+ "model-context-protocol",
12
+ "supply-chain",
13
+ "security",
14
+ "static-analysis",
15
+ ]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Topic :: Security",
23
+ ]
24
+ dependencies = [
25
+ "fastmcp>=4.1.5",
26
+ "httpx>=0.28.1",
27
+ "pyyaml>=6.0.3",
28
+ ]
29
+
30
+ [project.urls]
31
+ Repository = "https://github.com/kimmawla/mcp-supply-audit"
32
+ Issues = "https://github.com/kimmawla/mcp-supply-audit/issues"
33
+
34
+ [project.scripts]
35
+ mcp-supply-audit = "mcp_supply_audit.server:main"
36
+
37
+ [build-system]
38
+ requires = ["uv_build>=0.11.26,<0.12.0"]
39
+ build-backend = "uv_build"
40
+
41
+ [dependency-groups]
42
+ dev = [
43
+ "pytest>=9.2.0",
44
+ "pytest-asyncio>=1.4.1.post1",
45
+ "pyyaml>=6.0.3",
46
+ "respx>=0.23.1",
47
+ "ruff>=0.17.3",
48
+ ]
49
+
50
+ [tool.pytest.ini_options]
51
+ asyncio_default_fixture_loop_scope = "function"
@@ -0,0 +1,46 @@
1
+ [project]
2
+ name = "mcp-supply-audit"
3
+ version = "0.1.0"
4
+ description = "An MCP server that audits other MCP servers as software artifacts: registry listings, packages, configs, and tool definitions. Static checks only. It never runs the code it inspects."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ keywords = ["mcp", "model-context-protocol", "supply-chain", "security", "static-analysis"]
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Intended Audience :: Developers",
13
+ "Programming Language :: Python :: 3",
14
+ "Programming Language :: Python :: 3 :: Only",
15
+ "Programming Language :: Python :: 3.12",
16
+ "Topic :: Security",
17
+ ]
18
+ dependencies = [
19
+ "fastmcp>=4.1.5",
20
+ "httpx>=0.28.1",
21
+ "pyyaml>=6.0.3",
22
+ ]
23
+
24
+ [project.urls]
25
+ Repository = "https://github.com/kimmawla/mcp-supply-audit"
26
+ Issues = "https://github.com/kimmawla/mcp-supply-audit/issues"
27
+
28
+ [project.scripts]
29
+ mcp-supply-audit = "mcp_supply_audit.server:main"
30
+
31
+ [build-system]
32
+ requires = ["uv_build>=0.11.26,<0.12.0"]
33
+ build-backend = "uv_build"
34
+
35
+ [dependency-groups]
36
+ dev = [
37
+ "pytest>=9.2.0",
38
+ "pytest-asyncio>=1.4.1.post1",
39
+ "pyyaml>=6.0.3",
40
+ "respx>=0.23.1",
41
+ "ruff>=0.17.3",
42
+ ]
43
+
44
+
45
+ [tool.pytest.ini_options]
46
+ asyncio_default_fixture_loop_scope = "function"
@@ -0,0 +1,6 @@
1
+ def main() -> None:
2
+ """Run the MCP server over stdio (same as the mcp-supply-audit console script)."""
3
+ # Imported here so importing the package does not build the server.
4
+ from mcp_supply_audit.server import main as run_server
5
+
6
+ run_server()
@@ -0,0 +1 @@
1
+ """Clients for the allowlisted hosts. All network access goes through clients/_http.py."""