mcp-capdiff 0.1.1__py3-none-any.whl

mcp_audit/models/report.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mcp_audit import REPORT_SCHEMA_VERSION, RULESET_VERSION, __version__
+from mcp_audit.models.capability import Tool
+from mcp_audit.models.finding import Finding, Severity
+
+
+@dataclass(slots=True)
+class ScanReport:
+    target: str
+    server_name: str
+    tools: list[Tool] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    result: str = "pass"
+
+    @property
+    def risk_score(self) -> int:
+        weights = {
+            Severity.LOW: 5,
+            Severity.MEDIUM: 15,
+            Severity.HIGH: 30,
+            Severity.CRITICAL: 45,
+        }
+        return min(100, sum(weights[finding.severity] for finding in self.findings))
+
+    def counts_by_severity(self) -> dict[str, int]:
+        counts = {severity.name.lower(): 0 for severity in Severity}
+        for finding in self.findings:
+            counts[finding.severity.name.lower()] += 1
+        return counts
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": REPORT_SCHEMA_VERSION,
+            "report_type": "scan",
+            "versions": {"cli": __version__, "rules": RULESET_VERSION},
+            "target": self.target,
+            "server": {"name": self.server_name},
+            "summary": {
+                "tools": len(self.tools),
+                "findings": len(self.findings),
+                "risk_score": self.risk_score,
+                "result": self.result,
+                "severity_counts": self.counts_by_severity(),
+            },
+            "tools": [tool.as_dict() for tool in self.tools],
+            "findings": [finding.as_dict() for finding in self.findings],
+        }
+
+
+@dataclass(slots=True)
+class CapabilityChange:
+    tool: str
+    capability: str
+    before: object
+    after: object
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "tool": self.tool,
+            "capability": self.capability,
+            "before": self.before,
+            "after": self.after,
+        }
+
+
+@dataclass(slots=True)
+class SecurityDiff:
+    target: str
+    base: str
+    server_name: str
+    risk_before: int
+    risk_after: int
+    tools: list[Tool] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    new_tools: list[str] = field(default_factory=list)
+    removed_tools: list[str] = field(default_factory=list)
+    changed_tools: list[str] = field(default_factory=list)
+    capability_changes: list[CapabilityChange] = field(default_factory=list)
+    new_findings: list[Finding] = field(default_factory=list)
+    resolved_findings: list[Finding] = field(default_factory=list)
+    result: str = "pass"
+
+    @property
+    def risk_score(self) -> int:
+        return self.risk_after
+
+    def counts_by_severity(self) -> dict[str, int]:
+        counts = {severity.name.lower(): 0 for severity in Severity}
+        for finding in self.findings:
+            counts[finding.severity.name.lower()] += 1
+        return counts
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": REPORT_SCHEMA_VERSION,
+            "report_type": "diff",
+            "versions": {"cli": __version__, "rules": RULESET_VERSION},
+            "target": self.target,
+            "base": self.base,
+            "server": {"name": self.server_name},
+            "summary": {
+                "risk_before": self.risk_before,
+                "risk_after": self.risk_after,
+                "result": self.result,
+                "new_tools": len(self.new_tools),
+                "changed_tools": len(self.changed_tools),
+                "new_findings": len(self.new_findings),
+                "resolved_findings": len(self.resolved_findings),
+            },
+            "new_tools": self.new_tools,
+            "removed_tools": self.removed_tools,
+            "changed_tools": self.changed_tools,
+            "capability_changes": [change.as_dict() for change in self.capability_changes],
+            "new_findings": [finding.as_dict() for finding in self.new_findings],
+            "resolved_findings": [finding.as_dict() for finding in self.resolved_findings],
+            "regression_findings": [finding.as_dict() for finding in self.findings],
+        }

mcp_audit/policy/__init__.py

@@ -0,0 +1 @@
+"""Policy loading and evaluation."""

mcp_audit/policy/evaluator.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from datetime import date
+
+from mcp_audit.models.finding import Finding, Severity
+from mcp_audit.models.report import ScanReport, SecurityDiff
+from mcp_audit.policy.loader import Policy
+
+
+def apply_policy(
+    report: ScanReport | SecurityDiff, policy: Policy, fail_on: Severity | None = None
+) -> ScanReport | SecurityDiff:
+    report.findings = [
+        finding
+        for finding in report.findings
+        if not any(
+            suppression.matches(finding) and suppression.is_active(date.today())
+            for suppression in policy.suppressions
+        )
+    ]
+    thresholds = (
+        {severity for severity in Severity if severity >= fail_on}
+        if fail_on
+        else policy.fail_on
+    )
+    report.result = "fail" if any(finding.severity in thresholds for finding in report.findings) else "pass"
+    if policy.max_risk_score is not None and report.risk_score > policy.max_risk_score:
+        report.result = "fail"
+    return report

mcp_audit/policy/loader.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mcp_audit.models.finding import Finding, Severity
+
+
+SUPPORTED_RULES = {
+    "MCP001",
+    "MCP002",
+    "MCP003",
+    "MCP004",
+    "MCP005",
+    "MCP007",
+    "MCP010",
+    "MCP016",
+    "MCP017",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Suppression:
+    rule_id: str
+    reason: str
+    tool: str | None = None
+    expires: date | None = None
+
+    def matches(self, finding: Finding) -> bool:
+        return self.rule_id == finding.rule_id and (self.tool is None or self.tool == finding.tool)
+
+    def is_active(self, as_of: date | None = None) -> bool:
+        return self.expires is None or self.expires >= (as_of or date.today())
+
+
+@dataclass(slots=True)
+class Policy:
+    fail_on: set[Severity] = field(default_factory=lambda: {Severity.CRITICAL, Severity.HIGH})
+    max_risk_score: int | None = None
+    suppressions: list[Suppression] = field(default_factory=list)
+
+    def expired_suppressions(self, as_of: date | None = None) -> list[Suppression]:
+        return [suppression for suppression in self.suppressions if not suppression.is_active(as_of)]
+
+
+def load_policy(path: str | None) -> Policy:
+    if not path:
+        return Policy()
+    policy_path = Path(path)
+    if not policy_path.exists():
+        raise FileNotFoundError(f"policy file not found: {policy_path}")
+    try:
+        payload = yaml.safe_load(policy_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f"invalid YAML in policy file: {exc}") from exc
+    return _parse_policy(payload)
+
+
+def _parse_small_yaml_subset(text: str) -> Policy:
+    """Compatibility helper retained for callers of the pre-0.1 parser."""
+    try:
+        payload = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f"invalid YAML policy: {exc}") from exc
+    return _parse_policy(payload)
+
+
+def _parse_policy(payload: Any) -> Policy:
+    if not isinstance(payload, dict):
+        raise ValueError("policy document must be a YAML mapping")
+    policy = Policy()
+    policy_config = payload.get("policy", {})
+    if policy_config and not isinstance(policy_config, dict):
+        raise ValueError("policy must be a mapping")
+    ci_config = policy_config.get("ci", policy_config) if policy_config else {}
+    if ci_config and not isinstance(ci_config, dict):
+        raise ValueError("policy.ci must be a mapping")
+
+    if "fail_on" in ci_config:
+        values = ci_config["fail_on"]
+        if not isinstance(values, list) or not values:
+            raise ValueError("policy.ci.fail_on must be a non-empty list")
+        policy.fail_on = {Severity.parse(str(value)) for value in values}
+    if "max_risk_score" in ci_config:
+        score = ci_config["max_risk_score"]
+        if not isinstance(score, int) or isinstance(score, bool) or not 0 <= score <= 100:
+            raise ValueError("policy.ci.max_risk_score must be an integer from 0 to 100")
+        policy.max_risk_score = score
+
+    policy.suppressions = _parse_suppressions(payload.get("suppress", []))
+    return policy
+
+
+def _parse_suppressions(value: Any) -> list[Suppression]:
+    if value in ({}, [], None):
+        return []
+    entries: list[dict[str, Any]] = []
+    if isinstance(value, list):
+        for item in value:
+            if not isinstance(item, dict):
+                raise ValueError("each suppression must be a mapping")
+            entries.append(item)
+    elif isinstance(value, dict):
+        for rule_id, config in value.items():
+            if not isinstance(config, dict):
+                raise ValueError(f"suppression {rule_id} must be a mapping")
+            entries.append({"rule": rule_id, **config})
+    else:
+        raise ValueError("suppress must be a list or mapping")
+
+    suppressions: list[Suppression] = []
+    for entry in entries:
+        rule_id = str(entry.get("rule", "")).strip().upper()
+        if rule_id not in SUPPORTED_RULES:
+            raise ValueError(f"unknown suppression rule: {rule_id or '<empty>'}")
+        reason = str(entry.get("reason", "")).strip()
+        if not reason:
+            raise ValueError(f"suppression {rule_id} requires a non-empty reason")
+        tool_value = entry.get("tool")
+        tool = str(tool_value).strip() if tool_value is not None else None
+        expires = _parse_expiry(entry.get("expires"), rule_id)
+        suppressions.append(Suppression(rule_id=rule_id, tool=tool or None, reason=reason, expires=expires))
+    return suppressions
+
+
+def _parse_expiry(value: Any, rule_id: str) -> date | None:
+    if value in (None, ""):
+        return None
+    if isinstance(value, date):
+        return value
+    try:
+        return date.fromisoformat(str(value))
+    except ValueError as exc:
+        raise ValueError(f"suppression {rule_id} expires must use YYYY-MM-DD") from exc

mcp_audit/reporters/__init__.py

@@ -0,0 +1 @@
+"""Report renderers."""

mcp_audit/reporters/json.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import json
+
+from mcp_audit.models.report import ScanReport, SecurityDiff
+
+
+def render_json(report: ScanReport | SecurityDiff) -> str:
+    return json.dumps(report.as_dict(), indent=2, sort_keys=True)

mcp_audit/reporters/manifest.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from mcp_audit import MANIFEST_SCHEMA_VERSION, RULESET_VERSION
+from mcp_audit.models.report import ScanReport
+
+
+def render_manifest(report: ScanReport) -> str:
+    lines = [
+        f'schema_version: "{MANIFEST_SCHEMA_VERSION}"',
+        f'rules_version: "{RULESET_VERSION}"',
+        "server:",
+        f"  name: {report.server_name}",
+        "tools:",
+    ]
+    for tool in report.tools:
+        capability = tool.capability
+        lines.extend(
+            [
+                f"  {tool.name}:",
+                f"    source: {tool.source}",
+                f"    data_access: [{', '.join(sorted(capability.data_access))}]",
+                f"    side_effect: {capability.side_effect}",
+                f"    filesystem: {capability.filesystem}",
+                f"    network: {capability.network}",
+                f"    network_destination: {capability.network_destination or 'none'}",
+                f"    execution: {capability.execution}",
+                f"    requires_approval: {str(capability.requires_approval).lower()}",
+            ]
+        )
+    return "\n".join(lines) + "\n"

mcp_audit/reporters/sarif.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp_audit import RULESET_VERSION, __version__
+from mcp_audit.models.report import ScanReport, SecurityDiff
+
+
+def render_sarif(report: ScanReport | SecurityDiff) -> str:
+    rules: dict[str, dict[str, object]] = {}
+    results = []
+    for finding in report.findings:
+        rules.setdefault(
+            finding.rule_id,
+            {
+                "id": finding.rule_id,
+                "name": finding.title,
+                "shortDescription": {"text": finding.title},
+                "help": {"text": finding.recommendation},
+                "properties": {"security-severity": _security_severity(finding.severity.name.lower())},
+            },
+        )
+        result = {
+                "ruleId": finding.rule_id,
+                "level": _level(finding.severity.name.lower()),
+                "message": {"text": _message(finding)},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": _artifact_uri(finding.location.path)},
+                            "region": _region(finding),
+                        }
+                    }
+                ],
+            }
+        if finding.path:
+            result["properties"] = {"capabilityPath": finding.path}
+        results.append(result)
+    sarif = {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "MCP Audit",
+                        "semanticVersion": __version__,
+                        "informationUri": "https://github.com/robbyfa/MCP-Audit",
+                        "rules": list(rules.values()),
+                        "properties": {"rulesVersion": RULESET_VERSION},
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(sarif, indent=2, sort_keys=True)
+
+
+def _message(finding) -> str:
+    parts = [finding.message]
+    if finding.impact:
+        parts.append(f"Risk: {finding.impact}")
+    parts.append(f"Remediation: {finding.recommendation}")
+    return "\n\n".join(parts)
+
+
+def _region(finding) -> dict[str, object]:
+    region: dict[str, object] = {"startLine": finding.location.line}
+    if finding.location.column is not None:
+        region["startColumn"] = finding.location.column
+    snippet = next((item.snippet for item in finding.evidence if item.snippet), None)
+    if snippet:
+        region["snippet"] = {"text": snippet}
+    return region
+
+
+def _artifact_uri(path: str) -> str:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        try:
+            return candidate.relative_to(Path.cwd()).as_posix()
+        except ValueError:
+            return candidate.as_uri()
+    return candidate.as_posix()
+
+
+def _level(severity: str) -> str:
+    return "error" if severity in {"critical", "high"} else "warning"
+
+
+def _security_severity(severity: str) -> str:
+    return {"critical": "9.5", "high": "8.0", "medium": "5.0", "low": "2.0"}[severity]

mcp_audit/reporters/terminal.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from mcp_audit.models.finding import Severity
+from mcp_audit.models.report import ScanReport, SecurityDiff
+
+
+def render_terminal(report: ScanReport) -> str:
+    counts = report.counts_by_severity()
+    lines = [
+        "MCP AUDIT",
+        f"Server: {report.server_name}",
+        f"Target: {report.target}",
+        "",
+        f"Tools discovered: {len(report.tools)}",
+        "",
+        "Risk findings",
+        f"CRITICAL  {counts['critical']}",
+        f"HIGH      {counts['high']}",
+        f"MEDIUM    {counts['medium']}",
+        f"LOW       {counts['low']}",
+        f"Risk score: {report.risk_score}",
+        "",
+    ]
+    for finding in sorted(report.findings, key=lambda item: item.severity, reverse=True):
+        lines.extend(_finding_lines(finding))
+    lines.append(f"Result: {report.result.upper()}")
+    return "\n".join(lines)
+
+
+def render_diff_terminal(report: SecurityDiff) -> str:
+    lines = [
+        "MCP SECURITY DIFF",
+        f"Base: {report.base}",
+        f"Target: {report.target}",
+        "",
+        "Risk",
+        f"{report.risk_before} -> {report.risk_after}",
+        "",
+        "New tools",
+        *([f"+ {name}" for name in report.new_tools] or ["(none)"]),
+        "",
+        "Removed tools",
+        *([f"- {name}" for name in report.removed_tools] or ["(none)"]),
+        "",
+        "Changed tools",
+        *([f"~ {name}" for name in report.changed_tools] or ["(none)"]),
+        "",
+        "Capability changes",
+        *(
+            [f"~ {change.tool}.{change.capability}: {change.before} -> {change.after}" for change in report.capability_changes]
+            or ["(none)"]
+        ),
+        "",
+        "New findings",
+        *(
+            [f"+ {finding.rule_id} {finding.severity.name}  {finding.tool or 'n/a'}" for finding in report.new_findings]
+            or ["(none)"]
+        ),
+        "",
+        "Resolved findings",
+        *(
+            [f"- {finding.rule_id} {finding.severity.name}  {finding.tool or 'n/a'}" for finding in report.resolved_findings]
+            or ["(none)"]
+        ),
+        "",
+    ]
+    regressions = [finding for finding in report.findings if finding.rule_id in {"MCP016", "MCP017"}]
+    if regressions:
+        lines.append("Regression details")
+        for finding in regressions:
+            lines.extend(_finding_lines(finding))
+    lines.append(f"Result: {report.result.upper()}")
+    return "\n".join(lines)
+
+
+def _finding_lines(finding) -> list[str]:
+    path = " -> ".join(finding.path)
+    lines = [
+        f"{finding.severity.name} {finding.rule_id}",
+        f"Tool: {finding.tool or 'n/a'}",
+        "",
+        finding.title,
+        finding.message,
+        f"Location: {finding.location.path}:{finding.location.line}",
+    ]
+    if path:
+        lines.append(f"Path: {path}")
+    if finding.evidence:
+        lines.append("Evidence:")
+        for item in finding.evidence[:5]:
+            lines.append(f"  - {item.message}")
+            if item.snippet:
+                lines.append(f"    {item.snippet}")
+    if finding.impact:
+        lines.extend(["Risk:", finding.impact])
+    lines.extend(["Suggested remediation:", finding.recommendation, ""])
+    return lines

mcp_audit/rules/__init__.py

@@ -0,0 +1 @@
+"""Security rules."""