tweek 0.1.0__py3-none-any.whl

tweek/mcp/screening.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Tweek MCP Screening - Shared screening logic for MCP gateway and proxy.
+
+Extracts the screening pipeline from TweekMCPServer so it can be reused
+by both the MCP gateway (which converts should_prompt -> blocked) and
+the MCP proxy (which queues should_prompt for human approval).
+"""
+
+import logging
+from typing import Any, Dict
+
+from tweek.screening.context import ScreeningContext
+
+logger = logging.getLogger(__name__)
+
+
+def run_mcp_screening(context: ScreeningContext) -> Dict[str, Any]:
+    """
+    Run the shared screening pipeline on a tool call.
+
+    Returns dict with:
+        allowed: bool       - Whether execution is permitted
+        blocked: bool       - Whether execution is hard-blocked
+        should_prompt: bool - Whether human confirmation is needed
+        reason: Optional[str]
+        findings: List[Dict]
+    """
+    try:
+        from tweek.hooks.pre_tool_use import (
+            TierManager,
+            PatternMatcher,
+            run_compliance_scans,
+            run_screening_plugins,
+        )
+        from tweek.logging.security_log import get_logger as get_sec_logger
+
+        sec_logger = get_sec_logger()
+
+        # Resolve tier
+        tier_mgr = TierManager()
+        effective_tier, escalation = tier_mgr.get_effective_tier(
+            context.tool_name, context.content
+        )
+        context.tier = effective_tier
+
+        # Run compliance scans on input
+        should_block, compliance_msg, compliance_findings = run_compliance_scans(
+            content=context.content,
+            direction="input",
+            logger=sec_logger,
+            session_id=context.session_id,
+            tool_name=context.tool_name,
+        )
+
+        if should_block:
+            return {
+                "allowed": False,
+                "blocked": True,
+                "should_prompt": False,
+                "reason": compliance_msg or "Blocked by compliance scan",
+                "findings": compliance_findings,
+            }
+
+        # Skip further screening for safe tier
+        if effective_tier == "safe":
+            return {
+                "allowed": True,
+                "blocked": False,
+                "should_prompt": False,
+                "reason": None,
+                "findings": [],
+            }
+
+        # Pattern matching
+        pattern_matcher = PatternMatcher()
+        match = pattern_matcher.check(context.content)
+
+        if match:
+            pattern_name = match.get("pattern", match.get("name", "unknown"))
+            return {
+                "allowed": False,
+                "blocked": True,
+                "should_prompt": False,
+                "reason": f"Blocked by pattern match: {pattern_name}",
+                "findings": [match],
+            }
+
+        # Run screening plugins
+        legacy_context = context.to_legacy_dict()
+        allowed, should_prompt, screen_msg, screen_findings = run_screening_plugins(
+            tool_name=context.tool_name,
+            content=context.content,
+            context=legacy_context,
+            logger=sec_logger,
+        )
+
+        if not allowed:
+            return {
+                "allowed": False,
+                "blocked": True,
+                "should_prompt": False,
+                "reason": screen_msg or "Blocked by screening plugin",
+                "findings": screen_findings,
+            }
+
+        if should_prompt:
+            return {
+                "allowed": True,
+                "blocked": False,
+                "should_prompt": True,
+                "reason": screen_msg or "Requires user confirmation",
+                "findings": screen_findings,
+            }
+
+        return {
+            "allowed": True,
+            "blocked": False,
+            "should_prompt": False,
+            "reason": None,
+            "findings": [],
+        }
+
+    except ImportError as e:
+        logger.warning(f"Screening modules not available: {e}")
+        # Fail open with warning if screening not available
+        return {
+            "allowed": True,
+            "blocked": False,
+            "should_prompt": False,
+            "reason": f"Warning: screening unavailable ({e})",
+            "findings": [],
+        }
+    except Exception as e:
+        logger.error(f"Screening error: {e}")
+        # Fail closed on unexpected errors
+        return {
+            "allowed": False,
+            "blocked": True,
+            "should_prompt": False,
+            "reason": f"Screening error: {e}",
+            "findings": [],
+        }
+
+
+def run_output_scan(content: str) -> Dict[str, Any]:
+    """
+    Scan output content for leaked credentials or sensitive data.
+
+    Returns dict with:
+        blocked: bool
+        reason: Optional[str]
+        findings: List[Dict]
+    """
+    try:
+        from tweek.hooks.pre_tool_use import run_compliance_scans
+        from tweek.logging.security_log import get_logger as get_sec_logger
+
+        sec_logger = get_sec_logger()
+        should_block, msg, findings = run_compliance_scans(
+            content=content,
+            direction="output",
+            logger=sec_logger,
+            tool_name="mcp_output_scan",
+        )
+
+        if should_block:
+            return {"blocked": True, "reason": msg, "findings": findings}
+
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.debug(f"Output scan error: {e}")
+
+    return {"blocked": False}

tweek/mcp/server.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""
+Tweek MCP Gateway Server
+
+Minimal MCP server exposing only tools that add genuinely new capabilities
+not available as built-in desktop client tools:
+- tweek_vault: Secure keychain credential retrieval
+- tweek_status: Security status and activity reporting
+
+Desktop clients' built-in tools (Bash, Read, Write, etc.) cannot be
+intercepted via MCP. For upstream MCP server interception, use the
+proxy mode: tweek mcp proxy
+
+Usage:
+    tweek mcp serve       # stdio mode (desktop clients)
+"""
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import (
+        TextContent,
+        Tool,
+    )
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+
+from tweek.screening.context import ScreeningContext
+
+logger = logging.getLogger(__name__)
+
+# Version for MCP server identification
+MCP_SERVER_VERSION = "0.2.0"
+
+
+def _check_mcp_available():
+    """Raise RuntimeError if MCP SDK is not installed."""
+    if not MCP_AVAILABLE:
+        raise RuntimeError(
+            "MCP SDK not installed. Install with: pip install 'tweek[mcp]' "
+            "or pip install mcp"
+        )
+
+
+class TweekMCPServer:
+    """
+    Tweek MCP Gateway.
+
+    Exposes vault and status tools via MCP. These are genuinely new
+    capabilities not available as built-in desktop client tools.
+
+    For intercepting upstream MCP server tool calls, use TweekMCPProxy
+    from tweek.mcp.proxy instead.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        _check_mcp_available()
+        self.config = config or {}
+        self.server = Server("tweek-security")
+        self._setup_handlers()
+        self._request_count = 0
+        self._blocked_count = 0
+
+    def _setup_handlers(self):
+        """Register MCP protocol handlers."""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return the list of tools this server provides."""
+            tools = []
+
+            tool_configs = self.config.get("mcp", {}).get("gateway", {}).get("tools", {})
+
+            if tool_configs.get("vault", True):
+                tools.append(Tool(
+                    name="tweek_vault",
+                    description=(
+                        "Retrieve a credential from Tweek's secure vault. "
+                        "Credentials are stored in the system keychain, not in .env files. "
+                        "Use this instead of reading .env files or hardcoding secrets."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "skill": {
+                                "type": "string",
+                                "description": "Skill namespace for the credential",
+                            },
+                            "key": {
+                                "type": "string",
+                                "description": "Credential key name",
+                            },
+                        },
+                        "required": ["skill", "key"],
+                    },
+                ))
+
+            if tool_configs.get("status", True):
+                tools.append(Tool(
+                    name="tweek_status",
+                    description=(
+                        "Show Tweek security status including active plugins, "
+                        "recent activity, threat summary, and proxy statistics."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "detail": {
+                                "type": "string",
+                                "enum": ["summary", "plugins", "activity", "threats"],
+                                "description": "Level of detail (default: summary)",
+                            },
+                        },
+                    },
+                ))
+
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool calls."""
+            self._request_count += 1
+
+            handler_map = {
+                "tweek_vault": self._handle_vault,
+                "tweek_status": self._handle_status,
+            }
+
+            handler = handler_map.get(name)
+            if handler is None:
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({
+                        "error": f"Unknown tool: {name}",
+                        "available_tools": list(handler_map.keys()),
+                    }),
+                )]
+
+            try:
+                result = await handler(arguments)
+                return [TextContent(type="text", text=result)]
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e), "tool": name}),
+                )]
+
+    def _build_context(
+        self,
+        tool_name: str,
+        content: str,
+        tool_input: Optional[Dict[str, Any]] = None,
+    ) -> ScreeningContext:
+        """Build a ScreeningContext for MCP tool calls."""
+        return ScreeningContext(
+            tool_name=tool_name,
+            content=content,
+            tier="default",
+            working_dir=os.getcwd(),
+            source="mcp",
+            client_name=self.config.get("client_name"),
+            tool_input=tool_input,
+        )
+
+    def _run_screening(self, context: ScreeningContext) -> Dict[str, Any]:
+        """
+        Run the shared screening pipeline.
+
+        In gateway mode, should_prompt is converted to blocked
+        since there is no interactive user to confirm.
+        """
+        from tweek.mcp.screening import run_mcp_screening
+
+        result = run_mcp_screening(context)
+
+        if result.get("should_prompt"):
+            self._blocked_count += 1
+            return {
+                "allowed": False,
+                "blocked": True,
+                "reason": f"Requires user confirmation: {result.get('reason', '')}",
+                "findings": result.get("findings", []),
+            }
+
+        if result.get("blocked"):
+            self._blocked_count += 1
+
+        return {
+            "allowed": result.get("allowed", False),
+            "blocked": result.get("blocked", False),
+            "reason": result.get("reason"),
+            "findings": result.get("findings", []),
+        }
+
+    async def _handle_vault(self, arguments: Dict[str, Any]) -> str:
+        """Handle tweek_vault tool call."""
+        skill = arguments.get("skill", "")
+        key = arguments.get("key", "")
+
+        # Screen vault access
+        context = self._build_context("Vault", f"vault:{skill}/{key}", arguments)
+        screening = self._run_screening(context)
+
+        if screening["blocked"]:
+            return json.dumps({
+                "blocked": True,
+                "reason": screening["reason"],
+            })
+
+        try:
+            from tweek.vault.cross_platform import CrossPlatformVault
+
+            vault = CrossPlatformVault()
+            value = vault.get(skill, key)
+
+            if value is None:
+                return json.dumps({
+                    "error": f"Credential not found: {skill}/{key}",
+                    "available": False,
+                })
+
+            return json.dumps({
+                "value": value,
+                "skill": skill,
+                "key": key,
+            })
+
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+    async def _handle_status(self, arguments: Dict[str, Any]) -> str:
+        """Handle tweek_status tool call."""
+        detail = arguments.get("detail", "summary")
+
+        try:
+            status = {
+                "version": MCP_SERVER_VERSION,
+                "source": "mcp",
+                "mode": "gateway",
+                "gateway_requests": self._request_count,
+                "gateway_blocked": self._blocked_count,
+            }
+
+            if detail in ("summary", "plugins"):
+                try:
+                    from tweek.plugins import get_registry
+                    registry = get_registry()
+                    stats = registry.get_stats()
+                    status["plugins"] = stats
+                except ImportError:
+                    status["plugins"] = {"error": "Plugin system not available"}
+
+            if detail in ("summary", "activity"):
+                try:
+                    from tweek.logging.security_log import get_logger as get_sec_logger
+                    sec_logger = get_sec_logger()
+                    recent = sec_logger.get_recent(limit=10)
+                    status["recent_activity"] = [
+                        {
+                            "timestamp": str(e.timestamp),
+                            "event_type": e.event_type.value,
+                            "tool": e.tool_name,
+                            "decision": e.decision,
+                        }
+                        for e in recent
+                    ] if recent else []
+                except (ImportError, Exception):
+                    status["recent_activity"] = []
+
+            # Include approval queue stats if available
+            try:
+                from tweek.mcp.approval import ApprovalQueue
+                queue = ApprovalQueue()
+                status["approval_queue"] = queue.get_stats()
+            except Exception:
+                pass
+
+            return json.dumps(status, indent=2)
+
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+
+async def run_server(config: Optional[Dict[str, Any]] = None):
+    """
+    Run the Tweek MCP gateway server on stdio transport.
+
+    Exposes tweek_vault and tweek_status tools. For upstream MCP
+    server interception, use run_proxy() instead.
+    """
+    _check_mcp_available()
+
+    server = TweekMCPServer(config=config)
+
+    logger.info("Starting Tweek MCP Gateway...")
+    logger.info(f"Version: {MCP_SERVER_VERSION}")
+    logger.info("Tools: tweek_vault, tweek_status")
+    logger.info("For upstream MCP interception, use: tweek mcp proxy")
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.server.run(
+            read_stream,
+            write_stream,
+            server.server.create_initialization_options(),
+        )
+
+
+def create_server(config: Optional[Dict[str, Any]] = None) -> "TweekMCPServer":
+    """Create a TweekMCPServer instance for programmatic use."""
+    return TweekMCPServer(config=config)

tweek/platform/__init__.py

@@ -0,0 +1,131 @@
+"""
+Platform detection and cross-platform support for Tweek.
+
+Tweek supports:
+- macOS: Full support (Keychain via keyring, sandbox-exec)
+- Linux: Full support (Secret Service via keyring, firejail optional)
+- Windows: Partial support (Credential Locker via keyring, no sandbox)
+"""
+
+import platform
+import shutil
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class Platform(Enum):
+    """Supported platforms."""
+    MACOS = "Darwin"
+    LINUX = "Linux"
+    WINDOWS = "Windows"
+    UNKNOWN = "Unknown"
+
+
+@dataclass
+class PlatformCapabilities:
+    """Capabilities available on the current platform."""
+    platform: Platform
+    vault_available: bool
+    vault_backend: str
+    sandbox_available: bool
+    sandbox_tool: Optional[str]
+    sandbox_install_hint: Optional[str]
+
+
+# Detect current platform
+PLATFORM_NAME = platform.system()
+
+if PLATFORM_NAME == "Darwin":
+    PLATFORM = Platform.MACOS
+elif PLATFORM_NAME == "Linux":
+    PLATFORM = Platform.LINUX
+elif PLATFORM_NAME == "Windows":
+    PLATFORM = Platform.WINDOWS
+else:
+    PLATFORM = Platform.UNKNOWN
+
+IS_MACOS = PLATFORM == Platform.MACOS
+IS_LINUX = PLATFORM == Platform.LINUX
+IS_WINDOWS = PLATFORM == Platform.WINDOWS
+
+
+def get_sandbox_tool() -> Optional[str]:
+    """Detect available sandbox tool."""
+    if IS_MACOS:
+        if shutil.which("sandbox-exec"):
+            return "sandbox-exec"
+    elif IS_LINUX:
+        if shutil.which("firejail"):
+            return "firejail"
+        elif shutil.which("bwrap"):
+            return "bubblewrap"
+    return None
+
+
+def get_sandbox_install_hint() -> Optional[str]:
+    """Get installation hint for sandbox tool."""
+    if IS_MACOS:
+        return None  # sandbox-exec is always available
+    elif IS_LINUX:
+        # Detect package manager
+        if shutil.which("apt"):
+            return "sudo apt install firejail"
+        elif shutil.which("dnf"):
+            return "sudo dnf install firejail"
+        elif shutil.which("pacman"):
+            return "sudo pacman -S firejail"
+        elif shutil.which("zypper"):
+            return "sudo zypper install firejail"
+        elif shutil.which("apk"):
+            return "sudo apk add firejail"
+        else:
+            return "Install firejail from https://firejail.wordpress.com/download-2/"
+    elif IS_WINDOWS:
+        return "Sandbox not available on Windows"
+    return None
+
+
+def get_vault_backend() -> str:
+    """Get the vault backend name for current platform."""
+    if IS_MACOS:
+        return "macOS Keychain"
+    elif IS_LINUX:
+        return "Secret Service (GNOME Keyring/KWallet)"
+    elif IS_WINDOWS:
+        return "Windows Credential Locker"
+    return "Unknown"
+
+
+def get_capabilities() -> PlatformCapabilities:
+    """Get capabilities for the current platform."""
+    sandbox_tool = get_sandbox_tool()
+
+    return PlatformCapabilities(
+        platform=PLATFORM,
+        vault_available=True,  # keyring works everywhere
+        vault_backend=get_vault_backend(),
+        sandbox_available=sandbox_tool is not None,
+        sandbox_tool=sandbox_tool,
+        sandbox_install_hint=get_sandbox_install_hint() if not sandbox_tool else None,
+    )
+
+
+def get_linux_package_manager() -> Optional[tuple[str, list[str]]]:
+    """Detect Linux package manager and return firejail install command."""
+    if not IS_LINUX:
+        return None
+
+    managers = {
+        "apt": ["sudo", "apt", "install", "-y", "firejail"],
+        "dnf": ["sudo", "dnf", "install", "-y", "firejail"],
+        "pacman": ["sudo", "pacman", "-S", "--noconfirm", "firejail"],
+        "zypper": ["sudo", "zypper", "install", "-y", "firejail"],
+        "apk": ["sudo", "apk", "add", "firejail"],
+    }
+
+    for manager, command in managers.items():
+        if shutil.which(manager):
+            return manager, command
+
+    return None