forgex-cli 0.1.0__py3-none-any.whl

forgex/sandbox/executor.py

@@ -0,0 +1,418 @@
+"""Restricted command execution (spec sections 19, 20, 45, 75).
+
+Every command runs as an ARGV LIST — never a shell string.
+Guarantees:
+  * cwd must resolve inside the workspace (path traversal rejected)
+  * child environment is sanitized (parent secrets are never inherited)
+  * timeouts are enforced
+  * Docker sandbox option with container confinement
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shlex
+import shutil
+import time
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from forgex.config.schema import ForgexConfig
+from forgex.sandbox.policies import (
+    ApprovalCallback,
+    CommandPolicy,
+    Decision,
+    resolve_approval,
+)
+from forgex.schemas.error import CommandDeniedError, SandboxError
+from forgex.utils.paths import resolve_in_workspace
+
+logger = logging.getLogger("forgex.sandbox")
+
+_SAFE_ENV_VARS = (
+    "PATH",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "USERPROFILE",
+    "SYSTEMROOT",
+    "SYSTEMDRIVE",
+    "COMSPEC",
+    "PATHEXT",
+    "TEMP",
+    "TMP",
+)
+
+
+@dataclass
+class CommandResult:
+    argv: list[str]
+    exit_code: int
+    stdout: str = ""
+    stderr: str = ""
+    timed_out: bool = False
+    duration_ms: float = 0.0
+    truncated: bool = False
+
+
+class CommandExecutor(ABC):
+    @abstractmethod
+    async def run(
+        self,
+        command: list[str] | str,
+        *,
+        cwd: str = ".",
+        timeout: float | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> CommandResult:
+        pass
+
+
+class PolicyGatedExecutor(CommandExecutor):
+    def __init__(
+        self,
+        workspace: Path,
+        policy: CommandPolicy,
+        approval: ApprovalCallback | None = None,
+        default_timeout: int = 120,
+        max_output_bytes: int = 1_000_000,
+    ) -> None:
+        self.workspace = Path(workspace).resolve()
+        self.policy = policy
+        self.approval = approval
+        self.default_timeout = default_timeout
+        self.max_output_bytes = max_output_bytes
+
+    async def run(
+        self,
+        command: list[str] | str,
+        *,
+        cwd: str = ".",
+        timeout: float | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> CommandResult:
+        if isinstance(command, str):
+            argv = shlex.split(command)
+        else:
+            argv = list(command)
+
+        if not argv:
+            raise CommandDeniedError("Empty command")
+
+        # 1. Policy check
+        decision = self.policy.check(argv)
+        if decision.decision is Decision.DENY:
+            raise CommandDeniedError(f"Command denied by policy: {decision.reason}")
+        if decision.decision is Decision.APPROVAL:
+            approved = resolve_approval(self.policy.approval_mode, shlex.join(argv), self.approval)
+            if not approved:
+                raise CommandDeniedError(f"Command not approved: {shlex.join(argv)}")
+
+        # 2. Working directory confinement
+        try:
+            workdir = resolve_in_workspace(self.workspace, cwd)
+        except Exception as exc:
+            raise SandboxError(f"Working directory escapes workspace: {exc}") from exc
+
+        return await self._execute(argv, workdir, timeout or self.default_timeout, env)
+
+    @abstractmethod
+    async def _execute(
+        self,
+        argv: list[str],
+        workdir: Path,
+        timeout: float,
+        env: Mapping[str, str] | None,
+    ) -> CommandResult:
+        pass
+
+
+class RestrictedLocalExecutor(PolicyGatedExecutor):
+    async def _execute(
+        self,
+        argv: list[str],
+        workdir: Path,
+        timeout: float,
+        env: Mapping[str, str] | None,
+    ) -> CommandResult:
+        # Sanitize environment
+        child_env: dict[str, str] = {}
+        for var in _SAFE_ENV_VARS:
+            val = os.environ.get(var)
+            if val is not None:
+                child_env[var] = val
+        if env:
+            child_env.update(env)
+
+        start = time.perf_counter()
+        timed_out = False
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *argv,
+                cwd=str(workdir),
+                env=child_env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except FileNotFoundError:
+            duration = (time.perf_counter() - start) * 1000
+            return CommandResult(
+                argv=argv,
+                exit_code=127,
+                stderr=f"command not found: {argv[0]}",
+                duration_ms=duration,
+            )
+        except OSError as exc:
+            duration = (time.perf_counter() - start) * 1000
+            return CommandResult(
+                argv=argv,
+                exit_code=126,
+                stderr=f"failed to execute command: {exc}",
+                duration_ms=duration,
+            )
+
+        try:
+            stdout_b, stderr_b = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        except TimeoutError:
+            timed_out = True
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+            stdout_b, stderr_b = await proc.communicate()
+        except asyncio.CancelledError:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+            raise
+
+        duration = (time.perf_counter() - start) * 1000
+        truncated = False
+        if len(stdout_b) > self.max_output_bytes:
+            stdout_b = stdout_b[: self.max_output_bytes]
+            truncated = True
+        if len(stderr_b) > self.max_output_bytes:
+            stderr_b = stderr_b[: self.max_output_bytes]
+            truncated = True
+
+        return CommandResult(
+            argv=argv,
+            exit_code=proc.returncode if proc.returncode is not None else -1,
+            stdout=stdout_b.decode("utf-8", errors="replace"),
+            stderr=stderr_b.decode("utf-8", errors="replace"),
+            timed_out=timed_out,
+            duration_ms=duration,
+            truncated=truncated,
+        )
+
+
+class DockerExecutor(PolicyGatedExecutor):
+    DEFAULT_IMAGE = "python:3.12-slim"
+
+    def __init__(
+        self,
+        workspace: Path,
+        policy: CommandPolicy,
+        approval: ApprovalCallback | None = None,
+        image: str = DEFAULT_IMAGE,
+        cpu_limit: str | None = None,
+        memory_limit: str | None = None,
+        network: bool = False,
+        read_only: bool = True,
+        user: str | None = None,
+        default_timeout: int = 120,
+        max_output_bytes: int = 1_000_000,
+    ) -> None:
+        super().__init__(workspace, policy, approval, default_timeout, max_output_bytes)
+        self.image = image
+        self.cpu_limit = cpu_limit
+        self.memory_limit = memory_limit
+        self.network = network
+        self.read_only = read_only
+        self.user = user
+
+    def build_docker_argv(
+        self,
+        argv: list[str],
+        workdir: Path,
+        container_name: str,
+        env: Mapping[str, str] | None = None,
+    ) -> list[str]:
+        cmd = [
+            "docker",
+            "run",
+            "--rm",
+            "--name",
+            container_name,
+            "--network",
+            "bridge" if self.network else "none",
+            "--cap-drop",
+            "ALL",
+            "--security-opt",
+            "no-new-privileges",
+        ]
+        if self.read_only:
+            cmd.extend(["--read-only", "--tmpfs", "/tmp"])
+        if self.cpu_limit:
+            cmd.extend(["--cpus", self.cpu_limit])
+        if self.memory_limit:
+            cmd.extend(["--memory", self.memory_limit])
+
+        # UID/GID
+        if self.user:
+            cmd.extend(["--user", self.user])
+        elif os.name == "posix":
+            cmd.extend(["--user", f"{os.getuid()}:{os.getgid()}"])
+
+        # Mount workspace
+        ws_resolved = self.workspace.resolve()
+        cmd.extend(["-v", f"{ws_resolved}:/workspace"])
+
+        # Working directory inside container
+        try:
+            rel = workdir.relative_to(ws_resolved).as_posix()
+            w_path = f"/workspace/{rel}" if rel and rel != "." else "/workspace"
+        except ValueError:
+            w_path = "/workspace"
+        cmd.extend(["-w", w_path])
+
+        if env:
+            for k, v in env.items():
+                cmd.extend(["-e", f"{k}={v}"])
+
+        cmd.append(self.image)
+        cmd.extend(argv)
+        return cmd
+
+    async def _execute(
+        self,
+        argv: list[str],
+        workdir: Path,
+        timeout: float,
+        env: Mapping[str, str] | None,
+    ) -> CommandResult:
+        name = f"forgex-{uuid.uuid4().hex[:8]}"
+        docker_cmd = self.build_docker_argv(argv, workdir, name, env)
+
+        start = time.perf_counter()
+        timed_out = False
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *docker_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except OSError as exc:
+            duration = (time.perf_counter() - start) * 1000
+            return CommandResult(
+                argv=argv,
+                exit_code=125,
+                stderr=f"docker execution failed: {exc}",
+                duration_ms=duration,
+            )
+
+        try:
+            stdout_b, stderr_b = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        except TimeoutError:
+            timed_out = True
+            try:
+                # Force kill container
+                kill_p = await asyncio.create_subprocess_exec(
+                    "docker", "kill", name,
+                    stdout=asyncio.subprocess.DEVNULL,
+                    stderr=asyncio.subprocess.DEVNULL,
+                )
+                await kill_p.wait()
+                proc.kill()
+            except Exception:  # noqa: BLE001
+                pass
+            stdout_b, stderr_b = await proc.communicate()
+        except asyncio.CancelledError:
+            try:
+                kill_p = await asyncio.create_subprocess_exec(
+                    "docker", "kill", name,
+                    stdout=asyncio.subprocess.DEVNULL,
+                    stderr=asyncio.subprocess.DEVNULL,
+                )
+                await kill_p.wait()
+                proc.kill()
+            except Exception:  # noqa: BLE001
+                pass
+            raise
+
+        duration = (time.perf_counter() - start) * 1000
+        truncated = False
+        if len(stdout_b) > self.max_output_bytes:
+            stdout_b = stdout_b[: self.max_output_bytes]
+            truncated = True
+        if len(stderr_b) > self.max_output_bytes:
+            stderr_b = stderr_b[: self.max_output_bytes]
+            truncated = True
+
+        return CommandResult(
+            argv=argv,
+            exit_code=proc.returncode if proc.returncode is not None else -1,
+            stdout=stdout_b.decode("utf-8", errors="replace"),
+            stderr=stderr_b.decode("utf-8", errors="replace"),
+            timed_out=timed_out,
+            duration_ms=duration,
+            truncated=truncated,
+        )
+
+
+def docker_available() -> bool:
+    return shutil.which("docker") is not None
+
+
+def build_executor(
+    workspace: Path,
+    config: ForgexConfig,
+    approval: ApprovalCallback | None = None,
+) -> CommandExecutor:
+    policy = CommandPolicy.from_config(config)
+    if config.sandbox.enabled:
+        if docker_available():
+            sb = config.sandbox
+            return DockerExecutor(
+                workspace=workspace,
+                policy=policy,
+                approval=approval,
+                image=sb.image,
+                cpu_limit=sb.cpu_limit,
+                memory_limit=sb.memory_limit,
+                network=sb.network,
+                read_only=sb.read_only,
+                user=sb.user,
+                default_timeout=sb.timeout_seconds,
+                max_output_bytes=config.terminal.max_output_bytes,
+            )
+        logger.warning("sandbox.enabled is true but docker is not available — using restricted local executor")
+
+    return RestrictedLocalExecutor(
+        workspace=workspace,
+        policy=policy,
+        approval=approval,
+        default_timeout=config.terminal.timeout_seconds,
+        max_output_bytes=config.terminal.max_output_bytes,
+    )
+
+
+def make_executor(
+    workspace: Path | str,
+    *,
+    policy: CommandPolicy | None = None,
+    approval: ApprovalCallback | None = None,
+) -> PolicyGatedExecutor:
+    return RestrictedLocalExecutor(
+        workspace=Path(workspace),
+        policy=policy or CommandPolicy(),
+        approval=approval,
+    )

forgex/sandbox/permissions.py

@@ -0,0 +1,67 @@
+"""Per-agent tool permissions (spec section 32).
+
+No agent gets unlimited permissions. Unknown roles get an EMPTY set —
+fail closed, always.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from forgex.schemas.agent import AgentRole
+
+
+class Permission(str, Enum):
+    READ = "read"
+    WRITE = "write"
+    DELETE = "delete"
+    TERMINAL = "terminal"
+    GIT = "git"
+    TEST = "test"
+    BUILD = "build"
+    RESEARCH = "research"
+    NETWORK = "network"
+
+
+class PermissionSet(BaseModel):
+    allow: set[Permission] = Field(default_factory=set)
+
+    def permits(self, *permissions: Permission) -> bool:
+        return all(p in self.allow for p in permissions)
+
+    def deny_reason(self, *permissions: Permission) -> str | None:
+        missing = [p.value for p in permissions if p not in self.allow]
+        return f"missing permissions: {', '.join(missing)}" if missing else None
+
+
+def permission_set_for(role: Any) -> PermissionSet:
+    """Return the static permission grant for an agent role."""
+    role_val = getattr(role, "value", str(role))
+
+    if role_val == AgentRole.ARCHITECT.value:
+        return PermissionSet(allow={Permission.READ, Permission.RESEARCH})
+    elif role_val in (AgentRole.BUILDER.value, AgentRole.EXPERT_CODER.value):
+        return PermissionSet(
+            allow={
+                Permission.READ,
+                Permission.WRITE,
+                Permission.DELETE,
+                Permission.TERMINAL,
+                Permission.GIT,
+                Permission.TEST,
+                Permission.BUILD,
+            }
+        )
+    elif role_val == AgentRole.SUPERVISOR.value:
+        return PermissionSet(
+            allow={
+                Permission.READ,
+                Permission.TEST,
+                Permission.BUILD,
+                Permission.GIT,
+            }
+        )
+    return PermissionSet(allow=set())

forgex/sandbox/policies.py

@@ -0,0 +1,172 @@
+"""Command policy: allow/deny lists + network rules (spec sections 20, 45, 75).
+
+Decisions are fail-safe: unknown situations ask or deny — never silently
+allow.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from forgex.config.schema import ForgexConfig
+
+logger = logging.getLogger("forgex.sandbox")
+
+ApprovalCallback = Callable[[str], bool]
+
+DEFAULT_DENIED: frozenset[str] = frozenset(
+    {
+        # destructive / system
+        "rm",
+        "rmdir",
+        "sudo",
+        "su",
+        "doas",
+        "shutdown",
+        "reboot",
+        "poweroff",
+        "halt",
+        "mkfs",
+        "dd",
+        "fdisk",
+        "format",
+        "chmod",
+        "chown",
+        "kill",
+        "killall",
+        "pkill",
+        "systemctl",
+        "service",
+        "launchctl",
+        "reg",
+        "regedit",
+        # shells
+        "sh",
+        "bash",
+        "zsh",
+        "dash",
+        "ksh",
+        "csh",
+        "tcsh",
+        "fish",
+        "cmd",
+        "powershell",
+        "pwsh",
+        # argument launchers / bypasses
+        "env",
+        "xargs",
+        "find",
+        "nohup",
+        "timeout",
+        "stdbuf",
+        "nice",
+        "watch",
+        "tee",
+    }
+)
+
+DEFAULT_NETWORK_COMMANDS: frozenset[str] = frozenset(
+    {
+        "pip",
+        "pip3",
+        "uv",
+        "npm",
+        "npx",
+        "pnpm",
+        "yarn",
+        "bun",
+        "cargo",
+        "go",
+        "curl",
+        "wget",
+        "docker",
+        "podman",
+    }
+)
+
+
+class Decision(Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    APPROVAL = "approval"
+
+
+@dataclass(frozen=True)
+class PolicyDecision:
+    decision: Decision
+    reason: str = ""
+
+
+class CommandPolicy:
+    def __init__(
+        self,
+        allowed: frozenset[str] | None = None,
+        denied: frozenset[str] | None = None,
+        network_commands: frozenset[str] | None = None,
+        network_allowed: bool = False,
+        approval_mode: str = "ask",
+    ) -> None:
+        self.allowed = allowed
+        self.denied = denied or DEFAULT_DENIED
+        self.network_commands = network_commands or DEFAULT_NETWORK_COMMANDS
+        self.network_allowed = network_allowed
+        self.approval_mode = approval_mode
+
+    @classmethod
+    def from_config(cls, config: ForgexConfig) -> CommandPolicy:
+        term = config.terminal
+        perm = config.permissions
+        allowed = frozenset(term.allowed) if term.allowed else None
+        denied = frozenset(term.denied) if term.denied else DEFAULT_DENIED
+        return cls(
+            allowed=allowed,
+            denied=denied,
+            network_allowed=(perm.mode == "auto"),
+            approval_mode=perm.mode,
+        )
+
+    def check(self, argv: list[str]) -> PolicyDecision:
+        if not argv:
+            return PolicyDecision(Decision.DENY, "Empty command line")
+
+        raw_base = argv[0]
+        # Resolve command base name
+        base = Path(raw_base).name.lower()
+        base = base.removesuffix(".exe")
+
+        norm_base = re.sub(r"[0-9.]+$", "", base)
+
+        # 1. Deny list
+        if base in self.denied or norm_base in self.denied:
+            return PolicyDecision(Decision.DENY, f"Command '{base}' is in the deny list")
+
+        # 2. Allowlist mode
+        if self.allowed is not None:
+            if base not in self.allowed and norm_base not in self.allowed:
+                return PolicyDecision(Decision.DENY, f"Command '{base}' is not in the allowlist")
+
+        # 3. Network commands
+        if (base in self.network_commands or norm_base in self.network_commands) and not self.network_allowed:
+            return PolicyDecision(Decision.APPROVAL, f"Command '{base}' may access the network")
+
+        return PolicyDecision(Decision.ALLOW)
+
+
+def resolve_approval(mode: str, description: str, callback: ApprovalCallback | None) -> bool:
+    if mode == "safe":
+        return False
+    if mode == "auto":
+        return True
+    if mode == "ask":
+        if callback is None:
+            return False
+        try:
+            return bool(callback(description))
+        except Exception:  # noqa: BLE001
+            return False
+    return False