Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(server): validate network policy actions and reject unknown fields
Jackmeson10d17b748363f
diff --git a/docs/guides/network-isolation.md b/docs/guides/network-isolation.mdindex 6a51c107f..1adf6582c 100644--- a/docs/guides/network-isolation.md+++ b/docs/guides/network-isolation.md@@ -138,6 +138,8 @@ The request can still fail after DNS resolution if the Service ClusterIP falls iIf global enforced isolation is not desired, or if specific sandboxes need more permissive access, you can explicitly deny internal network access at sandbox creation time via the `network_policy` parameter:+At sandbox creation, rule `action` and policy `defaultAction` accept case and whitespace variants (for example, `" Allow "` and `"DENY"`) and are normalized to lowercase; blank actions retain the existing `deny` fallback. Unrecognized action names return HTTP 400. Unknown policy or rule fields, such as `port` instead of `ports`, return HTTP 422. Omitting `defaultAction` or `egress` keeps the existing defaults.+::: warning Pool mode limitationPer-request `networkPolicy` is not supported when the lifecycle API creates a sandbox from a pre-warmed Pool via `extensions.poolRef`. Pool pods already exist, so the server cannot inject the egress sidecar for an individual allocation and rejects requests that contain both fields. Configure the required network controls in the Pool pod template before its pods are created, or use a non-pooled sandbox when each request needs its own policy.:::diff --git a/server/opensandbox_server/api/lifecycle.py b/server/opensandbox_server/api/lifecycle.pyindex 128f7826d..f05c16ab2 100644--- a/server/opensandbox_server/api/lifecycle.py+++ b/server/opensandbox_server/api/lifecycle.py@@ -54,6 +54,7 @@ from opensandbox_server.services.constants import (from opensandbox_server.services.factory import create_sandbox_servicefrom opensandbox_server.services.snapshot_restore import resolve_sandbox_image_from_requestfrom opensandbox_server.services.snapshot_service import create_snapshot_service+from opensandbox_server.services.validators import normalize_network_policy_actionsrouter = APIRouter(tags=["Sandboxes"])@@ -114,6 +115,7 @@ async def create_sandbox("""validate_extensions(request.extensions)validate_renew_policy_conflict(request.lifecycle, request.extensions)+ normalize_network_policy_actions(request.network_policy)# Resolve snapshotId before backend routing: the owning backend recorded# on the snapshot row selects the fsb vs pod backend for restores.if not (request.template_id or "").strip():diff --git a/server/opensandbox_server/api/schema.py b/server/opensandbox_server/api/schema.pyindex 39ce31cc9..92deeb09b 100644--- a/server/opensandbox_server/api/schema.py+++ b/server/opensandbox_server/api/schema.py@@ -176,6 +176,7 @@ class NetworkRule(BaseModel):class Config:populate_by_name = True+ extra = "forbid"class NetworkPolicy(BaseModel):@@ -195,6 +196,7 @@ class NetworkPolicy(BaseModel):class Config:populate_by_name = True+ extra = "forbid"class CredentialProxyConfig(BaseModel):diff --git a/server/opensandbox_server/services/fast_sandbox/network_policy.py b/server/opensandbox_server/services/fast_sandbox/network_policy.pyindex c3927efa9..e3f769f25 100644--- a/server/opensandbox_server/services/fast_sandbox/network_policy.py+++ b/server/opensandbox_server/services/fast_sandbox/network_policy.py@@ -8,18 +8,15 @@from fastapi import HTTPExceptionfrom opensandbox_server.api.schema import NetworkPolicy, NetworkRule+from opensandbox_server.services.validators import normalize_network_policy_actiondef normalized_policy(policy: NetworkPolicy) -> dict:- default_action = (policy.default_action or "deny").strip().lower() or "deny"- if default_action not in ("allow", "deny"):- raise HTTPException(400, detail="networkPolicy.defaultAction must be allow or deny.")+ default_action = normalize_network_policy_action(policy.default_action, "networkPolicy.defaultAction")rules = []for rule in policy.egress:target = (rule.target or "").strip()- action = rule.action.strip().lower() or "deny"- if action not in ("allow", "deny"):- raise HTTPException(400, detail="networkPolicy rule action must be allow or deny.")+ action = normalize_network_policy_action(rule.action, "networkPolicy rule action")if rule.ports:# Not enforceable by the fastlet nft path yet (#2213); accepting# would silently drop deny rules.diff --git a/server/opensandbox_server/services/validators.py b/server/opensandbox_server/services/validators.pyindex 659ee5c76..384ad8f71 100644--- a/server/opensandbox_server/services/validators.py+++ b/server/opensandbox_server/services/validators.py@@ -524,6 +524,26 @@ def ensure_valid_ossfs_volume(ossfs: "OSSFS") -> None:)+def normalize_network_policy_action(action: Optional[str], field: str) -> str:+ """Normalize action names using the existing Fast Sandbox deny fallback."""+ normalized = (action or "deny").strip().lower() or "deny"+ if normalized not in ("allow", "deny"):+ raise HTTPException(400, detail=f"{field} must be allow or deny.")+ return normalized+++def normalize_network_policy_actions(network_policy: Optional["NetworkPolicy"]) -> None:+ """Validate create-time actions before runtime dispatch, preserving omitted defaults."""+ if network_policy is None:+ return+ if network_policy.default_action is not None:+ network_policy.default_action = normalize_network_policy_action(+ network_policy.default_action, "networkPolicy.defaultAction"+ )+ for rule in network_policy.egress:+ rule.action = normalize_network_policy_action(rule.action, "networkPolicy rule action")++def ensure_egress_configured(network_policy: Optional["NetworkPolicy"],egress_config: Optional["EgressConfig"],diff --git a/server/tests/test_routes_create_delete.py b/server/tests/test_routes_create_delete.pyindex c470f7fc8..f73366eb3 100644--- a/server/tests/test_routes_create_delete.py+++ b/server/tests/test_routes_create_delete.py@@ -12,12 +12,18 @@# See the License for the specific language governing permissions and# limitations under the License.+import jsonfrom datetime import datetime, timedelta, timezone+from unittest.mock import AsyncMock, MagicMock+import pytestfrom fastapi.testclient import TestClientfrom opensandbox_server.api import lifecyclefrom opensandbox_server.api.schema import CreateSandboxRequest, CreateSandboxResponse, SandboxStatus+from opensandbox_server.config import AppConfig, DockerConfig, EgressConfig, RuntimeConfig+from opensandbox_server.services.constants import EGRESS_RULES_ENV+from opensandbox_server.services.docker import DockerSandboxServicedef test_create_sandbox_openapi_describes_synchronous_provisioning(@@ -42,14 +48,31 @@ def test_create_sandbox_openapi_declares_quota_rejection_403(assert quota_response["content"]["application/json"]["schema"]["$ref"].endswith("ErrorResponse")+ "network_policy",+ [+ None,+ {},+ {"egress": [{"action": "allow", "target": "example.com"}]},+ {"defaultAction": "allow", "egress": [{"action": "deny", "ports": [25]}]},+ {+ "defaultAction": "deny",+ "egress": [+ {"action": "allow", "target": "*.example.com"},+ {"action": "deny", "target": "10.0.0.0/8", "ports": [22, 443]},+ ],+ },+ ],+)def test_create_sandbox_returns_202_and_service_payload(client: TestClient,auth_headers: dict,sample_sandbox_request: dict,monkeypatch,+ network_policy,) -> None:now = datetime.now(timezone.utc)- calls: list[object] = []+ calls: list[CreateSandboxRequest] = []class StubService:@staticmethod@@ -69,7 +92,7 @@ def test_create_sandbox_returns_202_and_service_payload(response = client.post("/v1/sandboxes",headers=auth_headers,- json=sample_sandbox_request,+ json={**sample_sandbox_request, "networkPolicy": network_policy},)assert response.status_code == 202@@ -79,7 +102,16 @@ def test_create_sandbox_returns_202_and_service_payload(assert payload["metadata"]["project"] == "test-project"assert payload["entrypoint"] == ["python", "-c", "print('Hello from sandbox')"]assert len(calls) == 1+ assert calls[0].image is not Noneassert calls[0].image.uri == "python:3.11"+ if network_policy is None:+ assert calls[0].network_policy is None+ else:+ assert calls[0].network_policy is not None+ assert calls[0].network_policy.model_dump(by_alias=True, exclude_none=True) == {+ "egress": [],+ **network_policy,+ }def test_create_sandbox_manual_cleanup_omits_none_fields(@@ -131,6 +163,148 @@ def test_create_sandbox_rejects_invalid_request()assert response.status_code == 422+ assert set(response.json()) == {"detail"}+ assert all(set(error) == {"type", "loc", "msg"} for error in response.json()["detail"])+++ ("network_policy", "location", "error_type"),+ [+ ({"egress": [{"action": "allow", "target": "10.0.0.0/8", "port": [443]}]}, ["egress", 0, "port"], "extra_forbidden"),+ ({"egres": []}, ["egres"], "extra_forbidden"),+ ({"egress": [{"action": "allow", "target": "example.com", "ports": [443]}]}, ["egress", 0], "value_error"),+ ],+)+def test_create_sandbox_rejects_invalid_network_policy(+ client: TestClient,+ auth_headers: dict,+ sample_sandbox_request: dict,+ monkeypatch,+ network_policy,+ location,+ error_type,+) -> None:+ now = datetime.now(timezone.utc)+ create = AsyncMock(return_value=CreateSandboxResponse.model_validate({+ "id": "sbx-001",+ "status": {"state": "Pending"},+ "createdAt": now,+ }))+ monkeypatch.setattr(lifecycle.sandbox_service, "create_sandbox", create)++ response = client.post(+ "/v1/sandboxes",+ headers=auth_headers,+ json={**sample_sandbox_request, "networkPolicy": network_policy},+ )++ assert response.status_code == 422+ messages = {+ "extra_forbidden": "Extra inputs are not permitted",+ "value_error": "Value error, NetworkRule ports are not supported for domain targets yet.",+ }+ assert response.json() == {"detail": [{+ "type": error_type,+ "loc": ["body", "networkPolicy", *location],+ "msg": messages[error_type],+ }]}+ create.assert_not_called()+++def docker_policy_runtime(monkeypatch):+ docker_client = MagicMock()+ docker_client.containers.list.return_value = []+ docker_client.api.create_container.side_effect = [+ {"Id": "sidecar-id"}, {"Id": "main-id"},+ ]+ docker_client.containers.get.side_effect = [+ MagicMock(id="sidecar-id"), MagicMock(id="main-id"),+ ]+ monkeypatch.setattr(+ "opensandbox_server.services.docker.docker_service.docker.from_env",+ lambda: docker_client,+ )+ service = DockerSandboxService(config=AppConfig(+ runtime=RuntimeConfig(type="docker", execd_image="execd:latest"),+ docker=DockerConfig(network_mode="bridge"),+ egress=EgressConfig(image="egress:latest"),+ ))+ monkeypatch.setattr(lifecycle, "sandbox_service", service)+ for name in (+ "_ensure_image_available",+ "_prepare_sandbox_runtime",+ "_wait_for_egress_sidecar_ready",+ "_schedule_expiration",+ ):+ monkeypatch.setattr(service, name, MagicMock())+ monkeypatch.setattr(+ "opensandbox_server.services.docker.docker_service.allocate_port_bindings",+ lambda *args, **kwargs: {+ "44772": ("0.0.0.0", 44772),+ "8080": ("0.0.0.0", 8080),+ "18080": ("0.0.0.0", 18080),+ },+ )+ return docker_client+++ ("network_policy", "message"),+ [+ ({"egress": [{"action": "permit", "target": "example.com"}]}, "networkPolicy rule action must be allow or deny."),+ ({"defaultAction": "permit"}, "networkPolicy.defaultAction must be allow or deny."),+ ({"egress": [{"action": " DROP ", "target": "example.com"}]}, "networkPolicy rule action must be allow or deny."),+ ({"defaultAction": " BLOCK "}, "networkPolicy.defaultAction must be allow or deny."),+ ],+)+def test_create_docker_rejects_invalid_network_policy_actions(+ client, auth_headers, sample_sandbox_request, docker_policy_runtime, network_policy, message,+):+ response = client.post(+ "/v1/sandboxes",+ headers=auth_headers,+ json={**sample_sandbox_request, "metadata": {}, "networkPolicy": network_policy},+ )++ assert response.status_code == 400+ assert response.json() == {"code": "GENERAL::UNKNOWN_ERROR", "message": message}+ docker_policy_runtime.api.create_container.assert_not_called()+++ ("network_policy", "expected"),+ [+ (+ {"defaultAction": "DENY", "egress": [{"action": " Allow ", "target": "example.com"}]},+ {"defaultAction": "deny", "egress": [{"action": "allow", "target": "example.com"}]},+ ),+ (+ {"defaultAction": " Allow ", "egress": [{"action": "DENY", "ports": [25]}]},+ {"defaultAction": "allow", "egress": [{"action": "deny", "ports": [25]}]},+ ),+ (+ {"defaultAction": "deny", "egress": [{"action": "allow", "target": "10.0.0.0/8", "ports": [443]}]},+ {"defaultAction": "deny", "egress": [{"action": "allow", "target": "10.0.0.0/8", "ports": [443]}]},+ ),+ ({"egress": [{"action": "allow", "target": "example.com"}]}, {"egress": [{"action": "allow", "target": "example.com"}]}),+ ({}, {"egress": []}),+ ],+)+def test_create_docker_sends_normalized_network_policy_to_sidecar(+ client, auth_headers, sample_sandbox_request, docker_policy_runtime, network_policy, expected,+):+ response = client.post(+ "/v1/sandboxes",+ headers=auth_headers,+ json={**sample_sandbox_request, "metadata": {}, "networkPolicy": network_policy},+ )++ assert response.status_code == 202+ sidecar_call = docker_policy_runtime.api.create_container.call_args_list[0]+ assert sidecar_call.kwargs["name"].startswith("sandbox-egress-")+ environment = dict(item.split("=", 1) for item in sidecar_call.kwargs["environment"])+ assert json.loads(environment[EGRESS_RULES_ENV]) == expecteddef test_create_sandbox_accepts_snapshot_id_without_entrypoint(diff --git a/server/tests/test_schema.py b/server/tests/test_schema.pyindex a627eb03d..5994e8c12 100644--- a/server/tests/test_schema.py+++ b/server/tests/test_schema.py@@ -916,6 +916,44 @@ class TestCreateSandboxRequestPoolMode:)+class TestNetworkPolicy:+ @pytest.mark.parametrize(+ "payload",+ [+ {"egress": [{"action": "allow", "target": "10.0.0.0/8", "port": [443]}]},+ {"egres": []},+ ],+ )+ def test_rejects_unknown_fields(self, payload):+ with pytest.raises(ValidationError, match="Extra inputs are not permitted"):+ NetworkPolicy.model_validate(payload)++ @pytest.mark.parametrize("action", ["allow", "deny"])+ def test_round_trips_valid_policy(self, action):+ payload = {+ "defaultAction": action,+ "egress": [+ {"action": action, "target": "*.example.com"},+ {"action": action, "target": "10.0.0.0/8", "ports": [22, 443]},+ {"action": action, "ports": [25]},+ ],+ }+ policy = NetworkPolicy.model_validate(payload)+ assert policy.model_dump(by_alias=True, exclude_none=True) == payload++ def test_preserves_omitted_defaults(self):+ policy = NetworkPolicy()+ assert policy.default_action is None+ assert policy.egress == []+ assert policy.model_dump(by_alias=True, exclude_none=True) == {"egress": []}++ def test_preserves_default_action_field_name(self):+ policy = NetworkPolicy.model_validate({"default_action": "deny"})+ assert policy.model_dump(by_alias=True, exclude_none=True) == {+ "defaultAction": "deny", "egress": [],+ }++class TestNetworkRule:"""NetworkRule.target became optional so a rule can be scoped by `ports`alone; these guard the target/ports combinations the API is meant to