mcphound 0.1.0__py3-none-any.whl

mcphound/__init__.py

@@ -0,0 +1,3 @@
+"""mcphound — security scanner for MCP servers and agent skills."""
+
+__version__ = "0.1.0"

mcphound/cli.py

@@ -0,0 +1,115 @@
+"""mcphound CLI — scan and inspect MCP configurations without executing servers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .discovery.clients import discover_configs, load_servers
+from .models import SEVERITY_ORDER, ScanResult
+from .output import to_json, to_sarif
+from .rules.engine import evaluate
+from .rules.loader import load_rules
+
+app = typer.Typer(
+    add_completion=False,
+    help="mcphound — security scanner for MCP servers and agent skills.",
+)
+
+
+def _collect(paths: list[Path] | None, deep: bool = False) -> ScanResult:
+    config_paths = paths or discover_configs()
+    servers = []
+    for p in config_paths:
+        if p.exists():
+            servers.extend(load_servers(p))
+    rules = load_rules()
+    if not deep:
+        rules = [r for r in rules if not r.get("network")]
+    findings = []
+    for server in servers:
+        findings.extend(evaluate(server, rules))
+    return ScanResult(
+        targets=[str(p) for p in config_paths],
+        servers=servers,
+        findings=findings,
+    )
+
+
+@app.command()
+def inspect(
+    config: Annotated[
+        Path | None, typer.Argument(help="Config file; defaults to auto-discovery")
+    ] = None,
+):
+    """List configured MCP servers WITHOUT executing them."""
+    paths = [config] if config else discover_configs()
+    existing = [p for p in paths if p.exists()]
+    if not existing:
+        typer.echo("No MCP configurations found.")
+        raise typer.Exit(0)
+    for p in existing:
+        typer.echo(f"\n# {p}")
+        for s in load_servers(p):
+            detail = s.url if s.transport == "http" else " ".join(s.command)
+            typer.echo(f"  {s.name:<20} {s.transport:<6} {detail}")
+
+
+@app.command()
+def scan(
+    config: Annotated[
+        list[Path] | None, typer.Argument(help="Config file(s); defaults to auto-discovery")
+    ] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output")] = False,
+    sarif: Annotated[
+        bool, typer.Option("--sarif", help="SARIF 2.1.0 output for code scanning")
+    ] = False,
+    fail_on: Annotated[
+        str | None,
+        typer.Option("--fail-on", help="Exit 1 on finding >= severity (low|medium|high|critical)"),
+    ] = None,
+    deep: Annotated[
+        bool,
+        typer.Option(
+            "--deep",
+            help="Also run network-dependent checks (e.g. npm registry provenance). "
+            "Slower and not fully deterministic offline; off by default.",
+        ),
+    ] = False,
+    output: Annotated[
+        Path | None,
+        typer.Option("-o", "--output", help="Write output to this file instead of stdout"),
+    ] = None,
+):
+    """Scan MCP configurations for security issues (static analysis only)."""
+    result = _collect(config, deep=deep)
+
+    if sarif:
+        text = json.dumps(to_sarif(result), indent=2)
+    elif as_json:
+        text = to_json(result)
+    else:
+        lines = [f"Scanned {len(result.servers)} server(s) from {len(result.targets)} config(s)."]
+        for f in result.findings:
+            lines.append(
+                f"  [{f.severity.upper():<8}] {f.rule_id:<16} {f.server or '-':<16} {f.title}"
+            )
+        if not result.findings:
+            lines.append("  No findings.")
+        text = "\n".join(lines)
+
+    if output:
+        output.write_text(text + "\n", encoding="utf-8")
+    else:
+        typer.echo(text)
+
+    if fail_on and fail_on in SEVERITY_ORDER:
+        if any(SEVERITY_ORDER[f.severity] >= SEVERITY_ORDER[fail_on] for f in result.findings):
+            raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

mcphound/discovery/clients.py

@@ -0,0 +1,167 @@
+"""Discover and parse MCP client configurations.
+
+Supports the config shapes used by Claude Desktop / Claude Code (.mcp.json, ~/.claude.json),
+Cursor, Windsurf, Gemini CLI, and OpenCode (opencode.json/jsonc, which uses the "mcp" key
+and "local"/"remote" type names).
+
+PARSING ONLY — this module never executes a server.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shlex
+from pathlib import Path
+
+from ..models import ServerConfig
+
+HOME = Path.home()
+
+
+def _user_config_paths() -> list[Path]:
+    paths = [
+        HOME / ".claude.json",
+        HOME / ".mcp.json",
+        HOME / ".cursor" / "mcp.json",
+        HOME / ".codeium" / "windsurf" / "mcp_config.json",
+        HOME / ".gemini" / "mcp.json",
+        HOME / ".config" / "opencode" / "opencode.json",
+    ]
+    if platform.system() == "Darwin":
+        paths.append(HOME / "Library/Application Support/Claude/claude_desktop_config.json")
+    elif platform.system() == "Windows":
+        appdata = os.environ.get("APPDATA", "")
+        if appdata:
+            paths.append(Path(appdata) / "Claude" / "claude_desktop_config.json")
+    return paths
+
+
+def discover_configs() -> list[Path]:
+    """Project configs first, then user-level configs; only existing files."""
+    project_local = [
+        Path.cwd() / ".mcp.json",
+        Path.cwd() / "opencode.json",
+        Path.cwd() / "opencode.jsonc",
+    ]
+    return [p for p in project_local + _user_config_paths() if p.exists()]
+
+
+def _strip_jsonc(text: str) -> str:
+    """Remove // and /* */ comments from JSONC, preserving string contents."""
+    out = []
+    i = 0
+    n = len(text)
+    in_string = False
+    escape = False
+    while i < n:
+        ch = text[i]
+        if in_string:
+            out.append(ch)
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            i += 1
+            continue
+        # not in string
+        if ch == '"':
+            in_string = True
+            out.append(ch)
+            i += 1
+            continue
+        if ch == "/" and i + 1 < n:
+            nxt = text[i + 1]
+            if nxt == "/":
+                while i < n and text[i] != "\n":
+                    i += 1
+                continue
+            if nxt == "*":
+                i += 2
+                while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                    i += 1
+                i += 2
+                continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _strip_trailing_commas(text: str) -> str:
+    """Remove trailing commas before } or ] (JSONC/JSON5 allows them; json.loads doesn't)."""
+    out = []
+    i = 0
+    n = len(text)
+    in_string = False
+    escape = False
+    while i < n:
+        ch = text[i]
+        if in_string:
+            out.append(ch)
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            i += 1
+            continue
+        if ch == '"':
+            in_string = True
+            out.append(ch)
+            i += 1
+            continue
+        if ch == ",":
+            j = i + 1
+            while j < n and text[j] in " \t\r\n":
+                j += 1
+            if j < n and text[j] in "}]":
+                i += 1
+                continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _as_command_list(entry: dict) -> list[str]:
+    cmd = entry.get("command")
+    args = [str(a) for a in entry.get("args", [])]
+    if isinstance(cmd, list):
+        return [str(x) for x in cmd] + args
+    if isinstance(cmd, str):
+        parts = shlex.split(cmd)
+        parts.extend(args)
+        return parts
+    return args
+
+
+def load_servers(path: Path) -> list[ServerConfig]:
+    text = path.read_text()
+    if path.suffix == ".jsonc":
+        text = _strip_jsonc(text)
+        text = _strip_trailing_commas(text)
+    data = json.loads(text)
+
+    raw_servers = data.get("mcpServers") or data.get("mcp") or {}
+    servers: list[ServerConfig] = []
+    for name, entry in raw_servers.items():
+        if not isinstance(entry, dict) or entry.get("enabled") is False:
+            continue
+        raw_type = entry.get("type", "http" if entry.get("url") else "stdio")
+        transport = "http" if raw_type in ("http", "remote", "sse", "streamable-http") else "stdio"
+        env = entry.get("env") or entry.get("environment") or {}
+        servers.append(
+            ServerConfig(
+                name=name,
+                transport=transport,
+                command=_as_command_list(entry),
+                url=entry.get("url"),
+                env={str(k): str(v) for k, v in env.items()},
+                source=str(path),
+                raw=entry,
+            )
+        )
+    return servers

mcphound/models.py

@@ -0,0 +1,39 @@
+"""Core data models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+SEVERITIES = ("low", "medium", "high", "critical")
+SEVERITY_ORDER = {"low": 1, "medium": 2, "high": 3, "critical": 4}
+
+
+class ServerConfig(BaseModel):
+    """One MCP server entry parsed from a client config file."""
+
+    name: str
+    transport: str = "stdio"  # "stdio" | "http"
+    command: list[str] = Field(default_factory=list)
+    url: str | None = None
+    env: dict[str, str] = Field(default_factory=dict)
+    source: str = ""  # config file path it came from
+    raw: dict = Field(default_factory=dict)
+
+
+class Finding(BaseModel):
+    rule_id: str
+    title: str
+    severity: str
+    confidence: str = "medium"
+    owasp: str = ""  # LLMxx (OWASP LLM Top 10) or ASTxx (Agentic/MCP Top 10)
+    phase: str = "static"  # static | dynamic
+    server: str | None = None
+    location: str = ""
+    detail: str = ""
+    recommendation: str = ""
+
+
+class ScanResult(BaseModel):
+    targets: list[str] = Field(default_factory=list)
+    servers: list[ServerConfig] = Field(default_factory=list)
+    findings: list[Finding] = Field(default_factory=list)

mcphound/output.py

@@ -0,0 +1,68 @@
+"""Output formatters: JSON and SARIF 2.1.0 (GitHub code scanning)."""
+
+from __future__ import annotations
+
+from .models import ScanResult
+
+_SARIF_LEVEL = {"low": "note", "medium": "warning", "high": "error", "critical": "error"}
+_INFORMATION_URI = "https://github.com/markdoyle4312-hash/mcphound"
+# GitHub's code-scanning ingestion requires security-severity to be a
+# stringified CVSS-like score, not the severity word — see
+# https://docs.github.com/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#security-severity
+_SECURITY_SEVERITY = {"low": "2.5", "medium": "5.5", "high": "7.5", "critical": "9.5"}
+
+
+def to_json(result: ScanResult) -> str:
+    return result.model_dump_json(indent=2)
+
+
+def _artifact_uri(location: str) -> str:
+    # location is "<config path> :: <server name>", built for human display
+    # (see rules/engine.py); SARIF's artifactLocation.uri must be a URI, so
+    # take just the path and normalize Windows separators.
+    path = location.split(" :: ", 1)[0] or "config"
+    return path.replace("\\", "/")
+
+
+def to_sarif(result: ScanResult) -> dict:
+    rules: dict[str, dict] = {}
+    sarif_results: list[dict] = []
+    for f in result.findings:
+        rules.setdefault(
+            f.rule_id,
+            {
+                "id": f.rule_id,
+                "name": f.title,
+                "shortDescription": {"text": f.title},
+                "properties": {
+                    "security-severity": _SECURITY_SEVERITY.get(f.severity, "5.5"),
+                    "owasp": f.owasp,
+                },
+            },
+        )
+        sarif_results.append(
+            {
+                "ruleId": f.rule_id,
+                "level": _SARIF_LEVEL.get(f.severity, "warning"),
+                "message": {"text": f"{f.title} ({f.server}) — {f.detail}"},
+                "locations": [
+                    {"physicalLocation": {"artifactLocation": {"uri": _artifact_uri(f.location)}}}
+                ],
+            }
+        )
+    return {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "mcphound",
+                        "informationUri": _INFORMATION_URI,
+                        "rules": list(rules.values()),
+                    }
+                },
+                "results": sarif_results,
+            }
+        ],
+    }

mcphound/rules/MCP-STATIC-001.yaml

@@ -0,0 +1,17 @@
+id: MCP-STATIC-001
+title: Hardcoded secret in MCP server environment
+owasp: LLM02          # Sensitive Information Disclosure
+phase: static
+severity: high
+confidence: high
+description: >
+  A literal credential/token appears in an MCP server env block. Committed
+  credentials leak through git, CI logs, and shared machine configs. Use
+  environment variable expansion (${VAR}) instead.
+detect:
+  target: env
+  pattern: '(?i)(api[_-]?key|secret|token|password)\s*[=:]\s*["'']?(sk-[a-z0-9]{12,}|xox[baprs]-[a-z0-9-]{10,}|gh[pousr]_[A-Za-z0-9]{20,}|[A-Za-z0-9]{32,})'
+  allow_if: '${'          # ${ENV_VAR} expansion is the allowed pattern
+recommendation: Replace with "${VAR}" expansion; rotate the leaked credential; add gitleaks.
+references:
+  - https://www.owasp.org/index.php/OWASP_Top_10_for_LLM_Applications

mcphound/rules/MCP-STATIC-002.yaml

@@ -0,0 +1,16 @@
+id: MCP-STATIC-002
+title: Remote code download-and-execute in launch command
+owasp: AST04          # Supply chain: malicious/unsigned tooling
+phase: static
+severity: critical
+confidence: high
+description: >
+  The server launch command pipes a remote download straight into a shell
+  (curl|sh / wget|sh), executing unversioned remote code at every startup —
+  the rug-pull / supply-chain kill chain in one line.
+detect:
+  target: command
+  pattern: '(curl|wget)\s+[^|]+\|\s*(sh|bash|zsh)'
+recommendation: Install a pinned package from a registry; vendor the script; verify signatures.
+references:
+  - https://labs.cloudsecurityalliance.org/research/csa-research-note-mcp-tool-poisoning-auto-execution-20260701/

mcphound/rules/MCP-STATIC-003.yaml

@@ -0,0 +1,17 @@
+id: MCP-STATIC-003
+title: Over-broad host/filesystem permissions in launch command
+owasp: LLM08          # Excessive Agency
+phase: static
+severity: high
+confidence: medium
+description: >
+  The server launch command requests host-level or filesystem-root access
+  (privileged containers, host networking, root volume mounts, disabled
+  browser sandboxing, or a bare "/" path argument) — violating least-privilege
+  and giving a compromised server full host reach instead of a scoped one.
+detect:
+  target: command
+  pattern: '(?i)(--privileged\b|--network[=\s]+host\b|--cap-add[=\s]+all\b|-v\s+/:/|--no-sandbox\b|(?:^|\s)/(?:\s|$))'
+recommendation: Scope volume mounts/paths to the minimum directory needed, drop --privileged/--network=host/--cap-add=ALL, and keep browser sandboxing enabled.
+references:
+  - https://labs.cloudsecurityalliance.org/agentic/agentic-mcp-security-best-practices-v1/

mcphound/rules/MCP-STATIC-004.yaml

@@ -0,0 +1,17 @@
+id: MCP-STATIC-004
+title: Unpinned or @latest package version in launch command
+owasp: AST04          # Supply chain: malicious/unsigned tooling
+phase: static
+severity: medium
+confidence: medium
+description: >
+  An npx/uvx launch command references a package with no version pin (or the
+  mutable "@latest" tag). The exact code that runs can change between
+  invocations without review — the same rug-pull risk class as unsigned
+  install scripts, just via registry mutation instead of a script.
+detect:
+  target: command
+  pattern: '(?i)\b(?:npx|uvx)\s+(?:-y\s+)?(?P<pkg>@?[\w][\w./-]*)(?!\S*@\d)'
+recommendation: Pin an exact version, e.g. "npx -y pkg@1.2.3"; bump deliberately and note the bump in the commit message.
+references:
+  - https://labs.cloudsecurityalliance.org/research/csa-research-note-mcp-tool-poisoning-auto-execution-20260701/

mcphound/rules/MCP-STATIC-005.yaml

@@ -0,0 +1,18 @@
+id: MCP-STATIC-005
+title: Tool-description injection markers in server config
+owasp: LLM01          # Prompt Injection
+phase: static
+severity: critical
+confidence: medium
+description: >
+  The server's config entry contains hidden HTML/XML comment blocks, zero-width
+  Unicode characters, or exfiltration-imperative phrasing ("ignore previous
+  instructions", "send ... to", "do not tell the user"). These are the
+  documented tool-poisoning markers used to plant instructions a human
+  reviewer won't see but an LLM reading the tool/description text will.
+detect:
+  target: raw
+  pattern: "(?i)([\\u200b\\u200c\\u200d\\ufeff\\u2060]|<!--[\\s\\S]*?-->|ignore\\s+(?:all\\s+)?previous\\s+instructions|do\\s+not\\s+tell\\s+the\\s+user|without\\s+(?:informing|telling)\\s+the\\s+user|send\\s+(?:this|it|the\\s+\\w+)\\s+to\\s+)"
+recommendation: Remove hidden/zero-width content and imperative phrasing from server metadata; review the server's actual tool descriptions via the MCP Inspector before trusting it.
+references:
+  - https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks

mcphound/rules/MCP-STATIC-006.yaml

@@ -0,0 +1,19 @@
+id: MCP-STATIC-006
+title: Typosquat of a known MCP server package name
+owasp: AST04          # Supply chain: malicious/unsigned tooling
+phase: static
+severity: high
+confidence: medium
+description: >
+  The npx/uvx package name launched by this server is one or two edits away
+  from a well-known legitimate MCP server package, but not an exact match —
+  the classic typosquat pattern (extra/missing/transposed characters) used to
+  trick installers into running a lookalike package instead of the real one.
+detect:
+  type: typosquat
+  target: command
+  reference_list: known_servers.yaml
+  max_distance: 2
+recommendation: Double-check the exact package name against the official registry/npm page before installing; pin the verified name and version.
+references:
+  - https://appsentinels.ai/blog/mcp-supply-chain-security-how-malicious-mcp-servers-are-infiltrating-enterprise-ai-environments/

mcphound/rules/MCP-STATIC-007.yaml

@@ -0,0 +1,19 @@
+id: MCP-STATIC-007
+title: npm package has no discoverable source repository
+owasp: AST04          # Supply chain: malicious/unsigned tooling
+phase: static
+network: true          # queries registry.npmjs.org — opt-in via `mcphound scan --deep`
+severity: medium
+confidence: low
+description: >
+  The npx-launched package's npm registry metadata has no "repository" field —
+  there's no public source to audit, review, or diff against a future version.
+  ~15% of registry MCP servers ship with no source repo (Nimblebrain, 2026).
+  A missing repo isn't proof of malice (small/private packages omit it too),
+  so this is a low-confidence signal, not a hard block.
+detect:
+  type: npm_provenance
+  target: command
+recommendation: Prefer packages with a public, reviewable source repository; if you maintain this package, add a "repository" field to package.json.
+references:
+  - https://nimblebrain.ai/mcp/mcp-security/state-of-mcp-security/

mcphound/rules/data/known_servers.yaml

@@ -0,0 +1,13 @@
+# Seed list of well-known, legitimate MCP server package names, used only by
+# MCP-STATIC-006's typosquat check. This is NOT the official registry — it's a
+# small bundled list so the check works fully offline and deterministically.
+# The Phase 2 registry poller (ROADMAP.md) will eventually supersede this with
+# live, comprehensive registry data.
+- "@modelcontextprotocol/server-filesystem"
+- "@modelcontextprotocol/server-postgres"
+- "@modelcontextprotocol/server-everything"
+- "@modelcontextprotocol/server-sqlite"
+- "@upstash/context7-mcp"
+- "@playwright/mcp"
+- "@google/mcp-server"
+- "mcp-server-sqlite"

mcphound/rules/engine.py

@@ -0,0 +1,176 @@
+"""Evaluate detection rules against parsed server configurations.
+
+Static rules only at this stage. A rule's `detect` block is one of two shapes:
+
+  Regex (default, `type` omitted):
+    target: command | url | env | raw      (which text to inspect)
+    pattern: <regex>
+    allow_if: <substring>                  (skip match when present on the matched line,
+                                            e.g. "${" to allow env-var expansion)
+
+  Typosquat (`type: typosquat`) — needs edit-distance, not a regex, so it has
+  dedicated engine support rather than being pure YAML data:
+    type: typosquat
+    target: command                        (only "command" is supported today)
+    reference_list: <file under rules/data/>   (YAML list of known-legitimate package names)
+    max_distance: <int>                    (flag names within this Levenshtein distance
+                                            of a reference name, but not an exact match)
+
+  npm provenance (`type: npm_provenance`) — queries the public npm registry, so it
+  is NOT part of the default free scan (GOVERNANCE.md: network-dependent checks
+  must be marked and separable). Any rule using it MUST also set `network: true`;
+  `cli.py` filters such rules out unless `--deep` is passed:
+    type: npm_provenance
+    target: command                        (only npx-launched packages are checked)
+
+One finding per rule per server (first match wins).
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import re
+from pathlib import Path
+
+import httpx
+import yaml
+from rapidfuzz.distance import Levenshtein
+
+from ..models import Finding, ServerConfig
+
+_DATA_DIR = Path(__file__).parent / "data"
+_NPM_TIMEOUT = 5.0
+
+
+def _target_text(server: ServerConfig, target: str) -> str:
+    if target == "command":
+        return " ".join(server.command)
+    if target == "url":
+        return server.url or ""
+    if target == "env":
+        return "\n".join(f"{k}={v}" for k, v in server.env.items())
+    return json.dumps(server.raw, sort_keys=True, ensure_ascii=False)
+
+
+def _make_finding(rule: dict, server: ServerConfig, detail: str) -> Finding:
+    return Finding(
+        rule_id=rule["id"],
+        title=rule.get("title", rule["id"]),
+        severity=rule.get("severity", "medium"),
+        confidence=rule.get("confidence", "medium"),
+        owasp=rule.get("owasp", ""),
+        phase="static",
+        server=server.name,
+        location=f"{server.source} :: {server.name}",
+        detail=detail[:160],
+        recommendation=rule.get("recommendation", ""),
+    )
+
+
+def _evaluate_regex(server: ServerConfig, rule: dict, detect: dict) -> list[Finding]:
+    pattern = detect.get("pattern")
+    if not pattern:
+        return []
+    text = _target_text(server, detect.get("target", "command"))
+    allow_if = detect.get("allow_if")
+    findings = []
+    for match in re.finditer(pattern, text, re.IGNORECASE | re.MULTILINE):
+        window = text[max(0, match.start() - 60) : match.end() + 60]
+        if allow_if and allow_if in window:
+            continue
+        findings.append(_make_finding(rule, server, match.group(0)))
+        break
+    return findings
+
+
+@functools.lru_cache
+def _load_reference_list(filename: str) -> tuple[str, ...]:
+    data = yaml.safe_load((_DATA_DIR / filename).read_text(encoding="utf-8"))
+    return tuple(data) if isinstance(data, list) else ()
+
+
+def _package_name(spec: str) -> str:
+    """Strip a trailing "@version" (or "@latest") from an npm-style package spec,
+    preserving a scoped package's own leading "@scope/" segment."""
+    if spec.startswith("@"):
+        slash = spec.find("/")
+        if slash == -1:
+            return spec
+        at = spec.find("@", slash)
+    else:
+        at = spec.find("@")
+    return spec[:at] if at != -1 else spec
+
+
+def _extract_command_package(server: ServerConfig) -> str | None:
+    tokens = server.command
+    for i, tok in enumerate(tokens):
+        if tok in ("npx", "uvx"):
+            for cand in tokens[i + 1 :]:
+                if cand.startswith("-"):
+                    continue
+                return _package_name(cand)
+    return None
+
+
+def _evaluate_typosquat(server: ServerConfig, rule: dict, detect: dict) -> list[Finding]:
+    pkg = _extract_command_package(server)
+    if not pkg:
+        return []
+    reference = _load_reference_list(detect.get("reference_list", ""))
+    if not reference or pkg in reference:
+        return []
+    max_distance = int(detect.get("max_distance", 2))
+    best = min(reference, key=lambda ref: Levenshtein.distance(pkg, ref))
+    distance = Levenshtein.distance(pkg, best)
+    if distance == 0 or distance > max_distance:
+        return []
+    detail = f'"{pkg}" is {distance} edit(s) from known package "{best}"'
+    return [_make_finding(rule, server, detail)]
+
+
+def _fetch_npm_metadata(pkg: str) -> dict | None:
+    """Isolated so tests can monkeypatch it instead of hitting the real registry."""
+    try:
+        resp = httpx.get(f"https://registry.npmjs.org/{pkg}", timeout=_NPM_TIMEOUT)
+        resp.raise_for_status()
+        return resp.json()
+    except httpx.HTTPError:
+        return None
+
+
+def _evaluate_npm_provenance(server: ServerConfig, rule: dict, detect: dict) -> list[Finding]:
+    if "npx" not in server.command:
+        return []
+    pkg = _extract_command_package(server)
+    if not pkg:
+        return []
+    meta = _fetch_npm_metadata(pkg)
+    if meta is None:
+        # Network error or unknown package: no data to judge on, so no finding —
+        # never let a provenance check fail closed against an offline/rate-limited registry.
+        return []
+    latest = meta.get("dist-tags", {}).get("latest")
+    version_info = meta.get("versions", {}).get(latest, {}) if latest else {}
+    repo = version_info.get("repository") or meta.get("repository")
+    if repo:
+        return []
+    detail = f'npm package "{pkg}" has no repository field in its registry metadata'
+    return [_make_finding(rule, server, detail)]
+
+
+def evaluate(server: ServerConfig, rules: list[dict]) -> list[Finding]:
+    findings: list[Finding] = []
+    for rule in rules:
+        if rule.get("phase", "static") != "static":
+            continue
+        detect = rule.get("detect") or {}
+        detect_type = detect.get("type")
+        if detect_type == "typosquat":
+            findings.extend(_evaluate_typosquat(server, rule, detect))
+        elif detect_type == "npm_provenance":
+            findings.extend(_evaluate_npm_provenance(server, rule, detect))
+        else:
+            findings.extend(_evaluate_regex(server, rule, detect))
+    return findings

mcphound/rules/loader.py

@@ -0,0 +1,19 @@
+"""Load YAML detection rules from src/mcphound/rules/*.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+RULES_DIR = Path(__file__).parent
+
+
+def load_rules(rules_dir: Path | None = None) -> list[dict]:
+    rules_dir = rules_dir or RULES_DIR
+    rules: list[dict] = []
+    for path in sorted(rules_dir.glob("*.yaml")):
+        data = yaml.safe_load(path.read_text())
+        if isinstance(data, dict) and data.get("id"):
+            rules.append(data)
+    return rules

mcphound-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: mcphound
+Version: 0.1.0
+Summary: Independent security scanner and reputation layer for MCP servers and agent skills
+Project-URL: Homepage, https://github.com/markdoyle4312-hash/mcphound
+Project-URL: Repository, https://github.com/markdoyle4312-hash/mcphound
+Project-URL: Issues, https://github.com/markdoyle4312-hash/mcphound/issues
+Project-URL: Changelog, https://github.com/markdoyle4312-hash/mcphound/blob/main/CHANGELOG.md
+Author-email: marky-dooda08 <mark.doyle4312@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,mcp,sarif,security,supply-chain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rapidfuzz>=3.9
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcpvet
+
+Independent security scanner and reputation layer for MCP servers and agent skills.
+
+> Status: **pre-launch.** v0.1 = static CLI scanning. Reputation site/API and the GitHub Action follow per [ROADMAP.md](ROADMAP.md).
+
+mcpvet discovers the MCP servers configured in your AI coding clients (Claude Code/Desktop, Cursor, Windsurf, Gemini CLI, OpenCode) and checks them for supply-chain risks: hardcoded secrets, download-and-execute launch commands, over-broad permissions, pinned-version drift, and (in later versions) tool-description poisoning, typosquats, and runtime rug-pulls. Findings map to the OWASP Top 10 for LLM and Agentic applications and can be exported as SARIF into GitHub code scanning.
+
+## Why another scanner?
+
+Local scanning is covered by [mcp-scan](https://github.com/invariantlabs-ai/mcp-scan) / Snyk Agent Scan. mcpvet's job is the layers around it:
+
+1. A **public reputation database** — continuously scanned public registry, per-server risk pages and change history.
+2. **Org-level enforcement** — `mcp-policy.yaml` + GitHub Action that blocks risky MCP/skill changes in PRs.
+3. **Compliance reporting** — findings mapped to OWASP, EU AI Act, and (later) Australian ISM / Essential Eight / DISP controls.
+
+## Quickstart
+
+```bash
+# published on PyPI as "mcphound" (mcpvet and mcp-vet were both already
+# taken/rejected) — mcphound is also installed as the "mcpvet" command,
+# kept as a back-compat alias
+uvx mcphound inspect   # inspect what you have (never executes a server)
+uvx mcphound scan      # scan auto-discovered configs
+
+# or install once:
+# pip install mcphound / uv tool install mcphound
+
+# CI: fail on high/critical findings, emit SARIF
+mcphound scan .mcp.json --fail-on high --sarif -o mcphound.sarif
+
+# opt-in: also run network-dependent checks (npm registry provenance) — slower,
+# not fully deterministic offline, so it's off unless you ask for it
+mcphound scan --deep
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest -q          # tests
+uv run ruff check .       # lint
+make scan-self            # scan this repo's own agent configs (dogfood)
+```
+
+## Safety
+
+mcpvet static scanning **never executes** MCP servers. Dynamic analysis (post-v1) runs only inside the disposable, network-isolated sandbox in `sandbox/`. Every malicious test fixture carries the marker `MCPVET-FIXTURE-CANARY` and must never be referenced from agent configurations.
+
+## Authoring a detection rule
+
+Every rule ships with four artifacts: YAML rule, malicious fixture, benign fixture, pytest. See `.claude/skills/rule-authoring/SKILL.md` (or the two worked examples under `src/mcpvet/rules/` and `tests/`).
+
+## License
+
+Apache-2.0

mcphound-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+mcphound/__init__.py,sha256=KZ4wU1jcPvuDtSibm8YmjmQ3V6rzC1DGNOy7ioFwyYE,96
+mcphound/cli.py,sha256=IrrRQFbifXluxxy5-k4StK31YnqYGVKQWeP5N4OBDUE,3769
+mcphound/models.py,sha256=R0q9y5V-1SKhZL3_C4LQ0zpVXlmOZrQLeUhshL7itdE,1191
+mcphound/output.py,sha256=yeFSyWp3n550euEzjND0g39G1nFX2xGum98VciTXzQ4,2539
+mcphound/discovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcphound/discovery/clients.py,sha256=tDJBpjJwJ8Ars-wOcwbMNb86NxaIf1Oo0f8SRfslZTQ,5071
+mcphound/rules/MCP-STATIC-001.yaml,sha256=wYufYk-PUkV0bWbshF5tpGoc3BSwd9KEOKxY8n_dwOA,829
+mcphound/rules/MCP-STATIC-002.yaml,sha256=KimwV2d0m80QbZrME8E24vBH56YsSU2iVXHFZWrsvrY,728
+mcphound/rules/MCP-STATIC-003.yaml,sha256=j1Prp_raE7ezwhMMruNrvTkjpTanw3MStOck5tq4X3A,914
+mcphound/rules/MCP-STATIC-004.yaml,sha256=cDV9e3kH0KIjmCk7IFJVjEacAK1iyjoIY3B-TKFZDks,866
+mcphound/rules/MCP-STATIC-005.yaml,sha256=aLzLilO3haLj_RKVfwbOmXW6nRP2O4Q4cyQ6S8dwj-k,1118
+mcphound/rules/MCP-STATIC-006.yaml,sha256=jzB805GKxzXEUH9N8DTTZw2ucXhgnD-ttnBsasM-xtE,913
+mcphound/rules/MCP-STATIC-007.yaml,sha256=SwbgVr12QTV38hvw1cVLUi8vsVzJmkUEo5x1GiFU2hA,959
+mcphound/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcphound/rules/engine.py,sha256=Xao2xNa5VXF3l4f69ginydHIimEz5XsHDx87gbmu2Ac,6762
+mcphound/rules/loader.py,sha256=3VU7jsA-SLsV_9pRbTAnGaTr7tVVmm71hsxExtZpJFA,522
+mcphound/rules/data/known_servers.yaml,sha256=VmVGFYjbvJCFFnEYh5NssI0dkOK8p1HP0oeqL52ZAX8,625
+mcphound-0.1.0.dist-info/METADATA,sha256=sk0KTPH98rCsxAEUexjbOMdAphfAFkcBdPWg5JCYPxY,4030
+mcphound-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcphound-0.1.0.dist-info/entry_points.txt,sha256=ERL5p0-evBvIbcl5REIO0WEx_7VnoG1xyfuVZFSOw0k,72
+mcphound-0.1.0.dist-info/licenses/LICENSE,sha256=4r_lcf9CteSJthIVtn90N2tG8dYr-Xczy9XfhcDUsqs,11449
+mcphound-0.1.0.dist-info/RECORD,,

mcphound-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcphound-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mcphound = mcphound.cli:app
+mcpvet = mcphound.cli:app

mcphound-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,205 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 mcpvet contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   APPENDIX: Full Apache License 2.0 terms are available at
+   http://www.apache.org/licenses/LICENSE-2.0.txt and reproduced below.
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS