mcp-riskmap 0.1.2__py3-none-any.whl

mcp_riskmap/__init__.py

@@ -0,0 +1,5 @@
+"""Static MCP and agent-tool repository risk scanner."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.2"

mcp_riskmap/analyzers/__init__.py

@@ -0,0 +1 @@
+"""File analyzers used by the scanner."""

mcp_riskmap/analyzers/common.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SUPPRESSION_RE = re.compile(r"mcp-riskmap:\s*ignore(?:\s+([A-Z0-9_, -]+))?", re.IGNORECASE)
+
+
+def relative_path(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def is_suppressed(lines: list[str], line_index: int, rule_id: str) -> bool:
+    comment_lines = [lines[line_index]]
+    if line_index > 0:
+        comment_lines.append(lines[line_index - 1])
+    return any(_suppresses_rule(line, rule_id) for line in comment_lines)
+
+
+def _suppresses_rule(line: str, rule_id: str) -> bool:
+    match = SUPPRESSION_RE.search(line)
+    if not match:
+        return False
+    raw_rules = match.group(1)
+    if not raw_rules:
+        return True
+    rules = {rule.strip().upper() for rule in re.split(r"[,\s]+", raw_rules) if rule.strip()}
+    return "ALL" in rules or rule_id.upper() in rules

mcp_riskmap/analyzers/config.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from mcp_riskmap.analyzers.common import relative_path, read_text
+from mcp_riskmap.models import Finding
+
+CONFIG_NAMES = {
+    "mcp.json",
+    "mcp.config.json",
+    "claude_desktop_config.json",
+    "settings.json",
+}
+
+SECRET_KEY_RE = re.compile(r"(api[_-]?key|token|secret|password|credential)", re.IGNORECASE)
+
+
+def is_candidate(path: Path) -> bool:
+    return path.name.lower() in CONFIG_NAMES or ".mcp" in path.name.lower()
+
+
+def analyze_config(root: Path, path: Path) -> list[Finding]:
+    text = read_text(path)
+    if "mcpServers" not in text and "mcp_servers" not in text:
+        return []
+
+    findings: list[Finding] = []
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return findings
+
+    servers = _server_entries(data)
+    for server_name, server in servers:
+        command = str(server.get("command", ""))
+        args = [str(arg) for arg in server.get("args", [])]
+        command_line = " ".join([command, *args]).lower()
+        path_text = relative_path(root, path)
+
+        if _looks_like_shell_wrapper(command, args):
+            findings.append(
+                Finding(
+                    rule_id="MCP-CONFIG-SHELL",
+                    title="MCP server starts through a shell wrapper",
+                    severity="high",
+                    message=f"MCP server '{server_name}' starts through a shell-capable command.",
+                    path=path_text,
+                    line=_line_for(text, command),
+                    remediation="Pin the server executable directly and avoid cmd, powershell, bash, or sh wrappers for untrusted configs.",
+                    evidence=" ".join([command, *args])[:240],
+                )
+            )
+
+        if "curl " in command_line and ("| sh" in command_line or "| iex" in command_line):
+            findings.append(
+                Finding(
+                    rule_id="MCP-CONFIG-REMOTE-INSTALL",
+                    title="MCP config pipes remote content into an interpreter",
+                    severity="critical",
+                    message=f"MCP server '{server_name}' downloads and executes remote content.",
+                    path=path_text,
+                    line=_line_for(text, "curl"),
+                    remediation="Replace remote install pipelines with pinned packages, checksums, or reviewed local scripts.",
+                    evidence=" ".join([command, *args])[:240],
+                )
+            )
+
+        env = server.get("env")
+        if isinstance(env, dict):
+            secret_keys = sorted(key for key in env if SECRET_KEY_RE.search(str(key)))
+            if secret_keys:
+                findings.append(
+                    Finding(
+                        rule_id="MCP-CONFIG-SECRET-ENV",
+                        title="MCP config passes secret-like environment variables",
+                        severity="medium",
+                        message=f"MCP server '{server_name}' passes secret-like environment keys: {', '.join(secret_keys)}.",
+                        path=path_text,
+                        line=_line_for(text, secret_keys[0]),
+                        remediation="Pass only the minimum required environment variables and document why each secret is needed.",
+                        evidence=", ".join(secret_keys),
+                    )
+                )
+
+        if command.lower() == "npx" and any(arg == "-y" for arg in args):
+            findings.append(
+                Finding(
+                    rule_id="MCP-CONFIG-NPX-LATEST",
+                    title="MCP config allows non-interactive npx package execution",
+                    severity="medium",
+                    message=f"MCP server '{server_name}' runs npx with automatic yes.",
+                    path=path_text,
+                    line=_line_for(text, "npx"),
+                    remediation="Pin package versions and review the resolved package before using npx -y in shared configs.",
+                    evidence=" ".join([command, *args])[:240],
+                )
+            )
+
+    return findings
+
+
+def _server_entries(data: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
+    servers = data.get("mcpServers") or data.get("mcp_servers") or {}
+    if not isinstance(servers, dict):
+        return []
+    return [(str(name), server) for name, server in servers.items() if isinstance(server, dict)]
+
+
+def _looks_like_shell_wrapper(command: str, args: list[str]) -> bool:
+    shell_commands = {"cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "bash", "sh"}
+    if Path(command).name.lower() in shell_commands:
+        return True
+    shell_flags = {"/c", "-c", "-command", "/command"}
+    return any(arg.lower() in shell_flags for arg in args)
+
+
+def _line_for(text: str, needle: str) -> int:
+    for index, line in enumerate(text.splitlines(), start=1):
+        if needle and needle in line:
+            return index
+    return 1

mcp_riskmap/analyzers/js_source.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp_riskmap.analyzers.common import is_suppressed, relative_path, read_text
+from mcp_riskmap.models import Finding
+
+
+def analyze_javascript(root: Path, path: Path) -> list[Finding]:
+    text = read_text(path)
+    rel = relative_path(root, path)
+    child_process_context = "child_process" in text or "node:child_process" in text
+    findings: list[Finding] = []
+
+    lines = text.splitlines()
+    for line_index, line in enumerate(lines):
+        line_number = line_index + 1
+        stripped = line.strip()
+        if not stripped or stripped.startswith("//"):
+            continue
+
+        # mcp-riskmap: ignore PY-EVAL-EXEC
+        if child_process_context and ("exec(" in stripped or ".exec(" in stripped) and not is_suppressed(lines, line_index, "JS-CHILD-PROCESS-EXEC"):
+            findings.append(
+                Finding(
+                    rule_id="JS-CHILD-PROCESS-EXEC",
+                    title="JavaScript tool invokes child_process.exec",
+                    severity="high",
+                    message="A JavaScript tool handler can pass input through a shell.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Use execFile or spawn with an argument array and validate allowed commands.",
+                    evidence=stripped[:240],
+                )
+            )
+
+        if "spawn(" in stripped and "shell: true" in stripped and not is_suppressed(lines, line_index, "JS-SPAWN-SHELL"):
+            findings.append(
+                Finding(
+                    rule_id="JS-SPAWN-SHELL",
+                    title="JavaScript tool invokes spawn with shell enabled",
+                    severity="high",
+                    message="A JavaScript tool handler enables shell execution.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Disable shell mode and pass command arguments as an array.",
+                    evidence=stripped[:240],
+                )
+            )
+
+        # mcp-riskmap: ignore TOOL-DESCRIPTION-INJECTION
+        if ("ignore previous" in stripped.lower() or "system prompt" in stripped.lower()) and not is_suppressed(lines, line_index, "TOOL-DESCRIPTION-INJECTION"):
+            findings.append(
+                Finding(
+                    rule_id="TOOL-DESCRIPTION-INJECTION",
+                    title="Tool text contains prompt-injection-like wording",
+                    severity="medium",
+                    message="Tool text includes phrases often used to override model instructions.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Keep tool descriptions factual and remove instructions that target the model control plane.",
+                    evidence=stripped[:240],
+                )
+            )
+
+    return findings

mcp_riskmap/analyzers/python_source.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from mcp_riskmap.analyzers.common import is_suppressed, relative_path, read_text
+from mcp_riskmap.models import Finding
+
+SHELL_TRUE_RE = re.compile(r"subprocess\.(run|call|Popen|check_call|check_output)\s*\([^)]*shell\s*=\s*True")
+EVAL_EXEC_RE = re.compile(r"\b(eval|exec)\s*\(")
+
+
+def analyze_python(root: Path, path: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    rel = relative_path(root, path)
+    lines = read_text(path).splitlines()
+    for line_index, line in enumerate(lines):
+        line_number = line_index + 1
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if SHELL_TRUE_RE.search(stripped) and not is_suppressed(lines, line_index, "PY-SHELL-TRUE"):
+            findings.append(
+                Finding(
+                    rule_id="PY-SHELL-TRUE",
+                    title="Python tool invokes subprocess with shell=True",
+                    severity="high",
+                    message="A Python tool handler can pass input through a shell.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Use subprocess with an argument list and validate allowed commands or paths before execution.",
+                    evidence=stripped[:240],
+                )
+            )
+
+        # mcp-riskmap: ignore PY-OS-SYSTEM
+        if "os.system(" in stripped and not is_suppressed(lines, line_index, "PY-OS-SYSTEM"):
+            findings.append(
+                Finding(
+                    rule_id="PY-OS-SYSTEM",
+                    title="Python tool invokes os.system",
+                    severity="high",
+                    message="A Python tool handler invokes a command through the system shell.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Replace os.system with subprocess argument lists and explicit allowlists.",
+                    evidence=stripped[:240],
+                )
+            )
+
+        if EVAL_EXEC_RE.search(stripped) and not is_suppressed(lines, line_index, "PY-EVAL-EXEC"):
+            findings.append(
+                Finding(
+                    rule_id="PY-EVAL-EXEC",
+                    title="Python tool evaluates dynamic code",
+                    severity="high",
+                    message="A Python tool handler uses eval or exec.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Replace dynamic evaluation with parsed data structures and explicit dispatch tables.",
+                    evidence=stripped[:240],
+                )
+            )
+
+        # mcp-riskmap: ignore TOOL-DESCRIPTION-INJECTION
+        if ("ignore previous" in stripped.lower() or "system prompt" in stripped.lower()) and not is_suppressed(lines, line_index, "TOOL-DESCRIPTION-INJECTION"):
+            findings.append(
+                Finding(
+                    rule_id="TOOL-DESCRIPTION-INJECTION",
+                    title="Tool text contains prompt-injection-like wording",
+                    severity="medium",
+                    message="Tool text includes phrases often used to override model instructions.",
+                    path=rel,
+                    line=line_number,
+                    remediation="Keep tool descriptions factual and remove instructions that target the model control plane.",
+                    evidence=stripped[:240],
+                )
+            )
+
+    return findings

mcp_riskmap/analyzers/repo_hygiene.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp_riskmap.models import Finding
+
+
+def analyze_repo_hygiene(root: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    checks = [
+        ("AGENTS.md", "REPO-MISSING-AGENTS", "Repository is missing AGENTS.md", "Add AGENTS.md with build, test, review, and security guidance for coding agents."),
+        ("SECURITY.md", "REPO-MISSING-SECURITY", "Repository is missing SECURITY.md", "Add SECURITY.md with vulnerability reporting and supported version guidance."),
+        ("LICENSE", "REPO-MISSING-LICENSE", "Repository is missing LICENSE", "Add an OSI-approved license such as MIT or Apache-2.0."),
+    ]
+    for filename, rule_id, title, remediation in checks:
+        if not (root / filename).exists() and not (root / f"{filename}.md").exists():
+            findings.append(
+                Finding(
+                    rule_id=rule_id,
+                    title=title,
+                    severity="low",
+                    message=title,
+                    path=".",
+                    line=1,
+                    remediation=remediation,
+                    evidence=filename,
+                )
+            )
+    return findings

mcp_riskmap/cli.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from mcp_riskmap import __version__
+from mcp_riskmap.models import SEVERITY_ORDER, ScanResult
+from mcp_riskmap.reporters.json_reporter import render_json
+from mcp_riskmap.reporters.markdown import render_markdown
+from mcp_riskmap.reporters.sarif import render_sarif
+from mcp_riskmap.reporters.table import render_table
+from mcp_riskmap.scanner import ScanInputError, scan_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.version:
+        print(f"mcp-riskmap {__version__}")
+        return 0
+    if args.command == "scan":
+        return _scan(args)
+    parser.print_help()
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcp-riskmap",
+        description="Static MCP and agent-tool repository risk scanner.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print the package version and exit.")
+    subparsers = parser.add_subparsers(dest="command")
+    scan = subparsers.add_parser("scan", help="Scan a repository or directory.")
+    scan.add_argument("path", nargs="?", default=".", help="Path to scan.")
+    scan.add_argument(
+        "--format",
+        choices=["table", "json", "markdown", "sarif"],
+        default="table",
+        help="Output format.",
+    )
+    scan.add_argument("--output", help="Write report to a file instead of stdout.")
+    scan.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        help="Exclude a relative path glob from scanning. Can be passed more than once.",
+    )
+    scan.add_argument(
+        "--fail-on",
+        choices=list(SEVERITY_ORDER),
+        help="Return exit code 1 when any finding is at or above this severity.",
+    )
+    return parser
+
+
+def _scan(args: argparse.Namespace) -> int:
+    try:
+        result = scan_path(args.path, exclude_patterns=args.exclude)
+    except ScanInputError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    rendered = render_result(result, args.format)
+    if args.output:
+        Path(args.output).write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+
+    if args.fail_on and result.count_at_or_above(args.fail_on):
+        return 1
+    return 0
+
+
+def render_result(result: ScanResult, report_format: str) -> str:
+    if report_format == "json":
+        return render_json(result)
+    if report_format == "markdown":
+        return render_markdown(result)
+    if report_format == "sarif":
+        return render_sarif(result)
+    return render_table(result)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

mcp_riskmap/models.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from mcp_riskmap.redaction import redact_text
+
+
+SEVERITY_ORDER = {
+    "info": 0,
+    "low": 1,
+    "medium": 2,
+    "high": 3,
+    "critical": 4,
+}
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    title: str
+    severity: str
+    message: str
+    path: str
+    line: int = 1
+    remediation: str = ""
+    evidence: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "rule_id": self.rule_id,
+            "title": self.title,
+            "severity": self.severity,
+            "message": self.message,
+            "path": self.path,
+            "line": self.line,
+            "remediation": self.remediation,
+            "evidence": redact_text(self.evidence),
+        }
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    root: Path
+    findings: list[Finding] = field(default_factory=list)
+
+    def count_at_or_above(self, severity: str) -> int:
+        threshold = SEVERITY_ORDER[severity]
+        return sum(1 for finding in self.findings if SEVERITY_ORDER[finding.severity] >= threshold)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "root": str(self.root),
+            "summary": {
+                "findings": len(self.findings),
+                "critical": self.count_at_or_above("critical"),
+                "high_or_above": self.count_at_or_above("high"),
+                "medium_or_above": self.count_at_or_above("medium"),
+            },
+            "findings": [finding.as_dict() for finding in self.findings],
+        }

mcp_riskmap/redaction.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import re
+
+SECRET_VALUE_RE = re.compile(
+    r"(?i)\b(token|api[_-]?key|secret|password|credential|authorization)\b"
+    r"(\s*[:=]\s*|/)"
+    r"([^\s&|,'\"]+)"
+)
+BEARER_RE = re.compile(r"(?i)\bbearer\s+[a-z0-9._~+/=-]{8,}")
+
+
+def redact_text(value: str) -> str:
+    if not value:
+        return value
+    redacted = SECRET_VALUE_RE.sub(lambda match: f"{match.group(1)}{match.group(2)}[REDACTED]", value)
+    redacted = BEARER_RE.sub("Bearer [REDACTED]", redacted)
+    return redacted

mcp_riskmap/reporters/__init__.py

@@ -0,0 +1 @@
+"""Report renderers for scan results."""

mcp_riskmap/reporters/json_reporter.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import json
+
+from mcp_riskmap.models import ScanResult
+
+
+def render_json(result: ScanResult) -> str:
+    return json.dumps(result.as_dict(), indent=2, sort_keys=True)

mcp_riskmap/reporters/markdown.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from mcp_riskmap.models import ScanResult
+
+
+def render_markdown(result: ScanResult) -> str:
+    lines = [
+        "# MCP Riskmap Report",
+        "",
+        f"- Root: `{result.root}`",
+        f"- Findings: {len(result.findings)}",
+        f"- High or above: {result.count_at_or_above('high')}",
+        "",
+    ]
+    if not result.findings:
+        lines.append("No findings.")
+        return "\n".join(lines)
+
+    lines.extend(["| Severity | Rule | Location | Message |", "| --- | --- | --- | --- |"])
+    for finding in result.findings:
+        location = f"{finding.path}:{finding.line}"
+        message = finding.message.replace("|", "\\|")
+        lines.append(f"| {finding.severity} | `{finding.rule_id}` | `{location}` | {message} |")
+
+    lines.extend(["", "## Remediation"])
+    for finding in result.findings:
+        lines.append(f"- `{finding.rule_id}` at `{finding.path}:{finding.line}`: {finding.remediation}")
+    return "\n".join(lines)

mcp_riskmap/reporters/sarif.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+from mcp_riskmap.models import ScanResult
+from mcp_riskmap.redaction import redact_text
+from mcp_riskmap.rules.registry import RULES
+
+
+def render_sarif(result: ScanResult) -> str:
+    rules = {}
+    sarif_results = []
+    for finding in result.findings:
+        metadata = RULES.metadata_for(finding.rule_id)
+        rules[finding.rule_id] = {
+            "id": finding.rule_id,
+            "name": finding.title,
+            "shortDescription": {"text": finding.title},
+            "fullDescription": {"text": finding.remediation or finding.message},
+            "helpUri": metadata.help_uri,
+            "help": {"text": metadata.description},
+            "defaultConfiguration": {"level": _level_for(finding.severity)},
+            "properties": {
+                "precision": metadata.precision,
+                "security-severity": metadata.security_severity,
+                "tags": list(metadata.tags),
+            },
+        }
+        fingerprint = _fingerprint_for(finding)
+        sarif_results.append(
+            {
+                "ruleId": finding.rule_id,
+                "level": _level_for(finding.severity),
+                "message": {"text": finding.message},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": finding.path},
+                            "region": {"startLine": max(finding.line, 1)},
+                        }
+                    }
+                ],
+                "partialFingerprints": {
+                    "primaryLocationLineHash": fingerprint,
+                },
+                "properties": {
+                    "severity": finding.severity,
+                    "evidence": redact_text(finding.evidence),
+                    "remediation": finding.remediation,
+                    "precision": metadata.precision,
+                    "security-severity": metadata.security_severity,
+                    "tags": list(metadata.tags),
+                },
+            }
+        )
+
+    sarif = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "mcp-riskmap",
+                        "informationUri": "https://github.com/vawkdh-job/mcp-riskmap",
+                        "rules": list(rules.values()),
+                    }
+                },
+                "automationDetails": {"id": "mcp-riskmap"},
+                "results": sarif_results,
+            }
+        ],
+    }
+    return json.dumps(sarif, indent=2, sort_keys=True)
+
+
+def _level_for(severity: str) -> str:
+    if severity in {"critical", "high"}:
+        return "error"
+    if severity == "medium":
+        return "warning"
+    return "note"
+
+
+def _fingerprint_for(finding) -> str:
+    source = f"{finding.rule_id}\0{finding.path}\0{finding.line}\0{finding.message}"
+    return hashlib.sha256(source.encode("utf-8")).hexdigest()[:32]

mcp_riskmap/reporters/table.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from mcp_riskmap.models import ScanResult
+
+
+def render_table(result: ScanResult) -> str:
+    if not result.findings:
+        return f"No findings for {result.root}"
+
+    rows = [("SEVERITY", "RULE", "LOCATION", "MESSAGE")]
+    for finding in result.findings:
+        rows.append(
+            (
+                finding.severity.upper(),
+                finding.rule_id,
+                f"{finding.path}:{finding.line}",
+                finding.message,
+            )
+        )
+
+    widths = [min(max(len(row[index]) for row in rows), 48) for index in range(4)]
+    rendered = []
+    for index, row in enumerate(rows):
+        rendered.append("  ".join(_fit(value, widths[col]) for col, value in enumerate(row)))
+        if index == 0:
+            rendered.append("  ".join("-" * width for width in widths))
+    return "\n".join(rendered)
+
+
+def _fit(value: str, width: int) -> str:
+    if len(value) <= width:
+        return value.ljust(width)
+    return value[: max(width - 1, 1)] + "…"

mcp_riskmap/rules/__init__.py

@@ -0,0 +1 @@
+"""Rule registry package."""

mcp_riskmap/rules/registry.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+DOCS_BASE_URL = "https://github.com/vawkdh-job/mcp-riskmap/blob/main/docs/rules.md"
+
+
+@dataclass(frozen=True)
+class RuleMetadata:
+    rule_id: str
+    description: str
+    precision: str
+    security_severity: str
+    tags: tuple[str, ...]
+
+    @property
+    def help_uri(self) -> str:
+        return f"{DOCS_BASE_URL}#{self.anchor}"
+
+    @property
+    def anchor(self) -> str:
+        return self.rule_id.lower().replace("_", "-")
+
+
+class RuleCatalog(dict[str, RuleMetadata]):
+    def metadata_for(self, rule_id: str) -> RuleMetadata:
+        return self.get(
+            rule_id,
+            _rule(rule_id, "Unregistered mcp-riskmap rule.", "medium", "5.0", ("mcp-riskmap",)),
+        )
+
+
+def _rule(rule_id: str, description: str, precision: str, security_severity: str, tags: tuple[str, ...]) -> RuleMetadata:
+    return RuleMetadata(rule_id, description, precision, security_severity, tags)
+
+
+RULES = RuleCatalog(
+    {
+        "MCP-CONFIG-SHELL": _rule("MCP-CONFIG-SHELL", "MCP config starts a server through a shell wrapper.", "high", "8.0", ("security", "mcp", "command-execution")),
+        "MCP-CONFIG-REMOTE-INSTALL": _rule("MCP-CONFIG-REMOTE-INSTALL", "MCP config downloads and executes remote content.", "high", "9.0", ("security", "mcp", "supply-chain")),
+        "MCP-CONFIG-SECRET-ENV": _rule("MCP-CONFIG-SECRET-ENV", "MCP config passes secret-like environment variables.", "medium", "6.5", ("security", "mcp", "secrets")),
+        "MCP-CONFIG-NPX-LATEST": _rule("MCP-CONFIG-NPX-LATEST", "MCP config runs npx -y without an explicit review gate.", "medium", "5.5", ("security", "mcp", "supply-chain")),
+        "PY-SHELL-TRUE": _rule("PY-SHELL-TRUE", "Python source uses subprocess with shell=True.", "high", "8.0", ("security", "python", "command-execution")),
+        "PY-OS-SYSTEM": _rule("PY-OS-SYSTEM", "Python source uses os.system.", "high", "8.0", ("security", "python", "command-execution")),
+        "PY-EVAL-EXEC": _rule("PY-EVAL-EXEC", "Python source uses eval or exec.", "high", "8.0", ("security", "python", "code-injection")),
+        "JS-CHILD-PROCESS-EXEC": _rule("JS-CHILD-PROCESS-EXEC", "JavaScript source uses child_process.exec.", "high", "8.0", ("security", "javascript", "command-execution")),
+        "JS-SPAWN-SHELL": _rule("JS-SPAWN-SHELL", "JavaScript source uses spawn with shell enabled.", "high", "8.0", ("security", "javascript", "command-execution")),
+        "TOOL-DESCRIPTION-INJECTION": _rule("TOOL-DESCRIPTION-INJECTION", "Tool text contains prompt-injection-like wording.", "medium", "6.0", ("security", "mcp", "prompt-injection")),
+        "REPO-MISSING-AGENTS": _rule("REPO-MISSING-AGENTS", "Repository does not define agent guidance.", "high", "3.0", ("repository-hygiene", "agents")),
+        "REPO-MISSING-SECURITY": _rule("REPO-MISSING-SECURITY", "Repository does not define vulnerability reporting guidance.", "high", "4.0", ("repository-hygiene", "security-policy")),
+        "REPO-MISSING-LICENSE": _rule("REPO-MISSING-LICENSE", "Repository does not define an open-source license.", "high", "2.0", ("repository-hygiene", "license")),
+    }
+)

mcp_riskmap/scanner.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from fnmatch import fnmatch
+from pathlib import Path
+
+from mcp_riskmap.analyzers.common import relative_path
+from mcp_riskmap.analyzers.config import analyze_config, is_candidate as is_config_candidate
+from mcp_riskmap.analyzers.js_source import analyze_javascript
+from mcp_riskmap.analyzers.python_source import analyze_python
+from mcp_riskmap.analyzers.repo_hygiene import analyze_repo_hygiene
+from mcp_riskmap.models import Finding, ScanResult
+
+SKIP_DIRS = {".git", ".hg", ".svn", "__pycache__", ".venv", "venv", "node_modules", "dist", "build"}
+JS_SUFFIXES = {".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"}
+
+
+class ScanInputError(ValueError):
+    pass
+
+
+def scan_path(path: str | Path, exclude_patterns: Sequence[str] | None = None) -> ScanResult:
+    root = Path(path).resolve()
+    if not root.exists():
+        raise ScanInputError(f"scan target does not exist: {root}")
+    if not root.is_file() and not root.is_dir():
+        raise ScanInputError(f"scan target is not a file or directory: {root}")
+
+    findings: list[Finding] = []
+    excludes = tuple(_normalize_pattern(pattern) for pattern in (exclude_patterns or ()) if pattern)
+
+    for file_path in _iter_files(root, excludes):
+        suffix = file_path.suffix.lower()
+        if is_config_candidate(file_path):
+            findings.extend(analyze_config(root, file_path))
+        if suffix == ".py":
+            findings.extend(analyze_python(root, file_path))
+        elif suffix in JS_SUFFIXES:
+            findings.extend(analyze_javascript(root, file_path))
+
+    findings.extend(analyze_repo_hygiene(root))
+    findings.sort(key=lambda finding: (finding.path, finding.line, finding.rule_id))
+    return ScanResult(root=root, findings=findings)
+
+
+def _iter_files(root: Path, exclude_patterns: Sequence[str]):
+    if root.is_file():
+        if not _is_excluded(root, root, exclude_patterns):
+            yield root
+        return
+
+    for candidate in root.rglob("*"):
+        if candidate.is_dir():
+            continue
+        if any(part in SKIP_DIRS for part in candidate.parts):
+            continue
+        if _is_excluded(root, candidate, exclude_patterns):
+            continue
+        yield candidate
+
+
+def _is_excluded(root: Path, candidate: Path, exclude_patterns: Sequence[str]) -> bool:
+    if not exclude_patterns:
+        return False
+    rel = relative_path(root, candidate)
+    return any(fnmatch(rel, pattern) or fnmatch(candidate.name, pattern) for pattern in exclude_patterns)
+
+
+def _normalize_pattern(pattern: str) -> str:
+    normalized = pattern.replace("\\", "/").strip()
+    if normalized.endswith("/"):
+        return f"{normalized}**"
+    return normalized

mcp_riskmap-0.1.2.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: mcp-riskmap
+Version: 0.1.2
+Summary: Local-first static auditor for risky MCP and agent-tool repository patterns.
+Author: mcp-riskmap contributors
+License: MIT License
+        
+        Copyright (c) 2026 mcp-riskmap contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/vawkdh-job/mcp-riskmap
+Project-URL: Repository, https://github.com/vawkdh-job/mcp-riskmap
+Project-URL: Issues, https://github.com/vawkdh-job/mcp-riskmap/issues
+Project-URL: Changelog, https://github.com/vawkdh-job/mcp-riskmap/blob/main/CHANGELOG.md
+Keywords: mcp,security,agent,static-analysis,sarif,github-actions,code-scanning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcp-riskmap
+
+[![CI](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/ci.yml)
+[![mcp-riskmap](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/mcp-riskmap.yml/badge.svg?branch=main)](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/mcp-riskmap.yml)
+[![Release](https://img.shields.io/github/v/release/vawkdh-job/mcp-riskmap)](https://github.com/vawkdh-job/mcp-riskmap/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`mcp-riskmap` is a local-first static auditor for MCP and agent-tool repositories. It looks for risky MCP configuration, shell-enabled tool handlers, prompt-injection-like tool descriptions, and missing maintainer guidance without starting untrusted MCP servers.
+
+This project is intentionally small and conservative. It is designed for maintainers who want a quick review signal in local development, pull requests, and GitHub Code Scanning.
+
+## Why this exists
+
+MCP servers often expose tools that can touch files, shells, networks, credentials, or local developer state. Reference servers and community examples are useful, but each maintainer still needs a threat model and basic safeguards before sharing configs or accepting tool changes.
+
+`mcp-riskmap` focuses on static signals that are cheap to review:
+
+- MCP config that starts through `cmd`, `powershell`, `bash`, or `sh`
+- Remote install pipelines such as `curl ... | sh` or `curl ... | iex`
+- Secret-like environment variables passed into MCP servers
+- Python `subprocess(..., shell=True)`, `os.system`, `eval`, and `exec`
+- JavaScript `child_process.exec` and `spawn(..., { shell: true })`
+- Tool text that looks like model-control prompt injection
+- Missing `AGENTS.md`, `SECURITY.md`, or `LICENSE`
+
+## Install
+
+From a checkout:
+
+```bash
+python -m pip install -e .
+```
+
+From GitHub:
+
+```bash
+python -m pip install "git+https://github.com/vawkdh-job/mcp-riskmap.git@v0.1.2"
+```
+
+For development without installing:
+
+```bash
+$env:PYTHONPATH = "src"
+python -m mcp_riskmap.cli scan examples/unsafe-mcp-server
+python -m mcp_riskmap.cli --version
+```
+
+## Usage
+
+```bash
+mcp-riskmap scan .
+mcp-riskmap scan . --format json
+mcp-riskmap scan . --format markdown --output report.md
+mcp-riskmap scan . --format sarif --output results.sarif --fail-on high
+mcp-riskmap scan . --exclude "examples/**" --exclude "tests/**"
+```
+
+`--fail-on high` returns exit code `1` when at least one finding is high or critical.
+
+Use `--exclude` for reviewed fixture directories, generated output, or intentionally unsafe examples that should not block CI.
+
+## Examples
+
+- `examples/unsafe-mcp-server/` contains intentionally risky MCP config and tool-handler patterns for scanner demonstrations.
+- `examples/safe-mcp-server/` contains a safer file-read pattern using a resolved base directory boundary check.
+
+## Example output
+
+```text
+SEVERITY  RULE                       LOCATION      MESSAGE
+--------  -------------------------  ------------  ------------------------------------------------
+CRITICAL  MCP-CONFIG-REMOTE-INSTALL  mcp.json:5    MCP server 'unsafe-demo' downloads and executes...
+HIGH      PY-SHELL-TRUE              server.py:6   A Python tool handler can pass input through a shell.
+HIGH      JS-CHILD-PROCESS-EXEC      server.js:4   A JavaScript tool handler can pass input through a shell.
+```
+
+## Output formats
+
+- `table`: compact terminal output
+- `json`: automation-friendly structured output
+- `markdown`: issue and release-note friendly report
+- `sarif`: GitHub Code Scanning compatible output
+
+Structured outputs redact secret-like evidence values before writing JSON or SARIF.
+
+## Reviewed suppressions
+
+If a maintainer reviews a finding and accepts the risk, add a narrow suppression on the same line or the previous line:
+
+```python
+# mcp-riskmap: ignore PY-SHELL-TRUE
+subprocess.run(command, shell=True)
+```
+
+Use rule-specific suppressions where possible. `mcp-riskmap: ignore` suppresses all rules on the next line and should be reserved for generated or documented fixture code.
+
+## GitHub Action
+
+This repository includes a composite GitHub Action:
+
+```yaml
+name: mcp-riskmap
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: vawkdh-job/mcp-riskmap@v0.1.2
+        with:
+          path: .
+          format: sarif
+          output: mcp-riskmap.sarif
+          fail-on: high
+          exclude: |
+            examples/**
+            tests/**
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: mcp-riskmap.sarif
+```
+
+## Safety stance
+
+`mcp-riskmap` does not execute MCP servers. It reads files and reports static findings. That means it will miss runtime-only behavior, but it is safer for quick review of unknown configs and pull requests.
+
+## Why static only?
+
+Some MCP scanners inspect live tool descriptions by starting configured servers. That can be useful, but it is risky when a reviewer is looking at an unknown repository or pull request. `mcp-riskmap` is meant to run earlier in the review flow: it reads files, flags obvious risk, and produces review artifacts without executing commands from the target project.
+
+## Compared with dynamic scanners
+
+`mcp-riskmap` is not a replacement for dynamic MCP inspection. It is a first-pass guardrail for maintainers who need quick review signals in CI and code review.
+
+| Area | mcp-riskmap | Dynamic scanners |
+| --- | --- | --- |
+| Starts scanned MCP servers | No | Often yes |
+| Safe for unknown PRs | Designed for this | Depends on sandboxing |
+| CI/SARIF friendly | Yes | Depends on tool |
+| Runtime behavior coverage | Limited | Better |
+| Static source/config review | Primary focus | Varies |
+
+## Current limitations
+
+- Rules are conservative regex/static checks, not full taint analysis.
+- The scanner does not inspect live MCP tool responses.
+- Secret detection is key-name based and does not do high-entropy scanning.
+- JavaScript and Python analyzers focus on common high-risk patterns first.
+
+## Roadmap
+
+- Add more MCP client config locations.
+- Detect unsafe filesystem writes and path traversal candidates.
+- Add rule severity profiles.
+- Add Semgrep-compatible pattern export.
+
+See [ROADMAP.md](ROADMAP.md) for issue-sized milestones.
+
+## OpenAI Codex for OSS fit
+
+This project is intended to be maintained as an open-source security and maintainer automation tool. It includes tests, CI, SARIF output, examples, security docs, contribution guidance, AGENTS.md, and tagged releases.
+
+Codex/API credits would be useful for reviewing rule changes, generating regression tests, triaging issues, improving documentation, and producing release notes. AI output should be reviewed by maintainers before merge.
+
+See [docs/codex-for-oss.md](docs/codex-for-oss.md) for application-specific maintainer workflow notes.

mcp_riskmap-0.1.2.dist-info/RECORD

@@ -0,0 +1,24 @@
+mcp_riskmap/__init__.py,sha256=ggnlgtwgdVr7IX8FqL_iEuoAx3hf8SfjdNdAvkU6_Mo,107
+mcp_riskmap/cli.py,sha256=tLYrRdzM98XLtTZ1udPLtNeM951NUcgYZgShlkdm8ck,2761
+mcp_riskmap/models.py,sha256=MVlmDUuw2vq3CaIQlPM2GBp6qk6ou6nSMI2W-PEDFPo,1621
+mcp_riskmap/redaction.py,sha256=V4mbosjNsH0A_lmFw1kZgnkKJit47o7pzd2TjIgu2UY,521
+mcp_riskmap/scanner.py,sha256=uUi5iNd87HL0ayTuj2KLjsUmmWy7YhALFmAws5DP6Qk,2725
+mcp_riskmap/analyzers/__init__.py,sha256=qYT7KzmU-lF9QIjddd8sjLeUm9BCF86CQxRz9yzcy5A,42
+mcp_riskmap/analyzers/common.py,sha256=5kRoxTvvljE0fs_mgY7CVQ5fkYFtp8oZ01vwnpvOErM,1049
+mcp_riskmap/analyzers/config.py,sha256=25nWr4c4ZXaHaBOEn8CGRya-XOCAal5Ml5dan3U-0bo,4999
+mcp_riskmap/analyzers/js_source.py,sha256=ZZXBQjgXfRcY4Ge6o8svqrnsgQupKH3Mz2f1ulJ_5iU,2907
+mcp_riskmap/analyzers/python_source.py,sha256=54XGtXNO9uLqJ_HowWTXHrZKbqKi5hginBUNZLRJyFk,3549
+mcp_riskmap/analyzers/repo_hygiene.py,sha256=H2kdce5gUxNvhXMHbHe2E_K0Xlq7hBEDIp_tAkI3Ftg,1212
+mcp_riskmap/reporters/__init__.py,sha256=FFClu4EdsinJvgjsv644_34bWdKjj-BtxLJVVYU2sak,41
+mcp_riskmap/reporters/json_reporter.py,sha256=dP9NbqzONENBLrv8THT-OEdN1scLZiIGDPZfZERpbsg,203
+mcp_riskmap/reporters/markdown.py,sha256=tEj4Q_uko8CrWzBcOSsqBt1i_BMuTuaVMXKTL6d-Ozc,991
+mcp_riskmap/reporters/sarif.py,sha256=_JKBLiUDLtpawYzA-8hYc-eysNrznOa83SusnNiLkv4,3077
+mcp_riskmap/reporters/table.py,sha256=yCd_T19fpYmnomQe9ui0aNrrYME9gkqRqBVVldlfc2A,1024
+mcp_riskmap/rules/__init__.py,sha256=9aiPn8WMJN104nwXPDG61scCYr3Ckw3WEyFyC4euh20,29
+mcp_riskmap/rules/registry.py,sha256=iS1lW73vj1csjTescBg_PMdGoV8gIUgfzFPlCGlwJaU,3174
+mcp_riskmap-0.1.2.dist-info/licenses/LICENSE,sha256=uX1ihazSovakOH230fz1aIKZjSUoSR24OI4VYACj_Uw,1081
+mcp_riskmap-0.1.2.dist-info/METADATA,sha256=2eXzgphbHADAjIzwhOg7JQ_y5YpoxrJoJ4Kg0pfil6o,9435
+mcp_riskmap-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_riskmap-0.1.2.dist-info/entry_points.txt,sha256=C_JZaF1-Xen4aYmmZRXdLlcE7j9TpfbH_XSSWYI7evM,53
+mcp_riskmap-0.1.2.dist-info/top_level.txt,sha256=5mDuPI_3ugnancUhEuy4wthZwLC95wgXHv415tf1fRw,12
+mcp_riskmap-0.1.2.dist-info/RECORD,,

mcp_riskmap-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_riskmap-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-riskmap = mcp_riskmap.cli:main

mcp_riskmap-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-riskmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_riskmap-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_riskmap