apsimo 1.3.0__py3-none-any.whl

apsimo/sandbox/backend.py

@@ -0,0 +1,195 @@
+"""Sandbox backends: pluggable isolated code execution (Phase B item 6).
+
+The backend -- NOT the caller -- enforces containment: no egress, no
+credentials, capped CPU/memory/pids/wall-clock, read-only rootfs with a single
+writable workdir. A tool can ask to run a script; it can never widen these
+limits (they come from env/policy, resolved by the manager, and are passed to
+the backend which applies them literally).
+
+Reference backend is Docker; a DisabledSandbox is the default when Docker is
+absent so the feature degrades to a clear "unavailable" rather than an unsafe
+host-side exec.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_LANG_INTERP = {
+    "python": ["python", "/work/script"],
+    "py": ["python", "/work/script"],
+    "bash": ["sh", "/work/script"],
+    "sh": ["sh", "/work/script"],
+    "node": ["node", "/work/script"],
+    "javascript": ["node", "/work/script"],
+}
+
+
+@dataclass
+class SandboxLimits:
+    """Containment limits, resolved from policy/env and applied by the backend."""
+    image: str = "python:3.12-slim"
+    cpus: float = 1.0
+    memory: str = "512m"
+    timeout_secs: int = 30
+    pids_limit: int = 128
+    egress: str = "none"                # none | allowlist
+    max_artifact_bytes: int = 1_048_576  # 1 MiB total read-back cap
+
+    @property
+    def network(self) -> str:
+        # Only "none" is honored as a hard no-egress; allowlist requires an
+        # egress proxy the deployment provides (documented, not default).
+        return "none" if self.egress == "none" else self.egress
+
+
+@dataclass
+class SandboxResult:
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: Optional[int] = None
+    timed_out: bool = False
+    artifacts: Dict[str, str] = field(default_factory=dict)
+    error: str = ""
+
+    def as_dict(self) -> Dict[str, object]:
+        return {
+            "stdout": self.stdout, "stderr": self.stderr,
+            "exit_code": self.exit_code, "timed_out": self.timed_out,
+            "artifacts": list(self.artifacts.keys()),
+            "artifact_preview": {k: v[:500] for k, v in self.artifacts.items()},
+            "error": self.error,
+        }
+
+
+class SandboxBackend(ABC):
+    name = "abstract"
+
+    @abstractmethod
+    def available(self) -> bool:
+        ...
+
+    @abstractmethod
+    def run(self, script: str, lang: str, limits: SandboxLimits) -> SandboxResult:
+        ...
+
+
+class DisabledSandbox(SandboxBackend):
+    """Default backend when no isolation is available. Never executes."""
+    name = "disabled"
+
+    def __init__(self, reason: str = "no container runtime available") -> None:
+        self._reason = reason
+
+    def available(self) -> bool:
+        return False
+
+    def run(self, script: str, lang: str, limits: SandboxLimits) -> SandboxResult:
+        return SandboxResult(error=f"sandbox unavailable: {self._reason}")
+
+
+class DockerSandbox(SandboxBackend):
+    """Ephemeral-container backend: no egress, no creds, capped resources."""
+    name = "docker"
+
+    def __init__(self, docker_bin: str = "docker") -> None:
+        self._docker = docker_bin
+
+    def available(self) -> bool:
+        return shutil.which(self._docker) is not None
+
+    def build_command(self, workdir: str, lang: str,
+                      limits: SandboxLimits) -> List[str]:
+        """The exact docker invocation (pure -- unit-tested for containment).
+
+        Guarantees: --network none (no egress), no -e/env (no credentials),
+        --read-only rootfs with a single writable bind workdir, dropped
+        capabilities + no-new-privileges, hard CPU/memory/pids caps, and a
+        wall-clock timeout inside the container.
+        """
+        interp = _LANG_INTERP.get((lang or "python").lower(),
+                                  _LANG_INTERP["python"])
+        return [
+            self._docker, "run", "--rm",
+            "--network", limits.network,
+            "--read-only",
+            "--tmpfs", "/tmp:rw,size=64m",
+            "-v", f"{workdir}:/work:rw",
+            "-w", "/work",
+            "--cpus", str(limits.cpus),
+            "--memory", str(limits.memory),
+            "--pids-limit", str(limits.pids_limit),
+            "--security-opt", "no-new-privileges",
+            "--cap-drop", "ALL",
+            limits.image,
+            "timeout", str(limits.timeout_secs), *interp,
+        ]
+
+    def run(self, script: str, lang: str, limits: SandboxLimits) -> SandboxResult:
+        workdir = tempfile.mkdtemp(prefix="colony-sandbox-")
+        try:
+            script_path = os.path.join(workdir, "script")
+            with open(script_path, "w") as f:
+                f.write(script or "")
+            cmd = self.build_command(workdir, lang, limits)
+            try:
+                proc = subprocess.run(
+                    cmd, capture_output=True, text=True,
+                    timeout=limits.timeout_secs + 10)  # outer guard > inner
+            except subprocess.TimeoutExpired:
+                return SandboxResult(timed_out=True,
+                                     error="wall-clock timeout")
+            except Exception as exc:
+                return SandboxResult(error=f"backend error: {exc}")
+            result = SandboxResult(
+                stdout=(proc.stdout or "")[:100_000],
+                stderr=(proc.stderr or "")[:20_000],
+                exit_code=proc.returncode,
+                timed_out=(proc.returncode == 124))  # timeout(1) exit code
+            self._read_artifacts(workdir, script_path, limits, result)
+            return result
+        finally:
+            shutil.rmtree(workdir, ignore_errors=True)
+
+    @staticmethod
+    def _read_artifacts(workdir: str, script_path: str,
+                        limits: SandboxLimits, result: SandboxResult) -> None:
+        budget = limits.max_artifact_bytes
+        for root, _dirs, files in os.walk(workdir):
+            for fn in files:
+                path = os.path.join(root, fn)
+                if path == script_path:
+                    continue
+                if budget <= 0:
+                    result.error = (result.error
+                                    or "artifact size cap reached").strip()
+                    return
+                try:
+                    with open(path, "rb") as fh:
+                        data = fh.read(budget + 1)
+                except Exception:
+                    continue
+                if len(data) > budget:
+                    result.error = "artifact size cap reached"
+                    data = data[:budget]
+                budget -= len(data)
+                rel = os.path.relpath(path, workdir)
+                result.artifacts[rel] = data.decode("utf-8", "replace")
+
+
+def select_backend(mode: str) -> SandboxBackend:
+    """Pick a backend: Docker when present, else Disabled. Mode gates whether
+    the manager actually executes, not which backend exists."""
+    docker = DockerSandbox()
+    if docker.available():
+        return docker
+    return DisabledSandbox()

apsimo/sandbox/manager.py

@@ -0,0 +1,173 @@
+"""SandboxManager -- policy front end for gated isolated execution (item 6).
+
+Wraps a backend with the safety envelope:
+  - mode gate: off (never), dry_run (validate + log the command, run nothing),
+    live (execute in the backend).
+  - boundary gate: the purpose + script are checked against DirectiveGuard
+    (ACT capability, fail-closed); a boundaried subject blocks the run.
+  - approval tiering: an owner-directed experiment or a contained read-only
+    evaluation runs AUTO; other mutations are FLAGGED for owner approval.
+  - server-side limits: the caller cannot widen containment -- limits are
+    resolved here from env and handed to the backend, which applies them.
+  - never mounts secrets: the backend passes no env/credentials into the
+    container.
+
+Every run (auto, flagged, dry-run, blocked) is journaled through the
+self-model action journal.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, Optional
+
+from apsimo.sandbox.backend import (
+    SandboxLimits, SandboxResult, select_backend,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def sandbox_mode() -> str:
+    from apsimo.util.autonomy_preset import resolve
+    return resolve("COLONY_SANDBOX_MODE", ("off", "dry_run", "live"), "off")
+
+
+def _fenv(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+def _ienv(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+def resolve_limits() -> SandboxLimits:
+    """Containment limits from env/policy. The caller can never widen these."""
+    return SandboxLimits(
+        image=os.environ.get("COLONY_SANDBOX_IMAGE", "python:3.12-slim"),
+        cpus=_fenv("COLONY_SANDBOX_CPUS", 1.0),
+        memory=os.environ.get("COLONY_SANDBOX_MEMORY", "512m"),
+        timeout_secs=_ienv("COLONY_SANDBOX_TIMEOUT", 30),
+        pids_limit=_ienv("COLONY_SANDBOX_PIDS", 128),
+        egress=os.environ.get("COLONY_SANDBOX_EGRESS", "none").strip().lower(),
+        max_artifact_bytes=_ienv("COLONY_SANDBOX_MAX_ARTIFACT_BYTES", 1_048_576),
+    )
+
+
+class SandboxManager:
+    def __init__(self, *, directive_manager: Any = None,
+                 self_model: Any = None) -> None:
+        self._directives = directive_manager
+        self._self_model = self_model
+        self._backend = select_backend(sandbox_mode())
+
+    def backend_name(self) -> str:
+        return self._backend.name
+
+    # -- approval tiering -------------------------------------------------
+    @staticmethod
+    def approval_tier(owner_directed: bool, read_only: bool = False) -> str:
+        """Keep contained read-only work fast without inventing authority."""
+
+        return "auto" if owner_directed or read_only else "flagged"
+
+    # -- boundary gate ----------------------------------------------------
+    def _boundary_ok(self, purpose: str, script: str) -> Dict[str, Any]:
+        if self._directives is None:
+            # No directive manager: nothing was evaluated. Never report the
+            # fabricated "ok" of a real allow — callers/journals must be able
+            # to tell "unchecked" from "checked and allowed".
+            return {"allowed": True, "reason": "boundary_unchecked"}
+        try:
+            from apsimo.directives import Action
+            verdict = self._directives.check(Action(
+                kind="execute_tool",
+                text=f"run sandbox script: {purpose}",
+                target=purpose,
+                args={"script": (script or "")[:500]},
+                high_risk=True))
+            return {"allowed": bool(verdict.allowed), "reason": verdict.reason}
+        except Exception:
+            logger.warning("sandbox boundary check failed closed", exc_info=True)
+            return {"allowed": False, "reason": "boundary_check_error"}
+
+    # -- the run entry point ----------------------------------------------
+    def run(self, script: str, lang: str = "python", *, purpose: str = "",
+            owner_directed: bool = False,
+            approved: bool = False,
+            read_only: bool = False) -> Dict[str, Any]:
+        mode = sandbox_mode()
+        limits = resolve_limits()
+        tier = self.approval_tier(owner_directed, read_only)
+
+        if mode == "off":
+            self._journal("sandbox", purpose, decision="held",
+                          reasoning="sandbox mode off")
+            return {"ran": False, "reason": "sandbox_off", "mode": mode}
+
+        boundary = self._boundary_ok(purpose, script)
+        if not boundary["allowed"]:
+            self._journal("sandbox", purpose, decision="blocked",
+                          reasoning=f"boundary: {boundary['reason']}")
+            return {"ran": False, "reason": "boundary_blocked",
+                    "detail": boundary["reason"], "mode": mode}
+
+        if tier == "flagged" and not approved:
+            self._journal("sandbox", purpose, decision="asked",
+                          reasoning="not owner-directed -> owner approval required")
+            return {"ran": False, "reason": "approval_required",
+                    "tier": tier, "mode": mode}
+
+        if mode == "dry_run":
+            from apsimo.sandbox.backend import DockerSandbox
+            command = DockerSandbox().build_command("<workdir>", lang, limits)
+            self._journal("sandbox", purpose, decision="held",
+                          reasoning="dry_run: validated, executed nothing")
+            return {"ran": False, "dry_run": True, "tier": tier,
+                    "read_only": bool(read_only),
+                    "command": command, "limits": limits.__dict__, "mode": mode}
+
+        # live
+        if not self._backend.available():
+            self._journal("sandbox", purpose, decision="held",
+                          reasoning=f"backend {self._backend.name} unavailable")
+            return {"ran": False, "reason": "backend_unavailable",
+                    "backend": self._backend.name, "mode": mode}
+
+        result: SandboxResult = self._backend.run(script, lang, limits)
+        outcome = ("timeout" if result.timed_out else
+                   "success" if (result.exit_code == 0 and not result.error)
+                   else "failure")
+        if self._self_model is not None:
+            try:
+                self._self_model.record("sandbox", outcome)
+            except Exception:
+                logger.debug("sandbox self-model record failed", exc_info=True)
+        self._journal("sandbox", purpose, decision="acted", outcome=outcome,
+                      reasoning=f"tier={tier}, exit={result.exit_code}")
+        return {"ran": True, "tier": tier, "read_only": bool(read_only),
+                "mode": mode, "outcome": outcome,
+                "result": result.as_dict()}
+
+    def status(self) -> Dict[str, Any]:
+        return {"mode": sandbox_mode(), "backend": self._backend.name,
+                "backend_available": self._backend.available(),
+                "limits": resolve_limits().__dict__}
+
+    # -- helpers ----------------------------------------------------------
+    def _journal(self, domain: str, description: str, **kw: Any) -> None:
+        journal = getattr(self._self_model, "journal", None)
+        if journal is None:
+            return
+        try:
+            journal.record(domain, description or "(sandbox run)",
+                           reversibility="reversible", **kw)
+        except Exception:
+            logger.debug("sandbox journal failed", exc_info=True)

apsimo/scope_bounds.py

@@ -0,0 +1,7 @@
+"""Shared bounds for authority-bearing person and visibility scopes."""
+
+SUBJECT_PERSON_ID_MAX_CHARS = 128
+VIEWER_SCOPE_MAX_CHARS = 192
+
+
+__all__ = ("SUBJECT_PERSON_ID_MAX_CHARS", "VIEWER_SCOPE_MAX_CHARS")

apsimo/secrets/__init__.py

@@ -0,0 +1,6 @@
+"""Colony secrets management — pluggable credential vault."""
+
+from apsimo.secrets.manager import SecretsManager
+from apsimo.secrets.types import SecretType, ALL_SECRET_KEYS, VAULT_NAME
+
+__all__ = ["SecretsManager", "SecretType", "ALL_SECRET_KEYS", "VAULT_NAME"]

apsimo/secrets/backends/__init__.py

@@ -0,0 +1,8 @@
+"""Secrets backend implementations."""
+
+from apsimo.secrets.backends.base import SecretsBackend
+from apsimo.secrets.backends.env import EnvBackend
+from apsimo.secrets.backends.keyring import KeyringBackend
+from apsimo.secrets.backends.onepassword import OnePasswordBackend
+
+__all__ = ["SecretsBackend", "EnvBackend", "KeyringBackend", "OnePasswordBackend"]

apsimo/secrets/backends/base.py

@@ -0,0 +1,42 @@
+"""Abstract base class for Colony secrets backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from apsimo.secrets.types import SecretType
+
+
+class SecretsBackend(ABC):
+    """Abstract secrets storage backend.
+
+    All backends must implement get/set/delete/list and is_available.
+    Backends are selected during onboarding and persisted in config.yaml.
+    """
+
+    name: str = "abstract"
+
+    @abstractmethod
+    def get(self, key: str, default: str | None = None) -> str | None:
+        """Retrieve a secret by key. Returns default if not found."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: str, *, secret_type: SecretType | None = None) -> None:
+        """Store a secret."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Remove a secret."""
+        ...
+
+    @abstractmethod
+    def list(self) -> list[str]:
+        """List all known secret keys (not values)."""
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if this backend can be used on the current system."""
+        ...

apsimo/secrets/backends/env.py

@@ -0,0 +1,110 @@
+"""Legacy .env file secrets backend."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from apsimo.secrets.backends.base import SecretsBackend
+from apsimo.secrets.types import SecretType
+
+
+class EnvBackend(SecretsBackend):
+    """Legacy .env file backend.
+
+    Reads from environment variables (which may be loaded from .env by
+    python-dotenv at startup). Writes update the .env file in place.
+
+    This backend is maintained for backward compatibility and for users
+    in containerized environments who inject secrets via environment variables.
+    It is the DEFAULT backend when no other backend is configured, ensuring
+    zero-friction upgrade from V1.
+
+    The .env file is always written with mode 0o600 (SEC-007).
+    """
+
+    name = "env"
+
+    def __init__(self, env_path: str | None = None) -> None:
+        self._env_path = env_path or str(
+            Path.home() / ".colony" / ".env"
+        )
+
+    def is_available(self) -> bool:
+        return True  # Always available
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        v = os.environ.get(key)
+        if v is not None:
+            return v
+        # Fall back to the .env file itself: set() writes there, and a fresh
+        # process (CLI, migration) has NOT loaded it into os.environ — without
+        # this read-back, get() returns None for every secret set() stored.
+        env_path = Path(self._env_path)
+        if env_path.exists():
+            try:
+                for line in env_path.read_text(encoding="utf-8").splitlines():
+                    if line.startswith(f"{key}="):
+                        return line.split("=", 1)[1]
+            except OSError:
+                pass
+        return default
+
+    def set(self, key: str, value: str, *, secret_type: SecretType | None = None) -> None:
+        """Write to .env file with 0o600 permissions (SEC-007 pattern)."""
+        env_path = Path(self._env_path)
+        env_path.parent.mkdir(parents=True, exist_ok=True)
+
+        lines: list[str] = []
+        if env_path.exists():
+            lines = env_path.read_text(encoding="utf-8").splitlines(keepends=True)
+
+        key_found = False
+        for i, line in enumerate(lines):
+            if line.startswith(f"{key}="):
+                lines[i] = f"{key}={value}\n"
+                key_found = True
+                break
+        if not key_found:
+            lines.append(f"{key}={value}\n")
+
+        # Write atomically with 0o600 (SEC-007: no TOCTOU window)
+        fd = os.open(
+            str(env_path),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            0o600,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.writelines(lines)
+
+        os.environ[key] = value
+
+    def delete(self, key: str) -> None:
+        env_path = Path(self._env_path)
+        if not env_path.exists():
+            os.environ.pop(key, None)
+            return
+        lines = [
+            line
+            for line in env_path.read_text(encoding="utf-8").splitlines(keepends=True)
+            if not line.startswith(f"{key}=")
+        ]
+        fd = os.open(
+            str(env_path),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            0o600,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.writelines(lines)
+        os.environ.pop(key, None)
+
+    def list(self) -> list[str]:
+        env_path = Path(self._env_path)
+        if not env_path.exists():
+            return []
+        keys = []
+        for line in env_path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#") and "=" in stripped:
+                keys.append(stripped.split("=", 1)[0])
+        return keys

apsimo/secrets/backends/keyring.py

@@ -0,0 +1,72 @@
+"""System keyring secrets backend (macOS Keychain, Linux SecretService, Windows Credential Manager)."""
+
+from __future__ import annotations
+
+import logging
+
+from apsimo.secrets.backends.base import SecretsBackend
+from apsimo.secrets.types import SecretType, ALL_SECRET_KEYS
+
+logger = logging.getLogger(__name__)
+
+_SERVICE = "colony-ai"
+
+
+class KeyringBackend(SecretsBackend):
+    """System keyring backend using the ``keyring`` library.
+
+    macOS: stores in Keychain.
+    Linux: uses SecretService (GNOME Keyring or KWallet).
+    Windows: uses Windows Credential Manager.
+
+    Requires: pip install keyring  (or colony[keyring] optional dep)
+    """
+
+    name = "keyring"
+
+    def is_available(self) -> bool:
+        try:
+            import keyring
+            import keyring.errors
+        except ImportError:
+            return False
+        try:
+            # Probe with a read to verify the backend is actually usable.
+            # get_keyring() alone doesn't raise on headless systems; a real
+            # read/write attempt is required to confirm a backend exists.
+            keyring.get_password(_SERVICE, "_colony_probe_")
+            return True
+        except keyring.errors.NoKeyringError:
+            return False
+        except Exception:
+            return False
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        try:
+            import keyring
+            value = keyring.get_password(_SERVICE, key)
+            return value if value is not None else default
+        except Exception:
+            return default
+
+    def set(self, key: str, value: str, *, secret_type: SecretType | None = None) -> None:
+        import keyring
+        keyring.set_password(_SERVICE, key, value)
+
+    def delete(self, key: str) -> None:
+        try:
+            import keyring
+            import keyring.errors
+            keyring.delete_password(_SERVICE, key)
+        except keyring.errors.PasswordDeleteError:
+            pass  # Key didn't exist — idempotent delete
+        except Exception as exc:
+            logger.warning("KeyringBackend: failed to delete secret %r: %s", key, exc)
+
+    def list(self) -> list[str]:
+        """Return all configured keys by probing ALL_SECRET_KEYS.
+
+        The keyring library does not support listing all keys for a service,
+        so we iterate the known key set and check which ones are set.
+        """
+        return [k for k in sorted(ALL_SECRET_KEYS) if self.get(k) is not None]