mcp-vulnerabilities 1.0.0__tar.gz

mcp_vulnerabilities-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: mcp-vulnerabilities
+Version: 1.0.0
+Summary: Open-Source OSV-Compliant Model Context Protocol (MCP) Vulnerability Advisory Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# Open-Source MCP Vulnerability Advisory Database
+
+[![Daily MCP Vulnerability Ingestion & Sync](https://github.com/JMartynov/mcp-vulnerabilities/actions/workflows/daily_sync.yml/badge.svg)](https://github.com/JMartynov/mcp-vulnerabilities/actions/workflows/daily_sync.yml)
+[![Advisories Count](https://img.shields.io/badge/advisories-500%2B-red.svg)](data/vulnerabilities)
+[![OSV Schema 1.6.0](https://img.shields.io/badge/schema-OSV%201.6.0-blue.svg)](https://ossf.github.io/osv-schema/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+An open-source, automated **Open Source Vulnerability (OSV 1.6)** compliant security advisory database specifically curated for the **Model Context Protocol (MCP)** ecosystem.
+
+## Sources
+- **CVE List v5**: Official CVE JSON 5.0 records.
+- **GitHub Security Advisories (GHSA)**: Live GraphQL/REST security alerts.
+- **OSV.dev**: Unified open-source vulnerability database.
+- **National Vulnerability Database (NVD)**: CVE 2.0 vulnerability metrics and CVSS scores.
+
+## Fast Consumption
+
+You can fetch the complete vulnerability database snapshot in a single GET request:
+```bash
+curl -sL https://raw.githubusercontent.com/JMartynov/mcp-vulnerabilities/main/vulnerabilities.json.gz | gzip -d > vulnerabilities.json
+```
+
+### Python
+```python
+import gzip, json, urllib.request
+
+url = "https://raw.githubusercontent.com/JMartynov/mcp-vulnerabilities/main/vulnerabilities.json.gz"
+with urllib.request.urlopen(url) as resp:
+    with gzip.GzipFile(fileobj=resp) as gz:
+        data = json.load(gz)
+
+print(f"Loaded {data['total_vulnerabilities']} MCP security advisories.")
+```
+
+## CI/CD Integration
+
+You can easily prevent vulnerable MCP server dependencies from entering your production environment or being configured into AI client settings by adding this official, reusable GitHub Action to your CI workflows.
+
+### Audit AI Client Configurations
+```yaml
+- name: Audit MCP Servers
+  uses: JMartynov/mcp-vulnerabilities@v1
+  with:
+    config-path: ".claude/claude_desktop_config.json"
+    fail-on-severity: "HIGH"
+```
+
+### Audit Dependency Manifests
+```yaml
+- name: Audit Transitive Dependencies
+  uses: JMartynov/mcp-vulnerabilities@v1
+  with:
+    manifest-path: "package.json"
+    fail-on-severity: "HIGH"
+```
+
+## CLI Usage
+```bash
+# Ingest latest advisories from live APIs
+python -m mcp_vulnerabilities.cli sync --live-api
+
+# Validate OSV schema compliance
+python -m mcp_vulnerabilities.cli validate --dir data/vulnerabilities
+
+# Compile compressed snapshot
+python -m mcp_vulnerabilities.cli snapshot
+```
+
+## Documentation
+
+- [Specification](docs/SPECIFICATION.md): Details the OSV 1.6 schema extensions, semantics, and vulnerability invariants.
+- [Implementation](docs/IMPLEMENTATION.md): Architecture blueprint covering ingestion pipelines, state machines, and acceptance tests.
+
+## Testing
+
+Execute the acceptance test suite to validate the end-to-end functionality:
+
+```bash
+uv run pytest -v tests/test_acceptance_*.py
+```
+
+## Publishing to PyPI
+
+### Final Optional Step: Tagging v1.0.0 for PyPI
+When you're ready to publish the inaugural release to PyPI:
+1. Ensure your [PyPI account](https://pypi.org/manage/account/publishing/) has a Pending Publisher configured:
+   - **Owner**: `JMartynov`
+   - **Repository**: `mcp-vulnerabilities`
+   - **Workflow name**: `release.yaml`
+   - **Environment**: `pypi` (or Any)
+2. Create and push the release tag:
+   ```bash
+   git tag -a v1.0.0 -m "Release v1.0.0: Inaugural open-source MCP vulnerability database & CLI"
+   git push origin v1.0.0
+   ```
+
+## License
+MIT
+

mcp_vulnerabilities-1.0.0/README.md

@@ -0,0 +1,99 @@
+# Open-Source MCP Vulnerability Advisory Database
+
+[![Daily MCP Vulnerability Ingestion & Sync](https://github.com/JMartynov/mcp-vulnerabilities/actions/workflows/daily_sync.yml/badge.svg)](https://github.com/JMartynov/mcp-vulnerabilities/actions/workflows/daily_sync.yml)
+[![Advisories Count](https://img.shields.io/badge/advisories-500%2B-red.svg)](data/vulnerabilities)
+[![OSV Schema 1.6.0](https://img.shields.io/badge/schema-OSV%201.6.0-blue.svg)](https://ossf.github.io/osv-schema/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+An open-source, automated **Open Source Vulnerability (OSV 1.6)** compliant security advisory database specifically curated for the **Model Context Protocol (MCP)** ecosystem.
+
+## Sources
+- **CVE List v5**: Official CVE JSON 5.0 records.
+- **GitHub Security Advisories (GHSA)**: Live GraphQL/REST security alerts.
+- **OSV.dev**: Unified open-source vulnerability database.
+- **National Vulnerability Database (NVD)**: CVE 2.0 vulnerability metrics and CVSS scores.
+
+## Fast Consumption
+
+You can fetch the complete vulnerability database snapshot in a single GET request:
+```bash
+curl -sL https://raw.githubusercontent.com/JMartynov/mcp-vulnerabilities/main/vulnerabilities.json.gz | gzip -d > vulnerabilities.json
+```
+
+### Python
+```python
+import gzip, json, urllib.request
+
+url = "https://raw.githubusercontent.com/JMartynov/mcp-vulnerabilities/main/vulnerabilities.json.gz"
+with urllib.request.urlopen(url) as resp:
+    with gzip.GzipFile(fileobj=resp) as gz:
+        data = json.load(gz)
+
+print(f"Loaded {data['total_vulnerabilities']} MCP security advisories.")
+```
+
+## CI/CD Integration
+
+You can easily prevent vulnerable MCP server dependencies from entering your production environment or being configured into AI client settings by adding this official, reusable GitHub Action to your CI workflows.
+
+### Audit AI Client Configurations
+```yaml
+- name: Audit MCP Servers
+  uses: JMartynov/mcp-vulnerabilities@v1
+  with:
+    config-path: ".claude/claude_desktop_config.json"
+    fail-on-severity: "HIGH"
+```
+
+### Audit Dependency Manifests
+```yaml
+- name: Audit Transitive Dependencies
+  uses: JMartynov/mcp-vulnerabilities@v1
+  with:
+    manifest-path: "package.json"
+    fail-on-severity: "HIGH"
+```
+
+## CLI Usage
+```bash
+# Ingest latest advisories from live APIs
+python -m mcp_vulnerabilities.cli sync --live-api
+
+# Validate OSV schema compliance
+python -m mcp_vulnerabilities.cli validate --dir data/vulnerabilities
+
+# Compile compressed snapshot
+python -m mcp_vulnerabilities.cli snapshot
+```
+
+## Documentation
+
+- [Specification](docs/SPECIFICATION.md): Details the OSV 1.6 schema extensions, semantics, and vulnerability invariants.
+- [Implementation](docs/IMPLEMENTATION.md): Architecture blueprint covering ingestion pipelines, state machines, and acceptance tests.
+
+## Testing
+
+Execute the acceptance test suite to validate the end-to-end functionality:
+
+```bash
+uv run pytest -v tests/test_acceptance_*.py
+```
+
+## Publishing to PyPI
+
+### Final Optional Step: Tagging v1.0.0 for PyPI
+When you're ready to publish the inaugural release to PyPI:
+1. Ensure your [PyPI account](https://pypi.org/manage/account/publishing/) has a Pending Publisher configured:
+   - **Owner**: `JMartynov`
+   - **Repository**: `mcp-vulnerabilities`
+   - **Workflow name**: `release.yaml`
+   - **Environment**: `pypi` (or Any)
+2. Create and push the release tag:
+   ```bash
+   git tag -a v1.0.0 -m "Release v1.0.0: Inaugural open-source MCP vulnerability database & CLI"
+   git push origin v1.0.0
+   ```
+
+## License
+MIT
+

mcp_vulnerabilities-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-vulnerabilities"
+version = "1.0.0"
+description = "Open-Source OSV-Compliant Model Context Protocol (MCP) Vulnerability Advisory Database"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "packaging>=24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+mcp-vuln = "mcp_vulnerabilities.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_vulnerabilities-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_vulnerabilities-1.0.0/src/mcp_vulnerabilities/__init__.py

@@ -0,0 +1,51 @@
+"""Open Source Vulnerability (OSV v1.6.0) ingestion and normalization engine."""
+
+from mcp_vulnerabilities.converters.ghsa import GhsaConverter
+from mcp_vulnerabilities.converters.markdown_cve import MarkdownAdvisoryConverter
+from mcp_vulnerabilities.converters.nvd import NvdConverter
+from mcp_vulnerabilities.converters.osv_dev import OsvDevConverter
+from mcp_vulnerabilities.converters.verity import VerityCatalogConverter
+from mcp_vulnerabilities.deduplicator import OsvDeduplicator
+from mcp_vulnerabilities.models import (
+    AffectedPackage,
+    DatabaseSpecificMcp,
+    EventSpec,
+    OsvVulnerability,
+    PackageSpec,
+    RangeSpec,
+    RangeType,
+    ReferenceSpec,
+    ReferenceType,
+    SeveritySpec,
+    SeverityType,
+    build_purl,
+    parse_purl,
+)
+from mcp_vulnerabilities.pipeline import McpVulnerabilityPipeline, PipelineResult
+from mcp_vulnerabilities.validator import OsvValidationError, OsvValidator
+
+__all__ = [
+    "AffectedPackage",
+    "DatabaseSpecificMcp",
+    "EventSpec",
+    "GhsaConverter",
+    "MarkdownAdvisoryConverter",
+    "McpVulnerabilityPipeline",
+    "NvdConverter",
+    "OsvDeduplicator",
+    "OsvDevConverter",
+    "OsvValidationError",
+    "OsvValidator",
+    "OsvVulnerability",
+    "PackageSpec",
+    "PipelineResult",
+    "RangeSpec",
+    "RangeType",
+    "ReferenceSpec",
+    "ReferenceType",
+    "SeveritySpec",
+    "SeverityType",
+    "VerityCatalogConverter",
+    "build_purl",
+    "parse_purl",
+]

mcp_vulnerabilities-1.0.0/src/mcp_vulnerabilities/audit/__init__.py

@@ -0,0 +1,14 @@
+"""Audit subpackage for MCP client configs and installed packages."""
+
+from .fixer import ClientConfigFixer
+from .matcher import AuditFinding, AuditReport, VulnerabilityMatcher
+from .parsers import ClientConfigParser, DiscoveredClientServer
+
+__all__ = [
+    "AuditFinding",
+    "AuditReport",
+    "ClientConfigFixer",
+    "ClientConfigParser",
+    "DiscoveredClientServer",
+    "VulnerabilityMatcher",
+]

mcp_vulnerabilities-1.0.0/src/mcp_vulnerabilities/audit/fixer.py

@@ -0,0 +1,164 @@
+"""Automated remediation for vulnerable MCP servers in client configurations."""
+
+import json
+import logging
+import os
+import re
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+from .matcher import VulnerabilityMatcher, AuditFinding
+from .parsers import ClientConfigParser
+
+logger = logging.getLogger(__name__)
+
+
+class ClientConfigFixer:
+    """Identifies and remediates vulnerable MCP servers in client configurations."""
+
+    def __init__(self, matcher: VulnerabilityMatcher):
+        self.matcher = matcher
+
+    def _calculate_minimum_safe_version(self, findings: list[AuditFinding]) -> str | None:
+        """Calculates the highest fixed version among all findings."""
+        if not findings:
+            return None
+
+        max_version: Version | None = None
+        best_version_str: str | None = None
+
+        for f in findings:
+            if not f.fixed_version:
+                continue
+
+            try:
+                v = Version(f.fixed_version)
+                if max_version is None or v > max_version:
+                    max_version = v
+                    best_version_str = f.fixed_version
+            except InvalidVersion:
+                # If we can't parse semver, just take the first one or continue
+                if max_version is None:
+                    best_version_str = f.fixed_version
+
+        return best_version_str
+
+    def fix_config(self, config_path: Path, dry_run: bool = False) -> dict[str, Any]:
+        """Fixes a client configuration file by replacing vulnerable versions."""
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {config_path}")
+
+        servers = ClientConfigParser.parse_file(config_path)
+        with open(config_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        report = self.matcher.audit_servers(servers)
+        
+        # Group findings by server name
+        findings_by_server: dict[str, list[AuditFinding]] = {}
+        for f in report.findings:
+            findings_by_server.setdefault(f.server_name, []).append(f)
+
+        changes_made = []
+        
+        # We need to find the specific mcpServers key or use root
+        raw_servers = data.get("mcpServers") or data.get("mcp_servers") or data.get("servers")
+        
+        
+        if not isinstance(raw_servers, dict):
+            if all(isinstance(v, dict) and ("command" in v or "args" in v) for v in data.values()):
+                raw_servers = data
+                
+            else:
+                return {"status": "no_servers_found"}
+
+        for server in servers:
+            findings = findings_by_server.get(server.server_name)
+            if not findings:
+                continue
+                
+            safe_version = self._calculate_minimum_safe_version(findings)
+            if not safe_version:
+                logger.warning(f"No safe version found for {server.server_name}, skipping.")
+                continue
+                
+            # If the current version is already >= safe_version (e.g. unpinned), skip
+            try:
+                if server.version and Version(server.version) >= Version(safe_version):
+                    continue
+            except InvalidVersion:
+                pass
+
+            old_version = server.version or "unpinned"
+            
+            # Find the args in the original dict
+            srv_dict = raw_servers.get(server.server_name)
+            if not srv_dict or not isinstance(srv_dict, dict):
+                continue
+                
+            args = srv_dict.get("args", [])
+            new_args = list(args)
+            
+            # We need to rewrite the args
+            # Simple approach: find the arg that contains the package name and old version
+            for i, arg in enumerate(new_args):
+                if server.package_name in str(arg):
+                    # Rewrite this arg based on ecosystem
+                    if server.ecosystem == "npm":
+                        if "@" in server.package_name and server.package_name.startswith("@"):
+                            # scoped package
+                            new_args[i] = f"{server.package_name}@{safe_version}"
+                        else:
+                            new_args[i] = f"{server.package_name}@{safe_version}"
+                    elif server.ecosystem == "PyPI":
+                        # We use == for pipx/uvx
+                        if "==" in arg or ">=" in arg:
+                            new_args[i] = re.sub(r"(==|>=|<=|>|<|~=|@).*", f"=={safe_version}", arg)
+                        else:
+                            new_args[i] = f"{arg}=={safe_version}"
+                    elif server.ecosystem == "Docker":
+                        if ":" in arg:
+                            pkg = arg.rsplit(":", 1)[0]
+                            new_args[i] = f"{pkg}:{safe_version}"
+                        else:
+                            new_args[i] = f"{arg}:{safe_version}"
+                    break
+            
+            srv_dict["args"] = new_args
+            changes_made.append({
+                "server_name": server.server_name,
+                "package_name": server.package_name,
+                "old_version": old_version,
+                "new_version": safe_version
+            })
+
+        if not changes_made:
+            return {"status": "no_changes_needed", "changes": []}
+
+        if not dry_run:
+            timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+            backup_path = config_path.with_name(f"{config_path.name}.bak.{timestamp}")
+            shutil.copy2(config_path, backup_path)
+            
+            # Atomically write
+            tmp_path = config_path.with_name(f"{config_path.name}.tmp")
+            with open(tmp_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+                f.write("\n")
+            os.replace(tmp_path, config_path)
+            
+            return {
+                "status": "success",
+                "changes": changes_made,
+                "backup_path": str(backup_path)
+            }
+        
+        return {
+            "status": "dry_run",
+            "changes": changes_made
+        }
+