isolattice 0.1.0__py3-none-any.whl

isolattice/__init__.py

@@ -0,0 +1,205 @@
+"""Async sandbox execution with explicit backend selection and verified policies."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .backend import Backend, BackendSession, Boundary
+from .backends import (
+    DockerBackend,
+    KubernetesBackend,
+    LinuxNamespaceBackend,
+    MacOSSeatbeltBackend,
+    PodmanBackend,
+    WindowsAppContainerBackend,
+    WindowsJobBackend,
+)
+from .commands import CommandRunner, SubprocessRunner
+from .configuration import (
+    BaselinePolicyValidator,
+    ConfigurationProvider,
+    MappingConfigurationProvider,
+    PolicyValidator,
+    TomlConfigurationProvider,
+    policy_from_mapping,
+)
+from .contracts import CONTRACT_VERSION, ExtensionPoint, extension_points, load_trusted_plugin
+from .errors import (
+    SandboxArtifactError,
+    SandboxBackendError,
+    SandboxCapabilityError,
+    SandboxError,
+    SandboxExecutionError,
+    SandboxQuotaError,
+    SandboxStateError,
+    SandboxTerminationError,
+    SandboxTimeoutError,
+    TerminationVerificationError,
+)
+from .events import EventKind, EventSink, LoggingEventSink, SandboxEvent
+from .models import (
+    DISABLEABLE_CAPABILITIES,
+    ArtifactKind,
+    ArtifactManifest,
+    ArtifactSignature,
+    BackendReport,
+    BindMount,
+    Capability,
+    CapabilityEvidence,
+    CapabilityState,
+    EgressRule,
+    ExecutionRequest,
+    ExecutionResult,
+    NetworkAccess,
+    OutputChunk,
+    ResourceBudget,
+    ResourceUsage,
+    SandboxPolicy,
+    TerminationPolicy,
+    TerminationReport,
+    TransportProtocol,
+    inherit_environment,
+    validate_artifact_key,
+)
+from .observability import (
+    AuditLogError,
+    AuditLogEventSink,
+    AuditLogSummary,
+    FanOutEventSink,
+    InstanceDiagnostics,
+    RecordingEventSink,
+    RedactingEventSink,
+    Redactor,
+    RegexRedactor,
+    SandboxDiagnostics,
+    SandboxHealth,
+    SecretRedactor,
+    verify_audit_log,
+)
+from .quotas import QuotaResourceController, ResourceClaim, ResourceController
+from .resolution import (
+    BackendResolver,
+    Candidate,
+    CapabilityResolver,
+    policy_compatibility,
+    select_backend,
+)
+from .runtime import ExecutionHandle, Sandbox, SandboxInstance
+from .s3 import S3ArtifactStore, S3Credentials
+from .shutdown import ShutdownSignals, default_shutdown_signals, shutdown_on_signals
+from .storage import ArtifactSigner, ArtifactStore, ArtifactVerifier, LocalArtifactStore
+from .supervision import (
+    FailedAttempt,
+    RestartPolicy,
+    SandboxPool,
+    SupervisedResult,
+    run_supervised,
+)
+from .termination import BoundaryState, Observation, TerminationDriver, terminate_boundary
+
+try:
+    __version__ = version("isolattice")
+except PackageNotFoundError:  # pragma: no cover - only when run from an uninstalled tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "DISABLEABLE_CAPABILITIES",
+    "ArtifactKind",
+    "ArtifactManifest",
+    "ArtifactSignature",
+    "ArtifactSigner",
+    "ArtifactStore",
+    "ArtifactVerifier",
+    "AuditLogError",
+    "AuditLogEventSink",
+    "AuditLogSummary",
+    "Backend",
+    "BackendReport",
+    "BackendResolver",
+    "BackendSession",
+    "BaselinePolicyValidator",
+    "BindMount",
+    "Boundary",
+    "BoundaryState",
+    "Candidate",
+    "Capability",
+    "CapabilityEvidence",
+    "CapabilityResolver",
+    "CapabilityState",
+    "CommandRunner",
+    "ConfigurationProvider",
+    "DockerBackend",
+    "EgressRule",
+    "EventKind",
+    "EventSink",
+    "ExecutionHandle",
+    "ExecutionRequest",
+    "ExecutionResult",
+    "ExtensionPoint",
+    "FailedAttempt",
+    "FanOutEventSink",
+    "InstanceDiagnostics",
+    "KubernetesBackend",
+    "LinuxNamespaceBackend",
+    "LocalArtifactStore",
+    "LoggingEventSink",
+    "MacOSSeatbeltBackend",
+    "MappingConfigurationProvider",
+    "NetworkAccess",
+    "Observation",
+    "OutputChunk",
+    "PodmanBackend",
+    "PolicyValidator",
+    "QuotaResourceController",
+    "RecordingEventSink",
+    "RedactingEventSink",
+    "Redactor",
+    "RegexRedactor",
+    "ResourceBudget",
+    "ResourceClaim",
+    "ResourceController",
+    "ResourceUsage",
+    "RestartPolicy",
+    "S3ArtifactStore",
+    "S3Credentials",
+    "Sandbox",
+    "SandboxArtifactError",
+    "SandboxBackendError",
+    "SandboxCapabilityError",
+    "SandboxDiagnostics",
+    "SandboxError",
+    "SandboxEvent",
+    "SandboxExecutionError",
+    "SandboxHealth",
+    "SandboxInstance",
+    "SandboxPolicy",
+    "SandboxPool",
+    "SandboxQuotaError",
+    "SandboxStateError",
+    "SandboxTerminationError",
+    "SandboxTimeoutError",
+    "SecretRedactor",
+    "ShutdownSignals",
+    "SubprocessRunner",
+    "SupervisedResult",
+    "TerminationDriver",
+    "TerminationPolicy",
+    "TerminationReport",
+    "TerminationVerificationError",
+    "TomlConfigurationProvider",
+    "TransportProtocol",
+    "WindowsAppContainerBackend",
+    "WindowsJobBackend",
+    "__version__",
+    "default_shutdown_signals",
+    "extension_points",
+    "inherit_environment",
+    "load_trusted_plugin",
+    "policy_compatibility",
+    "policy_from_mapping",
+    "run_supervised",
+    "select_backend",
+    "shutdown_on_signals",
+    "terminate_boundary",
+    "validate_artifact_key",
+    "verify_audit_log",
+]

isolattice/_artifacts.py

@@ -0,0 +1,219 @@
+"""Integrity manifests and safe-archive validation for snapshots and checkpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import hashlib
+import re
+import shutil
+import sys
+import tarfile
+import tempfile
+import time
+from pathlib import Path, PurePosixPath
+
+from .errors import SandboxArtifactError
+from .models import ArtifactKind, ArtifactManifest
+
+_READ_SIZE = 1024 * 1024
+_DRIVE = re.compile(r"[A-Za-z]:")
+_REMOVE_RETRY_DELAYS = (0.05, 0.1, 0.2, 0.4, 0.8)
+WORKSPACE_FORMAT = "tar"
+ROOTFS_FORMAT = "rootfs-tar"
+CHECKPOINT_FORMAT = "backend-checkpoint"
+
+
+async def stage(parent: Path | None) -> Path:
+    """Create a private staging directory for one artifact operation."""
+    return Path(await asyncio.to_thread(tempfile.mkdtemp, prefix="isolattice-", dir=parent))
+
+
+def _ignore_missing(_function: object, _path: str, error: BaseException) -> None:
+    # A concurrent or cancelled earlier removal already deleted this entry.
+    if not isinstance(error, FileNotFoundError):
+        raise error
+
+
+def _rmtree_if_present(directory: Path) -> None:
+    shutil.rmtree(directory, onexc=_ignore_missing)
+
+
+def _remove_tree(directory: Path) -> None:
+    # Retry transient failures a bounded number of times, then surface the failure.
+    # On Windows, scanners and indexers briefly hold just-deleted files open, leaving
+    # them delete-pending so removing the parent directory fails. On BSDs a concurrent
+    # removal of the same tree can report EAGAIN.
+    transient: tuple[type[OSError], ...] = (
+        (BlockingIOError, PermissionError) if sys.platform == "win32" else (BlockingIOError,)
+    )
+    for delay in _REMOVE_RETRY_DELAYS:
+        try:
+            _rmtree_if_present(directory)
+        except transient:
+            time.sleep(delay)
+        else:
+            return
+    _rmtree_if_present(directory)
+
+
+async def unstage(directory: Path) -> None:
+    """Remove a staging directory; archives may contain workload memory."""
+    await asyncio.to_thread(_remove_tree, directory)
+
+
+def _digest(path: Path) -> tuple[str, int]:
+    hasher = hashlib.sha256()
+    size = 0
+    with path.open("rb") as file:
+        while block := file.read(_READ_SIZE):
+            hasher.update(block)
+            size += len(block)
+    return hasher.hexdigest(), size
+
+
+async def seal(
+    kind: ArtifactKind, backend: str, archive_format: str, archive: Path, key: str
+) -> ArtifactManifest:
+    """Hash a completed archive and describe it as the artifact ``key``."""
+    digest, size = await asyncio.to_thread(_digest, archive)
+    return ArtifactManifest(
+        kind=kind,
+        backend=backend,
+        format=archive_format,
+        archive=key,
+        sha256=digest,
+        size=size,
+        created_at=datetime.datetime.now(datetime.UTC).isoformat(timespec="seconds"),
+    )
+
+
+async def verify(
+    archive: Path,
+    manifest: ArtifactManifest,
+    *,
+    key: str,
+    kind: ArtifactKind,
+    backend: str,
+    archive_format: str,
+    max_bytes: int,
+) -> None:
+    """Check a fetched archive against its manifest without trusting the store."""
+    if manifest.archive != key:
+        raise SandboxArtifactError("artifact manifest names a different key")
+    if manifest.kind is not kind:
+        raise SandboxArtifactError(f"artifact is a {manifest.kind.value}, not a {kind.value}")
+    if manifest.backend != backend:
+        raise SandboxArtifactError(
+            f"artifact was produced by backend {manifest.backend!r}, not {backend!r}"
+        )
+    if manifest.format != archive_format:
+        raise SandboxArtifactError(f"artifact format {manifest.format!r} is not {archive_format!r}")
+    if manifest.size > max_bytes:
+        raise SandboxArtifactError("artifact exceeds the configured restore size limit")
+    try:
+        digest, size = await asyncio.to_thread(_digest, archive)
+    except OSError as error:
+        raise SandboxArtifactError("fetched artifact archive is unreadable") from error
+    if size != manifest.size or digest != manifest.sha256:
+        raise SandboxArtifactError("artifact archive does not match its integrity manifest")
+
+
+def _validate_workspace_tar(archive: Path, max_members: int, max_bytes: int) -> None:
+    members = 0
+    total = 0
+    try:
+        with tarfile.open(archive, mode="r:") as bundle:
+            for member in bundle:
+                members += 1
+                if members > max_members:
+                    raise SandboxArtifactError("workspace archive has too many members")
+                if not (member.isreg() or member.isdir() or member.issym() or member.islnk()):
+                    raise SandboxArtifactError(
+                        f"workspace archive member {member.name!r} is not a regular file, "
+                        "directory or link"
+                    )
+                # data_filter rewrites absolute names; backend extractors may not, so
+                # reject them outright instead of relying on the rewrite.
+                name = PurePosixPath(member.name)
+                if (
+                    name.is_absolute()
+                    or ".." in name.parts
+                    or "\\" in member.name
+                    or _DRIVE.match(member.name) is not None
+                ):
+                    raise SandboxArtifactError(
+                        f"workspace archive member {member.name!r} is unsafe: "
+                        "absolute or traversing name"
+                    )
+                try:
+                    tarfile.data_filter(member, "/isolattice-workspace")
+                except tarfile.FilterError as error:
+                    raise SandboxArtifactError(
+                        f"workspace archive member {member.name!r} is unsafe: {error}"
+                    ) from error
+                total += member.size
+                if total > max_bytes:
+                    raise SandboxArtifactError("workspace archive expands beyond its size limit")
+    except (tarfile.TarError, OSError) as error:
+        raise SandboxArtifactError("workspace archive is not a valid uncompressed tar") from error
+
+
+async def validate_workspace_tar(archive: Path, *, max_members: int, max_bytes: int) -> None:
+    """Reject absolute, traversing, special, link-escaping or oversized members."""
+    await asyncio.to_thread(_validate_workspace_tar, archive, max_members, max_bytes)
+
+
+def _unsafe_name(name: str) -> bool:
+    path = PurePosixPath(name)
+    return (
+        not name
+        or path.is_absolute()
+        or ".." in path.parts
+        or "\\" in name
+        or _DRIVE.match(name) is not None
+    )
+
+
+def _validate_rootfs_tar(archive: Path, max_members: int, max_bytes: int) -> None:
+    members = 0
+    total = 0
+    seen: set[str] = set()
+    try:
+        with tarfile.open(archive, mode="r:") as bundle:
+            for member in bundle:
+                members += 1
+                if members > max_members:
+                    raise SandboxArtifactError("container snapshot has too many members")
+                if not (member.isreg() or member.isdir() or member.issym() or member.islnk()):
+                    raise SandboxArtifactError(
+                        f"container snapshot member {member.name!r} is a device or special file"
+                    )
+                if _unsafe_name(member.name):
+                    raise SandboxArtifactError(
+                        f"container snapshot member {member.name!r} has an absolute or "
+                        "traversing name"
+                    )
+                # Symbolic links resolve inside the container root; hard links must
+                # name an earlier member so the engine never links outside the archive.
+                if member.islnk() and (
+                    _unsafe_name(member.linkname)
+                    or PurePosixPath(member.linkname).as_posix() not in seen
+                ):
+                    raise SandboxArtifactError(
+                        f"container snapshot hard link {member.name!r} names no earlier member"
+                    )
+                seen.add(PurePosixPath(member.name).as_posix())
+                total += member.size
+                if total > max_bytes:
+                    raise SandboxArtifactError("container snapshot expands beyond its size limit")
+    except (tarfile.TarError, OSError) as error:
+        raise SandboxArtifactError("container snapshot is not a valid uncompressed tar") from error
+
+
+async def validate_rootfs_tar(archive: Path, *, max_members: int, max_bytes: int) -> None:
+    """Reject special files, unsafe names, dangling hard links and oversized archives.
+
+    The archive is handed to the container engine and never extracted on the host.
+    """
+    await asyncio.to_thread(_validate_rootfs_tar, archive, max_members, max_bytes)

isolattice/_async.py

@@ -0,0 +1,117 @@
+"""Helpers for owned tasks whose cleanup must survive repeated cancellation."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from dataclasses import dataclass
+from typing import NoReturn
+
+from .errors import SandboxBackendError
+
+_EXIT_POLL_INTERVAL = 0.1
+_ATTACH_EXIT_GRACE = 2.0
+_ATTACH_REAP_TIMEOUT = 5.0
+
+
+async def root_exit(process: asyncio.subprocess.Process) -> int:
+    """Return the exit code of ``process`` once it exits, even if its pipes stay open."""
+    # Python 3.12 resolves wait() only after every pipe closes, so descendants holding
+    # inherited pipes would hide the root's exit; returncode is set at exit everywhere.
+    waiter = asyncio.ensure_future(process.wait())
+    try:
+        while True:
+            done, _ = await asyncio.wait((waiter,), timeout=_EXIT_POLL_INTERVAL)
+            if done:
+                return waiter.result()
+            if (code := process.returncode) is not None:
+                return code
+    finally:
+        if not waiter.done():
+            waiter.cancel()
+
+
+async def reap_attach(process: asyncio.subprocess.Process) -> None:
+    """Wait briefly for an attach client to exit, then kill and reap it."""
+    if process.returncode is not None:
+        return
+    try:
+        async with asyncio.timeout(_ATTACH_EXIT_GRACE):
+            await process.wait()
+        return
+    except TimeoutError:
+        with contextlib.suppress(ProcessLookupError):
+            process.kill()
+    try:
+        async with asyncio.timeout(_ATTACH_REAP_TIMEOUT):
+            await process.wait()
+    except TimeoutError as error:
+        raise SandboxBackendError("the owned backend attach client could not be reaped") from error
+
+
+@dataclass(slots=True)
+class Settled[T]:
+    value: T | None
+    error: BaseException | None
+    interrupted: asyncio.CancelledError | None
+
+
+async def discard_remaining(reader: asyncio.StreamReader) -> bool:
+    discarded = False
+    while await reader.read(65536):
+        discarded = True
+        await asyncio.sleep(0)
+    return discarded
+
+
+async def settle[T](task: asyncio.Task[T]) -> Settled[T]:
+    interrupted: asyncio.CancelledError | None = None
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError as error:
+            if not task.done() and interrupted is None:
+                interrupted = error
+        except BaseException:
+            break
+    try:
+        return Settled(task.result(), None, interrupted)
+    except BaseException as error:
+        return Settled(None, error, interrupted)
+
+
+async def wait_until(task: asyncio.Task[object], deadline: float) -> asyncio.CancelledError | None:
+    """Wait for ``task`` until a loop-time deadline without cancelling it.
+
+    Caller cancellation is absorbed and returned so bounded cleanup still completes.
+    """
+    interrupted: asyncio.CancelledError | None = None
+    loop = asyncio.get_running_loop()
+    while not task.done():
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            break
+        try:
+            await asyncio.wait((task,), timeout=remaining)
+        except asyncio.CancelledError as error:
+            if interrupted is None:
+                interrupted = error
+    return interrupted
+
+
+def raise_combined(message: str, *errors: BaseException | None) -> None:
+    present = [error for error in errors if error is not None]
+    if len(present) == 1:
+        raise present[0]
+    if present:
+        raise BaseExceptionGroup(message, present)
+
+
+def raise_with_cleanup(
+    message: str, failure: BaseException, *cleanup: BaseException | None
+) -> NoReturn:
+    """Raise ``failure``, grouped with any cleanup errors that also occurred."""
+    present = [error for error in cleanup if error is not None]
+    if present:
+        raise BaseExceptionGroup(message, [failure, *present])
+    raise failure