mcp-zero-trust-layer 0.1.0__py3-none-any.whl

mcp_zero_trust_layer/__init__.py

@@ -0,0 +1,4 @@
+"""MCP Zero Trust Layer package."""
+
+__version__ = "0.1.0"
+

mcp_zero_trust_layer/approvals/__init__.py

@@ -0,0 +1,5 @@
+from .models import ApprovalRequest
+from .notifier import ApprovalNotifier
+from .store import ApprovalStore, hash_arguments
+
+__all__ = ["ApprovalNotifier", "ApprovalRequest", "ApprovalStore", "hash_arguments"]

mcp_zero_trust_layer/approvals/models.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class ApprovalRequest(BaseModel):
+    id: str = Field(default_factory=lambda: f"appr_{uuid4().hex}")
+    status: Literal["pending", "approved", "denied", "expired"] = "pending"
+    server: str
+    capability: str | None = None
+    capability_type: str
+    policy_id: str
+    identity_subject: str
+    client_id: str | None = None
+    agent_id: str | None = None
+    arguments_hash: str
+    arguments_redacted: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None
+    decided_at: datetime | None = None
+    decided_by: str | None = None
+    decision_comment: str | None = None
+
+    def is_active(self) -> bool:
+        if self.status != "approved":
+            return False
+        if self.expires_at is None:
+            return True
+        return self.expires_at > datetime.now(timezone.utc)

mcp_zero_trust_layer/approvals/notifier.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from mcp_zero_trust_layer.audit import redact_sensitive
+from mcp_zero_trust_layer.config.models import ApprovalsConfig
+from mcp_zero_trust_layer.config.secrets import resolve_secret_value
+
+
+class ApprovalNotifier:
+    def __init__(self, config: ApprovalsConfig):
+        self.config = config
+
+    def notify(self, action: str, approval: dict[str, Any]) -> None:
+        if not self.config.webhook_url:
+            return
+        url = resolve_secret_value(self.config.webhook_url, field="approvals.webhook_url")
+        payload = {
+            "event_type": "approval",
+            "action": action,
+            "approval": redact_sensitive(approval),
+        }
+        try:
+            response = httpx.post(url, json=payload, timeout=self.config.webhook_timeout)
+            response.raise_for_status()
+        except Exception:
+            if self.config.webhook_strict:
+                raise

mcp_zero_trust_layer/approvals/store.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import hashlib
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - Windows fallback
+    fcntl = None  # type: ignore[assignment]
+
+from mcp_zero_trust_layer.approvals.models import ApprovalRequest
+from mcp_zero_trust_layer.audit import redact_sensitive
+from mcp_zero_trust_layer.config.models import ApprovalsConfig
+from mcp_zero_trust_layer.core.context import RequestContext
+
+
+class ApprovalStore:
+    def __init__(self, config: ApprovalsConfig):
+        self.path = Path(config.path)
+        self.lock_path = Path(f"{self.path}.lock")
+        self.default_ttl_seconds = config.default_ttl_seconds
+
+    def create(self, context: RequestContext, policy_id: str) -> ApprovalRequest:
+        with self._locked():
+            request = ApprovalRequest(
+                server=context.server,
+                capability=context.capability,
+                capability_type=context.capability_type,
+                policy_id=policy_id,
+                identity_subject=context.identity.subject,
+                client_id=context.identity.client_id,
+                agent_id=context.identity.agent_id,
+                arguments_hash=hash_arguments(context.arguments),
+                arguments_redacted=redact_sensitive(context.arguments),
+                expires_at=datetime.now(timezone.utc) + timedelta(seconds=self.default_ttl_seconds),
+            )
+            approvals = self._load_unlocked()
+            approvals[request.id] = request
+            self._save_unlocked(approvals)
+            return request
+
+    def get(self, approval_id: str) -> ApprovalRequest | None:
+        return self._load().get(approval_id)
+
+    def list(self) -> list[ApprovalRequest]:
+        return sorted(self._load().values(), key=lambda item: item.created_at)
+
+    def set_status(
+        self,
+        approval_id: str,
+        status: Literal["pending", "approved", "denied", "expired"],
+        *,
+        decided_by: str | None = None,
+        decision_comment: str | None = None,
+    ) -> ApprovalRequest:
+        with self._locked():
+            approvals = self._load_unlocked()
+            if approval_id not in approvals:
+                raise KeyError(approval_id)
+            update: dict[str, Any] = {"status": status}
+            if status == "pending":
+                update.update(
+                    {
+                        "decided_at": None,
+                        "decided_by": None,
+                        "decision_comment": None,
+                    }
+                )
+            else:
+                update["decided_at"] = datetime.now(timezone.utc)
+                update["decided_by"] = decided_by
+                update["decision_comment"] = decision_comment
+            updated = approvals[approval_id].model_copy(update=update)
+            approvals[approval_id] = updated
+            self._save_unlocked(approvals)
+            return updated
+
+    def is_valid_for(self, approval_id: str, context: RequestContext, policy_id: str) -> bool:
+        approval = self.get(approval_id)
+        if approval is None or not approval.is_active():
+            return False
+        return all(
+            [
+                approval.policy_id == policy_id,
+                approval.server == context.server,
+                approval.capability == context.capability,
+                approval.capability_type == context.capability_type,
+                approval.identity_subject == context.identity.subject,
+                approval.client_id == context.identity.client_id,
+                approval.agent_id == context.identity.agent_id,
+                approval.arguments_hash == hash_arguments(context.arguments),
+            ]
+        )
+
+    def _load(self) -> dict[str, ApprovalRequest]:
+        with self._locked():
+            return self._load_unlocked()
+
+    def _load_unlocked(self) -> dict[str, ApprovalRequest]:
+        if not self.path.exists():
+            return {}
+        raw = json.loads(self.path.read_text(encoding="utf-8"))
+        return {
+            approval_id: ApprovalRequest.model_validate(payload)
+            for approval_id, payload in raw.items()
+        }
+
+    def _save_unlocked(self, approvals: dict[str, ApprovalRequest]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            approval_id: approval.model_dump(mode="json")
+            for approval_id, approval in approvals.items()
+        }
+        tmp_path = self.path.with_name(f".{self.path.name}.{os.getpid()}.tmp")
+        tmp_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        os.replace(tmp_path, self.path)
+
+    @contextlib.contextmanager
+    def _locked(self) -> Any:
+        self.lock_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.lock_path.open("a+", encoding="utf-8") as handle:
+            if fcntl is not None:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                if fcntl is not None:
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def hash_arguments(arguments: dict[str, Any]) -> str:
+    canonical = json.dumps(arguments, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

mcp_zero_trust_layer/audit/__init__.py

@@ -0,0 +1,3 @@
+from .logger import AuditLogger, redact_sensitive, verify_audit_hash_chain
+
+__all__ = ["AuditLogger", "redact_sensitive", "verify_audit_hash_chain"]

mcp_zero_trust_layer/audit/logger.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from mcp_zero_trust_layer.config.models import AuditConfig
+from mcp_zero_trust_layer.core.context import RequestContext
+from mcp_zero_trust_layer.policy import PolicyDecision
+
+SECRET_KEY_RE = re.compile(r"(password|token|api[_-]?key|secret|authorization|cookie)", re.I)
+SECRET_VALUE_RES = [
+    re.compile(r"Bearer\s+[A-Za-z0-9._\-]+", re.I),
+    re.compile(r"sk-[A-Za-z0-9]{20,}"),
+]
+
+
+class AuditLogger:
+    def __init__(self, config: AuditConfig):
+        self.config = config
+
+    def log_decision(
+        self,
+        context: RequestContext,
+        decision: PolicyDecision,
+        *,
+        upstream_called: bool | None = None,
+        upstream_status: str | None = None,
+    ) -> dict[str, Any]:
+        event = {
+            "event_id": f"evt_{uuid4().hex}",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "correlation_id": context.correlation_id or f"corr_{uuid4().hex}",
+            "event_type": "policy_decision",
+            "identity": redact_sensitive(context.identity.model_dump()),
+            "server": context.server,
+            "method": context.method,
+            "capability_type": context.capability_type,
+            "capability": context.capability,
+            "decision": decision.decision,
+            "policy_id": decision.policy_id,
+            "reason": decision.reason,
+            "arguments_redacted": redact_sensitive(context.arguments),
+            "dry_run": decision.dry_run,
+            "approval_required": decision.approval_required,
+            "upstream_called": upstream_called,
+            "upstream_status": upstream_status,
+        }
+        self._write(event)
+        return event
+
+    def log_approval(self, action: str, approval: dict[str, Any]) -> dict[str, Any]:
+        event = {
+            "event_id": f"evt_{uuid4().hex}",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "event_type": "approval",
+            "action": action,
+            "approval": redact_sensitive(approval),
+        }
+        self._write(event)
+        return event
+
+    def _write(self, event: dict[str, Any]) -> None:
+        if self.config.hash_chain:
+            event = self._with_hash(event)
+        line = json.dumps(event, sort_keys=True)
+        if self.config.destination == "stdout":
+            print(line)
+            return
+
+        path = Path(self.config.path)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as handle:
+                handle.write(line + "\n")
+        except OSError:
+            if self.config.strict:
+                raise
+            log_to_stderr(f"mcpzt audit write failed for {path}")
+
+    def _with_hash(self, event: dict[str, Any]) -> dict[str, Any]:
+        event = dict(event)
+        event["previous_event_hash"] = self._previous_hash()
+        event["event_hash"] = event_hash(event)
+        return event
+
+    def _previous_hash(self) -> str | None:
+        if self.config.destination != "file":
+            return None
+        path = Path(self.config.path)
+        if not path.exists():
+            return None
+        try:
+            with path.open("rb") as handle:
+                handle.seek(0, 2)
+                position = handle.tell()
+                if position == 0:
+                    return None
+                buffer = bytearray()
+                position -= 1
+                while position >= 0:
+                    handle.seek(position)
+                    char = handle.read(1)
+                    if char == b"\n" and buffer:
+                        break
+                    if char != b"\n":
+                        buffer.extend(char)
+                    position -= 1
+            last_line = bytes(reversed(buffer)).decode("utf-8")
+            if not last_line:
+                return None
+            event = json.loads(last_line)
+            previous = event.get("event_hash")
+            return previous if isinstance(previous, str) else None
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            return None
+
+
+def event_hash(event: dict[str, Any]) -> str:
+    hashed = {key: value for key, value in event.items() if key != "event_hash"}
+    payload = json.dumps(hashed, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def verify_audit_hash_chain(path: str | Path) -> tuple[bool, str]:
+    previous: str | None = None
+    try:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        return False, str(exc)
+
+    for index, line in enumerate(lines, start=1):
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            return False, f"line {index}: invalid JSON: {exc}"
+        if event.get("previous_event_hash") != previous:
+            return False, f"line {index}: previous_event_hash mismatch"
+        expected = event_hash(event)
+        if event.get("event_hash") != expected:
+            return False, f"line {index}: event_hash mismatch"
+        previous = expected
+    return True, f"verified {len(lines)} event(s)"
+
+
+def redact_sensitive(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            if SECRET_KEY_RE.search(str(key)):
+                redacted[key] = "[REDACTED]"
+            else:
+                redacted[key] = redact_sensitive(item)
+        return redacted
+    if isinstance(value, list):
+        return [redact_sensitive(item) for item in value]
+    if isinstance(value, str):
+        redacted = value
+        for pattern in SECRET_VALUE_RES:
+            redacted = pattern.sub("[REDACTED]", redacted)
+        return redacted
+    return value
+
+
+def log_to_stderr(message: str) -> None:
+    print(message, file=sys.stderr)

mcp_zero_trust_layer/capabilities/__init__.py

@@ -0,0 +1,10 @@
+from .discovery import CapabilityDiff, CapabilitySnapshot, diff_snapshots, discover_capabilities
+from .mapping import lookup_capability_metadata
+
+__all__ = [
+    "CapabilityDiff",
+    "CapabilitySnapshot",
+    "diff_snapshots",
+    "discover_capabilities",
+    "lookup_capability_metadata",
+]

mcp_zero_trust_layer/capabilities/discovery.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from mcp_zero_trust_layer.config.models import MCPZTConfig, ServerConfig
+from mcp_zero_trust_layer.upstream import UpstreamClient
+
+DISCOVERY_METHODS = {
+    "tools": ("tools/list", "tools", "name"),
+    "resources": ("resources/list", "resources", "uri"),
+    "prompts": ("prompts/list", "prompts", "name"),
+}
+
+
+class CapabilitySnapshot(BaseModel):
+    server: str
+    discovered_at: str
+    tools: list[dict[str, Any]] = Field(default_factory=list)
+    resources: list[dict[str, Any]] = Field(default_factory=list)
+    prompts: list[dict[str, Any]] = Field(default_factory=list)
+    errors: dict[str, str] = Field(default_factory=dict)
+
+
+class CapabilityDiff(BaseModel):
+    server: str
+    added: dict[str, list[str]] = Field(default_factory=dict)
+    removed: dict[str, list[str]] = Field(default_factory=dict)
+    changed: dict[str, list[str]] = Field(default_factory=dict)
+
+    def has_changes(self) -> bool:
+        return any(self.added.values()) or any(self.removed.values()) or any(self.changed.values())
+
+
+def discover_capabilities(
+    config: MCPZTConfig,
+    server_name: str,
+    upstream: UpstreamClient,
+) -> CapabilitySnapshot:
+    server = _server(config, server_name)
+    snapshot = CapabilitySnapshot(
+        server=server.name,
+        discovered_at=datetime.now(timezone.utc).isoformat(),
+    )
+    for field, (method, result_key, _identity_key) in DISCOVERY_METHODS.items():
+        request = {"jsonrpc": "2.0", "id": field, "method": method, "params": {}}
+        try:
+            response = upstream.send(server, request)
+        except Exception as exc:  # discovery should collect per-capability errors
+            snapshot.errors[field] = str(exc)
+            continue
+        result = response.get("result") if isinstance(response, dict) else None
+        items = result.get(result_key) if isinstance(result, dict) else []
+        if isinstance(items, list):
+            setattr(snapshot, field, items)
+    return snapshot
+
+
+def diff_snapshots(previous: CapabilitySnapshot, current: CapabilitySnapshot) -> CapabilityDiff:
+    diff = CapabilityDiff(server=current.server)
+    for field, (_method, _result_key, identity_key) in DISCOVERY_METHODS.items():
+        previous_items = _indexed(getattr(previous, field), identity_key)
+        current_items = _indexed(getattr(current, field), identity_key)
+        previous_names = set(previous_items)
+        current_names = set(current_items)
+        diff.added[field] = sorted(current_names - previous_names)
+        diff.removed[field] = sorted(previous_names - current_names)
+        diff.changed[field] = sorted(
+            name
+            for name in previous_names & current_names
+            if _fingerprint(previous_items[name]) != _fingerprint(current_items[name])
+        )
+    return diff
+
+
+def write_snapshot(snapshot: CapabilitySnapshot, path: str | Path) -> None:
+    snapshot_path = Path(path)
+    snapshot_path.parent.mkdir(parents=True, exist_ok=True)
+    snapshot_path.write_text(snapshot.model_dump_json(indent=2) + "\n", encoding="utf-8")
+
+
+def read_snapshot(path: str | Path) -> CapabilitySnapshot:
+    return CapabilitySnapshot.model_validate_json(Path(path).read_text(encoding="utf-8"))
+
+
+def default_snapshot_path(server_name: str) -> Path:
+    return Path(".mcpzt-capabilities") / f"{server_name}.json"
+
+
+def _server(config: MCPZTConfig, name: str) -> ServerConfig:
+    for server in config.servers:
+        if server.name == name:
+            return server
+    raise ValueError(f"unknown server: {name}")
+
+
+def _indexed(items: list[dict[str, Any]], identity_key: str) -> dict[str, dict[str, Any]]:
+    indexed: dict[str, dict[str, Any]] = {}
+    for item in items:
+        identity = item.get(identity_key)
+        if isinstance(identity, str):
+            indexed[identity] = item
+    return indexed
+
+
+def _fingerprint(item: dict[str, Any]) -> str:
+    canonical = json.dumps(item, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+

mcp_zero_trust_layer/capabilities/filtering.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from mcp_zero_trust_layer.config.models import MCPZTConfig
+from mcp_zero_trust_layer.core import RequestContext
+from mcp_zero_trust_layer.identity import Identity
+from mcp_zero_trust_layer.policy.engine import PolicyEngine
+
+CapabilityType = Literal["tool", "resource", "prompt"]
+
+
+def filter_capabilities(
+    config: MCPZTConfig,
+    server: str,
+    capability_type: CapabilityType,
+    capabilities: list[dict[str, Any]],
+    *,
+    identity: Identity | None = None,
+    environment: str | None = None,
+) -> list[dict[str, Any]]:
+    """Return only capabilities visible to the supplied identity/context."""
+    if config.runtime.dry_run:
+        return capabilities
+
+    method_by_type = {
+        "tool": "tools/list",
+        "resource": "resources/list",
+        "prompt": "prompts/list",
+    }
+    name_key_by_type = {
+        "tool": "name",
+        "resource": "uri",
+        "prompt": "name",
+    }
+    engine = PolicyEngine(config)
+    visible: list[dict[str, Any]] = []
+    name_key = name_key_by_type[capability_type]
+
+    for capability in capabilities:
+        capability_name = capability.get(name_key)
+        context = RequestContext(
+            server=server,
+            method=method_by_type[capability_type],
+            capability_type=capability_type,
+            capability=capability_name,
+            identity=identity or Identity(),
+            environment=environment or config.project.environment,
+            config_base_dir=config.config_base_dir,
+        )
+        decision = engine.evaluate(context)
+        if decision.decision in {"allow", "require_approval", "redact", "limit", "transform", "log"}:
+            visible.append(capability)
+
+    return visible

mcp_zero_trust_layer/capabilities/mapping.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from mcp_zero_trust_layer.config.models import CapabilityMetadata, MCPZTConfig
+from mcp_zero_trust_layer.core import RequestContext
+
+
+def lookup_capability_metadata(
+    config: MCPZTConfig, context: RequestContext
+) -> CapabilityMetadata | None:
+    if not context.capability:
+        return None
+
+    server_mappings = config.capability_mappings.get(context.server)
+    if not server_mappings:
+        return None
+
+    if context.capability_type == "tool":
+        return server_mappings.tools.get(context.capability)
+    if context.capability_type == "resource":
+        return server_mappings.resources.get(context.capability)
+    if context.capability_type == "prompt":
+        return server_mappings.prompts.get(context.capability)
+    return None
+

mcp_zero_trust_layer/cli/__init__.py

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