minimalcode 1.5.2__py3-none-any.whl

minimalcode/sandbox/policy.py

@@ -0,0 +1,253 @@
+"""Sandbox configuration, validation, and path/network policy checks."""
+
+from __future__ import annotations
+
+import math
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..errors import ConfigError
+from .network import host_allowed, network_signals
+
+SANDBOX_BACKENDS: tuple[str, ...] = (
+    "auto",
+    "local",
+    "bwrap",
+    "firejail",
+    "sandbox-exec",
+    "docker",
+)
+NETWORK_POLICIES: tuple[str, ...] = ("deny", "allowlist", "allow")
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    """Case-insensitive containment check that works with resolved paths."""
+    child = os.path.normcase(os.path.abspath(str(path)))
+    parent = os.path.normcase(os.path.abspath(str(root))).rstrip(os.sep)
+    if child == parent:
+        return True
+    return child.startswith(parent + os.sep)
+
+
+def _string_tuple(value: Any, label: str) -> tuple[str, ...]:
+    """Validate a configuration value that must be a list of non-empty strings."""
+    if value is None:
+        return ()
+    if not isinstance(value, (list, tuple)):
+        raise ConfigError(f"{label} must be a list of strings")
+    result: list[str] = []
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            raise ConfigError(f"{label} must contain non-empty strings")
+        result.append(item.strip())
+    return tuple(result)
+
+
+def _number(value: Any, label: str) -> float:
+    """Validate a finite numeric setting, rejecting bool as an int subclass."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ConfigError(f"{label} must be a number")
+    try:
+        numeric = float(value)
+    except (OverflowError, ValueError) as exc:
+        raise ConfigError(f"{label} must be a finite number") from exc
+    if not math.isfinite(numeric):
+        raise ConfigError(f"{label} must be a finite number")
+    return numeric
+
+
+@dataclass(frozen=True, slots=True)
+class SandboxPolicy:
+    """Immutable policy shared by path checks, backends, and the runner."""
+
+    enabled: bool
+    backend: str
+    allowed_roots: tuple[Path, ...]
+    network_policy: str
+    allowed_hosts: tuple[str, ...]
+    timeout_seconds: float
+    max_output_chars: int
+    allow_sensitive_files: bool
+    max_memory_mb: int
+    max_processes: int
+    docker_image: str
+    workspace: Path
+
+    @classmethod
+    def disabled(cls, workspace: str | Path) -> SandboxPolicy:
+        """Return a permissive execution policy with file checks still active."""
+        root = Path(workspace).resolve(strict=False)
+        return cls(
+            enabled=False,
+            backend="local",
+            allowed_roots=(root,),
+            network_policy="allow",
+            allowed_hosts=(),
+            timeout_seconds=3600.0,
+            max_output_chars=10_000_000,
+            # File checks stay active in this class's own contract: only the
+            # command execution layer is disabled.
+            allow_sensitive_files=False,
+            max_memory_mb=0,
+            max_processes=0,
+            docker_image="",
+            workspace=root,
+        )
+
+    @classmethod
+    def from_settings(
+        cls,
+        settings: Any,
+        workspace: str | Path,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> SandboxPolicy:
+        """Build a policy from settings, treating malformed values as fatal.
+
+        Configuration validation normally catches these cases, but the same
+        builder is used by tests and embedders, so it must not silently widen
+        the policy when a value is missing or wrong.
+        """
+        root = Path(workspace).resolve()
+        raw = settings.get("sandbox", {}) if hasattr(settings, "get") else {}
+        data: dict[str, Any] = dict(raw) if isinstance(raw, dict) else {}
+        if overrides:
+            data.update(
+                {key: value for key, value in overrides.items() if value is not None}
+            )
+
+        enabled = data.get("enabled", False)
+        if not isinstance(enabled, bool):
+            raise ConfigError("sandbox.enabled must be a boolean")
+        backend = data.get("backend", "local")
+        if not isinstance(backend, str) or backend not in SANDBOX_BACKENDS:
+            raise ConfigError(
+                f"sandbox.backend must be one of {', '.join(SANDBOX_BACKENDS)}"
+            )
+        network_policy = data.get("network_policy", "deny")
+        if network_policy not in NETWORK_POLICIES:
+            raise ConfigError(
+                f"sandbox.network_policy must be one of {', '.join(NETWORK_POLICIES)}"
+            )
+        allowed_hosts = _string_tuple(
+            data.get("allowed_hosts", ()), "sandbox.allowed_hosts"
+        )
+        if network_policy == "allowlist" and not allowed_hosts:
+            raise ConfigError(
+                "sandbox.network_policy is 'allowlist' but sandbox.allowed_hosts is empty"
+            )
+
+        # The workspace is always the first root; extras are resolved relative
+        # to it when not absolute.
+        roots: list[Path] = [root]
+        for entry in _string_tuple(
+            data.get("allowed_roots", ()), "sandbox.allowed_roots"
+        ):
+            try:
+                candidate = Path(entry).expanduser()
+                if not candidate.is_absolute():
+                    candidate = root / candidate
+                resolved = candidate.resolve(strict=False)
+            except (OSError, RuntimeError, ValueError) as exc:
+                raise ConfigError(
+                    f"invalid sandbox.allowed_roots entry: {entry!r}"
+                ) from exc
+            if resolved not in roots:
+                roots.append(resolved)
+
+        timeout = _number(data.get("timeout_seconds", 120), "sandbox.timeout_seconds")
+        if not 1 <= timeout <= 3600:
+            raise ConfigError("sandbox.timeout_seconds must be from 1 to 3600")
+        max_output = data.get("max_output_chars", 60_000)
+        if (
+            isinstance(max_output, bool)
+            or not isinstance(max_output, int)
+            or max_output < 1
+        ):
+            raise ConfigError("sandbox.max_output_chars must be a positive integer")
+        allow_sensitive = data.get("allow_sensitive_files", False)
+        if not isinstance(allow_sensitive, bool):
+            raise ConfigError("sandbox.allow_sensitive_files must be a boolean")
+        max_memory = data.get("max_memory_mb", 0)
+        if (
+            isinstance(max_memory, bool)
+            or not isinstance(max_memory, int)
+            or max_memory < 0
+        ):
+            raise ConfigError("sandbox.max_memory_mb must be a non-negative integer")
+        max_processes = data.get("max_processes", 0)
+        if (
+            isinstance(max_processes, bool)
+            or not isinstance(max_processes, int)
+            or max_processes < 0
+        ):
+            raise ConfigError("sandbox.max_processes must be a non-negative integer")
+        docker_image = data.get("docker_image", "alpine:3")
+        if not isinstance(docker_image, str) or not docker_image.strip():
+            raise ConfigError("sandbox.docker_image must be a non-empty string")
+
+        return cls(
+            enabled=enabled,
+            backend=backend,
+            allowed_roots=tuple(roots),
+            network_policy=network_policy,
+            allowed_hosts=allowed_hosts,
+            timeout_seconds=timeout,
+            max_output_chars=max_output,
+            allow_sensitive_files=allow_sensitive,
+            max_memory_mb=max_memory,
+            max_processes=max_processes,
+            docker_image=docker_image.strip(),
+            workspace=root,
+        )
+
+    def contains(self, path: Path) -> bool:
+        """Return True when ``path`` is inside any allowed root."""
+        return any(_is_within(path, root) for root in self.allowed_roots)
+
+    def write_roots(self, cwd: Path) -> tuple[Path, ...]:
+        """Return roots a filesystem-capable backend must mount read-write."""
+        roots = list(self.allowed_roots)
+        resolved_cwd = Path(cwd).resolve(strict=False)
+        if not any(_is_within(resolved_cwd, root) for root in roots):
+            # An explicit legacy opt-out still needs the working directory
+            # mounted by filesystem-capable backends.
+            roots.append(resolved_cwd)
+        return tuple(roots)
+
+    @property
+    def isolates_network(self) -> bool:
+        """Return True when a backend must remove network access entirely.
+
+        ``allowlist`` isolates exactly like ``deny``. A container or network
+        namespace cannot enforce a host allowlist, so treating it as ``allow``
+        handed the backend's process unrestricted egress and left only the
+        string gate -- best-effort by design -- as the control. The host check
+        stays in `network_denial`; only ``allow`` opens the network.
+        """
+        return self.network_policy != "allow"
+
+    def network_denial(self, command: str) -> str | None:
+        """Return a denial reason, or None when the command may run."""
+        if not self.enabled or self.network_policy == "allow":
+            return None
+        detected, hosts = network_signals(command)
+        if not detected:
+            return None
+        if self.network_policy == "deny":
+            return (
+                "network access is disabled by sandbox.network_policy=deny "
+                "(rejected command resembles a network client)"
+            )
+        if not hosts:
+            return (
+                "sandbox.network_policy=allowlist cannot verify the target host "
+                "for this command"
+            )
+        for host in hosts:
+            if not host_allowed(host, self.allowed_hosts):
+                return f"host {host!r} is not in sandbox.allowed_hosts"
+        return None

minimalcode/sandbox/runner.py

@@ -0,0 +1,347 @@
+"""The unified path and command sandbox runner."""
+
+from __future__ import annotations
+
+import math
+import shutil
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ..errors import ToolError
+from .audit import SandboxAudit
+from .backends import (
+    CommandRequest,
+    LocalSandboxBackend,
+    SandboxBackend,
+    SandboxUnavailable,
+    backend_for,
+)
+from .execution import _child_env, _execute, _resource_limiter
+from .policy import SandboxPolicy
+from .sensitive import is_sensitive_path, sensitive_command_paths
+
+
+def _sensitive_command_denial(command: str) -> str | None:
+    """Return a denial message for credentials a shell command names.
+
+    `read` and `write` already refuse `.env` / `~/.ssh/id_rsa`; without this the
+    same file came back through `type .env` or `cat ~/.ssh/id_rsa`.
+    """
+    hits = sensitive_command_paths(command)
+    if not hits:
+        return None
+    return (
+        f"sensitive path is blocked by sandbox policy: {', '.join(hits)} "
+        "(set sandbox.allow_sensitive_files=true to allow)"
+    )
+
+
+class SandboxRunner:
+    """Single entry point for sandboxed paths and child processes."""
+
+    def __init__(
+        self,
+        policy: SandboxPolicy,
+        *,
+        backend: SandboxBackend | None = None,
+        audit: SandboxAudit | None = None,
+    ) -> None:
+        self.policy = policy
+        self.backend = backend if backend is not None else backend_for(policy.backend)
+        self.audit = audit or SandboxAudit()
+        self.last_temp_dir: Path | None = None
+        self.last_temp_cleaned: bool | None = None
+
+    @classmethod
+    def disabled(cls, workspace: str | Path) -> SandboxRunner:
+        """Create a runner that keeps file checks but skips command isolation."""
+        return cls(
+            SandboxPolicy.disabled(workspace),
+            backend=LocalSandboxBackend(),
+        )
+
+    @classmethod
+    def from_settings(
+        cls,
+        settings: Any,
+        workspace: str | Path,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> SandboxRunner:
+        """Build a runner and policy from configuration."""
+        return cls(
+            SandboxPolicy.from_settings(settings, workspace, overrides=overrides)
+        )
+
+    def resolve_path(
+        self,
+        raw: str | Path,
+        *,
+        cwd: Path,
+        operation: str = "read",
+        allow_outside: bool = False,
+    ) -> Path:
+        """Resolve a tool path and enforce roots and sensitive-file policy.
+
+        ``sandbox.enabled`` only governs how *commands* are executed. The
+        filesystem boundary and the sensitive-file filter stay in force even
+        when the execution layer is disabled, so ``--no-sandbox`` cannot
+        silently turn every file tool into an unrestricted one.
+        """
+        if not isinstance(raw, (str, Path)) or (
+            isinstance(raw, str) and not raw.strip()
+        ):
+            raise ToolError("path must be a non-empty string")
+        try:
+            path = Path(raw).expanduser()
+            if not path.is_absolute():
+                path = Path(cwd) / path
+            resolved = path.resolve(strict=False)
+        except (OSError, RuntimeError, ValueError) as exc:
+            raise ToolError(f"invalid path: {raw}") from exc
+        if not allow_outside and not self.policy.contains(resolved):
+            reason = "path escapes the sandbox allowed roots"
+            self.audit.deny(operation, str(resolved), reason)
+            raise ToolError(
+                f"path is outside workspace: {resolved} (sandbox denied: {reason})"
+            )
+        if not self.policy.allow_sensitive_files and is_sensitive_path(resolved):
+            reason = "sensitive file or directory"
+            self.audit.deny(operation, str(resolved), reason)
+            raise ToolError(
+                f"sensitive path is blocked by sandbox policy: {resolved} "
+                "(set sandbox.allow_sensitive_files=true to allow)"
+            )
+        return resolved
+
+    def is_allowed(
+        self,
+        path: Path,
+        *,
+        operation: str = "read",
+        allow_outside: bool = False,
+    ) -> bool:
+        """Non-raising variant used to filter bulk search results."""
+        candidate = Path(path)
+        if not candidate.is_absolute():
+            # A relative candidate belongs to the tool workspace, not to the
+            # process's own working directory.
+            candidate = self.policy.workspace / candidate
+        try:
+            resolved = candidate.resolve(strict=False)
+        except (OSError, RuntimeError, ValueError):
+            return False
+        if not allow_outside and not self.policy.contains(resolved):
+            return False
+        return self.policy.allow_sensitive_files or not is_sensitive_path(resolved)
+
+    def summary(self) -> dict[str, Any]:
+        """Return the sandbox status payload shown by the CLI."""
+        # One audit snapshot keeps the counter and the history consistent even
+        # when worker threads record denials at the same time.
+        audit = self.audit.summary()
+        return {
+            "enabled": self.policy.enabled,
+            "backend": self.backend.name,
+            "backend_requested": self.policy.backend,
+            "backend_available": self.backend.available(),
+            "network_policy": self.policy.network_policy,
+            "allowed_hosts": list(self.policy.allowed_hosts),
+            "allowed_roots": [str(root) for root in self.policy.allowed_roots],
+            "allow_sensitive_files": self.policy.allow_sensitive_files,
+            "timeout_seconds": self.policy.timeout_seconds,
+            "max_output_chars": self.policy.max_output_chars,
+            "max_memory_mb": self.policy.max_memory_mb,
+            "max_processes": self.policy.max_processes,
+            "total_denials": audit["total_denials"],
+            "recent_denials": audit["recent"][-5:],
+            "notes": audit["notes"][-5:],
+            "last_temp_cleaned": self.last_temp_cleaned,
+        }
+
+    def _sandbox_metadata(self, cleaned: bool | None) -> dict[str, Any]:
+        """Describe the execution environment attached to command results."""
+        return {
+            "backend": self.backend.name,
+            "network_policy": self.policy.network_policy,
+            "temp_dir_cleaned": cleaned,
+        }
+
+    def _denied_result(
+        self,
+        *,
+        shell_label: str,
+        message: str,
+        cleaned: bool | None = None,
+    ) -> dict[str, Any]:
+        """Shape a refusal exactly like a command result for the caller."""
+        return {
+            "status": "error",
+            "shell": shell_label,
+            "message": message,
+            "sandbox": self._sandbox_metadata(cleaned),
+        }
+
+    def run_argv(
+        self,
+        argv: list[str] | tuple[str, ...],
+        *,
+        command: str | None = None,
+        shell_kind: str = "",
+        shell_label: str = "",
+        cwd: Path,
+        timeout: float,
+        max_output_chars: int,
+        env: Mapping[str, str] | None = None,
+        stdin_text: str | None = None,
+    ) -> dict[str, Any]:
+        """Execute argv through the configured backend and policy."""
+        if not argv:
+            return {
+                "status": "error",
+                "shell": shell_label,
+                "message": "command is empty",
+            }
+        try:
+            requested_timeout = float(timeout)
+        except (TypeError, ValueError, OverflowError):
+            return {
+                "status": "error",
+                "shell": shell_label,
+                "message": "timeout must be a number",
+            }
+        if math.isnan(requested_timeout):
+            return {
+                "status": "error",
+                "shell": shell_label,
+                "message": "timeout must be a number",
+            }
+        try:
+            requested_output = int(max_output_chars)
+        except (TypeError, ValueError, OverflowError):
+            requested_output = 1
+        requested_output = max(1, requested_output)
+
+        # The sensitive-file rule is a path policy, not an execution setting: it
+        # stays in force when the sandbox is disabled, exactly like `read` and
+        # `write`. Only shell strings are inspected; internal argv searches
+        # filter their own results through `is_allowed`.
+        if command is not None and not self.policy.allow_sensitive_files:
+            sensitive_reason = _sensitive_command_denial(command)
+            if sensitive_reason is not None:
+                self.audit.deny("shell", command, sensitive_reason)
+                return self._denied_result(
+                    shell_label=shell_label, message=sensitive_reason
+                )
+
+        # With execution isolation disabled, still run through the same bounded
+        # executor so timeouts and output caps behave consistently.
+        if not self.policy.enabled:
+            result = _execute(
+                list(argv),
+                cwd=cwd,
+                timeout=max(1.0, min(requested_timeout, 3600.0)),
+                max_output_chars=requested_output,
+                env=_child_env(env, None),
+                stdin_text=stdin_text,
+                shell_label=shell_label,
+            )
+            result.setdefault("sandbox", self._sandbox_metadata(None))
+            return result
+
+        effective_timeout = max(
+            1.0, min(requested_timeout, self.policy.timeout_seconds)
+        )
+        # Output policy applies to shell strings; internal argv searches have
+        # their own byte/line budgets.
+        effective_output = (
+            min(requested_output, self.policy.max_output_chars)
+            if command is not None
+            else requested_output
+        )
+
+        if command is not None:
+            denial = self.policy.network_denial(command)
+            if denial is not None:
+                self.audit.deny("shell", command, denial)
+                return self._denied_result(
+                    shell_label=shell_label,
+                    message=f"network access denied by sandbox policy: {denial}",
+                )
+
+        if not self.backend.available():
+            reason = (
+                f"sandbox backend {self.backend.name!r} is unavailable; "
+                "refusing to execute (fail-closed)"
+            )
+            self.audit.deny("shell", command or " ".join(argv[:3]), reason)
+            return self._denied_result(shell_label=shell_label, message=reason)
+
+        temp_dir: Path | None = None
+        cleaned: bool | None = None
+        failure: str | None = None
+        try:
+            try:
+                temp_dir = Path(tempfile.mkdtemp(prefix="minimalcode-sandbox-"))
+            except OSError as exc:
+                reason = f"cannot create sandbox temporary directory: {exc}"
+                self.audit.deny("shell", command or " ".join(argv[:3]), reason)
+                return self._denied_result(shell_label=shell_label, message=reason)
+            self.last_temp_dir = temp_dir
+            request = CommandRequest(
+                argv=tuple(argv),
+                command=command,
+                shell_kind=shell_kind,
+                shell_label=shell_label,
+                cwd=Path(cwd),
+                temp_dir=temp_dir,
+                policy=self.policy,
+            )
+            try:
+                prepared = self.backend.wrap(request)
+            except SandboxUnavailable as exc:
+                failure = str(exc)
+                self.audit.deny("shell", command or " ".join(argv[:3]), failure)
+                result: dict[str, Any] = {}
+            if failure is None:
+                result = _execute(
+                    prepared,
+                    cwd=Path(cwd),
+                    timeout=effective_timeout,
+                    max_output_chars=effective_output,
+                    env=_child_env(env, self.backend.temp_path(request)),
+                    stdin_text=stdin_text,
+                    shell_label=shell_label,
+                    preexec=_resource_limiter(self.policy, effective_timeout),
+                    on_timeout=lambda: self.backend.cleanup(request),
+                )
+        finally:
+            # Per-command temp directories are always removed, including when
+            # backend wrapping or process startup raises.
+            cleaned = True
+            if temp_dir is not None:
+                try:
+                    shutil.rmtree(temp_dir)
+                except OSError as exc:
+                    cleaned = False
+                    self.audit.note(
+                        f"temporary directory cleanup failed: {temp_dir}: {exc}"
+                    )
+            self.last_temp_cleaned = cleaned
+
+        if failure is not None:
+            return self._denied_result(
+                shell_label=shell_label, message=failure, cleaned=cleaned
+            )
+        if result.get("status") == "timeout":
+            self.audit.note(
+                f"command timed out after {effective_timeout:g}s; process tree killed"
+            )
+        if result.get("truncated"):
+            self.audit.note(
+                f"command output truncated at {effective_output} characters"
+            )
+        result["sandbox"] = self._sandbox_metadata(cleaned)
+        return result