Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

15.8 KB
Raw Blame
#
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
Isolated session data models.

Pydantic models for namespace-isolated execution sessions (OSEP-0013).
"""

from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field


class IsolatedWorkspaceSpec(BaseModel):
    """Workspace configuration for an isolated session."""

    path: str = Field(description="Host path to bind as workspace")
    mode: str | None = Field(
        default=None,
        description="Bind mode: 'rw' (read-write), 'overlay' (copy-on-write), or 'ro' (read-only). None = server default.",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedOverlaySpec(BaseModel):
    """One overlay mount inside the isolated namespace.

    ``mode='overlay'`` mounts a copy-on-write view: ``persist=True``
    (default) uses a host upper directory, ``persist=False`` an ephemeral
    tmpfs discarded with the session. ``rw``/``ro`` bind directly and must
    leave ``persist`` unset.
    """

    path: str = Field(description="Mount destination inside the namespace (absolute)")
    mode: str | None = Field(
        default=None,
        description="Mount mode: 'rw' (read-write), 'overlay' (copy-on-write), or 'ro' (read-only). None = server default ('overlay').",
    )
    persist: bool | None = Field(
        default=None,
        description="Overlay mode only. True (default) allocates a host upper directory; False uses an ephemeral tmpfs upper. None = server default.",
    )

    model_config = ConfigDict(populate_by_name=True)


class EnvPassthroughSpec(BaseModel):
    """Environment variable passthrough configuration."""

    mode: str = Field(
        default="deny",
        description="Passthrough mode: 'allow' (allowlist) or 'deny' (denylist)",
    )
    keys: list[str] = Field(
        default_factory=list,
        description="Environment variable keys to allow or deny",
    )

    model_config = ConfigDict(populate_by_name=True)


class BindMount(BaseModel):
    """An explicit source-to-destination bind mount into the namespace."""

    source: str = Field(description="Host path to bind-mount into the namespace")
    dest: str | None = Field(
        default=None,
        description="Mount destination inside the namespace. Defaults to source when omitted.",
    )
    readonly: bool | None = Field(
        default=None,
        description="Mount read-only (--ro-bind) when true; read-write (--bind) otherwise.",
    )

    model_config = ConfigDict(populate_by_name=True)


class CreateIsolatedSessionRequest(BaseModel):
    """Request to create an isolated bash session.

    ``workspace`` is legacy sugar: at least one of ``workspace`` or
    ``overlays`` is required, and ``workspace`` is prepended when both are
    set.
    """

    workspace: IsolatedWorkspaceSpec | None = Field(
        default=None,
        description="Workspace bind configuration (legacy single-workspace sugar)",
    )
    overlays: list[IsolatedOverlaySpec] | None = Field(
        default=None,
        description=(
            "Independent overlay mounts inside one namespace. bubblewrap applies "
            "mounts shallow-first, so a nested overlay shadows its ancestors "
            "within its own subtree. Paths must be absolute and unique."
        ),
    )
    profile: str | None = Field(
        default=None,
        description="Isolation profile: 'strict' or 'balanced'. None = server default.",
    )
    extra_writable: list[str] | None = Field(
        default=None,
        description="Additional paths to bind read-write inside the namespace",
    )
    binds: list[BindMount] | None = Field(
        default=None,
        description="Additional host paths bind-mounted with explicit source-to-destination mapping",
    )
    share_net: bool | None = Field(
        default=None,
        description="Share host network namespace (default: profile-dependent)",
    )
    env_passthrough: EnvPassthroughSpec | None = Field(
        default=None,
        description="Environment variable passthrough configuration",
    )
    uid: int | None = Field(
        default=None,
        description="Run as this Unix UID inside the namespace",
    )
    gid: int | None = Field(
        default=None,
        description="Run as this Unix GID inside the namespace",
    )
    uid_mode: str | None = Field(
        default=None,
        description="How user identity is established inside the namespace: 'setpriv' (default) or 'userns'.",
    )
    idle_timeout_seconds: int | None = Field(
        default=None,
        description="Auto-destroy session after this many idle seconds (0 = no timeout)",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedSessionInfo(BaseModel):
    """Response after creating an isolated session.

    In addition to the required ``session_id``/``created_at`` fields, execd may
    echo back the creation-parameter fields used to create the session. These
    let a stateless caller rebuild a session handle from just a session ID via
    :meth:`IsolationService.attach`. Older execd builds omit them; when absent
    the fields default to ``None`` and the handle remains fully usable through
    its ``session_id`` (run/get/delete/files still work).
    """

    session_id: str = Field(description="Unique session identifier")
    created_at: datetime | None = Field(
        default=None, description="Session creation timestamp"
    )
    profile: str | None = Field(
        default=None,
        description="Isolation profile the session was created with ('strict' or 'balanced').",
    )
    workspace: IsolatedWorkspaceSpec | None = Field(
        default=None,
        description="Workspace bind configuration used at session creation (single-overlay sessions only).",
    )
    overlays: list[IsolatedOverlaySpec] | None = Field(
        default=None,
        description="Effective overlay mounts of the session.",
    )
    extra_writable: list[str] | None = Field(
        default=None,
        description="Additional paths bound read-write inside the namespace.",
    )
    binds: list[BindMount] | None = Field(
        default=None,
        description="Additional host paths bind-mounted into the namespace.",
    )
    share_net: bool | None = Field(
        default=None,
        description="Whether the session shares the host network namespace.",
    )
    env_passthrough: EnvPassthroughSpec | None = Field(
        default=None,
        description="Environment variable passthrough configuration.",
    )
    uid: int | None = Field(
        default=None,
        description="Unix UID the session runs as inside the namespace.",
    )
    gid: int | None = Field(
        default=None,
        description="Unix GID the session runs as inside the namespace.",
    )
    uid_mode: str | None = Field(
        default=None,
        description="How user identity is established inside the namespace ('setpriv' or 'userns').",
    )
    idle_timeout_seconds: int | None = Field(
        default=None,
        description="Idle timeout in seconds (0 = no timeout).",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedSessionState(BaseModel):
    """Current state of an isolated session.

    In addition to the required ``status`` field and the runtime timestamps,
    execd may echo back the creation-parameter fields used when the session was
    created. Older execd builds omit them; when absent the fields default to
    ``None``. This mirrors the extended shape of :class:`IsolatedSessionInfo`
    so callers using :meth:`IsolationSession.get` can observe the same
    configuration they would have seen via :meth:`IsolationService.attach`.
    """

    status: str = Field(description="Session status: 'active' or 'destroyed'")
    created_at: datetime | None = Field(
        default=None, description="Session creation timestamp"
    )
    last_run_at: datetime | None = Field(
        default=None, description="Timestamp of last code execution"
    )
    idle_remaining_seconds: int | None = Field(
        default=None, description="Seconds until idle auto-destroy (null if no timeout)"
    )
    profile: str | None = Field(
        default=None,
        description="Isolation profile the session was created with ('strict' or 'balanced').",
    )
    workspace: IsolatedWorkspaceSpec | None = Field(
        default=None,
        description="Workspace bind configuration used at session creation (single-overlay sessions only).",
    )
    overlays: list[IsolatedOverlaySpec] | None = Field(
        default=None,
        description="Effective overlay mounts of the session.",
    )
    extra_writable: list[str] | None = Field(
        default=None,
        description="Additional paths bound read-write inside the namespace.",
    )
    binds: list[BindMount] | None = Field(
        default=None,
        description="Additional host paths bind-mounted into the namespace.",
    )
    share_net: bool | None = Field(
        default=None,
        description="Whether the session shares the host network namespace.",
    )
    env_passthrough: EnvPassthroughSpec | None = Field(
        default=None,
        description="Environment variable passthrough configuration.",
    )
    uid: int | None = Field(
        default=None,
        description="Unix UID the session runs as inside the namespace.",
    )
    gid: int | None = Field(
        default=None,
        description="Unix GID the session runs as inside the namespace.",
    )
    uid_mode: str | None = Field(
        default=None,
        description="How user identity is established inside the namespace ('setpriv' or 'userns').",
    )
    idle_timeout_seconds: int | None = Field(
        default=None,
        description="Idle timeout in seconds (0 = no timeout).",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedSessionSummary(BaseModel):
    """Summary of an isolated session as returned by list."""

    session_id: str = Field(description="Unique session identifier")
    status: str = Field(
        description="Session status: 'active', 'dead', or 'destroyed'"
    )
    created_at: datetime = Field(description="Session creation timestamp")
    last_run_at: datetime = Field(description="Timestamp of last code execution")
    idle_remaining_seconds: int | None = Field(
        default=None, description="Seconds until idle auto-destroy (null if no timeout)"
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedRunOpts(BaseModel):
    """Options for running code in an isolated session.

    Background execution is only available through
    :meth:`IsolationSession.run_background`; this opts type carries no
    background flag because :meth:`IsolationSession.run` is foreground-only.
    """

    envs: dict[str, str] | None = Field(
        default=None,
        description="Environment variables to inject for this run",
    )
    timeout_seconds: int | None = Field(
        default=None,
        description="Maximum execution time in seconds (foreground runs only)",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedBackgroundRun(BaseModel):
    """Handle returned when a run is started with background: true.

    Background runs require a writable log location under the first
    overlay, so sessions whose first overlay is read-only (``ro``) or an
    ephemeral overlay (``persist=False``) reject them with an error.
    """

    session_id: str = Field(description="Session the run was started in")
    run_id: str = Field(description="Run ID for status and logs polling")
    started_at: datetime | None = Field(
        default=None, description="Run start timestamp"
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedRunStatus(BaseModel):
    """Lifecycle state of an isolated background run."""

    session_id: str = Field(description="Session the run belongs to")
    run_id: str = Field(description="Run identifier")
    running: bool = Field(description="Whether the run is still executing")
    exit_code: int | None = Field(
        default=None, description="Exit code if the run has finished"
    )
    error: str | None = Field(
        default=None, description="Error message if the run failed"
    )
    started_at: datetime | None = Field(
        default=None, description="Run start timestamp"
    )
    finished_at: datetime | None = Field(
        default=None,
        description="Run finish timestamp (null while still running)",
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedRunLogs(BaseModel):
    """Incremental log read of an isolated background run."""

    text: str = Field(description="Log content from the requested cursor")
    cursor: int = Field(
        description="Next byte cursor for incremental reads (pass to the next run_logs call)"
    )

    model_config = ConfigDict(populate_by_name=True)


class HardeningLayerState(BaseModel):
    """Whether one hardening layer is actually enforced (OSEP-0018)."""

    state: str | None = Field(
        default=None,
        description="active | disabled (not configured) | degraded | unsupported",
    )
    message: str | None = Field(
        default=None,
        description="Concrete reason whenever state is not active",
    )


class HardeningStatus(BaseModel):
    """execd init-mode and workload-hardening state (OSEP-0018)."""

    init_mode: str | None = Field(
        default=None, description='"pid1" | "subreaper" | "none"'
    )
    signal_shield: bool = Field(
        default=False,
        description="Whether the kernel PID 1 signal shield is active",
    )
    cap_drop: HardeningLayerState | None = Field(
        default=None, description="Capability/bounding-set reduction on user code"
    )
    seccomp: HardeningLayerState | None = Field(
        default=None, description="Seccomp floor installed on user code"
    )
    landlock: HardeningLayerState | None = Field(
        default=None, description="Landlock filesystem confinement"
    )
    ebpf: HardeningLayerState | None = Field(
        default=None, description="eBPF exec/connect/privilege observation"
    )

    model_config = ConfigDict(populate_by_name=True)


class IsolatedCapabilities(BaseModel):
    """Isolator capabilities reported by execd."""

    available: bool = Field(
        default=False, description="Whether isolation is available"
    )
    isolator: str | None = Field(
        default=None, description="Isolator name (e.g. 'bubblewrap')"
    )
    version: str | None = Field(
        default=None, description="Isolator version string"
    )
    message: str | None = Field(
        default=None, description="Diagnostic message when unavailable"
    )
    setpriv_available: bool = Field(
        default=False,
        description=(
            "Whether sessions using setpriv can be created with execd's default UID/GID. "
            "Requests selecting different UID/GID values may still return NOT_SUPPORTED "
            "when identity switching is unavailable."
        ),
    )
    userns_available: bool = Field(
        default=False, description="Whether userns uid mode is available"
    )
    commit_supported: bool = Field(
        default=False, description="Whether commit is supported"
    )
    diff_supported: bool = Field(
        default=False, description="Whether diff is supported"
    )
    hardening: HardeningStatus | None = Field(
        default=None,
        description="execd init-mode and workload-hardening state (OSEP-0018)",
    )

    model_config = ConfigDict(populate_by_name=True)