spidershield 0.3.0__py3-none-any.whl

spidershield/__init__.py

@@ -0,0 +1,166 @@
+"""SpiderShield -- Scan, improve, certify, and guard MCP servers.
+
+Public API:
+    from spidershield import SpiderGuard, Decision
+
+    guard = SpiderGuard(policy="balanced")
+    result = guard.check(tool_name="read_file", arguments={"path": "/etc/passwd"})
+    # result.decision == Decision.DENY
+    # result.reason == "System file access blocked"
+    # result.suggestion == "Use application-level files instead"
+
+    # With audit logging:
+    guard = SpiderGuard(policy="strict", audit=True)
+
+    # MCP proxy shortcut:
+    from spidershield import guard_mcp_server
+    guard_mcp_server(["npx", "server-filesystem", "/tmp"], policy="balanced")
+"""
+
+__version__ = "0.3.0"
+
+from .guard.context import CallContext
+from .guard.core import RuntimeGuard
+from .guard.decision import Decision, InterceptResult
+from .guard.policy import PolicyEngine, PolicyRule
+
+
+class SpiderGuard:
+    """High-level API for SpiderShield Runtime Guard.
+
+    Usage:
+        guard = SpiderGuard(policy="balanced")
+        result = guard.check("read_file", {"path": "/etc/passwd"})
+        if result.denied:
+            print(result.reason, result.suggestion)
+
+    With audit logging:
+        guard = SpiderGuard(policy="strict", audit=True)
+
+    With DLP (redact secrets from tool output):
+        guard = SpiderGuard(policy="strict", dlp="redact")
+    """
+
+    def __init__(
+        self,
+        policy: str = "balanced",
+        *,
+        audit: bool = False,
+        audit_dir: str | None = None,
+        dlp: str | None = None,
+    ) -> None:
+        engine = PolicyEngine.from_name_or_path(policy)
+
+        logger = None
+        if audit:
+            from .audit.logger import AuditLogger
+            logger = AuditLogger(audit_dir)
+
+        dlp_engine = None
+        if dlp:
+            from .dlp.engine import DLPEngine
+            dlp_engine = DLPEngine(action=dlp)
+
+        self._guard = RuntimeGuard(
+            policy_engine=engine,
+            audit_logger=logger,
+            dlp_engine=dlp_engine,
+        )
+        self._call_index = 0
+
+    def check(
+        self,
+        tool_name: str,
+        arguments: dict | None = None,
+        *,
+        session_id: str = "",
+        agent_id: str = "",
+    ) -> InterceptResult:
+        """Check if a tool call is allowed (pre-execution)."""
+        ctx = CallContext(
+            session_id=session_id or "default",
+            agent_id=agent_id or "default",
+            tool_name=tool_name,
+            arguments=arguments or {},
+            call_index=self._call_index,
+        )
+        self._call_index += 1
+        return self._guard.before_call(ctx)
+
+    def after_check(
+        self,
+        tool_name: str,
+        tool_result: object,
+        *,
+        session_id: str = "",
+        agent_id: str = "",
+        call_index: int | None = None,
+    ) -> object:
+        """Inspect tool output after execution (DLP scan)."""
+        ctx = CallContext(
+            session_id=session_id or "default",
+            agent_id=agent_id or "default",
+            tool_name=tool_name,
+            arguments={},
+            call_index=call_index if call_index is not None else self._call_index,
+        )
+        return self._guard.after_call(ctx, tool_result)
+
+    @property
+    def guard(self) -> RuntimeGuard:
+        """Access the underlying RuntimeGuard for advanced usage."""
+        return self._guard
+
+    @property
+    def policy_engine(self) -> PolicyEngine:
+        """Access the policy engine for inspection."""
+        return self._guard.policy_engine
+
+
+def guard_mcp_server(
+    server_cmd: list[str],
+    *,
+    policy: str = "balanced",
+    verbose: bool = False,
+    audit: bool = True,
+    audit_dir: str | None = None,
+) -> int:
+    """Start an MCP proxy with security guard around a server.
+
+    Usage:
+        from spidershield import guard_mcp_server
+        guard_mcp_server(["npx", "server-filesystem", "/tmp"], policy="balanced")
+
+    Args:
+        server_cmd: Command to start the real MCP server.
+        policy: Policy preset (strict/balanced/permissive) or YAML file path.
+        verbose: Enable verbose logging to stderr.
+        audit: Enable audit logging (default: True).
+        audit_dir: Custom audit log directory.
+
+    Returns:
+        Server process return code.
+    """
+    from .adapters.mcp_proxy import run_mcp_proxy
+
+    return run_mcp_proxy(
+        server_cmd=server_cmd,
+        policy=policy,
+        verbose=verbose,
+        audit_dir=audit_dir,
+        no_audit=not audit,
+    )
+
+
+__all__ = [
+    # High-level API
+    "SpiderGuard",
+    "guard_mcp_server",
+    # Core types
+    "CallContext",
+    "Decision",
+    "InterceptResult",
+    "PolicyEngine",
+    "PolicyRule",
+    "RuntimeGuard",
+]

spidershield/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running SpiderShield as ``python -m spidershield``."""
+
+from spidershield.cli import main
+
+main()

spidershield/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""SpiderShield Framework Adapters.
+
+Adapters bridge between agent frameworks and the RuntimeGuard core.
+"""
+
+from .base import AdapterBase, AdapterStats
+from .mcp_proxy import MCPProxyGuard, run_mcp_proxy
+from .standalone import StandaloneGuard, run_standalone_guard
+
+__all__ = [
+    "AdapterBase",
+    "AdapterStats",
+    "MCPProxyGuard",
+    "StandaloneGuard",
+    "run_mcp_proxy",
+    "run_standalone_guard",
+]

spidershield/adapters/base.py

@@ -0,0 +1,144 @@
+"""AdapterBase — abstract base for SpiderShield framework adapters.
+
+All adapters bridge between an agent framework and the RuntimeGuard core.
+Each adapter intercepts tool calls, evaluates them via the guard,
+and returns results (or blocks them).
+
+Concrete adapters:
+    - MCPProxyGuard (mcp_proxy.py): stdio MCP proxy
+    - StandaloneGuard (standalone.py): wraps any subprocess
+"""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..guard.context import CallContext
+from ..guard.core import RuntimeGuard
+from ..guard.decision import Decision, InterceptResult
+
+
+class AdapterBase(ABC):
+    """Abstract base class for SpiderShield adapters.
+
+    Adapters sit between an agent framework and the RuntimeGuard.
+    They intercept tool calls, evaluate them, and forward or block.
+    """
+
+    def __init__(
+        self,
+        guard: RuntimeGuard,
+        *,
+        session_id: str = "",
+        verbose: bool = False,
+        dry_run: bool = False,
+    ) -> None:
+        self._guard = guard
+        self._session_id = session_id or uuid.uuid4().hex[:12]
+        self._verbose = verbose
+        self._dry_run = dry_run
+        self._call_index = 0
+        self._stats = AdapterStats()
+
+    @property
+    def guard(self) -> RuntimeGuard:
+        return self._guard
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    @property
+    def stats(self) -> AdapterStats:
+        return self._stats
+
+    @abstractmethod
+    def run(self, **kwargs: Any) -> int:
+        """Start the adapter. Returns exit code."""
+        ...
+
+    def evaluate_tool_call(
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> InterceptResult:
+        """Evaluate a tool call against the guard.
+
+        In dry-run mode, always allows but still logs the decision.
+        """
+        ctx = CallContext(
+            session_id=self._session_id,
+            agent_id="adapter",
+            tool_name=tool_name,
+            arguments=arguments,
+            call_index=self._call_index,
+            framework=self.framework_name,
+        )
+        self._call_index += 1
+        result = self._guard.before_call(ctx)
+
+        # Update stats
+        self._stats.total_calls += 1
+        if result.decision == Decision.ALLOW:
+            self._stats.allowed += 1
+        elif result.decision == Decision.DENY:
+            self._stats.denied += 1
+        elif result.decision == Decision.ESCALATE:
+            self._stats.escalated += 1
+
+        # In dry-run mode, log but don't enforce
+        if self._dry_run and result.decision == Decision.DENY:
+            self._log(f"DRY-RUN DENY (would block): {tool_name} — {result.reason}")
+            return InterceptResult(
+                decision=Decision.ALLOW,
+                reason=f"[dry-run] {result.reason}",
+                suggestion=result.suggestion,
+                policy_matched=result.policy_matched,
+            )
+
+        return result
+
+    def evaluate_tool_result(
+        self, tool_name: str, tool_result: Any
+    ) -> Any:
+        """Evaluate tool output (DLP scan)."""
+        ctx = CallContext(
+            session_id=self._session_id,
+            agent_id="adapter",
+            tool_name=tool_name,
+            arguments={},
+            call_index=self._call_index,
+            framework=self.framework_name,
+        )
+        return self._guard.after_call(ctx, tool_result)
+
+    @property
+    def framework_name(self) -> str:
+        """Override in subclasses to identify the framework."""
+        return "unknown"
+
+    def _log(self, message: str) -> None:
+        """Log to stderr if verbose."""
+        if self._verbose:
+            import sys
+            print(f"[SpiderShield] {message}", file=sys.stderr)
+
+
+class AdapterStats:
+    """Simple counter for adapter-level statistics."""
+
+    __slots__ = ("total_calls", "allowed", "denied", "escalated")
+
+    def __init__(self) -> None:
+        self.total_calls = 0
+        self.allowed = 0
+        self.denied = 0
+        self.escalated = 0
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "total_calls": self.total_calls,
+            "allowed": self.allowed,
+            "denied": self.denied,
+            "escalated": self.escalated,
+        }

spidershield/adapters/mcp_proxy.py

@@ -0,0 +1,221 @@
+"""MCP Proxy Adapter — stdio proxy between MCP Client and Server.
+
+Sits between Claude Desktop / Cursor and the real MCP server.
+Intercepts tools/call requests and enforces security policies.
+
+Architecture:
+    MCP Client (Claude Desktop)
+         ↓ stdin
+    SpiderShield MCP Proxy
+         ├─ tools/call → RuntimeGuard.before_call()
+         │   ├─ ALLOW → forward to server
+         │   ├─ DENY → return error with reason + suggestion
+         │   └─ ESCALATE → terminal prompt → allow/deny
+         ├─ other messages → passthrough
+         ↓ stdout
+    MCP Server (real server subprocess)
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import threading
+from typing import IO, Any
+
+from ..guard.core import RuntimeGuard
+from ..guard.decision import Decision
+from ..guard.policy import PolicyEngine
+from ..utils.jsonrpc import (
+    extract_tool_info,
+    is_tool_call,
+    make_denied_response,
+    parse_message,
+    serialize_message,
+)
+from .base import AdapterBase
+
+
+class MCPProxyGuard(AdapterBase):
+    """MCP stdio proxy with security guard.
+
+    Reads JSON-RPC messages from client_in, evaluates tools/call
+    against the RuntimeGuard, and forwards allowed calls to the
+    real MCP server subprocess.
+    """
+
+    @property
+    def framework_name(self) -> str:
+        return "mcp"
+
+    def run(
+        self,
+        server_cmd: list[str] | None = None,
+        client_in: IO[str] | None = None,
+        client_out: IO[str] | None = None,
+        **kwargs: Any,
+    ) -> int:
+        """Start proxy: launch server subprocess and relay messages.
+
+        Args:
+            server_cmd: Command to start the real MCP server.
+            client_in: Client input stream (default: sys.stdin).
+            client_out: Client output stream (default: sys.stdout).
+
+        Returns:
+            Server process return code.
+        """
+        if not server_cmd:
+            raise ValueError("server_cmd is required")
+
+        client_in = client_in or sys.stdin
+        client_out = client_out or sys.stdout
+
+        # Launch real MCP server as subprocess
+        proc = subprocess.Popen(
+            server_cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=sys.stderr,
+            text=True,
+            bufsize=1,
+        )
+
+        try:
+            # Thread: relay server stdout → client stdout
+            relay_thread = threading.Thread(
+                target=self._relay_server_to_client,
+                args=(proc.stdout, client_out),
+                daemon=True,
+            )
+            relay_thread.start()
+
+            # Main thread: relay client stdin → (guard) → server stdin
+            self._relay_client_to_server(client_in, proc.stdin, client_out)
+
+        except (KeyboardInterrupt, BrokenPipeError):
+            pass
+        finally:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+
+        return proc.returncode or 0
+
+    def _relay_client_to_server(
+        self,
+        client_in: IO[str],
+        server_in: IO[str],
+        client_out: IO[str],
+    ) -> None:
+        """Read from client, evaluate tool calls, forward to server."""
+        for line in client_in:
+            msg = parse_message(line)
+            if msg is None:
+                # Non-JSON line — passthrough
+                server_in.write(line)
+                server_in.flush()
+                continue
+
+            if is_tool_call(msg):
+                # Intercept tools/call
+                tool_name, arguments = extract_tool_info(msg)
+                result = self.evaluate_tool_call(tool_name, arguments)
+
+                if result.decision == Decision.DENY:
+                    # Return error to client, don't forward to server
+                    error_msg = make_denied_response(
+                        request_id=msg.get("id"),
+                        reason=result.reason,
+                        suggestion=result.suggestion,
+                        policy_matched=result.policy_matched,
+                    )
+                    client_out.write(serialize_message(error_msg))
+                    client_out.flush()
+                    self._log(f"DENY: {tool_name} — {result.reason}")
+                    continue
+
+                if result.decision == Decision.ESCALATE:
+                    # Terminal prompt for human approval
+                    if not self._prompt_human(tool_name, arguments, result.reason):
+                        error_msg = make_denied_response(
+                            request_id=msg.get("id"),
+                            reason="Denied by human review",
+                            suggestion=result.suggestion,
+                        )
+                        client_out.write(serialize_message(error_msg))
+                        client_out.flush()
+                        self._log(f"ESCALATE→DENY: {tool_name}")
+                        continue
+                    self._log(f"ESCALATE→ALLOW: {tool_name}")
+
+                self._log(f"ALLOW: {tool_name}")
+
+            # Forward to server (passthrough or allowed tool call)
+            server_in.write(line)
+            server_in.flush()
+
+    def _relay_server_to_client(
+        self,
+        server_out: IO[str],
+        client_out: IO[str],
+    ) -> None:
+        """Relay server responses to client (with DLP scanning)."""
+        for line in server_out:
+            # DLP scan on server responses
+            scanned = self.evaluate_tool_result("server_response", line)
+            if isinstance(scanned, str):
+                client_out.write(scanned)
+            else:
+                client_out.write(line)
+            client_out.flush()
+
+    def _prompt_human(
+        self, tool_name: str, arguments: dict[str, Any], reason: str
+    ) -> bool:
+        """Terminal prompt for ESCALATE decisions."""
+        print(
+            "\n[SpiderShield] Tool call requires approval:",
+            file=sys.stderr,
+        )
+        print(f"  Tool: {tool_name}", file=sys.stderr)
+        print(f"  Args: {json.dumps(arguments, indent=2)}", file=sys.stderr)
+        print(f"  Reason: {reason}", file=sys.stderr)
+        try:
+            answer = input("  Allow? [y/N] ").strip().lower()
+            return answer in ("y", "yes")
+        except (EOFError, KeyboardInterrupt):
+            return False
+
+
+def run_mcp_proxy(
+    server_cmd: list[str],
+    policy: str = "balanced",
+    verbose: bool = False,
+    audit_dir: str | None = None,
+    no_audit: bool = False,
+    dry_run: bool = False,
+) -> int:
+    """Convenience function to run an MCP proxy with security guard.
+
+    Args:
+        server_cmd: Command to start the real MCP server.
+        policy: Policy preset name or YAML file path.
+        verbose: Enable verbose logging to stderr.
+        audit_dir: Custom audit log directory (default: ~/.spidershield/audit/).
+        no_audit: Disable audit logging.
+        dry_run: Log decisions but don't enforce denials.
+
+    Returns:
+        Server process return code.
+    """
+    from ..audit.logger import AuditLogger
+
+    engine = PolicyEngine.from_name_or_path(policy)
+    logger = None if no_audit else AuditLogger(audit_dir)
+    guard = RuntimeGuard(policy_engine=engine, audit_logger=logger)
+    proxy = MCPProxyGuard(guard, verbose=verbose, dry_run=dry_run)
+    return proxy.run(server_cmd=server_cmd)