opensandbox-server 0.2.0__tar.gz → 0.2.1__tar.gz

opensandbox_server-0.2.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: opensandbox-server
+Version: 0.2.1
+Summary: FastAPI control plane for OpenSandbox that manages sandbox lifecycle on Docker (ready) and Kubernetes (planned) runtimes.
+Project-URL: Homepage, https://github.com/opensandbox-group/OpenSandbox
+Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
+Project-URL: Issues, https://github.com/opensandbox-group/OpenSandbox/issues
+Author-email: OpenSandbox Team <pangjiping.pjp@alibaba-inc.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: control-plane,fastapi,opensandbox,sandbox,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: docker
+Requires-Dist: fastapi>=0.137.0
+Requires-Dist: httpx[socks]
+Requires-Dist: kubernetes
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings
+Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: pyyaml
+Requires-Dist: redis>=5
+Requires-Dist: starlette>=1.3.1
+Requires-Dist: tomli; python_version < '3.11'
+Requires-Dist: uvicorn[standard]
+Requires-Dist: websockets>=14.0
+Description-Content-Type: text/markdown
+
+# OpenSandbox Server
+
+Documentation: [docs/components/server.md](../docs/components/server.md)
+

opensandbox_server-0.2.1/README.md

@@ -0,0 +1,4 @@
+# OpenSandbox Server
+
+Documentation: [docs/components/server.md](../docs/components/server.md)
+

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/api/schema.py

@@ -198,9 +198,9 @@ class PVC(BaseModel):
         description=(
             "When true, the volume is automatically removed when the sandbox is "
             "deleted. Only applies to volumes that were auto-created by the server "
-            "(Docker only). Pre-existing volumes are never removed. Has no effect "
-            "on Kubernetes PVCs, whose lifecycle is managed by the StorageClass "
-            "reclaim policy."
+            "on this request; pre-existing volumes are never removed. For "
+            "Kubernetes, the resulting PVC delete then triggers the bound PV's "
+            "StorageClass reclaim policy (Retain/Delete)."
         ),
     )
 
@@ -424,7 +424,16 @@ class CreateSandboxRequest(BaseModel):
     resource_limits: Optional[ResourceLimits] = Field(
         None,
         alias="resourceLimits",
-        description="Runtime resource constraints for the sandbox instance. Optional when poolRef is provided.",
+        description="Runtime resource constraints (hard caps) for the sandbox instance. Optional when poolRef is provided.",
+    )
+    resource_requests: Optional[ResourceLimits] = Field(
+        None,
+        alias="resourceRequests",
+        description=(
+            "Resource reservations (guaranteed minimums) for the sandbox instance. "
+            "When provided, used as Kubernetes resource requests, enabling Burstable QoS. "
+            "When omitted, resourceLimits values are used for both limits and requests."
+        ),
     )
     env: Optional[Dict[str, Optional[str]]] = Field(
         None,

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/examples/example.config.k8s.toml

@@ -32,7 +32,7 @@ level = "INFO"
 
 [runtime]
 type = "kubernetes"
-execd_image = "opensandbox/execd:v1.0.19"
+execd_image = "opensandbox/execd:v1.0.20"
 
 [storage]
 # Allowlist of host path prefixes permitted for bind mounts.
@@ -75,7 +75,7 @@ batchsandbox_template_file = "~/batchsandbox-template.yaml"
 mode = "direct"
 
 [egress]
-image = "opensandbox/egress:v1.1.0"
+image = "opensandbox/egress:v1.1.3"
 mode = "dns"
 # Default is true (recommended for dual-stack CNI). Set false only if you need IPv6 in the netns (see server/configuration.md).
 # disable_ipv6 = false

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/examples/example.config.k8s.zh.toml

@@ -32,7 +32,7 @@ level = "INFO"
 
 [runtime]
 type = "kubernetes"
-execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.19"
+execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.20"
 
 [storage]
 # 允许进行 bind mount 的宿主机路径前缀白名单。
@@ -76,7 +76,7 @@ batchsandbox_template_file = "~/batchsandbox-template.yaml"
 mode = "direct"
 
 [egress]
-image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.1.0"
+image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.1.3"
 mode = "dns"
 # Default is true (recommended for dual-stack CNI). Set false only if you need IPv6 in the netns (see server/configuration.md).
 # disable_ipv6 = false

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/examples/example.config.toml

@@ -32,7 +32,7 @@ level = "INFO"
 
 [runtime]
 type = "docker"
-execd_image = "opensandbox/execd:v1.0.19"
+execd_image = "opensandbox/execd:v1.0.20"
 
 [storage]
 # Allowlist of host path prefixes permitted for bind mounts.
@@ -63,7 +63,7 @@ seccomp_profile = ""
 mode = "direct"
 
 [egress]
-image = "opensandbox/egress:v1.1.0"
+image = "opensandbox/egress:v1.1.3"
 mode = "dns"
 
 # 🧪 [EXPERIMENTAL] Renew-on-access. Off by default — see server/README.md.

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/examples/example.config.zh.toml

@@ -32,7 +32,7 @@ level = "INFO"
 
 [runtime]
 type = "docker"
-execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.19"
+execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.20"
 
 [storage]
 allowed_host_paths = []
@@ -61,7 +61,7 @@ seccomp_profile = ""
 mode = "direct"
 
 [egress]
-image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.1.0"
+image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.1.3"
 mode = "dns"
 
 # 🧪 [EXPERIMENTAL] 按访问续期。默认关闭 — 见 server/README_zh.md。

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/extensions/__init__.py

@@ -23,8 +23,10 @@ from opensandbox_server.extensions.codec import (
 from opensandbox_server.extensions.keys import (
     ACCESS_RENEW_EXTEND_SECONDS_KEY,
     ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY,
+    BOOTSTRAP_EXECD_ISOLATION_KEY,
     EXTENSIONS_ANNOTATION_PREFIX,
     ANNOTATION_METADATA_PREFIX,
+    ISOLATION_UPPER_MOUNT_PATH,
 )
 from opensandbox_server.extensions.validation import (
     ACCESS_RENEW_EXTEND_SECONDS_MAX,
@@ -42,4 +44,6 @@ __all__ = [
     "apply_extensions_to_annotations",
     "EXTENSIONS_ANNOTATION_PREFIX",
     "ANNOTATION_METADATA_PREFIX",
+    "BOOTSTRAP_EXECD_ISOLATION_KEY",
+    "ISOLATION_UPPER_MOUNT_PATH",
 ]

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/extensions/keys.py

@@ -18,6 +18,15 @@
 ACCESS_RENEW_EXTEND_SECONDS_KEY = "access.renew.extend.seconds"
 ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY = "opensandbox.io/access-renew-extend-seconds"
 
+# bootstrap.execd.isolation extension key
+# When set to "enable", the sandbox container receives CAP_SYS_ADMIN so that
+# execd can use bwrap namespace isolation (OSEP-0013).
+BOOTSTRAP_EXECD_ISOLATION_KEY = "bootstrap.execd.isolation"
+
+# Default mount path for the isolation upper directory.
+# Must match the execd DefaultConfig().UpperRoot value.
+ISOLATION_UPPER_MOUNT_PATH = "/var/lib/execd/isolation"
+
 # Extensions to annotations transformation prefix
 # User-specified extension keys starting with EXTENSIONS_ANNOTATION_PREFIX
 # are automatically propagated to Pod annotations with ANNOTATION_METADATA_PREFIX

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/services/constants.py

@@ -42,6 +42,19 @@ EGRESS_MODE_ENV = "OPENSANDBOX_EGRESS_MODE"
 # Must match components/egress/pkg/constants/configuration.go EnvEgressToken
 OPENSANDBOX_EGRESS_TOKEN = "OPENSANDBOX_EGRESS_TOKEN"
 OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT = "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT"
+
+EGRESS_ENV_PREFIX = "OPENSANDBOX_EGRESS_"
+OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE = "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE"
+ALLOWED_EGRESS_ENV_VARS = frozenset({
+    "OPENSANDBOX_EGRESS_LOG_LEVEL",
+    "OPENSANDBOX_EGRESS_DNS_UPSTREAM_TIMEOUT",
+    OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE,
+    OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
+    "OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT",
+    "OPENSANDBOX_EGRESS_DENY_WEBHOOK",
+    "OPENSANDBOX_EGRESS_METRICS_EXTRA_ATTRS",
+    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_TLS",
+})
 OPENSANDBOX_RUNTIME_VOLUME_NAME = "opensandbox-bin"
 OPENSANDBOX_RUNTIME_MOUNT_PATH = "/opt/opensandbox"
 
@@ -146,6 +159,9 @@ __all__ = [
     "EGRESS_MODE_ENV",
     "OPENSANDBOX_EGRESS_TOKEN",
     "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT",
+    "EGRESS_ENV_PREFIX",
+    "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE",
+    "ALLOWED_EGRESS_ENV_VARS",
     "OPENSANDBOX_RUNTIME_VOLUME_NAME",
     "OPENSANDBOX_RUNTIME_MOUNT_PATH",
     "SandboxErrorCodes",

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/services/docker/docker_service.py

@@ -39,6 +39,8 @@ from fastapi import HTTPException, status
 
 from opensandbox_server.extensions import (
     ACCESS_RENEW_EXTEND_SECONDS_METADATA_KEY,
+    BOOTSTRAP_EXECD_ISOLATION_KEY,
+    ISOLATION_UPPER_MOUNT_PATH,
 )
 from opensandbox_server.api.schema import (
     CreateSandboxRequest,
@@ -83,6 +85,7 @@ from opensandbox_server.services.docker.windows_profile import (
 )
 from opensandbox_server.services.extension_service import ExtensionService
 from opensandbox_server.services.constants import (
+    OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE,
     OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
     OPENSANDBOX_RUNTIME_MOUNT_PATH,
     SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY,
@@ -102,6 +105,7 @@ from opensandbox_server.services.endpoint_auth import (
 from opensandbox_server.services.helpers import (
     matches_filter,
     parse_timestamp,
+    split_egress_env,
 )
 from opensandbox_server.services.docker.ossfs_mixin import OSSFSMixin
 from opensandbox_server.services.sandbox_service import SandboxService
@@ -157,6 +161,7 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
         self.network_mode = (self.app_config.docker.network_mode or HOST_NETWORK_MODE).lower()
         self._execd_archive_cache: Dict[str, bytes] = {}
         self._bootstrap_script_cache: Dict[str, bytes] = {}
+        self._bwrap_archive_cache: Dict[str, bytes] = {}
         self._windows_profile_cache: Dict[str, bytes] = {}
         self._daemon_platform: Optional[PlatformSpec] = None
         self._metadata_store = DockerMetadataStore()
@@ -402,11 +407,18 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
         except DockerException as exc:
             logger.warning("Failed to remove expired sandbox %s: %s", sandbox_id, exc)
 
+        managed_volumes_raw = labels.get(SANDBOX_MANAGED_VOLUMES_LABEL, "[]")
+        try:
+            managed_volumes: list[str] = json.loads(managed_volumes_raw)
+        except (TypeError, json.JSONDecodeError):
+            managed_volumes = []
+
         self._remove_expiration_tracking(sandbox_id)
         # Ensure sidecar is also cleaned up on expiration
         self._cleanup_egress_sidecar(sandbox_id)
         self._cleanup_windows_oem_volume(sandbox_id, labels)
         self._release_ossfs_mounts(mount_keys)
+        self._cleanup_managed_volumes(sandbox_id, managed_volumes)
         self._metadata_store.delete(sandbox_id)
 
     def _restore_existing_sandboxes(self) -> None:
@@ -630,11 +642,33 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
         self._ensure_secure_access_support(request)
         self._ensure_network_policy_support(request)
         self._validate_network_exists()
+
+        try:
+            sandbox_env, egress_env = split_egress_env(request.env)
+        except ValueError as e:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={
+                    "code": SandboxErrorCodes.INVALID_PARAMETER,
+                    "message": str(e),
+                },
+            ) from e
+
         pvc_inspect_cache, auto_created_volumes = self._validate_volumes(request)
         sandbox_id, created_at, expires_at = self._prepare_creation_context(request)
-        return self._provision_sandbox(
-            sandbox_id, request, created_at, expires_at, pvc_inspect_cache, auto_created_volumes,
-        )
+        try:
+            return self._provision_sandbox(
+                sandbox_id, request, created_at, expires_at, pvc_inspect_cache, auto_created_volumes,
+                sandbox_env=sandbox_env, egress_env=egress_env,
+            )
+        except ValueError as e:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={
+                    "code": SandboxErrorCodes.INVALID_PARAMETER,
+                    "message": str(e),
+                },
+            ) from e
 
     def _async_provision_worker(
         self,
@@ -761,8 +795,13 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
         expires_at: Optional[datetime],
         pvc_inspect_cache: Optional[dict[str, dict]] = None,
         auto_created_volumes: Optional[list[str]] = None,
+        sandbox_env: Optional[Dict[str, Optional[str]]] = None,
+        egress_env: Optional[Dict[str, Optional[str]]] = None,
     ) -> CreateSandboxResponse:
-        labels, environment = self._build_labels_and_env(sandbox_id, request, expires_at)
+        if sandbox_env is None and egress_env is None:
+            sandbox_env, egress_env = split_egress_env(request.env)
+        patched_request = request.model_copy(update={"env": sandbox_env or None})
+        labels, environment = self._build_labels_and_env(sandbox_id, patched_request, expires_at)
         if auto_created_volumes:
             labels[SANDBOX_MANAGED_VOLUMES_LABEL] = json.dumps(
                 auto_created_volumes, separators=(",", ":"),
@@ -772,6 +811,25 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
         egress_token: Optional[str] = None
         requested_windows_profile = is_windows_platform(request.platform)
 
+        credential_proxy_enabled = bool(
+            request.credential_proxy and request.credential_proxy.enabled
+        )
+
+        if credential_proxy_enabled and egress_env.get(OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE):
+            raise ValueError(
+                f"'{OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE}' cannot be set when credential proxy is enabled"
+            )
+
+        if egress_env and not request.network_policy:
+            dropped_keys = sorted(egress_env.keys())
+            logger.warning(
+                "Sandbox %s has OPENSANDBOX_EGRESS_ env vars %s but no networkPolicy; "
+                "these variables will be ignored because no egress sidecar is created",
+                sandbox_id,
+                dropped_keys,
+            )
+            egress_env = {}
+
         if requested_windows_profile:
             validate_windows_resource_limits((request.resource_limits.root if request.resource_limits else None) or {})
             validate_windows_runtime_prerequisites()
@@ -785,9 +843,6 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
             )
 
         sidecar_container = None
-        credential_proxy_enabled = bool(
-            request.credential_proxy and request.credential_proxy.enabled
-        )
         runtime_volume_name: Optional[str] = None
         try:
             # For dockur/windows profile, resourceLimits are translated to
@@ -814,21 +869,21 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
             container_exposed_ports: Optional[list[str]] = exposed_ports
 
             if request.network_policy:
-                if credential_proxy_enabled:
-                    runtime_volume_name = f"opensandbox-runtime-{sandbox_id}"
-                    with self._docker_operation(
-                        "create credential proxy runtime volume", sandbox_id
-                    ):
-                        self.docker_client.volumes.create(
-                            name=runtime_volume_name,
-                            labels={SANDBOX_MANAGED_VOLUMES_LABEL: "server"},
-                        )
-                    auto_created_volumes = list(auto_created_volumes or [])
-                    auto_created_volumes.append(runtime_volume_name)
-                    labels[SANDBOX_MANAGED_VOLUMES_LABEL] = json.dumps(
-                        auto_created_volumes,
-                        separators=(",", ":"),
+                runtime_volume_name = f"opensandbox-runtime-{sandbox_id}"
+                with self._docker_operation(
+                    "create egress runtime volume", sandbox_id
+                ):
+                    self.docker_client.volumes.create(
+                        name=runtime_volume_name,
+                        labels={SANDBOX_MANAGED_VOLUMES_LABEL: "server"},
                     )
+                auto_created_volumes = list(auto_created_volumes or [])
+                auto_created_volumes.append(runtime_volume_name)
+                labels[SANDBOX_MANAGED_VOLUMES_LABEL] = json.dumps(
+                    auto_created_volumes,
+                    separators=(",", ":"),
+                )
+                if credential_proxy_enabled:
                     environment = [
                         entry
                         for entry in environment
@@ -859,6 +914,7 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
                     ),
                     runtime_volume_name=runtime_volume_name,
                     credential_proxy_enabled=credential_proxy_enabled,
+                    extra_env=egress_env or None,
                 )
                 labels[SANDBOX_EMBEDDING_PROXY_PORT_LABEL] = str(host_execd_port)
                 labels[SANDBOX_HTTP_PORT_LABEL] = str(host_http_port)
@@ -891,9 +947,16 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
 
             # Inject volume bind mounts into Docker host config
             if runtime_volume_name:
-                volume_binds.append(
-                    f"{runtime_volume_name}:{OPENSANDBOX_RUNTIME_MOUNT_PATH}:rw"
+                runtime_mount_suffix = f":{OPENSANDBOX_RUNTIME_MOUNT_PATH}:"
+                runtime_mount_end = f":{OPENSANDBOX_RUNTIME_MOUNT_PATH}"
+                has_runtime_mount = any(
+                    runtime_mount_suffix in bind or bind.endswith(runtime_mount_end)
+                    for bind in volume_binds
                 )
+                if not has_runtime_mount:
+                    volume_binds.append(
+                        f"{runtime_volume_name}:{OPENSANDBOX_RUNTIME_MOUNT_PATH}:rw"
+                    )
             if volume_binds:
                 host_config_kwargs["binds"] = volume_binds
             if requested_windows_profile:
@@ -907,6 +970,26 @@ class DockerSandboxService(DockerDiagnosticsMixin, DockerRuntimeMixin, DockerVol
                 )
                 environment = inject_windows_user_ports(environment, exposed_ports)
 
+            # Inject CAP_SYS_ADMIN + unconfined AppArmor when bwrap isolation is requested.
+            # bwrap needs pivot_root/mount which require CAP_SYS_ADMIN and are blocked
+            # by Docker's default AppArmor profile.
+            if (request.extensions or {}).get(BOOTSTRAP_EXECD_ISOLATION_KEY) == "enable":
+                cap_add = set(host_config_kwargs.get("cap_add") or [])
+                cap_add.add("SYS_ADMIN")
+                host_config_kwargs["cap_add"] = sorted(cap_add)
+                security_opt = list(host_config_kwargs.get("security_opt") or [])
+                security_opt = [s for s in security_opt if not s.startswith(("apparmor=", "seccomp="))]
+                security_opt.append("apparmor=unconfined")
+                security_opt.append("seccomp=unconfined")
+                host_config_kwargs["security_opt"] = security_opt
+                tmpfs = dict(host_config_kwargs.get("tmpfs") or {})
+                tmpfs[ISOLATION_UPPER_MOUNT_PATH] = ""
+                host_config_kwargs["tmpfs"] = tmpfs
+                logger.warning(
+                    "sandbox %s: granting CAP_SYS_ADMIN + apparmor/seccomp=unconfined + tmpfs for bwrap isolation (bootstrap.execd.isolation=enable)",
+                    sandbox_id,
+                )
+
             created_container = self._create_and_start_container(
                 sandbox_id,
                 image_uri,

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/services/docker/networking.py

@@ -28,7 +28,7 @@ import socket
 import time
 import urllib.error
 import urllib.request
-from typing import Any, Optional
+from typing import Any, Dict, Optional
 
 from docker.errors import DockerException, NotFound as DockerNotFound
 from fastapi import HTTPException, status
@@ -53,7 +53,7 @@ from opensandbox_server.services.endpoint_auth import (
     build_egress_auth_headers,
     merge_endpoint_headers,
 )
-from opensandbox_server.services.validators import ensure_egress_configured
+from opensandbox_server.services.validators import ensure_egress_configured, ensure_egress_runtime_compatible
 
 logger = logging.getLogger(__name__)
 
@@ -139,6 +139,7 @@ class DockerNetworkingMixin:
 
         # Common validation: egress.image must be configured
         ensure_egress_configured(request.network_policy, self.app_config.egress)
+        ensure_egress_runtime_compatible(request.network_policy, self.app_config.secure_runtime)
 
     def _ensure_secure_access_support(self, request) -> None:
         """Validate that secure access can be honored under the current Docker runtime."""
@@ -370,6 +371,7 @@ class DockerNetworkingMixin:
         egress_api_host_port: Optional[int] = None,
         runtime_volume_name: Optional[str] = None,
         credential_proxy_enabled: bool = False,
+        extra_env: Optional[Dict[str, Optional[str]]] = None,
     ):
         sidecar_name = f"sandbox-egress-{sandbox_id}"
         sidecar_labels = {
@@ -393,6 +395,12 @@ class DockerNetworkingMixin:
         if credential_proxy_enabled:
             sidecar_env.append(f"{OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT}=true")
 
+        if extra_env:
+            skip_keys = {OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT} if credential_proxy_enabled else set()
+            for key, value in extra_env.items():
+                if key not in skip_keys and value is not None:
+                    sidecar_env.append(f"{key}={value}")
+
         sidecar_port_bindings: dict[str, tuple[str, int]] = {
             "44772": ("0.0.0.0", host_execd_port),
             "8080": ("0.0.0.0", host_http_port),

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/services/docker/runtime.py

@@ -117,6 +117,14 @@ class DockerRuntimeMixin:
                     with self._docker_operation("execd cache read bootstrap", "execd-cache"):
                         bs_stream, _ = container.get_archive("/bootstrap.sh")
                         self._bootstrap_script_cache[cache_key] = b"".join(bs_stream)
+                # Cache bwrap binary (best-effort — may not exist in older images).
+                if cache_key not in self._bwrap_archive_cache:
+                    try:
+                        with self._docker_operation("execd cache read bwrap", "execd-cache"):
+                            bwrap_stream, _ = container.get_archive("/usr/local/bin/bwrap")
+                            self._bwrap_archive_cache[cache_key] = b"".join(bwrap_stream)
+                    except DockerException:
+                        logger.warning("bwrap not found in execd image — isolation will be unavailable, upgrade execd image to v1.1.0+")
             except DockerException as exc:
                 raise HTTPException(
                     status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
@@ -227,6 +235,33 @@ class DockerRuntimeMixin:
                 },
             ) from exc
 
+    def _copy_bwrap_to_container(
+        self,
+        container,
+        sandbox_id: str,
+        platform: Optional[PlatformSpec] = None,
+    ) -> None:
+        """Copy bwrap binary into /opt/opensandbox/bin/ (best-effort).
+
+        Bwrap may not exist in older execd images, so failure is non-fatal —
+        isolation will simply be unavailable at runtime.
+        """
+        cache_key = self._normalize_platform_key(platform)
+        archive = self._bwrap_archive_cache.get(cache_key)
+        if archive is None:
+            logger.warning("bwrap archive not cached for %s — isolation will be unavailable, upgrade execd image to v1.1.0+", cache_key)
+            return
+
+        try:
+            with self._docker_operation("copy bwrap to sandbox", sandbox_id):
+                container.put_archive(path=OPENSANDBOX_DIR, data=archive)
+        except DockerException as exc:
+            logger.warning(
+                "Failed to copy bwrap into sandbox %s: %s (isolation will be unavailable)",
+                sandbox_id,
+                exc,
+            )
+
     def _prepare_sandbox_runtime(
         self,
         container,
@@ -236,3 +271,4 @@ class DockerRuntimeMixin:
         """Copy execd artifacts and bootstrap launcher into the sandbox container."""
         self._copy_execd_to_container(container, sandbox_id, platform)
         self._install_bootstrap_script(container, sandbox_id, platform)
+        self._copy_bwrap_to_container(container, sandbox_id, platform)

{opensandbox_server-0.2.0 → opensandbox_server-0.2.1}/opensandbox_server/services/helpers.py

@@ -27,7 +27,12 @@ from datetime import datetime, timezone
 from typing import Dict, Optional
 
 from opensandbox_server.api.schema import Endpoint, Sandbox, SandboxFilter
-from opensandbox_server.services.constants import OPEN_SANDBOX_INGRESS_HEADER
+from opensandbox_server.services.constants import (
+    ALLOWED_EGRESS_ENV_VARS,
+    EGRESS_ENV_PREFIX,
+    OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
+    OPEN_SANDBOX_INGRESS_HEADER,
+)
 from opensandbox_server.config import (
     GATEWAY_ROUTE_MODE_HEADER,
     GATEWAY_ROUTE_MODE_URI,
@@ -234,6 +239,34 @@ def format_ingress_endpoint(
     raise RuntimeError(f"Unsupported route mode: {route_mode}")
 
 
+def split_egress_env(
+    env: Optional[Dict[str, Optional[str]]],
+) -> tuple[Dict[str, Optional[str]], Dict[str, Optional[str]]]:
+    """Split request env into (sandbox_env, egress_env) by OPENSANDBOX_EGRESS_ prefix.
+
+    Only env vars listed in ALLOWED_EGRESS_ENV_VARS are forwarded to the egress
+    sidecar.  Any other OPENSANDBOX_EGRESS_ key raises ValueError.
+    """
+    if not env:
+        return {}, {}
+
+    sandbox_env: Dict[str, Optional[str]] = {}
+    egress_env: Dict[str, Optional[str]] = {}
+    for key, value in env.items():
+        if key.startswith(EGRESS_ENV_PREFIX):
+            if key not in ALLOWED_EGRESS_ENV_VARS:
+                raise ValueError(
+                    f"Environment variable '{key}' is not allowed; "
+                    f"permitted OPENSANDBOX_EGRESS_ keys: {sorted(ALLOWED_EGRESS_ENV_VARS)}"
+                )
+            egress_env[key] = value
+            if key == OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT:
+                sandbox_env[key] = value
+        else:
+            sandbox_env[key] = value
+    return sandbox_env, egress_env
+
+
 __all__ = [
     "parse_memory_limit",
     "parse_nano_cpus",
@@ -242,4 +275,5 @@ __all__ = [
     "normalize_external_endpoint_url",
     "format_ingress_endpoint",
     "matches_filter",
+    "split_egress_env",
 ]