truthound 1.0.8__py3-none-any.whl

truthound/plugins/security/sandbox/context.py

@@ -0,0 +1,158 @@
+"""Sandbox context implementation.
+
+This module provides the concrete implementation of SandboxContext
+that tracks sandbox state and resource usage.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from truthound.plugins.security.protocols import SecurityPolicy, SandboxContext
+
+
+@dataclass
+class SandboxContextImpl:
+    """Concrete implementation of SandboxContext.
+
+    Tracks the state of a sandbox instance including resource usage
+    and lifecycle information.
+
+    Attributes:
+        plugin_id: ID of the plugin being sandboxed
+        policy: Security policy applied to this sandbox
+        sandbox_id: Unique ID for this sandbox instance
+        created_at: When the sandbox was created
+        started_at: When execution started (None if not started)
+        finished_at: When execution finished (None if not finished)
+    """
+
+    plugin_id: str
+    policy: SecurityPolicy
+    sandbox_id: str = ""
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+    # Internal state
+    _process_id: int | None = field(default=None, repr=False)
+    _container_id: str | None = field(default=None, repr=False)
+    _alive: bool = field(default=True, repr=False)
+    _memory_used_mb: float = field(default=0.0, repr=False)
+    _cpu_percent: float = field(default=0.0, repr=False)
+    _start_time: float = field(default=0.0, repr=False)
+
+    def __post_init__(self) -> None:
+        """Generate sandbox ID if not provided."""
+        if not self.sandbox_id:
+            self.sandbox_id = self._generate_id()
+
+    def _generate_id(self) -> str:
+        """Generate unique sandbox ID."""
+        content = f"{self.plugin_id}-{self.created_at.isoformat()}-{id(self)}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def is_alive(self) -> bool:
+        """Check if sandbox is still running."""
+        return self._alive
+
+    def get_resource_usage(self) -> dict[str, float]:
+        """Get current resource usage.
+
+        Returns:
+            Dict with memory_mb, cpu_percent, and execution_time_sec
+        """
+        execution_time = 0.0
+        if self._start_time > 0:
+            if self.finished_at:
+                execution_time = (self.finished_at - self.started_at).total_seconds() if self.started_at else 0.0
+            else:
+                execution_time = time.perf_counter() - self._start_time
+
+        return {
+            "memory_mb": self._memory_used_mb,
+            "cpu_percent": self._cpu_percent,
+            "execution_time_sec": execution_time,
+        }
+
+    def mark_started(self) -> None:
+        """Mark sandbox as started."""
+        self.started_at = datetime.now(timezone.utc)
+        self._start_time = time.perf_counter()
+
+    def mark_finished(self) -> None:
+        """Mark sandbox as finished."""
+        self.finished_at = datetime.now(timezone.utc)
+        self._alive = False
+
+    def mark_terminated(self) -> None:
+        """Mark sandbox as terminated."""
+        self._alive = False
+        if not self.finished_at:
+            self.finished_at = datetime.now(timezone.utc)
+
+    def update_resource_usage(
+        self,
+        memory_mb: float | None = None,
+        cpu_percent: float | None = None,
+    ) -> None:
+        """Update resource usage metrics."""
+        if memory_mb is not None:
+            self._memory_used_mb = memory_mb
+        if cpu_percent is not None:
+            self._cpu_percent = cpu_percent
+
+    def set_process_id(self, pid: int) -> None:
+        """Set the process ID for process-based sandboxes."""
+        self._process_id = pid
+
+    def set_container_id(self, container_id: str) -> None:
+        """Set the container ID for container-based sandboxes."""
+        self._container_id = container_id
+
+    @property
+    def process_id(self) -> int | None:
+        """Get process ID if applicable."""
+        return self._process_id
+
+    @property
+    def container_id(self) -> str | None:
+        """Get container ID if applicable."""
+        return self._container_id
+
+    @property
+    def execution_time_sec(self) -> float:
+        """Get current execution time in seconds."""
+        return self.get_resource_usage()["execution_time_sec"]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "plugin_id": self.plugin_id,
+            "sandbox_id": self.sandbox_id,
+            "created_at": self.created_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "finished_at": self.finished_at.isoformat() if self.finished_at else None,
+            "is_alive": self._alive,
+            "resource_usage": self.get_resource_usage(),
+            "process_id": self._process_id,
+            "container_id": self._container_id,
+        }
+
+
+# Verify implementation satisfies protocol
+def _verify_protocol() -> None:
+    """Verify SandboxContextImpl implements SandboxContext protocol."""
+    context: SandboxContext = SandboxContextImpl(
+        plugin_id="test",
+        policy=SecurityPolicy.standard(),
+    )
+    assert hasattr(context, "plugin_id")
+    assert hasattr(context, "policy")
+    assert hasattr(context, "sandbox_id")
+    assert callable(context.is_alive)
+    assert callable(context.get_resource_usage)

truthound/plugins/security/sandbox/engines/__init__.py

@@ -0,0 +1,19 @@
+"""Sandbox engine implementations.
+
+This module contains concrete implementations of the SandboxEngine protocol:
+- NoopSandboxEngine: No isolation (for trusted plugins)
+- ProcessSandboxEngine: Subprocess isolation with resource limits
+- ContainerSandboxEngine: Docker/Podman container isolation
+"""
+
+from __future__ import annotations
+
+from truthound.plugins.security.sandbox.engines.noop import NoopSandboxEngine
+from truthound.plugins.security.sandbox.engines.process import ProcessSandboxEngine
+from truthound.plugins.security.sandbox.engines.container import ContainerSandboxEngine
+
+__all__ = [
+    "NoopSandboxEngine",
+    "ProcessSandboxEngine",
+    "ContainerSandboxEngine",
+]

truthound/plugins/security/sandbox/engines/container.py

@@ -0,0 +1,379 @@
+"""Container-based sandbox engine using Docker/Podman.
+
+This engine provides maximum isolation by running code in containers:
+- Complete filesystem isolation
+- Network isolation
+- Resource limits via cgroups
+- Seccomp profiles for syscall filtering
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import pickle
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+
+from truthound.plugins.security.protocols import (
+    IsolationLevel,
+    SecurityPolicy,
+    SandboxContext,
+)
+from truthound.plugins.security.sandbox.context import SandboxContextImpl
+from truthound.plugins.security.exceptions import (
+    SandboxTimeoutError,
+    SandboxResourceError,
+    SandboxError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ContainerSandboxEngine:
+    """Container-based sandbox engine using Docker or Podman.
+
+    Provides the strongest isolation by running code in containers.
+    Automatically detects and uses Docker or Podman.
+
+    Features:
+        - Complete filesystem isolation
+        - Network isolation (configurable)
+        - Memory and CPU limits via cgroups
+        - Read-only filesystem option
+        - Configurable image
+    """
+
+    DEFAULT_IMAGE = "python:3.11-slim"
+
+    @property
+    def isolation_level(self) -> IsolationLevel:
+        """Return the isolation level provided by this engine."""
+        return IsolationLevel.CONTAINER
+
+    def __init__(
+        self,
+        image: str = DEFAULT_IMAGE,
+        runtime: str | None = None,
+    ) -> None:
+        """Initialize the container sandbox engine.
+
+        Args:
+            image: Default Docker image to use
+            runtime: Container runtime ("docker" or "podman"), auto-detected if None
+        """
+        self._image = image
+        self._runtime = runtime
+        self._contexts: dict[str, SandboxContextImpl] = {}
+        self._container_ids: list[str] = []
+
+    async def _detect_runtime(self) -> str:
+        """Detect available container runtime."""
+        if self._runtime:
+            return self._runtime
+
+        # Try Docker first, then Podman
+        for runtime in ["docker", "podman"]:
+            try:
+                process = await asyncio.create_subprocess_exec(
+                    runtime, "version",
+                    stdout=asyncio.subprocess.DEVNULL,
+                    stderr=asyncio.subprocess.DEVNULL,
+                )
+                await process.communicate()
+                if process.returncode == 0:
+                    self._runtime = runtime
+                    return runtime
+            except FileNotFoundError:
+                continue
+
+        raise SandboxError(
+            "No container runtime available. Install Docker or Podman."
+        )
+
+    def create_sandbox(
+        self,
+        plugin_id: str,
+        policy: SecurityPolicy,
+    ) -> SandboxContext:
+        """Create a sandbox context.
+
+        Args:
+            plugin_id: Plugin identifier
+            policy: Security policy to apply
+
+        Returns:
+            SandboxContext for execution
+        """
+        context = SandboxContextImpl(
+            plugin_id=plugin_id,
+            policy=policy,
+        )
+        self._contexts[context.sandbox_id] = context
+        logger.debug(f"Created container sandbox context for {plugin_id}")
+        return context
+
+    async def execute(
+        self,
+        context: SandboxContext,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute function in container.
+
+        Args:
+            context: Sandbox context
+            func: Function to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Function result
+
+        Raises:
+            SandboxTimeoutError: If execution times out
+            SandboxResourceError: If resource limits exceeded
+            SandboxError: If container execution fails
+        """
+        impl = self._get_impl(context)
+        impl.mark_started()
+        policy = context.policy
+        limits = policy.resource_limits
+
+        # Detect runtime
+        runtime = await self._detect_runtime()
+
+        # Create temporary directory
+        temp_dir = Path(tempfile.mkdtemp(prefix="truthound_container_"))
+        data_path = temp_dir / "data.pkl"
+        result_path = temp_dir / "result.pkl"
+        script_path = temp_dir / "executor.py"
+
+        try:
+            # Serialize function and data
+            with open(data_path, "wb") as f:
+                pickle.dump({
+                    "func": func,
+                    "args": args,
+                    "kwargs": kwargs,
+                }, f)
+
+            # Create executor script
+            script = self._create_executor_script()
+            with open(script_path, "w") as f:
+                f.write(script)
+
+            # Build container command
+            container_cmd = self._build_container_command(
+                runtime=runtime,
+                policy=policy,
+                temp_dir=temp_dir,
+            )
+
+            # Execute container
+            process = await asyncio.create_subprocess_exec(
+                *container_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+
+            try:
+                # Wait with timeout
+                stdout, stderr = await asyncio.wait_for(
+                    process.communicate(),
+                    timeout=limits.max_execution_time_sec + 10,
+                )
+            except asyncio.TimeoutError:
+                process.kill()
+                await process.wait()
+                impl.mark_terminated()
+                raise SandboxTimeoutError(
+                    f"Container timed out after {limits.max_execution_time_sec}s",
+                    plugin_id=context.plugin_id,
+                    sandbox_id=context.sandbox_id,
+                    timeout_seconds=limits.max_execution_time_sec,
+                    execution_time=impl.execution_time_sec,
+                )
+
+            impl.mark_finished()
+
+            # Check for result
+            if not result_path.exists():
+                stderr_text = stderr.decode() if stderr else "No output"
+                raise SandboxError(
+                    f"Container produced no result. stderr: {stderr_text}",
+                    plugin_id=context.plugin_id,
+                    sandbox_id=context.sandbox_id,
+                )
+
+            # Load result
+            with open(result_path, "rb") as f:
+                result_data = pickle.load(f)
+
+            if result_data.get("success"):
+                return result_data.get("result")
+
+            # Handle errors
+            error_type = result_data.get("error", "UnknownError")
+            error_msg = result_data.get("message", "Unknown error")
+
+            if error_type == "MemoryError":
+                raise SandboxResourceError(
+                    f"Container memory limit exceeded: {error_msg}",
+                    plugin_id=context.plugin_id,
+                    sandbox_id=context.sandbox_id,
+                    resource_type="memory",
+                    limit=limits.max_memory_mb,
+                )
+            else:
+                raise SandboxError(
+                    f"Container error ({error_type}): {error_msg}",
+                    plugin_id=context.plugin_id,
+                    sandbox_id=context.sandbox_id,
+                )
+
+        finally:
+            # Cleanup temp directory
+            if temp_dir.exists():
+                shutil.rmtree(temp_dir, ignore_errors=True)
+
+    def _build_container_command(
+        self,
+        runtime: str,
+        policy: SecurityPolicy,
+        temp_dir: Path,
+    ) -> list[str]:
+        """Build container run command."""
+        limits = policy.resource_limits
+
+        cmd = [
+            runtime, "run",
+            "--rm",  # Auto-remove container
+            f"--memory={limits.max_memory_mb}m",
+            f"--cpus={limits.max_cpu_percent / 100}",
+            f"--network={'bridge' if policy.allow_network else 'none'}",
+            "-v", f"{temp_dir}:/workspace:rw",
+            "-w", "/workspace",
+        ]
+
+        # Add read-only root filesystem if not allowing file writes
+        if not policy.allow_file_write:
+            cmd.extend([
+                "--read-only",
+                "--tmpfs", "/tmp:rw,noexec,nosuid",
+            ])
+
+        # Add security options
+        cmd.extend([
+            "--security-opt", "no-new-privileges",
+            "--cap-drop", "ALL",
+        ])
+
+        # Add image and command
+        cmd.extend([
+            self._image,
+            "python", "/workspace/executor.py",
+        ])
+
+        return cmd
+
+    def _create_executor_script(self) -> str:
+        """Create Python script for container execution."""
+        return '''
+import sys
+import pickle
+
+try:
+    # Load data
+    with open("/workspace/data.pkl", "rb") as f:
+        data = pickle.load(f)
+
+    func = data["func"]
+    args = data["args"]
+    kwargs = data["kwargs"]
+
+    # Execute
+    result = func(*args, **kwargs)
+
+    # Save result
+    with open("/workspace/result.pkl", "wb") as f:
+        pickle.dump({"success": True, "result": result}, f)
+
+except MemoryError as e:
+    with open("/workspace/result.pkl", "wb") as f:
+        pickle.dump({"success": False, "error": "MemoryError", "message": str(e)}, f)
+except Exception as e:
+    with open("/workspace/result.pkl", "wb") as f:
+        pickle.dump({"success": False, "error": type(e).__name__, "message": str(e)}, f)
+'''
+
+    def terminate(self, context: SandboxContext) -> None:
+        """Terminate sandbox container.
+
+        Args:
+            context: Sandbox to terminate
+        """
+        impl = self._get_impl(context)
+        impl.mark_terminated()
+
+        # Kill container if running
+        container_id = impl.container_id
+        if container_id and self._runtime:
+            try:
+                asyncio.create_task(self._kill_container(container_id))
+            except Exception:
+                pass
+
+        self._contexts.pop(context.sandbox_id, None)
+
+    async def _kill_container(self, container_id: str) -> None:
+        """Kill a container by ID."""
+        if not self._runtime:
+            return
+        try:
+            process = await asyncio.create_subprocess_exec(
+                self._runtime, "rm", "-f", container_id,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            await process.wait()
+        except Exception as e:
+            logger.warning(f"Failed to kill container {container_id}: {e}")
+
+    async def cleanup(self) -> None:
+        """Clean up all sandbox resources."""
+        # Terminate all contexts
+        for context in list(self._contexts.values()):
+            self.terminate(context)
+        self._contexts.clear()
+
+        # Kill any remaining containers
+        for container_id in self._container_ids:
+            await self._kill_container(container_id)
+        self._container_ids.clear()
+
+    def _get_impl(self, context: SandboxContext) -> SandboxContextImpl:
+        """Get implementation from context."""
+        if isinstance(context, SandboxContextImpl):
+            return context
+        impl = self._contexts.get(context.sandbox_id)
+        if impl is None:
+            raise ValueError(f"Unknown sandbox context: {context.sandbox_id}")
+        return impl
+
+    async def check_available(self) -> bool:
+        """Check if container runtime is available.
+
+        Returns:
+            True if Docker or Podman is available
+        """
+        try:
+            await self._detect_runtime()
+            return True
+        except SandboxError:
+            return False

truthound/plugins/security/sandbox/engines/noop.py

@@ -0,0 +1,144 @@
+"""No-op sandbox engine for trusted plugins.
+
+This engine provides no isolation but still enforces timeout limits.
+Use only for trusted plugins that don't require sandboxing.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Callable
+
+from truthound.plugins.security.protocols import (
+    IsolationLevel,
+    SecurityPolicy,
+    SandboxContext,
+)
+from truthound.plugins.security.sandbox.context import SandboxContextImpl
+from truthound.plugins.security.exceptions import SandboxTimeoutError
+
+logger = logging.getLogger(__name__)
+
+
+class NoopSandboxEngine:
+    """No-isolation sandbox engine.
+
+    Executes code directly in the current process with only timeout
+    enforcement. Suitable for trusted plugins that don't need isolation.
+
+    Warning:
+        This engine provides NO security isolation. Only use for
+        fully trusted plugins in development or controlled environments.
+    """
+
+    @property
+    def isolation_level(self) -> IsolationLevel:
+        """Return the isolation level provided by this engine."""
+        return IsolationLevel.NONE
+
+    def __init__(self) -> None:
+        """Initialize the no-op sandbox engine."""
+        self._contexts: dict[str, SandboxContextImpl] = {}
+
+    def create_sandbox(
+        self,
+        plugin_id: str,
+        policy: SecurityPolicy,
+    ) -> SandboxContext:
+        """Create a sandbox context (no actual sandbox created).
+
+        Args:
+            plugin_id: Plugin identifier
+            policy: Security policy (only timeout is enforced)
+
+        Returns:
+            SandboxContext for tracking
+        """
+        context = SandboxContextImpl(
+            plugin_id=plugin_id,
+            policy=policy,
+        )
+        self._contexts[context.sandbox_id] = context
+        logger.debug(f"Created no-op sandbox context for {plugin_id}")
+        return context
+
+    async def execute(
+        self,
+        context: SandboxContext,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute function with timeout enforcement only.
+
+        Args:
+            context: Sandbox context
+            func: Function to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Function result
+
+        Raises:
+            SandboxTimeoutError: If execution times out
+        """
+        impl = self._get_impl(context)
+        impl.mark_started()
+        timeout = context.policy.resource_limits.max_execution_time_sec
+
+        try:
+            # Check if function is a coroutine
+            if asyncio.iscoroutinefunction(func):
+                result = await asyncio.wait_for(
+                    func(*args, **kwargs),
+                    timeout=timeout,
+                )
+            else:
+                # Run sync function in executor with timeout
+                loop = asyncio.get_event_loop()
+                result = await asyncio.wait_for(
+                    loop.run_in_executor(None, lambda: func(*args, **kwargs)),
+                    timeout=timeout,
+                )
+
+            impl.mark_finished()
+            return result
+
+        except asyncio.TimeoutError:
+            impl.mark_terminated()
+            raise SandboxTimeoutError(
+                f"Execution timed out after {timeout}s",
+                plugin_id=context.plugin_id,
+                sandbox_id=context.sandbox_id,
+                timeout_seconds=timeout,
+                execution_time=impl.execution_time_sec,
+            )
+
+    def terminate(self, context: SandboxContext) -> None:
+        """Terminate sandbox (no-op for this engine).
+
+        Args:
+            context: Sandbox to terminate
+        """
+        impl = self._get_impl(context)
+        impl.mark_terminated()
+        self._contexts.pop(context.sandbox_id, None)
+
+    async def cleanup(self) -> None:
+        """Clean up all contexts."""
+        for context in self._contexts.values():
+            context.mark_terminated()
+        self._contexts.clear()
+
+    def _get_impl(self, context: SandboxContext) -> SandboxContextImpl:
+        """Get implementation from context."""
+        if isinstance(context, SandboxContextImpl):
+            return context
+        # Fallback: look up by sandbox_id
+        impl = self._contexts.get(context.sandbox_id)
+        if impl is None:
+            raise ValueError(f"Unknown sandbox context: {context.sandbox_id}")
+        return impl