mcp-capdiff 0.1.1__py3-none-any.whl

mcp_audit/__init__.py

@@ -0,0 +1,6 @@
+"""MCP Audit public package and independently evolving contract versions."""
+
+__version__ = "0.1.1"
+RULESET_VERSION = "0.1"
+REPORT_SCHEMA_VERSION = "1.0"
+MANIFEST_SCHEMA_VERSION = "1.0"

mcp_audit/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from mcp_audit.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_audit/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis entry points."""

mcp_audit/analysis/diff.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+from mcp_audit.analysis.scan import scan_path
+from mcp_audit.models.capability import Tool
+from mcp_audit.models.finding import Evidence, Finding, Location, Severity
+from mcp_audit.models.report import CapabilityChange, ScanReport, SecurityDiff
+
+
+def diff_against_base(base: str, target: str | Path = ".") -> SecurityDiff:
+    target_path = Path(target).resolve()
+    repo_root = _git_root(target_path.parent if target_path.is_file() else target_path)
+    relative_target = target_path.relative_to(repo_root)
+    head = scan_path(target_path)
+    with tempfile.TemporaryDirectory(prefix="mcp-audit-base-") as temp_dir:
+        base_root = Path(temp_dir) / "base"
+        _export_git_tree(base, base_root, repo_root)
+        base_target = base_root / relative_target
+        base_report = (
+            scan_path(base_target)
+            if base_target.exists()
+            else ScanReport(target=str(base_target), server_name=head.server_name)
+        )
+    if not head.tools and not base_report.tools:
+        raise ValueError(
+            f"no MCP tools discovered in either {target_path} or baseline {base}; "
+            "check the target path, filesystem access, and supported decorators"
+        )
+    return _build_diff(base, base_report, head)
+
+
+def _git_root(cwd: Path) -> Path:
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=cwd,
+        check=True,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    return Path(result.stdout.strip()).resolve()
+
+
+def _export_git_tree(base: str, destination: Path, cwd: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    archive = subprocess.run(
+        ["git", "archive", base],
+        cwd=cwd,
+        check=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    subprocess.run(
+        ["tar", "-x", "-C", str(destination)],
+        input=archive.stdout,
+        check=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+
+def _build_diff(base_name: str, base: ScanReport, head: ScanReport) -> SecurityDiff:
+    base_tools = {tool.name: tool for tool in base.tools}
+    head_tools = {tool.name: tool for tool in head.tools}
+    new_tools = sorted(head_tools.keys() - base_tools.keys())
+    removed_tools = sorted(base_tools.keys() - head_tools.keys())
+    changed_tools = sorted(
+        name
+        for name in head_tools.keys() & base_tools.keys()
+        if _tool_signature(head_tools[name]) != _tool_signature(base_tools[name])
+    )
+    capability_changes = _capability_changes(base_tools, head_tools)
+
+    base_findings = {_finding_key(finding): finding for finding in base.findings}
+    head_findings = {_finding_key(finding): finding for finding in head.findings}
+    new_findings = [head_findings[key] for key in sorted(head_findings.keys() - base_findings.keys())]
+    resolved_findings = [base_findings[key] for key in sorted(base_findings.keys() - head_findings.keys())]
+    regressions = _security_regressions(base_tools, head_tools, new_tools, capability_changes)
+    actionable = _deduplicate([*new_findings, *regressions])
+
+    return SecurityDiff(
+        target=head.target,
+        base=base_name,
+        server_name=head.server_name,
+        risk_before=base.risk_score,
+        risk_after=head.risk_score,
+        tools=head.tools,
+        findings=actionable,
+        new_tools=new_tools,
+        removed_tools=removed_tools,
+        changed_tools=changed_tools,
+        capability_changes=capability_changes,
+        new_findings=new_findings,
+        resolved_findings=resolved_findings,
+    )
+
+
+def _capability_changes(base_tools: dict[str, Tool], head_tools: dict[str, Tool]) -> list[CapabilityChange]:
+    changes: list[CapabilityChange] = []
+    for name in sorted(base_tools.keys() & head_tools.keys()):
+        before = base_tools[name].capability.as_dict()
+        after = head_tools[name].capability.as_dict()
+        for capability in sorted(before.keys() | after.keys()):
+            if before.get(capability) != after.get(capability):
+                changes.append(CapabilityChange(name, capability, before.get(capability), after.get(capability)))
+    return changes
+
+
+def _security_regressions(
+    base_tools: dict[str, Tool],
+    head_tools: dict[str, Tool],
+    new_tools: list[str],
+    changes: list[CapabilityChange],
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for name in new_tools:
+        tool = head_tools[name]
+        if _is_high_impact(tool):
+            findings.append(
+                Finding(
+                    rule_id="MCP016",
+                    title="Capability escalation",
+                    severity=Severity.HIGH,
+                    tool=name,
+                    message="A new tool introduces a high-impact security capability.",
+                    impact="The MCP server's authority expands beyond the reviewed baseline.",
+                    recommendation="Review the capability, require approval where appropriate, and update the approved manifest.",
+                    location=_location(tool.source),
+                    evidence=[Evidence(message=f"New capabilities: {tool.capability.as_dict()}", kind="capability_diff")],
+                )
+            )
+    changed_names = {change.tool for change in changes}
+    for name in sorted(changed_names):
+        previous = base_tools[name]
+        tool = head_tools[name]
+        if previous.capability.requires_approval and not tool.capability.requires_approval:
+            findings.append(
+                Finding(
+                    rule_id="MCP017",
+                    title="Approval removed",
+                    severity=Severity.HIGH,
+                    tool=name,
+                    message="A previously approval-gated tool no longer requires approval.",
+                    impact="High-impact actions may now execute without human confirmation.",
+                    recommendation="Restore the approval boundary or document the reviewed policy exception.",
+                    location=_location(tool.source),
+                    evidence=[Evidence(message="requires_approval: true -> false", kind="capability_diff")],
+                )
+            )
+        expanded = [change for change in changes if change.tool == name and _is_expansion(change)]
+        if expanded:
+            findings.append(
+                Finding(
+                    rule_id="MCP016",
+                    title="Capability escalation",
+                    severity=Severity.HIGH,
+                    tool=name,
+                    message="A tool capability expanded relative to the Git baseline.",
+                    impact="Existing clients may gain access to broader resources or side effects.",
+                    recommendation="Constrain the capability or approve and document the expanded baseline.",
+                    location=_location(tool.source),
+                    evidence=[
+                        Evidence(message=f"{change.capability}: {change.before} -> {change.after}", kind="capability_diff")
+                        for change in expanded
+                    ],
+                )
+            )
+    return findings
+
+
+def _tool_signature(tool: Tool) -> tuple[object, ...]:
+    return (
+        tuple(sorted(tool.capability.as_dict().items(), key=lambda item: item[0])),
+        tuple((parameter.name, parameter.annotation, parameter.bounded) for parameter in tool.parameters),
+    )
+
+
+def _finding_key(finding: Finding) -> tuple[str, str]:
+    return finding.rule_id, finding.tool or ""
+
+
+def _deduplicate(findings: list[Finding]) -> list[Finding]:
+    result: dict[tuple[str, str], Finding] = {}
+    for finding in findings:
+        result.setdefault(_finding_key(finding), finding)
+    return list(result.values())
+
+
+def _is_high_impact(tool: Tool) -> bool:
+    capability = tool.capability
+    return (
+        capability.network == "unrestricted_outbound"
+        or capability.filesystem == "unrestricted"
+        or capability.execution != "none"
+        or capability.side_effect in {"external_write", "destructive_action"}
+    )
+
+
+def _is_expansion(change: CapabilityChange) -> bool:
+    if change.capability in {"filesystem", "network", "execution", "side_effect"}:
+        return _rank(str(change.after)) > _rank(str(change.before))
+    if change.capability in {"destructive", "financial"}:
+        return change.before is False and change.after is True
+    if change.capability == "data_access":
+        return bool(set(change.after or []) - set(change.before or []))
+    return False
+
+
+def _rank(value: str) -> int:
+    return {
+        "none": 0,
+        "fixed_file": 1,
+        "allowlisted_files": 2,
+        "allowlisted_hosts": 2,
+        "local_write": 2,
+        "directory": 3,
+        "external_write": 4,
+        "multiple_directories": 4,
+        "destructive_action": 5,
+        "unrestricted": 5,
+        "unrestricted_outbound": 5,
+        "shell": 5,
+        "arbitrary_code": 6,
+    }.get(value, 0)
+
+
+def _location(source: str) -> Location:
+    path, _, line = source.rpartition(":")
+    try:
+        return Location(path=path or source, line=int(line or "1"))
+    except ValueError:
+        return Location(path=source)

mcp_audit/analysis/scan.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp_audit.models.report import ScanReport
+from mcp_audit.rules.engine import evaluate_tools
+from mcp_audit.scanners.source.python import scan_python_sources
+
+
+def scan_path(path: str | Path, *, require_tools: bool = False) -> ScanReport:
+    target = Path(path).resolve()
+    tools = scan_python_sources(target)
+    if require_tools and not tools:
+        raise ValueError(
+            f"no MCP tools discovered in {target}; check the target path, filesystem access, and supported decorators"
+        )
+    findings = evaluate_tools(tools)
+    return ScanReport(
+        target=str(target),
+        server_name=_server_name(target),
+        tools=tools,
+        findings=findings,
+    )
+
+
+def _server_name(target: Path) -> str:
+    if target.is_file():
+        return target.stem
+    return target.name

mcp_audit/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

mcp_audit/cli/main.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from mcp_audit import __version__
+from mcp_audit.analysis.diff import diff_against_base
+from mcp_audit.analysis.scan import scan_path
+from mcp_audit.models.finding import Severity
+from mcp_audit.policy.evaluator import apply_policy
+from mcp_audit.policy.loader import load_policy
+from mcp_audit.reporters.json import render_json
+from mcp_audit.reporters.manifest import render_manifest
+from mcp_audit.reporters.sarif import render_sarif
+from mcp_audit.reporters.terminal import render_diff_terminal, render_terminal
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "scan":
+            report = scan_path(args.target, require_tools=not args.allow_empty)
+            policy = load_policy(args.policy)
+            fail_on = Severity.parse(args.fail_on) if args.fail_on else None
+            report = apply_policy(report, policy, fail_on)
+            _write(_render(report, args.format), args.output)
+            return 1 if report.result == "fail" else 0
+        if args.command == "manifest":
+            report = scan_path(args.target, require_tools=True)
+            _write(render_manifest(report), args.output)
+            return 0
+        if args.command == "diff":
+            report = diff_against_base(args.base, args.target)
+            policy = load_policy(args.policy)
+            fail_on = Severity.parse(args.fail_on) if args.fail_on else None
+            report = apply_policy(report, policy, fail_on)
+            _write(_render(report, args.format), args.output)
+            return 1 if report.result == "fail" else 0
+        if args.command == "policy" and args.policy_command == "check":
+            policy = load_policy(args.policy)
+            expired = policy.expired_suppressions()
+            if expired:
+                for suppression in expired:
+                    print(
+                        f"Expired suppression: {suppression.rule_id} "
+                        f"({suppression.tool or 'all tools'}) expired {suppression.expires}",
+                        file=sys.stderr,
+                    )
+                return 1
+            print(f"Policy OK: {args.policy}")
+            return 0
+    except Exception as exc:
+        print(f"mcp-audit: {exc}", file=sys.stderr)
+        return 2
+    parser.print_help()
+    return 2
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mcp-audit", description="Security regression scanner for MCP servers.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subcommands = parser.add_subparsers(dest="command")
+
+    scan = subcommands.add_parser("scan", help="scan local source")
+    scan.add_argument("target", nargs="?", default=".")
+    scan.add_argument(
+        "--allow-empty",
+        action="store_true",
+        help="allow a successful scan when no MCP tools are discovered",
+    )
+    _report_options(scan)
+
+    manifest = subcommands.add_parser("manifest", help="generate a capability manifest")
+    manifest.add_argument("target", nargs="?", default=".")
+    manifest.add_argument("--output")
+
+    diff = subcommands.add_parser("diff", help="compare the current tree with a git baseline")
+    diff.add_argument("target", nargs="?", default=".")
+    diff.add_argument("--base", required=True)
+    _report_options(diff)
+
+    policy = subcommands.add_parser("policy", help="policy utilities")
+    policy_subcommands = policy.add_subparsers(dest="policy_command")
+    check = policy_subcommands.add_parser("check", help="validate that a policy file can be loaded")
+    check.add_argument("policy")
+    return parser
+
+
+def _report_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--format", choices=["terminal", "json", "sarif"], default="terminal")
+    parser.add_argument("--output")
+    parser.add_argument("--policy")
+    parser.add_argument("--fail-on", choices=["low", "medium", "high", "critical"])
+
+
+def _render(report, fmt: str) -> str:
+    if fmt == "json":
+        return render_json(report)
+    if fmt == "sarif":
+        return render_sarif(report)
+    if hasattr(report, "base"):
+        return render_diff_terminal(report)
+    return render_terminal(report)
+
+
+def _write(text: str, output: str | None) -> None:
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    else:
+        print(text)

mcp_audit/models/__init__.py

@@ -0,0 +1,12 @@
+from mcp_audit.models.capability import Capability, Tool
+from mcp_audit.models.finding import Finding, Location, Severity
+from mcp_audit.models.report import ScanReport
+
+__all__ = [
+    "Capability",
+    "Finding",
+    "Location",
+    "ScanReport",
+    "Severity",
+    "Tool",
+]

mcp_audit/models/capability.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mcp_audit.models.finding import Evidence
+
+
+@dataclass(slots=True)
+class Capability:
+    data_access: set[str] = field(default_factory=set)
+    side_effect: str = "none"
+    filesystem: str = "none"
+    network: str = "none"
+    network_destination: str | None = None
+    execution: str = "none"
+    sensitivity: str = "public"
+    destructive: bool = False
+    financial: bool = False
+    requires_approval: bool = False
+    audit_metadata: bool = False
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "data_access": sorted(self.data_access),
+            "side_effect": self.side_effect,
+            "filesystem": self.filesystem,
+            "network": self.network,
+            "network_destination": self.network_destination,
+            "execution": self.execution,
+            "sensitivity": self.sensitivity,
+            "destructive": self.destructive,
+            "financial": self.financial,
+            "requires_approval": self.requires_approval,
+            "audit_metadata": self.audit_metadata,
+        }
+
+
+@dataclass(slots=True)
+class Parameter:
+    name: str
+    annotation: str | None = None
+    default: str | None = None
+    bounded: bool = False
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "annotation": self.annotation,
+            "default": self.default,
+            "bounded": self.bounded,
+        }
+
+
+@dataclass(slots=True)
+class Tool:
+    name: str
+    source: str
+    context: str = ""
+    description: str = ""
+    parameters: list[Parameter] = field(default_factory=list)
+    capability: Capability = field(default_factory=Capability)
+    evidence: list[Evidence] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "source": self.source,
+            "context": self.context,
+            "description": self.description,
+            "parameters": [parameter.as_dict() for parameter in self.parameters],
+            "capabilities": self.capability.as_dict(),
+            "evidence": [item.as_dict() for item in self.evidence],
+        }

mcp_audit/models/finding.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    @classmethod
+    def parse(cls, value: str) -> "Severity":
+        normalized = value.strip().upper()
+        try:
+            return cls[normalized]
+        except KeyError as exc:
+            valid = ", ".join(severity.name.lower() for severity in cls)
+            raise ValueError(f"unknown severity '{value}', expected one of: {valid}") from exc
+
+
+@dataclass(slots=True)
+class Location:
+    path: str
+    line: int = 1
+    column: int | None = None
+    end_line: int | None = None
+    end_column: int | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        result: dict[str, object] = {"path": self.path, "line": self.line}
+        if self.column is not None:
+            result["column"] = self.column
+        if self.end_line is not None:
+            result["end_line"] = self.end_line
+        if self.end_column is not None:
+            result["end_column"] = self.end_column
+        return result
+
+
+@dataclass(slots=True)
+class Evidence:
+    message: str
+    location: Location | None = None
+    snippet: str | None = None
+    kind: str = "code"
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "kind": self.kind,
+            "message": self.message,
+            "location": self.location.as_dict() if self.location else None,
+            "snippet": self.snippet,
+        }
+
+
+@dataclass(slots=True)
+class Finding:
+    rule_id: str
+    title: str
+    severity: Severity
+    tool: str | None
+    message: str
+    recommendation: str
+    location: Location
+    impact: str = ""
+    evidence: list[Evidence] = field(default_factory=list)
+    path: list[str] = field(default_factory=list)
+    data_classification: list[str] = field(default_factory=list)
+    destination: str | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "rule_id": self.rule_id,
+            "title": self.title,
+            "severity": self.severity.name.lower(),
+            "tool": self.tool,
+            "message": self.message,
+            "impact": self.impact,
+            "recommendation": self.recommendation,
+            "location": self.location.as_dict(),
+            "evidence": [item.as_dict() for item in self.evidence],
+            "path": self.path,
+            "data_classification": self.data_classification,
+            "destination": self.destination,
+        }