From 784882383d64870134d6d79a2eaeb41427ef9736 Mon Sep 17 00:00:00 2001 From: Dhruvit Talati Date: Mon, 16 Nov 2026 17:59:14 -0500 Subject: [PATCH 1/3] feat(sandbox): add a kosa8 Cloud sandbox provider Adds kosa8 as a built-in VM sandbox provider, `kosa8`. It needs no extra: it drives kosa8 Cloud's REST API with httpx. Each sandbox is a microVM booted with docker: true from kosa8's universal Ubuntu 24.04 image, so agent-env's docker-in-VM flows run unchanged; exposed ports are public previews, egress allow lists are enforced on the host, and get_sandbox restores both. Co-Authored-By: Claude Opus 5.5 --- .agentenv/config.example.toml | 5 + AGENTS.md | 8 +- src/agent_env/cli/a2a_agent/deploy.py | 2 +- src/agent_env/cli/env/deploy.py | 2 +- .../sandbox_providers/kosa8/README.md | 128 ++++++ .../sandbox_providers/kosa8/__init__.py | 1 + .../sandbox_providers/kosa8/provider.py | 330 ++++++++++++++ .../sandbox_providers/kosa8/sandbox.py | 410 ++++++++++++++++++ .../sandbox_providers/sandbox_provider.py | 1 + tst/integration/env/gateway/gateway_test.py | 8 + .../env/task_step/task_steps_test.py | 9 + .../kosa8_sandbox_smoke_test.py | 121 ++++++ .../sandbox_providers/websockets_live_test.py | 2 +- .../sandbox_providers/egress_hosts_test.py | 3 +- .../sandbox_providers/kosa8_fakes.py | 170 ++++++++ .../kosa8_sandbox_provider_test.py | 312 +++++++++++++ .../sandbox_providers/kosa8_sandbox_test.py | 144 ++++++ .../network_policy_stamping_test.py | 8 + .../provider_capabilities_test.py | 9 +- .../test_config_sandbox_providers.py | 28 ++ tst/unit/test_capabilities.py | 3 +- tst/util/capabilities.py | 12 +- 22 files changed, 1698 insertions(+), 18 deletions(-) create mode 100644 src/agent_env/providers/sandbox_providers/kosa8/README.md create mode 100644 src/agent_env/providers/sandbox_providers/kosa8/__init__.py create mode 100644 src/agent_env/providers/sandbox_providers/kosa8/provider.py create mode 100644 src/agent_env/providers/sandbox_providers/kosa8/sandbox.py create mode 100644 tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py create mode 100644 tst/unit/providers/sandbox_providers/kosa8_fakes.py create mode 100644 tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py create mode 100644 tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py diff --git a/.agentenv/config.example.toml b/.agentenv/config.example.toml index d73a63705..eeb112d8f 100644 --- a/.agentenv/config.example.toml +++ b/.agentenv/config.example.toml @@ -44,6 +44,11 @@ agent_default = "local" # agents too # api_key = "secret:agent37_api_key" # or "env:AGENT37_API_KEY" # region = "us" # or "eu", "ap-south" +# Optional kosa8 Cloud microVMs (no extra needed): +# [sandbox.providers.kosa8.config] +# api_key = "secret:kosa8_api_key" # or "env:KOSA8_API_KEY" +# region = "us" # optional: "us", "eu", "us-ash1" or "eu-hel1" + # Optional CoreWeave Sandboxes (install the 'coreweave' extra): # [sandbox.providers.coreweave.config] # api_key = "secret:cwsandbox_api_key" # or wandb_api_key, with optional wandb_entity and wandb_project diff --git a/AGENTS.md b/AGENTS.md index d547c1c53..b201750b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,9 +71,9 @@ or one of them only where it is used. store, an OCI registry at `localhost:5000`, env-var secret store, `LocalRunner`, `local` Docker sandboxes for envs and agents. MongoDB, DynamoDB, Firestore, S3, Cloud Storage, ECR, AWS Secrets Manager, Google Cloud Secret Manager, and the Modal, E2B, Sail, SmolVM, Tensorlake, Tenki, Vercel, boxd, - CoreWeave, Daytona, boat and Agent37 sandboxes exist as implementations and are selected by config (all but - Agent37 through their extras: `sail`, `smol`, `tensorlake`, `tenki`, `vercel`, `boxd`, `coreweave`, `daytona`, - `boat`; every extra but `smol` is in `dev`; Agent37 needs only `httpx`). + CoreWeave, Daytona, boat, Agent37 and kosa8 sandboxes exist as implementations and are selected by config (all but + Agent37 and kosa8 through their extras: `sail`, `smol`, `tensorlake`, `tenki`, `vercel`, `boxd`, `coreweave`, `daytona`, + `boat`; every extra but `smol` is in `dev`; Agent37 and kosa8 need only `httpx`). - The model endpoint is unset until `[model] base_url` / `api_key` (or `LITELLM_BASE_URL` / `LITELLM_API_KEY`) is configured. A loopback URL handed into a `local` container (the model endpoint, an agent, peer or gateway on this machine) becomes `host.docker.internal`. On Linux that @@ -128,7 +128,7 @@ and deserialized through a registry. | `task/`, `task_step/` | A `Task` holds its `TaskStep`s inline; `Task.run()` executes them as a DAG. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`), a multi env's computers the multi env's own, which its gateway passes on only on their `/svc` routes and its clock watch (`CONTROL_TOKEN_CHILDREN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). | | `store/` | Four store ABCs with local and cloud implementations: `DocumentStore` (SQLite, MongoDB, DynamoDB, Firestore with MongoDB compatibility), `ObjectStore` (filesystem, S3, Cloud Storage), `ImageStore` (local OCI registry, ECR), `SecretStore` (env vars or file, AWS Secrets Manager, Google Cloud Secret Manager). `VersionedEntityStore` implements the shared versioned get/put logic, `QueryBuilder` is the immutable chained query API, `store/base.py` holds the error types. `store/routing.py` is the local namespaces, `@local` and `@hf` (`is_local_id`), each with a documents file of its own: while the CLI or a `build_app` server runs, a local id and what a local task's run records go to local stores beside the configured ones, and that run's writes to the configured stores are refused. A new backend must pass the conformance kits in `tst/store/`. | | `config/` | The `Config` singleton (`get_config`, `configure`, `reset_config`) in `config/runtime.py`, file discovery in `config/loader.py`, and `load_impl`, which resolves `module:Class` pointers. `agent_env.store` re-exports the config names for compatibility. | -| `providers/` | `providers/sandbox_providers/` holds the sandbox providers `local`, `modal`, `modal_vm`, `e2b`, `sail_vm` (the `sail` extra), `smol_vm` (the `smol` extra), `tensorlake` (the `tensorlake` extra), `tenki` (the `tenki` extra), `vercel` (the `vercel` extra), `boxd` (the `boxd` extra), `coreweave` (the `coreweave` extra), `daytona` (the `daytona` extra), `boat` (the `boat` extra), `agent37` (no extra); `[sandbox] default` and `agent_default` accept a comma-separated fallback chain, whose deploys skip a provider that can't run them. A sandbox provider declares what it runs (`ON_THIS_MACHINE`, and for VMs on this machine the address their requests to it arrive at, `REACHES_HOST_AT`; `CONTAINER_ACCEPTS`, `PRIVATE_NETWORK`, `WEBSOCKETS`; `SUPPORTED_SANDBOX_MODES`, derived from whether it implements `create_sandbox` and `create_vm`; and `SANDBOX_ACCEPTS`, the images an agent's sandbox runs, which defaults to those a VM loads when it implements `create_vm` and to `CONTAINER_ACCEPTS` otherwise, so only a provider that implements `create_vm` yet gives an agent a container, like the local one, declares it), each sandbox carries the `platform` of the images it runs (linux/amd64 unless its provider sets another when it creates it; None, any, unchecked, for a local sandbox), and code outside `providers/sandbox_providers/` reads those, never which provider it has. `providers/env_providers/` holds the environment providers: `EnvironmentProvider` (an env's containers and state store), `EnvironmentGatewayProvider` (`gateway`, an env's default), which renders a docker-compose for the gateway and its MCP servers inside the sandbox, and `EnvironmentServerProvider` (`server`), one MCP server in its own container with no gateway in front and no state store; `providers/env_state/` holds env-state providers (`local_postgres` built in). | +| `providers/` | `providers/sandbox_providers/` holds the sandbox providers `local`, `modal`, `modal_vm`, `e2b`, `sail_vm` (the `sail` extra), `smol_vm` (the `smol` extra), `tensorlake` (the `tensorlake` extra), `tenki` (the `tenki` extra), `vercel` (the `vercel` extra), `boxd` (the `boxd` extra), `coreweave` (the `coreweave` extra), `daytona` (the `daytona` extra), `boat` (the `boat` extra), `agent37` (no extra), `kosa8` (no extra); `[sandbox] default` and `agent_default` accept a comma-separated fallback chain, whose deploys skip a provider that can't run them. A sandbox provider declares what it runs (`ON_THIS_MACHINE`, and for VMs on this machine the address their requests to it arrive at, `REACHES_HOST_AT`; `CONTAINER_ACCEPTS`, `PRIVATE_NETWORK`, `WEBSOCKETS`; `SUPPORTED_SANDBOX_MODES`, derived from whether it implements `create_sandbox` and `create_vm`; and `SANDBOX_ACCEPTS`, the images an agent's sandbox runs, which defaults to those a VM loads when it implements `create_vm` and to `CONTAINER_ACCEPTS` otherwise, so only a provider that implements `create_vm` yet gives an agent a container, like the local one, declares it), each sandbox carries the `platform` of the images it runs (linux/amd64 unless its provider sets another when it creates it; None, any, unchecked, for a local sandbox), and code outside `providers/sandbox_providers/` reads those, never which provider it has. `providers/env_providers/` holds the environment providers: `EnvironmentProvider` (an env's containers and state store), `EnvironmentGatewayProvider` (`gateway`, an env's default), which renders a docker-compose for the gateway and its MCP servers inside the sandbox, and `EnvironmentServerProvider` (`server`), one MCP server in its own container with no gateway in front and no state store; `providers/env_state/` holds env-state providers (`local_postgres` built in). | | `a2a_agent/` | The `A2AAgent` entity (`a2a_agent`), its stores and the validator steps. The protocol package provides the agent-side framework. | | `openenv/` | `build_app(bundle)`: the [OpenEnv](https://github.com/openenv/OpenEnv) server for a bundle's tasks, each session playing one episode through the Episode API, with the envs' MCP tools, an added `end_turn` tool and the task's verifier score as the reward. It prepares bundles as `agent-env run` does (`prepare_bundle(played=True)`, without the agent the client plays) and keeps namespace routing on for the app's life. `openenv` comes with the `openenv` extra, a floor with no cap; this package and `training/` are the only ones that import it. Each task's description in the Task API names its `toolset` (the played agent's envs, role, and whether it gets `bash`). With `token`, every request and WebSocket but `/health` must carry `Authorization: Bearer `, for a server others reach. | | `training/` | One module per outside trainer, each behind its own extra, and the modules they share; [Training helpers](#training-helpers) lists them. | diff --git a/src/agent_env/cli/a2a_agent/deploy.py b/src/agent_env/cli/a2a_agent/deploy.py index d1b2298de..3ce956c66 100644 --- a/src/agent_env/cli/a2a_agent/deploy.py +++ b/src/agent_env/cli/a2a_agent/deploy.py @@ -18,7 +18,7 @@ @click.option("--ttl-seconds", type=click.IntRange(min=MIN_TTL_SECONDS, max=MAX_TTL_SECONDS), default=DEFAULT_TTL_SECONDS, help=f"VM lifetime in seconds (default {DEFAULT_TTL_SECONDS})") @click.option("--sandbox", default=None, - help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, local) " + help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, kosa8, local) " "or a name from [sandbox.providers] in .agentenv/config.toml; comma-separated for a " "fallback chain. Defaults to [sandbox].agent_default (else local) when omitted.") def deploy(agent_id: str, agent_version: int | None, env_var_pairs: tuple[str, ...], ttl_seconds: int, sandbox: str): diff --git a/src/agent_env/cli/env/deploy.py b/src/agent_env/cli/env/deploy.py index 284923533..25e6f3749 100644 --- a/src/agent_env/cli/env/deploy.py +++ b/src/agent_env/cli/env/deploy.py @@ -19,7 +19,7 @@ @click.option("--gateway-mode", type=click.Choice([m.value for m in GatewayMode], case_sensitive=False), default=GatewayMode.PERFORMANCE.value, help="Gateway mode (performance or consistent)") @click.option("--sandbox", default=None, - help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, local) " + help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, kosa8, local) " "or a name from [sandbox.providers] in .agentenv/config.toml; comma-separated for a " "fallback chain. Defaults to [sandbox].default (else local) when omitted.") @click.option("--service-db", "service_db_env_id", default=None, diff --git a/src/agent_env/providers/sandbox_providers/kosa8/README.md b/src/agent_env/providers/sandbox_providers/kosa8/README.md new file mode 100644 index 000000000..e0ea557df --- /dev/null +++ b/src/agent_env/providers/sandbox_providers/kosa8/README.md @@ -0,0 +1,128 @@ +# `kosa8` sandbox provider + +Runs agent-env sandboxes on [kosa8 Cloud](https://kosa8.com). Each environment and each agent gets its own microVM, +booted with Docker inside and a public HTTPS URL for each of its ports. It is a VM provider: agent-env's docker-in-VM +flows run on it unchanged. That covers the gateway's docker-compose, an agent's `docker run`, image loading and +artifact collection. + +## Set up + +### 1. No extra to install + +The provider drives kosa8's REST API with `httpx`, which agent-env already depends on. + +### 2. Get a kosa8 API key + +Create a key in the [dashboard](https://app.kosa8.com) under API keys, with the `sandboxes:read` and `sandboxes:write` +scopes. Sandboxes booted at a size, as these are, need a payment method on the organization. For local work, export +it: + +```bash +export KOSA8_API_KEY=... +``` + +For a shared deployment, put it in your secret store instead, for example as `kosa8_api_key`, and reference it with +`secret:kosa8_api_key`. Never put the key itself in `config.toml`. The provider reads the key only from its config, +never from the process environment. + +### 3. Configure + +A complete `.agentenv/config.toml` that runs every environment and agent on kosa8, with the local stores: + +```toml +[sandbox] +default = "kosa8" # environments and sandboxes +agent_default = "kosa8" # agents + +[sandbox.providers.kosa8.config] +api_key = "env:KOSA8_API_KEY" # or "secret:kosa8_api_key" + +[model] +base_url = "https://litellm.example.com" +api_key = "env:LITELLM_API_KEY" +``` + +To keep the local default and use kosa8 per run instead, add only the `[sandbox.providers.kosa8.config]` table and +pass `--sandbox kosa8`, or `--env-sandbox kosa8` / `--agent-sandbox kosa8` on `agent-env task run`. + +### 4. Run something + +```bash +agent-env run hello --sandbox kosa8 +``` + +`agent-env -v run …` also logs each sandbox as it starts +(`kosa8 sandbox started: id=… name=… size=… disk_gb=… ttl_s=… ports=… attribution=…`). + +## Configuration reference + +All keys go under `[sandbox.providers.kosa8.config]`. Unknown keys are refused. + +| Key | Default | Meaning | +| ---------- | ------------------------------------------ | -------------------------------------------------------------------------- | +| `api_key` | required | The kosa8 API key, as an `env:` or `secret:` reference. | +| `base_url` | `https://api.kosa8.com` | The kosa8 control plane. | +| `region` | the organization's default | `us`, `eu`, or a region such as `us-ash1` or `eu-hel1`. | +| `image` | `kosa8-template/universal-24.04-20261115.2` | The sandbox's own image. It must ship `dockerd` and the Compose v2 plugin. | + +## Resources and lifetime + +- **Sizes:** kosa8 has four: 2 vCPU / 4 GiB, 4 / 8, 8 / 16 and 16 / 32. A request gets the smallest that covers both + its CPU and its memory, so agent-env's default (1 vCPU, 8 GiB) runs on 4 vCPU / 8 GiB. A larger request is refused + before anything is created, not shrunk. +- **Disk:** the request's disk, at least 32 GB (kosa8's default, which holds the images Docker pulls) and at most + 200 GB; a larger request is refused. +- **Ignored requests:** `boot_mode` and `env` have no kosa8 equivalent here; one that is set logs a warning. +- **Lifetime:** the sandbox's `timeout` is its `ttl_s` (60 s to 90 days), so kosa8 deletes it then even if a crashed + run never tears it down. +- **Sleep:** `sleep_after_s` is 0, so a sandbox never sleeps while agent-env uses it. + +## Networking + +- **Ports:** each exposed port is a public kosa8 preview, `https://-.kosa8labs.com`, which fills + `tunnel_urls`. It serves HTTP and WebSocket with no platform authentication, like other providers' tunnels; the + random part is the only secret. +- **Egress:** allow-all, or an allow list of at most 256 hostnames, `*.` wildcards and IPv4 addresses or ranges. kosa8 + enforces it on the host, outside the VM, so one list covers `dockerd` and every container. It is applied right after + the sandbox is running, before anything runs in it. IPv6 entries are refused with `NetworkPolicyUnsupportedError` + before anything is created; a list kosa8 itself refuses (or an organization policy that does not allow it) deletes + the sandbox and raises the same error, so a fallback chain moves on. +- **Wildcards:** `*.example.com` covers every name under `example.com` but not `example.com` itself. +- **kosa8's own hosts:** `*.kosa8labs.com` is added to every allow list, so a restricted agent can reach the + environments it talks to. +- **Organization policy:** an organization's default egress policy applies to sandboxes that set none, and the + sandbox's `network_policy` reports what kosa8 enforces. A deny-only policy reads as allow-all. +- **Reconnect:** `get_sandbox` restores the ports and the applied policy from kosa8. + +## Cleanup + +- A sandbox whose setup fails after it is created (boot, egress, ports, Docker readiness) is deleted. +- If a create fails after kosa8 may have made the sandbox, or its caller is cancelled, the provider finds it by its + unique `agentenv-` name and deletes it. +- Whatever else happens, `ttl_s` removes the sandbox at the sandbox's `timeout`. +- `terminate` is idempotent: a sandbox that is already gone is not an error. + +## Things to know + +- **Commands run as root**, so the `sudo` agent-env prefixes is dropped, and read no input (standard input is + `/dev/null`). +- **Long commands:** exec is streamed, which no time limit holds; kosa8 sends a heartbeat every 15 s while a command + is quiet. +- **Lost connections:** when a command's stream ends without an exit status, `exec` returns exit code -1. + `exec_script` retries idempotent scripts on -1 only. A call kosa8 refused before the command started (`409 + starting`, `429`, `503`) is resent. +- **Large commands:** kosa8 takes at most 256 arguments of 8 KiB each. A longer command is uploaded to + `/workspace/.agentenv` through the files API and read back as its argument list. +- **Files:** `write_host_file` uploads through the files API, which reaches only `/workspace`, in 4 MiB pieces, then + moves the bytes into place, so a secret never enters a command line. +- **Images:** `create_vm(image=...)` is refused. Sandboxes boot the configured image, and OCI images run under Docker + inside them. +- **Platform:** linux/amd64. GPUs are not supported. +- **The model key enters the sandbox:** an agent's `LITELLM_API_KEY` is passed in, as on other providers. + +## Testing + +`tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py` runs against a real kosa8 organization when +`[sandbox.providers.kosa8.config]` resolves. Otherwise it skips with `agentenv-capability-missing: remote_sandbox`. +The unit tests are `tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py` and `kosa8_sandbox_test.py`, +and run offline against an in-memory kosa8 API behind `httpx.MockTransport`. diff --git a/src/agent_env/providers/sandbox_providers/kosa8/__init__.py b/src/agent_env/providers/sandbox_providers/kosa8/__init__.py new file mode 100644 index 000000000..8dc5aeb1e --- /dev/null +++ b/src/agent_env/providers/sandbox_providers/kosa8/__init__.py @@ -0,0 +1 @@ +"""kosa8 Cloud sandbox provider (no extra: it drives kosa8's REST API with ``httpx``); see README.md.""" diff --git a/src/agent_env/providers/sandbox_providers/kosa8/provider.py b/src/agent_env/providers/sandbox_providers/kosa8/provider.py new file mode 100644 index 000000000..8ea41cc43 --- /dev/null +++ b/src/agent_env/providers/sandbox_providers/kosa8/provider.py @@ -0,0 +1,330 @@ +"""kosa8 Cloud sandbox provider. + +Each sandbox is one kosa8 microVM, booted from an image that runs Docker (``docker: true``). The gateway and agent +containers run under that Docker through the inherited ``VmSandbox`` helpers. +""" + +from __future__ import annotations + +import asyncio +import ipaddress +import logging +import math +import re +import time +import uuid +from typing import Any, ClassVar, Self + +import httpx + +from agent_env.attribution import Attribution +from agent_env.config.errors import ConfigError +from agent_env.providers.sandbox_providers.kosa8.sandbox import ( + DEFAULT_BASE_URL, + Kosa8Api, + Kosa8Error, + Kosa8Sandbox, + policy_from_enforced, +) +from agent_env.providers.sandbox_providers.sandbox import NetworkPolicy, NetworkPolicyUnsupportedError +from agent_env.providers.sandbox_providers.sandbox_provider import SandboxProvider, apply_default_attribution + +logger = logging.getLogger(__name__) + +# kosa8's universal Ubuntu 24.04 image: dockerd, containerd, the Docker CLI, buildx and the Compose v2 plugin. +DEFAULT_IMAGE = "kosa8-template/universal-24.04-20261115.2" +NAME_PREFIX = "agentenv" +_SECTION = "[sandbox.providers.kosa8.config]" +_CONFIG_KEYS = frozenset({"api_key", "base_url", "region", "image"}) + +# kosa8's sizes, (vCPU, GiB of memory), smallest first. +SIZES = ((2, 4), (4, 8), (8, 16), (16, 32)) +DEFAULT_DISK_GB = 32 +MAX_DISK_GB = 200 +MIN_TTL_SEC = 60 +MAX_TTL_SEC = 90 * 86400 +MAX_EGRESS_ENTRIES = 256 +READY_TIMEOUT_SEC = 600 +POLL_SEC = (1.0, 5.0) +_FAILED_STATES = frozenset({"error", "deleted", "stopped", "paused", "host_removed", "host_lost"}) +_NAME = re.compile(r"(?=.{1,253}$)[a-z0-9_-]{1,63}(\.[a-z0-9_-]{1,63})*") +_cleanups: set[asyncio.Task] = set() + + +def sandbox_size(cpu: float, memory_mb: int) -> str: + """The smallest kosa8 size, ``x``, that covers the request. A request beyond the largest is refused, not + shrunk.""" + for vcpu, memory_gib in SIZES: + if cpu <= vcpu and memory_mb <= memory_gib * 1024: + return f"{vcpu}x{memory_gib}" + vcpu, memory_gib = SIZES[-1] + raise ValueError(f"kosa8 cannot size a sandbox for cpu={cpu}, memory={memory_mb}MB " + f"(at most {vcpu} vCPU, {memory_gib} GiB memory)") + + +def disk_gb(disk_size_gb: float) -> int: + """The data disk for ``disk_size_gb``: at least kosa8's default, which holds the images Docker pulls.""" + wanted = max(DEFAULT_DISK_GB, math.ceil(disk_size_gb)) + if wanted > MAX_DISK_GB: + raise ValueError(f"kosa8 cannot give a sandbox a {disk_size_gb} GB disk (at most {MAX_DISK_GB} GB)") + return wanted + + +def lifetime(timeout: int) -> int: + """``ttl_s`` for ``timeout``: kosa8 deletes the sandbox then. It takes 60 s to 90 days.""" + if timeout > MAX_TTL_SEC: + raise ValueError(f"kosa8 cannot keep a sandbox for {timeout}s (at most {MAX_TTL_SEC}s)") + return max(MIN_TTL_SEC, int(timeout)) + + +def sandbox_name() -> str: + """``agentenv-``, unique, so the sandbox a create lost its answer for can be found again.""" + return f"{NAME_PREFIX}-{uuid.uuid4().hex[:16]}" + + +def egress_entries(policy: NetworkPolicy) -> list[str]: + """The sandbox's egress allow list for ``policy``: its hosts, then its addresses and ranges.""" + return list(dict.fromkeys([*policy.allow_hosts, *policy.allow_cidrs])) + + +def _allowed_entry(entry: str) -> bool: + """A hostname, a ``*.`` wildcard over at least two labels, or an IPv4 address or range, as kosa8 takes them.""" + entry = entry.strip().lower().rstrip(".") + try: + network = ipaddress.ip_network(entry, strict=False) + except ValueError: + if entry.startswith("*."): + name = entry[2:] + return "." in name and _NAME.fullmatch(name) is not None + return _NAME.fullmatch(entry) is not None and not re.fullmatch(r"[0-9.]+", entry) + return network.version == 4 + + +async def _settle(cleanup: Any) -> None: + """Run ``cleanup`` to its end, also while the caller is being cancelled: ``asyncio.run`` waits for the task it + cancels, so it waits for the cleanup too. A second cancellation leaves the cleanup running on its own.""" + task = asyncio.ensure_future(cleanup) + _cleanups.add(task) + task.add_done_callback(_cleanups.discard) + await asyncio.shield(task) + + +class Kosa8SandboxProvider(SandboxProvider): + """Provision Docker-capable kosa8 microVMs. + + ``api_key`` comes from resolved provider config, never from the process environment: configure it with an ``env:`` + or ``secret:`` reference in ``[sandbox.providers.kosa8.config]``. Workloads never see it. + """ + + # Exposed ports get public preview URLs under this domain. + EGRESS_HOSTS: ClassVar[tuple[str, ...]] = ("*.kosa8labs.com",) + # kosa8's preview proxy passes a WebSocket upgrade through to the sandbox. + WEBSOCKETS = True + + def __init__( + self, + *, + api_key: str, + base_url: str = DEFAULT_BASE_URL, + region: str | None = None, + image: str = DEFAULT_IMAGE, + transport: httpx.AsyncBaseTransport | None = None, + ): + if not isinstance(api_key, str) or not api_key.strip(): + raise ValueError("kosa8 api_key must be a non-empty resolved secret") + self._region = region + self._image = image + self._api = Kosa8Api(api_key, base_url=base_url, transport=transport) + + @classmethod + def from_config(cls, **config: Any) -> Self: + unknown = set(config) - _CONFIG_KEYS + if unknown: + raise ConfigError(f"{_SECTION} has unknown key(s): {sorted(unknown)}") + if not config.get("api_key"): + raise ConfigError(f"{_SECTION} requires a non-empty 'api_key'") + for key in _CONFIG_KEYS: + value = config.get(key) + if value is not None and (not isinstance(value, str) or not value.strip()): + raise ConfigError(f"{_SECTION} '{key}' must be a non-empty string") + return cls(**config) + + @classmethod + def effective_network_policy(cls, policy: NetworkPolicy | None) -> NetworkPolicy: + """Every platform's hosts, as on the base, and always kosa8's own, so a restricted sandbox still reaches the + environments it talks to.""" + return super().effective_network_policy(policy).with_hosts(cls.EGRESS_HOSTS) + + @classmethod + def supports_network_policy(cls, policy: NetworkPolicy) -> bool: + """Allow-all, or an allow list of at most 256 hostnames, ``*.`` wildcards and IPv4 addresses or ranges.""" + if not policy.restricts_egress: + return True + entries = (*policy.allow_hosts, *policy.allow_cidrs) + return len(entries) <= MAX_EGRESS_ENTRIES and all(_allowed_entry(entry) for entry in entries) + + async def close(self) -> None: + """Close this event loop's client; a sandbox this provider made reopens its connection if it is used again.""" + await self._api.close() + + async def create_vm( + self, + *, + image: str | None = None, + boot_mode: str | None = None, + cpu: float = 1.0, + memory: int = 8192, + disk_size_gb: float = 10, + timeout: int = 3600 * 2, + exposed_ports: list[int] | None = None, + setup_for_gateway: bool = True, + attribution: Attribution | None = None, + network_policy: NetworkPolicy | None = None, + env: dict[str, str] | None = None, + ) -> Kosa8Sandbox: + """Create a kosa8 microVM that runs Docker, with a public URL for each of ``exposed_ports``. ``timeout`` is the + sandbox's ``ttl_s``, its hard maximum lifetime. Sandboxes boot the configured image, so a per-call ``image`` is + refused rather than ignored; ``boot_mode`` and ``env`` have no kosa8 equivalent here and are ignored.""" + if image is not None: + raise ValueError("kosa8 sandboxes boot the configured Docker-capable image; a per-call image is unsupported") + if boot_mode is not None: + logger.warning("Ignoring boot_mode=%s: kosa8 sandboxes have no boot modes", boot_mode) + if env: + logger.warning("Ignoring env for a kosa8 VM: it boots no disk image to seed") + size, disk, ttl = sandbox_size(cpu, memory), disk_gb(disk_size_gb), lifetime(timeout) + effective_policy = self.effective_network_policy(network_policy) + if not self.supports_network_policy(effective_policy): + raise NetworkPolicyUnsupportedError( + "kosa8 enforces allow-all or an allow list of at most 256 hostnames, wildcards and IPv4 addresses or " + f"ranges, not {effective_policy.to_dict()}" + ) + resolved_attribution = { + key: str(value) + for key, value in apply_default_attribution(dict(attribution or {})).items() + if value is not None + } + ports = list(dict.fromkeys(exposed_ports or [])) + body: dict[str, Any] = { + "image": self._image, + "size": size, + "disk_gb": disk, + "docker": True, + "sleep_after_s": 0, + "ttl_s": ttl, + "name": sandbox_name(), + } + if self._region: + body["region"] = self._region + created = await self._create(body) + sandbox_id = created["id"] + sandbox = Kosa8Sandbox(self._api, sandbox_id, tunnel_urls={}, network_policy=effective_policy) + try: + await self._wait_until_running(created) + if effective_policy.restricts_egress: + await self._set_egress(sandbox_id, egress_entries(effective_policy)) + sandbox.network_policy = policy_from_enforced(await self._api.enforced_egress(sandbox_id)) + sandbox.tunnel_urls = {port: await self._api.open_port(sandbox_id, port) for port in ports} + logger.info( + "kosa8 sandbox started: id=%s name=%s size=%s disk_gb=%s ttl_s=%s ports=%s attribution=%s", + sandbox_id, body["name"], size, disk, ttl, ports, resolved_attribution, + ) + if setup_for_gateway: + await sandbox.setup_vm_for_gateway(ports) + return sandbox + except BaseException: + # The sandbox is deleted before the create's own error or cancellation is raised. + await _settle(self._delete_quietly(sandbox_id)) + raise + + async def _create(self, body: dict[str, Any]) -> dict[str, Any]: + """Await the create. When it fails or its caller is cancelled, the sandbox it may have made anyway is deleted + once it settles, found by its unique name if its answer was lost.""" + task = asyncio.ensure_future(self._api.create_sandbox(body)) + try: + return await asyncio.shield(task) + except BaseException: + await _settle(self._reclaim(task, body["name"])) + raise + + async def _reclaim(self, create: asyncio.Future, name: str) -> None: + try: + ids = [(await create)["id"]] + except BaseException: + try: + ids = [sandbox["id"] for sandbox in await self._api.sandboxes_named(name)] + except Exception as exc: # noqa: BLE001 - logged; its ttl_s still removes the sandbox + logger.error("Could not look for a kosa8 sandbox %s left by a failed create: %s", name, exc) + return + for sandbox_id in ids: + await self._delete_quietly(sandbox_id) + + async def _delete_quietly(self, sandbox_id: str) -> None: + try: + await self._api.delete_sandbox(sandbox_id) + logger.info("Deleted kosa8 sandbox %s after its create failed or was cancelled", sandbox_id) + except Exception as exc: # noqa: BLE001 - logged; the caller's own error is the one raised + logger.error("kosa8 sandbox %s from a failed create is still running until its ttl_s: %s", sandbox_id, exc) + + async def _wait_until_running(self, sandbox: dict[str, Any]) -> None: + """A sized create answers while the VM boots (state ``creating``); poll until it runs.""" + deadline = time.monotonic() + READY_TIMEOUT_SEC + interval, longest = POLL_SEC + while sandbox.get("state") != "running": + if sandbox.get("state") in _FAILED_STATES: + raise RuntimeError(f"kosa8 sandbox {sandbox['id']} did not start ({sandbox.get('state')}): " + f"{sandbox.get('last_error') or 'no reason given'}") + if time.monotonic() >= deadline: + raise RuntimeError(f"kosa8 sandbox {sandbox['id']} still {sandbox.get('state')} " + f"after {READY_TIMEOUT_SEC}s") + await asyncio.sleep(interval) + interval = min(interval * 1.5, longest) + sandbox = await self._api.get_sandbox(sandbox["id"]) + + async def _set_egress(self, sandbox_id: str, allow: list[str]) -> None: + """Apply the allow list on the host, before anything runs in the sandbox. One kosa8 refuses (an entry it can't + parse, a host without egress controls, an org policy that doesn't allow it) is a policy it can't enforce, so a + fallback chain moves on.""" + try: + await self._api.set_egress(sandbox_id, allow) + except Kosa8Error as exc: + if exc.status_code not in (400, 403, 501): + raise + raise NetworkPolicyUnsupportedError(f"kosa8 refused the egress allow list {allow}: {exc}") from exc + + async def create_sandbox( + self, + *, + image_name: str, + port: int, + env: dict[str, str], + cpu: float = 1.0, + memory: int = 8192, + disk_size_gb: float = 10, + timeout: int = 3600 * 2, + attribution: Attribution | None = None, + network_policy: NetworkPolicy | None = None, + ) -> Kosa8Sandbox: + # A VM backend: the gateway and agent paths start image_name inside the VM afterwards. + del image_name, env + return await self.create_vm( + cpu=cpu, + memory=memory, + disk_size_gb=disk_size_gb, + timeout=timeout, + exposed_ports=[port], + attribution=attribution, + network_policy=network_policy, + ) + + async def get_sandbox(self, sandbox_id: str) -> Kosa8Sandbox: + """Reconnect, restoring the public URLs and the applied egress policy.""" + sandbox = await self._api.get_sandbox(sandbox_id) + return Kosa8Sandbox( + self._api, + sandbox["id"], + tunnel_urls=await self._api.open_ports(sandbox["id"]), + network_policy=policy_from_enforced(await self._api.enforced_egress(sandbox["id"])), + ) + + async def terminate_sandbox(self, sandbox_id: str) -> None: + await self._api.delete_sandbox(sandbox_id) diff --git a/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py new file mode 100644 index 000000000..81fb9f543 --- /dev/null +++ b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py @@ -0,0 +1,410 @@ +"""A kosa8 Cloud sandbox presented through the :class:`VmSandbox` contract. + +Each sandbox is a microVM booted with ``docker: true`` from kosa8's universal Ubuntu 24.04 image, which ships dockerd +and the Compose v2 plugin, so the gateway's docker-compose, an agent's ``docker run`` and image loading run under Docker +inside it. Commands run as root, so the ``sudo`` agent-env prefixes is dropped. kosa8 applies the egress policy on the +host, outside the VM, so one policy covers ``dockerd`` and every container it runs. +""" + +from __future__ import annotations + +import asyncio +import base64 +import ipaddress +import json +import logging +import shlex +import uuid +import weakref +from typing import Any +from urllib.parse import urlparse + +import httpx + +from agent_env.config import get_config +from agent_env.providers.sandbox_providers.sandbox import CURL_RETRY_FLAGS, NetworkMode, NetworkPolicy, VmSandbox +from agent_env.providers.sandbox_providers.sandbox_provider import SANDBOX_MODE_VM, SandboxNotFoundError + +logger = logging.getLogger(__name__) + +DEFAULT_BASE_URL = "https://api.kosa8.com" +# dockerd is installed in the image but not started at boot; the sandbox is persistent, so a daemon started by one +# command keeps running after it returns. +DOCKER_READY = r""" +if ! docker info >/dev/null 2>&1; then + setsid nohup dockerd >/var/log/dockerd.log 2>&1 /dev/null 2>&1 && exec docker compose version + sleep 1 +done +echo "docker daemon did not become ready" >&2 +tail -n 20 /var/log/dockerd.log >&2 +exit 1 +""" +# What exec returns when no exit status arrives; exec_script retries only this. +UNKNOWN_EXIT_CODE = -1 +# kosa8 takes at most 256 argv entries of at most 8 KiB each. A command past either limit is written to a file through +# the files API and read back as argv in the sandbox. +MAX_ARGS = 256 +MAX_ARG_BYTES = 8000 +# The files API reaches /workspace only, and takes at most 8 MiB a request. +STAGING_DIR = "/workspace/.agentenv" +FILE_PIECE_BYTES = 4 * 1024 * 1024 +_NO_INPUT = 'exec "$@" tuple[str, str]: + """``(code, message)`` of kosa8's ``{"error": "", "message": "..."}`` error answer.""" + try: + body = response.json() + except ValueError: + return "unknown", response.text[:500] + if not isinstance(body, dict): + return "unknown", str(body)[:500] + return str(body.get("error", "unknown")), str(body.get("message", "")) + + +class Kosa8Api: + """The kosa8 Cloud calls a sandbox makes. + + The key comes from the provider's resolved config and is sent only to ``base_url``. ``transport`` is injectable so + unit tests never open a connection.""" + + def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, + transport: httpx.AsyncBaseTransport | None = None): + self._api_key = api_key + self._base_url = base_url.rstrip("/") + self._transport = transport + # One client per event loop: a client's connections belong to the loop that opened them, and the CLI runs + # several loops in one process. + self._clients: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, httpx.AsyncClient] = ( + weakref.WeakKeyDictionary()) + + def _client(self) -> httpx.AsyncClient: + loop = asyncio.get_running_loop() + client = self._clients.get(loop) + if client is None: + client = self._clients[loop] = httpx.AsyncClient( + base_url=self._base_url, transport=self._transport, timeout=_TIMEOUT, + headers={"Authorization": f"Bearer {self._api_key}", "User-Agent": "agentenv-framework"}, + ) + return client + + async def close(self) -> None: + client = self._clients.pop(asyncio.get_running_loop(), None) + if client is not None: + await client.aclose() + + async def _call(self, method: str, path: str, *, resend: frozenset[int] = IDEMPOTENT_RESENDABLE, + resend_lost: bool = True, **kwargs: Any) -> httpx.Response: + """One call, sent again after an answer in ``resend`` or, with ``resend_lost``, a lost connection.""" + delays = iter(RESEND_DELAYS) + while True: + try: + response = await self._client().request(method, path, **kwargs) + except httpx.TransportError: + if not resend_lost or (delay := next(delays, None)) is None: + raise + else: + if response.status_code < 400: + return response + if response.status_code not in resend or (delay := next(delays, None)) is None: + raise Kosa8Error(response) + logger.debug("kosa8 %s %s got no usable answer; sending it again in %ss", method, path, delay) + await asyncio.sleep(delay) + + async def create_sandbox(self, body: dict[str, Any]) -> dict[str, Any]: + """Create a sandbox. Only answers that say nothing was made are resent; a lost answer is raised, and the + caller finds what the create may have made by its name.""" + response = await self._call("POST", "/v1/sandboxes", json=body, resend=RESENDABLE, resend_lost=False) + return response.json()["sandbox"] + + async def get_sandbox(self, sandbox_id: str) -> dict[str, Any]: + try: + sandbox = (await self._call("GET", f"/v1/sandboxes/{sandbox_id}")).json()["sandbox"] + except Kosa8Error as exc: + if exc.status_code == 404: + raise SandboxNotFoundError(f"kosa8 sandbox {sandbox_id!r} was not found") from exc + raise + if sandbox.get("state") == "deleted": + raise SandboxNotFoundError(f"kosa8 sandbox {sandbox_id!r} was deleted") + return sandbox + + async def sandboxes_named(self, name: str) -> list[dict[str, Any]]: + response = await self._call("GET", "/v1/sandboxes", params={"name": name}) + return [sandbox for sandbox in response.json()["sandboxes"] if sandbox.get("state") != "deleted"] + + async def delete_sandbox(self, sandbox_id: str) -> None: + """Delete a sandbox; one that is already gone is not an error.""" + try: + await self._call("DELETE", f"/v1/sandboxes/{sandbox_id}") + except Kosa8Error as exc: + if exc.status_code != 404: + raise + logger.info("kosa8 sandbox %s was already gone at terminate", sandbox_id) + + async def set_egress(self, sandbox_id: str, allow: list[str]) -> None: + """Let the sandbox reach only ``allow``; nothing at all when it is empty.""" + body: dict[str, Any] = {"allow": allow} if allow else {"internet": False} + await self._call("PUT", f"/v1/sandboxes/{sandbox_id}/egress", json=body) + + async def enforced_egress(self, sandbox_id: str) -> str: + """The policy kosa8 enforces on the sandbox, compiled: ``any``, ``deny``, ``allow:…[;deny:…]`` or + ``block:…``. It is the org's default when the sandbox has none of its own.""" + response = await self._call("GET", f"/v1/sandboxes/{sandbox_id}/egress") + return str(response.json()["egress"]["enforced"]) + + async def open_port(self, sandbox_id: str, port: int) -> str: + """The public preview URL of ``port``; opening one that is open answers with it again.""" + response = await self._call("POST", f"/v1/sandboxes/{sandbox_id}/previews", json={"port": port, "public": True}) + return _origin(response.json()["preview"]["url"]) + + async def open_ports(self, sandbox_id: str) -> dict[int, str]: + response = await self._call("GET", f"/v1/sandboxes/{sandbox_id}/previews") + return {int(preview["port"]): _origin(preview["url"]) for preview in response.json()["previews"] + if preview.get("public")} + + async def make_dir(self, sandbox_id: str, path: str) -> None: + await self._call("POST", f"/v1/sandboxes/{sandbox_id}/files/mkdir", json={"path": path}) + + async def write_file(self, sandbox_id: str, path: str, data: bytes) -> None: + await self._call("PUT", f"/v1/sandboxes/{sandbox_id}/files", params={"path": path}, content=data, + headers={"Content-Type": "application/octet-stream"}) + + async def exec(self, sandbox_id: str, argv: list[str]) -> tuple[int, bytes, bytes]: + """Run ``argv`` streamed, which no time limit holds, and return ``(exit, stdout, stderr)``. A call refused + before the command started is resent; one whose stream ends without an exit status is exit -1.""" + delays = iter(RESEND_DELAYS) + while True: + try: + async with self._client().stream("POST", f"/v1/sandboxes/{sandbox_id}/exec", + json={"cmd": argv, "stream": True}) as response: + if response.status_code == 200: + return await _frames(response) + await response.aread() + error = Kosa8Error(response) + except (httpx.ConnectError, httpx.ConnectTimeout) as exc: + failure = f"{type(exc).__name__}: {exc}" + except httpx.TransportError as exc: + return UNKNOWN_EXIT_CODE, b"", f"{type(exc).__name__}: {exc}".encode() + else: + if error.status_code not in RESENDABLE: + if error.status_code >= 500: + return UNKNOWN_EXIT_CODE, b"", str(error).encode() + raise error + failure = str(error) + delay = next(delays, None) + if delay is None: + return UNKNOWN_EXIT_CODE, b"", failure.encode() + logger.warning("kosa8 exec in %s was refused before it started (%s); resending in %ss", + sandbox_id, failure, delay) + await asyncio.sleep(delay) + + +async def _frames(response: httpx.Response) -> tuple[int, bytes, bytes]: + """Read a streamed exec's NDJSON frames: ``{stream, data}`` output, heartbeats, then ``{done, exit}`` or + ``{done, error}``.""" + stdout, stderr = bytearray(), bytearray() + async for line in response.aiter_lines(): + if not line.strip(): + continue + frame = json.loads(line) + if frame.get("done"): + if isinstance(frame.get("exit"), int): + return frame["exit"], bytes(stdout), bytes(stderr) + stderr += f"kosa8: {frame.get('error') or 'the command ended without an exit status'}".encode() + return UNKNOWN_EXIT_CODE, bytes(stdout), bytes(stderr) + if frame.get("data"): + (stdout if frame.get("stream") == "stdout" else stderr).extend(base64.b64decode(frame["data"])) + stderr += b"kosa8: the stream ended before the command's exit status" + return UNKNOWN_EXIT_CODE, bytes(stdout), bytes(stderr) + + +def _origin(url: str) -> str: + return url.rstrip("/") + + +def policy_from_enforced(enforced: str) -> NetworkPolicy: + """The egress policy a compiled kosa8 policy applies. ``block:…`` lets everything out but a deny list, which an + allowlist can't express, so it reads as allow-all.""" + if enforced == "deny": + return NetworkPolicy(mode=NetworkMode.ALLOWLIST) + if enforced.startswith("allow:"): + entries = [entry for entry in enforced.removeprefix("allow:").split(";deny:")[0].split(",") if entry] + return NetworkPolicy( + mode=NetworkMode.ALLOWLIST, + allow_hosts=tuple(entry for entry in entries if not _is_address(entry)), + allow_cidrs=tuple(entry for entry in entries if _is_address(entry)), + ) + return NetworkPolicy() + + +def allows_host(policy: NetworkPolicy, host: str) -> bool: + """Whether ``policy`` lets the sandbox reach ``host`` by kosa8's rules: an exact name, a ``*.domain`` entry, which + covers every name under ``domain`` but not ``domain`` itself, or an address in a listed address or range.""" + if not policy.restricts_egress: + return True + host = host.lower().rstrip(".") + for entry in policy.allow_hosts: + entry = entry.lower().rstrip(".") + if entry == host or (entry.startswith("*.") and host.endswith(entry[1:])): + return True + try: + address = ipaddress.ip_address(host) + except ValueError: + return False + return any( + address in ipaddress.ip_network(entry, strict=False) + for entry in (*policy.allow_cidrs, *policy.allow_hosts) + if _is_address(entry) + ) + + +def _is_address(entry: str) -> bool: + try: + ipaddress.ip_network(entry, strict=False) + except ValueError: + return False + return True + + +class _BytesReader: + """The small ``StreamReader`` subset consumed by ``Sandbox.exec_with_output``.""" + + def __init__(self, value: bytes): + self._value = value + + async def read(self) -> bytes: + return self._value + + +class _CompletedProcess: + """A finished kosa8 exec in the common process protocol.""" + + def __init__(self, stdout: bytes, stderr: bytes, exit_code: int): + self.stdout = _BytesReader(stdout) + self.stderr = _BytesReader(stderr) + self._exit_code = exit_code + + async def wait(self) -> int: + return self._exit_code + + +class Kosa8Sandbox(VmSandbox): + """A kosa8 microVM with Docker; its API is its provider's, shared with the provider's other sandboxes.""" + + type = "kosa8" + + def __init__( + self, + api: Kosa8Api, + sandbox_id: str, + *, + tunnel_urls: dict[int, str], + network_policy: NetworkPolicy | None, + ): + self._api = api + self.sandbox_id = sandbox_id + self.mode = SANDBOX_MODE_VM + self.vnc_url = None + self.tunnel_urls = tunnel_urls + self.network_policy = network_policy + self._staging_ready = False + + async def terminate(self) -> None: + await self._api.delete_sandbox(self.sandbox_id) + + async def exec(self, *command: str) -> _CompletedProcess: + """Run argv to completion as root, with no input. A command past kosa8's argv limits goes through a file. A + stream lost before the command's exit status is exit -1, which ``exec_script`` retries.""" + argv = list(command[1:] if command[:1] == ("sudo",) else command) + if len(argv) + 4 <= MAX_ARGS and all(len(arg.encode()) <= MAX_ARG_BYTES for arg in argv): + wrapped = ["bash", "-c", _NO_INPUT, "kosa8-exec", *argv] + else: + path = f"{STAGING_DIR}/argv-{uuid.uuid4().hex}" + await self._upload(path, b"".join(arg.encode() + b"\0" for arg in argv)) + wrapped = ["bash", "-c", _FROM_FILE, "kosa8-exec", path] + exit_code, stdout, stderr = await self._api.exec(self.sandbox_id, wrapped) + return _CompletedProcess(stdout, stderr, exit_code) + + async def exec_with_output(self, *args: str) -> tuple[int, str, str]: + """An exec whose stream was cut (exit -1) returns no stdout, so a caller that skips the exit code can't mistake + partial output for the whole.""" + process = await self.exec(*args) + stdout, stderr = await asyncio.gather(process.stdout.read(), process.stderr.read()) + exit_code = await process.wait() + kept = b"" if exit_code == UNKNOWN_EXIT_CODE else stdout + return exit_code, kept.decode(errors="replace"), stderr.decode(errors="replace") + + async def _upload(self, path: str, data: bytes) -> None: + if not self._staging_ready: + await self._api.make_dir(self.sandbox_id, STAGING_DIR) + self._staging_ready = True + await self._api.write_file(self.sandbox_id, path, data) + + async def _write_bytes_to_vm_path(self, data: bytes, vm_path: str) -> None: + """Upload the bytes through the files API, a piece per request, and put them together at ``vm_path``. The bytes + never enter a command line, so a secret written this way stays out of the sandbox's process list.""" + stage = f"{STAGING_DIR}/upload-{uuid.uuid4().hex}" + pieces = [f"{stage}.{index}" for index in range(max(1, -(-len(data) // FILE_PIECE_BYTES)))] + quoted = " ".join(shlex.quote(piece) for piece in pieces) + try: + for index, piece in enumerate(pieces): + await self._upload(piece, data[index * FILE_PIECE_BYTES:(index + 1) * FILE_PIECE_BYTES]) + except BaseException: + await self._remove_vm_temp_file(*pieces) + raise + await self.exec_script(f"cat {quoted} > {shlex.quote(vm_path)}; c=$?; rm -f {quoted}; exit $c") + + async def wait_for_vm(self) -> None: + """Start dockerd and wait until it answers, and check for Compose v2, which ``deploy_env`` needs.""" + try: + await self.exec_script(DOCKER_READY, max_retries=2) + except RuntimeError as exc: + raise RuntimeError(f"Docker not ready on kosa8 sandbox {self.sandbox_id}: {exc}") from exc + logger.info("Docker ready on kosa8 sandbox %s", self.sandbox_id) + + async def setup_vm_for_gateway(self, exposed_ports: list[int] | None = None) -> None: + """Ready Docker; kosa8's preview proxy routes each exposed port into the VM, so no firewall.""" + await self.wait_for_vm() + + def _can_download(self, url: str | None) -> bool: + """Whether the sandbox can fetch ``url`` itself; an unknown policy counts as no.""" + if url is None or self.network_policy is None: + return False + host = urlparse(url).hostname + return host is not None and allows_host(self.network_policy, host) + + async def _download_object_to_vm(self, object_url: str, vm_path: str) -> None: + """Curl a signed URL the policy admits; push anything else over exec, which needs no egress.""" + object_store = get_config().get_object_store_at(object_url) + signed = await asyncio.to_thread(object_store.signed_get_url, object_url) + if self._can_download(signed): + await self.exec_script(f"curl -fsSL {CURL_RETRY_FLAGS} {shlex.quote(signed)} -o {shlex.quote(vm_path)}") + return + await self._write_unsigned_object(object_store, object_url, vm_path) + + async def _load_tarballs(self, artifacts: list) -> None: + """Load image tarballs, pushing over exec those the sandbox's policy can't download.""" + signed_urls = await self._signed_image_urls(artifacts) + reachable = [url if self._can_download(url) else None for url in signed_urls] + await self._load_docker_images(artifacts, reachable) diff --git a/src/agent_env/providers/sandbox_providers/sandbox_provider.py b/src/agent_env/providers/sandbox_providers/sandbox_provider.py index 1cc76fcca..0d314371c 100644 --- a/src/agent_env/providers/sandbox_providers/sandbox_provider.py +++ b/src/agent_env/providers/sandbox_providers/sandbox_provider.py @@ -383,6 +383,7 @@ def effective_network_policy(cls, policy: Optional[NetworkPolicy]) -> NetworkPol "boat": "agent_env.providers.sandbox_providers.boat.provider:BoatSandboxProvider", "coreweave": "agent_env.providers.sandbox_providers.coreweave.provider:CoreWeaveSandboxProvider", "agent37": "agent_env.providers.sandbox_providers.agent37.provider:Agent37SandboxProvider", + "kosa8": "agent_env.providers.sandbox_providers.kosa8.provider:Kosa8SandboxProvider", "local": "agent_env.providers.sandbox_providers.local_docker.provider:LocalSandboxProvider", "lume": "agent_env.providers.sandbox_providers.lume.provider:LumeSandboxProvider", } diff --git a/tst/integration/env/gateway/gateway_test.py b/tst/integration/env/gateway/gateway_test.py index 2c1c779b5..86b1977c9 100644 --- a/tst/integration/env/gateway/gateway_test.py +++ b/tst/integration/env/gateway/gateway_test.py @@ -439,6 +439,11 @@ def agentenv_website_env() -> WebsiteEnv: id="agent37", marks=skip_without_remote_sandbox("agent37"), ), + pytest.param( + "kosa8", + id="kosa8", + marks=skip_without_remote_sandbox("kosa8"), + ), ]) def sandbox_provider(request): from agent_env.providers import ( @@ -481,6 +486,9 @@ def sandbox_provider(request): elif request.param == "agent37": set_sandbox_provider(build_sandbox_provider("agent37")) set_env_sandbox_provider(build_sandbox_provider("agent37")) + elif request.param == "kosa8": + set_sandbox_provider(build_sandbox_provider("kosa8")) + set_env_sandbox_provider(build_sandbox_provider("kosa8")) try: yield request.param finally: diff --git a/tst/integration/env/task_step/task_steps_test.py b/tst/integration/env/task_step/task_steps_test.py index 21397dc3e..54c8a5614 100644 --- a/tst/integration/env/task_step/task_steps_test.py +++ b/tst/integration/env/task_step/task_steps_test.py @@ -312,6 +312,11 @@ def echo_agent() -> A2AAgent: id="agent37", marks=skip_without_remote_sandbox("agent37"), ), + pytest.param( + "kosa8", + id="kosa8", + marks=skip_without_remote_sandbox("kosa8"), + ), ]) def sandbox_provider(request): from agent_env.providers import ( @@ -366,6 +371,10 @@ def sandbox_provider(request): set_sandbox_provider(build_sandbox_provider("agent37")) set_env_sandbox_provider(build_sandbox_provider("agent37")) set_agent_sandbox_provider(build_sandbox_provider("agent37")) + elif request.param == "kosa8": + set_sandbox_provider(build_sandbox_provider("kosa8")) + set_env_sandbox_provider(build_sandbox_provider("kosa8")) + set_agent_sandbox_provider(build_sandbox_provider("kosa8")) try: yield request.param finally: diff --git a/tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py b/tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py new file mode 100644 index 000000000..cc2514e4e --- /dev/null +++ b/tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py @@ -0,0 +1,121 @@ +"""kosa8 Cloud sandbox smoke test. + +Runs when the resolved config can build the ``kosa8`` sandbox provider (``[sandbox.providers.kosa8.config]`` with +``api_key = "env:KOSA8_API_KEY"`` or a ``secret:`` reference), the ``remote_sandbox`` capability, and skips with the +declared reason otherwise. The test never reads or prints the API key. +""" + +from __future__ import annotations + +import asyncio +import hashlib +import os + +import httpx +import pytest +import pytest_asyncio + +from agent_env.providers.sandbox_providers.sandbox import NetworkMode, NetworkPolicy, read_vm_file +from agent_env.providers.sandbox_providers.sandbox_provider import SandboxNotFoundError, build_sandbox_provider +from tst.util.capabilities import skip_without_remote_sandbox + +_PORT = 8080 + +pytestmark = [ + pytest.mark.integration, + pytest.mark.int_test_slow, + pytest.mark.asyncio, + skip_without_remote_sandbox("kosa8"), +] + + +async def _wait_for_200(url: str) -> None: + async with httpx.AsyncClient(timeout=10) as client: + for _ in range(60): + try: + if (await client.get(url)).status_code == 200: + return + except httpx.HTTPError: + pass + await asyncio.sleep(2) + pytest.fail(f"{url} never answered 200") + + +@pytest.fixture(scope="module") +def kosa8_provider(): + return build_sandbox_provider("kosa8") + + +@pytest_asyncio.fixture(scope="module") +async def kosa8_sandbox(kosa8_provider): + """One kosa8 sandbox serving on ``_PORT`` from a container, always deleted after the module.""" + sandbox = await kosa8_provider.create_vm(cpu=2, memory=4096, exposed_ports=[_PORT], timeout=900) + try: + await sandbox.exec_script( + f"docker run -d --name smoke -p {_PORT}:{_PORT} public.ecr.aws/docker/library/python:3.12-slim " + f"python -m http.server {_PORT}" + ) + await _wait_for_200(sandbox.tunnel_urls[_PORT]) + yield sandbox + finally: + await sandbox.terminate() + + +async def test_kosa8_sandbox_docker_ports_files_and_reconnect(kosa8_provider, kosa8_sandbox, tmp_path): + """Nested Docker and Compose, a public port end to end, a file through the files API, a long command, a + multi-range read, and reconnect.""" + assert (kosa8_sandbox.type, kosa8_sandbox.mode) == ("kosa8", "vm") + + exit_code, version, stderr = await kosa8_sandbox.exec_with_output("sudo", "docker", "compose", "version") + assert exit_code == 0, stderr + assert version.strip() + + payload = os.urandom(5 * 1024 * 1024 + 17) + await kosa8_sandbox.write_host_file(payload, "/opt/smoke/payload.bin") + digest = await kosa8_sandbox.exec_script("sha256sum /opt/smoke/payload.bin") + assert digest.split()[0] == hashlib.sha256(payload).hexdigest() + + long_script = "printf '%s' " + "y" * 20000 + " | wc -c" + assert (await kosa8_sandbox.exec_script(long_script)).strip() == "20000" + assert (await kosa8_sandbox.exec_script("sleep 100 && echo slept")).strip() == "slept" + + await kosa8_sandbox.exec_script("head -c 5242887 /dev/urandom > /opt/smoke/large.bin") + remote = (await kosa8_sandbox.exec_script("sha256sum /opt/smoke/large.bin")).split()[0] + await read_vm_file(kosa8_sandbox, "/opt/smoke/large.bin", str(tmp_path / "large.bin")) + assert hashlib.sha256((tmp_path / "large.bin").read_bytes()).hexdigest() == remote + + reconnected = await build_sandbox_provider("kosa8").get_sandbox(kosa8_sandbox.sandbox_id) + assert reconnected.tunnel_urls == kosa8_sandbox.tunnel_urls + assert reconnected.network_policy == kosa8_sandbox.network_policy + assert (await reconnected.exec_with_output("true"))[0] == 0 + + +async def test_kosa8_concurrent_commands_that_read_input_end(kosa8_sandbox): + """Several execs that read standard input at once each see its end and exit.""" + results = await asyncio.wait_for( + asyncio.gather(*(kosa8_sandbox.exec_with_output("bash", "-c", f"cat; echo {i}") for i in range(6))), 60, + ) + assert [(code, out.strip()) for code, out, _ in results] == [(0, str(i)) for i in range(6)] + + +async def test_kosa8_allowlisted_sandbox_reaches_its_environment_and_nothing_else(kosa8_provider, kosa8_sandbox): + """An allowlisted sandbox reaches an allowed host and another kosa8 sandbox's public port, and nothing else.""" + policy = NetworkPolicy(mode=NetworkMode.ALLOWLIST, allow_hosts=("example.com",)) + agent = await kosa8_provider.create_vm(cpu=2, memory=4096, timeout=600, setup_for_gateway=False, + network_policy=policy) + try: + async def fetch(url: str) -> int: + return (await agent.exec_with_output("curl", "-fsS", "-o", "/dev/null", "--max-time", "15", url))[0] + + assert await fetch("https://example.com") == 0 + assert await fetch(kosa8_sandbox.tunnel_urls[_PORT]) == 0 + assert await fetch("https://www.wikipedia.org") != 0 + + reconnected = await build_sandbox_provider("kosa8").get_sandbox(agent.sandbox_id) + assert reconnected.network_policy.restricts_egress + assert set(reconnected.network_policy.allow_hosts) == set(agent.network_policy.allow_hosts) + finally: + await agent.terminate() + await reconnected.terminate() + with pytest.raises(SandboxNotFoundError): + await kosa8_provider.get_sandbox(agent.sandbox_id) diff --git a/tst/integration/providers/sandbox_providers/websockets_live_test.py b/tst/integration/providers/sandbox_providers/websockets_live_test.py index 677301302..5e386fa12 100644 --- a/tst/integration/providers/sandbox_providers/websockets_live_test.py +++ b/tst/integration/providers/sandbox_providers/websockets_live_test.py @@ -29,7 +29,7 @@ #: The remote providers, each of which declares whether it carries WebSockets. REMOTE = ("e2b", "tensorlake", "vercel", "coreweave", "daytona", "boat", "modal", "modal_vm", "boxd", "sail_vm", "tenki", - "agent37") + "agent37", "kosa8") PORT = 8765 FRAME_BYTES = 10 * 1024 * 1024 IDLE_S = 300 diff --git a/tst/unit/providers/sandbox_providers/egress_hosts_test.py b/tst/unit/providers/sandbox_providers/egress_hosts_test.py index 49aef5fbf..0d5789fde 100644 --- a/tst/unit/providers/sandbox_providers/egress_hosts_test.py +++ b/tst/unit/providers/sandbox_providers/egress_hosts_test.py @@ -51,6 +51,7 @@ def test_union_covers_every_registered_platforms_tunnel_hosts(platform_registry) assert "*.boxd.sh" in hosts # boxd's p. subdomain proxies assert "*.daytonaproxy01.net" in hosts # Daytona's - preview URLs assert "*.agent37.app" in hosts # Agent37's public-port URLs + assert "*.kosa8labs.com" in hosts # kosa8's - preview URLs def test_union_holds_only_platform_hosts(): @@ -103,5 +104,5 @@ def test_the_builtin_floor_is_pinned(builtin_registry): assert set(all_sandbox_egress_hosts()) == { "*.modal.host", "*.w.modal.host", "*.e2b.app", "*.sail.box", "*.sandbox.tensorlake.ai", "*.sb.tenki.sh", "*.us.sb.tenki.sh", "*.vercel.run", "*.boxd.sh", "*.daytonaproxy01.net", "*.daytonaproxy01.eu", - "*.on.boat.dev", "*.agent37.app", + "*.on.boat.dev", "*.agent37.app", "*.kosa8labs.com", } diff --git a/tst/unit/providers/sandbox_providers/kosa8_fakes.py b/tst/unit/providers/sandbox_providers/kosa8_fakes.py new file mode 100644 index 000000000..793217c52 --- /dev/null +++ b/tst/unit/providers/sandbox_providers/kosa8_fakes.py @@ -0,0 +1,170 @@ +"""An in-memory kosa8 Cloud API behind an ``httpx.MockTransport``, for the offline provider and sandbox tests.""" + +from __future__ import annotations + +import base64 +import json +from collections.abc import Callable +from typing import Any + +import httpx + +API_KEY = "k8_live_test_secret" +BASE_URL = "https://api.kosa8.com" + +ExecAnswer = httpx.Response | Exception | dict[str, Any] | list[dict[str, Any]] + + +def error(status: int, code: str) -> httpx.Response: + return httpx.Response(status, json={"error": code, "message": code}) + + +def frames(stdout: bytes = b"", stderr: bytes = b"", exit_code: int | None = 0, error_text: str | None = None, + heartbeats: int = 0) -> list[dict[str, Any]]: + """The NDJSON frames of a streamed exec: heartbeats, output, then its exit (or an error with no exit).""" + out: list[dict[str, Any]] = [{"stream": "stdout", "data": "", "heartbeat": True} for _ in range(heartbeats)] + if stdout: + out.append({"stream": "stdout", "data": base64.b64encode(stdout).decode()}) + if stderr: + out.append({"stream": "stderr", "data": base64.b64encode(stderr).decode()}) + if error_text is not None: + out.append({"done": True, "error": error_text}) + elif exit_code is not None: + out.append({"done": True, "exit": exit_code}) + return out + + +class FakeKosa8: + """Sandboxes, egress, previews, files and streamed exec on ``api.kosa8.com``. A create answers 202 ``creating`` and + the sandbox is ``running`` from the ``boot_polls``-th GET on. Each exec answers with the next of ``exec_answers`` (a + result dict, a list of frames, a response, or an exception to raise), then with ``exec_result``. A create answers + ``create_answer`` when it is set: a response refuses it, an exception is raised after the sandbox is made.""" + + def __init__(self) -> None: + self.sandboxes: dict[str, dict[str, Any]] = {} + self.egress: dict[str, str] = {} + self.previews: dict[str, dict[int, dict[str, Any]]] = {} + self.files: dict[tuple[str, str], bytes] = {} + self.dirs: list[tuple[str, str]] = [] + self.requests: list[httpx.Request] = [] + self.created: list[dict[str, Any]] = [] + self.deleted: list[str] = [] + self.execs: list[list[str]] = [] + self.exec_answers: list[ExecAnswer] = [] + self.exec_result: Callable[[list[str]], ExecAnswer] = lambda argv: {"exit": 0} + self.create_answer: httpx.Response | Exception | None = None + self.egress_answer: httpx.Response | None = None + self.org_default = "any" + self.boot_polls = 1 + + def transport(self) -> httpx.MockTransport: + return httpx.MockTransport(self._handle) + + def requests_to(self, method: str, path: str) -> list[httpx.Request]: + return [r for r in self.requests if r.method == method and r.url.path == path] + + def _handle(self, request: httpx.Request) -> httpx.Response: + self.requests.append(request) + assert f"{request.url.scheme}://{request.url.host}" == BASE_URL + assert request.headers["Authorization"] == f"Bearer {API_KEY}" + parts = request.url.path.strip("/").split("/") + if parts == ["v1", "sandboxes"] and request.method == "POST": + return self._create(json.loads(request.content)) + if parts == ["v1", "sandboxes"]: + name = request.url.params.get("name") + return httpx.Response(200, json={"sandboxes": [s for s in self.sandboxes.values() + if name is None or s["name"] == name], + "next_cursor": None}) + sandbox = self.sandboxes.get(parts[2]) + if sandbox is None or sandbox["state"] == "deleted": + return error(404, "not_found") + route = parts[3:] + if not route: + return self._sandbox(request, sandbox) + if route == ["egress"]: + return self._egress(request, sandbox) + if route == ["previews"]: + return self._previews(request, sandbox) + if route == ["files", "mkdir"]: + self.dirs.append((sandbox["id"], json.loads(request.content)["path"])) + return httpx.Response(200, json={"file": {"path": json.loads(request.content)["path"], "type": "dir"}}) + if route == ["files"] and request.method == "PUT": + path = request.url.params["path"] + assert path.startswith("/workspace/") + assert len(request.content) <= 8 * 1024 * 1024 + self.files[(sandbox["id"], path)] = request.content + return httpx.Response(200, json={"file": {"path": path, "size": len(request.content)}}) + if route == ["exec"]: + return self._exec(json.loads(request.content)) + return error(404, "not_found") + + def _create(self, body: dict[str, Any]) -> httpx.Response: + self.created.append(body) + if isinstance(self.create_answer, httpx.Response): + return self.create_answer + sandbox_id = f"sbx_{len(self.created):08d}" + self.sandboxes[sandbox_id] = {"id": sandbox_id, "state": "creating", "name": body.get("name"), + "template": "base", "polls": 0} + if self.create_answer is not None: + raise self.create_answer + return httpx.Response(202, json={"sandbox": self._view(self.sandboxes[sandbox_id]), "host_ms": 4}) + + @staticmethod + def _view(sandbox: dict[str, Any]) -> dict[str, Any]: + return {key: value for key, value in sandbox.items() if key != "polls"} + + def _sandbox(self, request: httpx.Request, sandbox: dict[str, Any]) -> httpx.Response: + if request.method == "DELETE": + sandbox["state"] = "deleted" + self.deleted.append(sandbox["id"]) + return httpx.Response(200, json={"deleted": sandbox["id"]}) + sandbox["polls"] += 1 + if sandbox["state"] == "creating" and sandbox["polls"] >= self.boot_polls: + sandbox["state"] = "running" + return httpx.Response(200, json={"sandbox": self._view(sandbox)}) + + def _egress(self, request: httpx.Request, sandbox: dict[str, Any]) -> httpx.Response: + if request.method == "PUT": + if self.egress_answer is not None: + return self.egress_answer + body = json.loads(request.content) + self.egress[sandbox["id"]] = f"allow:{','.join(body['allow'])}" if body.get("allow") else "deny" + enforced = self.egress.get(sandbox["id"], self.org_default) + return httpx.Response(200, json={"egress": {"enforced": enforced}}) + + def _previews(self, request: httpx.Request, sandbox: dict[str, Any]) -> httpx.Response: + open_ports = self.previews.setdefault(sandbox["id"], {}) + if request.method == "GET": + return httpx.Response(200, json={"previews": list(open_ports.values()), "configured": True}) + body = json.loads(request.content) + port = body["port"] + preview = {"port": port, "public": body.get("public") is True, + "url": f"https://{port}-{sandbox['id'][-8:]}.kosa8labs.com/"} + status = 200 if port in open_ports else 201 + open_ports[port] = preview + return httpx.Response(status, json={"preview": preview}) + + def _exec(self, body: dict[str, Any]) -> httpx.Response: + argv = body["cmd"] + assert body.get("stream") is True + if len(argv) > 256 or any(len(arg) > 8192 for arg in argv): + return error(400, "invalid_cmd") + self.execs.append(argv) + answer = self.exec_answers.pop(0) if self.exec_answers else self.exec_result(argv) + if isinstance(answer, Exception): + raise answer + if isinstance(answer, httpx.Response): + return answer + if isinstance(answer, dict): + answer = frames(answer.get("stdout", b""), answer.get("stderr", b""), answer.get("exit", 0)) + content = "".join(json.dumps(frame) + "\n" for frame in answer).encode() + return httpx.Response(200, content=content, headers={"Content-Type": "application/x-ndjson"}) + + +def command_of(argv: list[str], fake: FakeKosa8, sandbox_id: str) -> list[str]: + """The argv a wrapped exec runs: inline after ``bash -c … kosa8-exec``, or read back from its spilled file.""" + assert argv[:2] == ["bash", "-c"] and argv[3] == "kosa8-exec" + if "mapfile" not in argv[2]: + return argv[4:] + data = fake.files[(sandbox_id, argv[4])] + return [part.decode() for part in data.split(b"\0")[:-1]] diff --git a/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py new file mode 100644 index 000000000..9272ddda5 --- /dev/null +++ b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py @@ -0,0 +1,312 @@ +"""Offline unit tests for the kosa8 sandbox provider.""" + +from __future__ import annotations + +import asyncio + +import httpx +import pytest + +from agent_env.config.errors import ConfigError +from agent_env.providers.sandbox_providers.kosa8 import provider as provider_module +from agent_env.providers.sandbox_providers.kosa8 import sandbox as sandbox_module +from agent_env.providers.sandbox_providers.kosa8.provider import ( + DEFAULT_IMAGE, + Kosa8SandboxProvider, + disk_gb, + egress_entries, + lifetime, + sandbox_name, + sandbox_size, +) +from agent_env.providers.sandbox_providers.kosa8.sandbox import DOCKER_READY, Kosa8Error, policy_from_enforced +from agent_env.providers.sandbox_providers.sandbox import NetworkMode, NetworkPolicy, NetworkPolicyUnsupportedError +from agent_env.providers.sandbox_providers.sandbox_provider import SandboxNotFoundError +from tst.unit.providers.sandbox_providers.kosa8_fakes import API_KEY, FakeKosa8, command_of, error + +ALLOWLIST = NetworkMode.ALLOWLIST + + +@pytest.fixture +def api(): + return FakeKosa8() + + +@pytest.fixture(autouse=True) +def _no_waits(monkeypatch): + monkeypatch.setattr(sandbox_module, "RESEND_DELAYS", (0, 0, 0, 0, 0)) + monkeypatch.setattr(provider_module, "POLL_SEC", (0, 0)) + + +def _provider(api: FakeKosa8, **kwargs) -> Kosa8SandboxProvider: + return Kosa8SandboxProvider(api_key=API_KEY, transport=api.transport(), **kwargs) + + +@pytest.mark.parametrize(("cpu", "memory", "size"), [ + (1.0, 8192, "4x8"), + (0.5, 1024, "2x4"), + (2, 4096, "2x4"), + (2.5, 2048, "4x8"), + (1, 8193, "8x16"), + (16, 32768, "16x32"), +]) +def test_size_is_the_smallest_that_covers_cpu_and_memory(cpu, memory, size): + assert sandbox_size(cpu, memory) == size + + +@pytest.mark.parametrize(("cpu", "memory"), [(17, 1024), (1, 32769)]) +def test_size_refuses_rather_than_shrinks(cpu, memory): + with pytest.raises(ValueError, match="kosa8 cannot size a sandbox"): + sandbox_size(cpu, memory) + + +def test_disk_and_lifetime_stay_within_what_kosa8_takes(): + assert (disk_gb(10), disk_gb(32), disk_gb(100.5), disk_gb(200)) == (32, 32, 101, 200) + assert (lifetime(1), lifetime(900)) == (60, 900) + with pytest.raises(ValueError, match="200 GB"): + disk_gb(201) + with pytest.raises(ValueError, match="cannot keep a sandbox"): + lifetime(91 * 86400) + + +def test_sandbox_names_are_unique_and_carry_no_attribution(): + name = sandbox_name() + assert name.startswith("agentenv-") and len(name) == len("agentenv-") + 16 + assert sandbox_name() != name + + +@pytest.mark.parametrize("policy", [ + NetworkPolicy(), + NetworkPolicy(mode=ALLOWLIST), + NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org", "*.npmjs.org", "Files.PythonHosted.org", "203.0.113.7"), + allow_cidrs=("10.0.0.0/8",)), +]) +def test_supports_allow_all_and_allow_lists_kosa8_takes(policy): + assert Kosa8SandboxProvider.supports_network_policy(policy) + + +@pytest.mark.parametrize("entry", [ + "2001:db8::/32", "::1", "*.com", "example.com:443", "https://example.com", "example.com/path", "1.2.3", +]) +def test_refuses_an_allow_list_entry_kosa8_refuses(entry): + assert not Kosa8SandboxProvider.supports_network_policy(NetworkPolicy(mode=ALLOWLIST, allow_hosts=(entry,))) + + +def test_refuses_an_allow_list_longer_than_kosa8_keeps(): + hosts = tuple(f"h{index}.example.com" for index in range(257)) + assert not Kosa8SandboxProvider.supports_network_policy(NetworkPolicy(mode=ALLOWLIST, allow_hosts=hosts)) + + +def test_egress_entries_are_hosts_then_addresses_without_repeats(): + policy = NetworkPolicy(mode=ALLOWLIST, allow_hosts=("a.com", "*.b.com", "a.com"), allow_cidrs=("1.1.1.0/24",)) + assert egress_entries(policy) == ["a.com", "*.b.com", "1.1.1.0/24"] + + +def test_from_config_takes_the_known_keys(): + provider = Kosa8SandboxProvider.from_config(api_key="k8_x", region="eu", image="ghcr.io/acme/dind:1") + assert (provider._region, provider._image) == ("eu", "ghcr.io/acme/dind:1") + assert Kosa8SandboxProvider.from_config(api_key="k8_x")._image == DEFAULT_IMAGE + + +@pytest.mark.parametrize(("config", "message"), [ + ({"api_key": "k", "org": "x"}, "unknown key"), + ({}, "requires a non-empty 'api_key'"), + ({"api_key": "k", "region": " "}, "non-empty string"), + ({"api_key": "k", "base_url": 443}, "non-empty string"), + ({"api_key": "k", "image": ""}, "non-empty string"), +]) +def test_from_config_refuses_bad_config(config, message): + with pytest.raises(ConfigError, match=message): + Kosa8SandboxProvider.from_config(**config) + + +@pytest.mark.asyncio +async def test_create_vm_boots_a_docker_sandbox_with_a_lifetime_and_a_public_url_per_port(api): + sandbox = await _provider(api, region="eu").create_vm( + cpu=1.5, memory=4096, timeout=900, exposed_ports=[8080, 8080, 9000], setup_for_gateway=False, + attribution={"run_id": "r1"}, + ) + [body] = api.created + assert body.pop("name").startswith("agentenv-") + assert body == {"image": DEFAULT_IMAGE, "size": "2x4", "disk_gb": 32, "docker": True, "sleep_after_s": 0, + "ttl_s": 900, "region": "eu"} + assert (sandbox.type, sandbox.mode, sandbox.sandbox_id) == ("kosa8", "vm", "sbx_00000001") + assert sandbox.tunnel_urls == {8080: "https://8080-00000001.kosa8labs.com", + 9000: "https://9000-00000001.kosa8labs.com"} + assert all(preview["public"] for preview in api.previews["sbx_00000001"].values()) + assert sandbox.network_policy == NetworkPolicy() + assert api.requests_to("PUT", "/v1/sandboxes/sbx_00000001/egress") == [] + assert api.execs == [] + + +@pytest.mark.asyncio +async def test_create_vm_waits_for_a_cold_boot(api): + api.boot_polls = 3 + await _provider(api).create_vm(setup_for_gateway=False) + assert len(api.requests_to("GET", "/v1/sandboxes/sbx_00000001")) == 3 + + +@pytest.mark.asyncio +async def test_create_vm_starts_docker_for_the_gateway(api): + await _provider(api).create_vm(exposed_ports=[8000]) + [check] = api.execs + assert command_of(check, api, "sbx_00000001") == ["bash", "-c", DOCKER_READY] + + +@pytest.mark.asyncio +async def test_create_vm_applies_an_allow_list_with_kosa8s_hosts_and_reports_it(api): + policy = NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",), allow_cidrs=("203.0.113.0/24",)) + sandbox = await _provider(api).create_vm(network_policy=policy, setup_for_gateway=False) + [put] = api.requests_to("PUT", "/v1/sandboxes/sbx_00000001/egress") + allow = sandbox_module.json.loads(put.content)["allow"] + assert allow[0] == "pypi.org" and allow[-1] == "203.0.113.0/24" + assert "*.kosa8labs.com" in allow and "*.boxd.sh" in allow + assert sandbox.network_policy.restricts_egress + assert sandbox.network_policy.allow_cidrs == ("203.0.113.0/24",) + assert set(sandbox.network_policy.allow_hosts) == set(allow[:-1]) + + +@pytest.mark.asyncio +async def test_an_org_default_policy_is_what_the_sandbox_reports(api): + api.org_default = "allow:pypi.org;deny:gist.github.com" + sandbox = await _provider(api).create_vm(setup_for_gateway=False) + assert sandbox.network_policy == NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",)) + + +@pytest.mark.parametrize("status", [400, 403, 501]) +@pytest.mark.asyncio +async def test_an_allow_list_kosa8_refuses_deletes_the_sandbox_and_is_unsupported(api, status): + api.egress_answer = error(status, "invalid_egress") + with pytest.raises(NetworkPolicyUnsupportedError, match="refused the egress allow list"): + await _provider(api).create_vm(network_policy=NetworkPolicy(mode=ALLOWLIST, allow_hosts=("a.com",)), + setup_for_gateway=False) + assert api.deleted == ["sbx_00000001"] + + +@pytest.mark.asyncio +async def test_create_vm_refuses_what_it_cannot_honour_before_creating_anything(api): + provider = _provider(api) + with pytest.raises(ValueError, match="per-call image is unsupported"): + await provider.create_vm(image="ubuntu:24.04") + with pytest.raises(NetworkPolicyUnsupportedError): + await provider.create_vm(network_policy=NetworkPolicy(mode=ALLOWLIST, allow_hosts=("2001:db8::1",))) + with pytest.raises(ValueError, match="cannot size"): + await provider.create_vm(cpu=32) + assert api.requests == [] + + +@pytest.mark.asyncio +async def test_a_sandbox_whose_docker_never_readies_is_deleted(api): + api.exec_result = lambda argv: {"exit": 1, "stderr": b"docker daemon did not become ready"} + with pytest.raises(RuntimeError, match="Docker not ready on kosa8 sandbox sbx_00000001"): + await _provider(api).create_vm(exposed_ports=[8000]) + assert api.deleted == ["sbx_00000001"] + + +@pytest.mark.asyncio +async def test_a_sandbox_that_fails_to_boot_is_deleted(api): + api.boot_polls = 2 + provider = _provider(api) + get = provider._api.get_sandbox + + async def failed(sandbox_id): + sandbox = await get(sandbox_id) + return {**sandbox, "state": "error", "last_error": "no image"} + + provider._api.get_sandbox = failed + with pytest.raises(RuntimeError, match=r"did not start \(error\): no image"): + await provider.create_vm(setup_for_gateway=False) + assert api.deleted == ["sbx_00000001"] + + +@pytest.mark.asyncio +async def test_a_create_whose_answer_is_lost_deletes_the_sandbox_it_made_by_name(api): + api.create_answer = httpx.ReadError("connection reset") + with pytest.raises(httpx.ReadError): + await _provider(api).create_vm(setup_for_gateway=False) + assert api.deleted == ["sbx_00000001"] + assert len(api.created) == 1 + + +@pytest.mark.asyncio +async def test_a_refused_create_raises_the_reason_and_deletes_nothing(api): + api.create_answer = httpx.Response(402, json={"error": "payment_required", "message": "Add a payment method."}) + with pytest.raises(Kosa8Error, match="402 payment_required: Add a payment method."): + await _provider(api).create_vm(setup_for_gateway=False) + assert api.sandboxes == {} and api.deleted == [] + + +@pytest.mark.asyncio +async def test_a_create_refused_for_capacity_is_sent_again(api): + answers = [error(503, "no_capacity")] + provider = _provider(api) + create = api._create + + def busy_once(body): + return answers.pop() if answers else create(body) + + api._create = busy_once + sandbox = await provider.create_vm(setup_for_gateway=False) + assert sandbox.sandbox_id == "sbx_00000001" + + +@pytest.mark.asyncio +async def test_a_cancelled_create_deletes_the_sandbox_once_the_create_answers(api): + gate = asyncio.Event() + provider = _provider(api) + create = provider._api.create_sandbox + + async def slow_create(body): + await gate.wait() + return await create(body) + + provider._api.create_sandbox = slow_create + task = asyncio.ensure_future(provider.create_vm(setup_for_gateway=False)) + await asyncio.sleep(0) + task.cancel() + await asyncio.sleep(0) + gate.set() + with pytest.raises(asyncio.CancelledError): + await task + assert api.deleted == ["sbx_00000001"] + + +@pytest.mark.asyncio +async def test_create_sandbox_is_a_vm_exposing_the_agent_port(api): + sandbox = await _provider(api).create_sandbox(image_name="agent:latest", port=8000, env={"A": "1"}, + attribution={"run_id": "r2"}) + assert list(sandbox.tunnel_urls) == [8000] + assert "env" not in api.created[0] + + +@pytest.mark.asyncio +async def test_get_sandbox_from_a_fresh_provider_restores_ports_and_policy(api): + policy = NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",)) + created = await _provider(api).create_vm(exposed_ports=[8080], network_policy=policy, setup_for_gateway=False) + reconnected = await _provider(api).get_sandbox(created.sandbox_id) + assert (reconnected.sandbox_id, reconnected.tunnel_urls) == (created.sandbox_id, created.tunnel_urls) + assert reconnected.network_policy == created.network_policy + + +@pytest.mark.parametrize(("enforced", "policy"), [ + ("any", NetworkPolicy()), + ("block:gist.github.com", NetworkPolicy()), + ("deny", NetworkPolicy(mode=ALLOWLIST)), + ("allow:pypi.org,*.npmjs.org,203.0.113.0/24;deny:x.com", + NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org", "*.npmjs.org"), allow_cidrs=("203.0.113.0/24",))), +]) +def test_policy_from_enforced_reads_kosa8s_compiled_policy(enforced, policy): + assert policy_from_enforced(enforced) == policy + + +@pytest.mark.asyncio +async def test_terminate_is_idempotent_and_a_gone_sandbox_is_not_found(api): + provider = _provider(api) + sandbox = await provider.create_vm(setup_for_gateway=False) + await sandbox.terminate() + await sandbox.terminate() + await provider.terminate_sandbox(sandbox.sandbox_id) + with pytest.raises(SandboxNotFoundError): + await provider.get_sandbox(sandbox.sandbox_id) + with pytest.raises(SandboxNotFoundError): + await provider.get_sandbox("sbx_missing") diff --git a/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py b/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py new file mode 100644 index 000000000..4bf3ee5f9 --- /dev/null +++ b/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py @@ -0,0 +1,144 @@ +"""Offline unit tests for the kosa8 sandbox: exec, its limits, file writes, readiness and egress.""" + +from __future__ import annotations + +import httpx +import pytest + +from agent_env.providers.sandbox_providers.kosa8 import sandbox as sandbox_module +from agent_env.providers.sandbox_providers.kosa8.sandbox import Kosa8Api, Kosa8Error, Kosa8Sandbox, allows_host +from agent_env.providers.sandbox_providers.sandbox import NetworkMode, NetworkPolicy +from tst.unit.providers.sandbox_providers.kosa8_fakes import API_KEY, FakeKosa8, command_of, error, frames + +ALLOWLIST = NetworkMode.ALLOWLIST + + +@pytest.fixture(autouse=True) +def _no_resend_delays(monkeypatch): + monkeypatch.setattr(sandbox_module, "RESEND_DELAYS", (0, 0, 0, 0, 0)) + + +@pytest.fixture +def api(): + fake = FakeKosa8() + fake.sandboxes["sbx_1"] = {"id": "sbx_1", "state": "running", "name": "agentenv-x", "polls": 0} + return fake + + +def _sandbox(api: FakeKosa8, policy: NetworkPolicy | None = NetworkPolicy()) -> Kosa8Sandbox: + return Kosa8Sandbox(Kosa8Api(API_KEY, transport=api.transport()), "sbx_1", tunnel_urls={}, network_policy=policy) + + +@pytest.mark.asyncio +async def test_exec_runs_argv_as_root_with_no_input(api): + api.exec_answers = [{"stdout": b"hi there\n"}] + assert await _sandbox(api).exec_with_output("sudo", "echo", "hi there") == (0, "hi there\n", "") + [argv] = api.execs + assert argv == ["bash", "-c", 'exec "$@" Sandbox: return await provider.create_vm(exposed_ports=[], setup_for_gateway=False) +async def _kosa8() -> Sandbox: + from tst.unit.providers.sandbox_providers.kosa8_fakes import API_KEY, FakeKosa8 + provider = Kosa8SandboxProvider(api_key=API_KEY, transport=FakeKosa8().transport()) + return await provider.create_vm(exposed_ports=[], setup_for_gateway=False) + + async def _smol_vm() -> Sandbox: pytest.importorskip("smol") from agent_env.providers.sandbox_providers.smol_vm import provider as smol_module @@ -202,6 +209,7 @@ async def _lume() -> Sandbox: "daytona": _daytona, "boat": _boat, "agent37": _agent37, + "kosa8": _kosa8, "smol_vm": _smol_vm, "local": _local, "lume": _lume, diff --git a/tst/unit/providers/sandbox_providers/provider_capabilities_test.py b/tst/unit/providers/sandbox_providers/provider_capabilities_test.py index cf738e2fc..9a020a7af 100644 --- a/tst/unit/providers/sandbox_providers/provider_capabilities_test.py +++ b/tst/unit/providers/sandbox_providers/provider_capabilities_test.py @@ -24,6 +24,8 @@ from agent_env.providers.sandbox_providers.daytona.sandbox import DaytonaSandbox from agent_env.providers.sandbox_providers.e2b.provider import E2BSandboxProvider from agent_env.providers.sandbox_providers.e2b.sandbox import E2BSandbox +from agent_env.providers.sandbox_providers.kosa8.provider import Kosa8SandboxProvider +from agent_env.providers.sandbox_providers.kosa8.sandbox import Kosa8Sandbox from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandbox, LocalSandboxProvider from agent_env.providers.sandbox_providers.modal_sandbox import ModalSandbox, ModalSandboxProvider from agent_env.providers.sandbox_providers.modal_vm_sandbox import ModalVmSandbox, ModalVmSandboxProvider @@ -49,7 +51,7 @@ PROVIDER_CLASSES = [LocalSandboxProvider, ModalSandboxProvider, ModalVmSandboxProvider, E2BSandboxProvider, SailVmSandboxProvider, TensorlakeSandboxProvider, TenkiSandboxProvider, BoxdSandboxProvider, CoreWeaveSandboxProvider, DaytonaSandboxProvider, BoatSandboxProvider, Agent37SandboxProvider, - ChainedSandboxProvider] + Kosa8SandboxProvider, ChainedSandboxProvider] @pytest.mark.parametrize("cls, on_this_machine, creates_vms, sandbox, container, private_network, websockets", [ @@ -65,8 +67,9 @@ (DaytonaSandboxProvider, False, True, LOADABLE, NAME, False, False), (BoatSandboxProvider, False, True, LOADABLE, NAME, False, True), (Agent37SandboxProvider, False, True, LOADABLE, NAME, False, True), + (Kosa8SandboxProvider, False, True, LOADABLE, NAME, False, True), ], ids=["local", "modal", "modal_vm", "e2b", "sail_vm", "tensorlake", "tenki", "boxd", "coreweave", "daytona", "boat", - "agent37"]) + "agent37", "kosa8"]) def test_each_provider_declares_where_it_runs_and_the_images_it_runs(cls, on_this_machine, creates_vms, sandbox, container, private_network, websockets): assert ((cls.ON_THIS_MACHINE, SANDBOX_MODE_VM in cls.SUPPORTED_SANDBOX_MODES, cls.PRIVATE_NETWORK, cls.WEBSOCKETS) @@ -290,7 +293,7 @@ def test_an_image_that_records_no_platform_isnt_checked(): @pytest.mark.parametrize("sandbox", [Sandbox, ModalSandbox, ModalVmSandbox, E2BSandbox, SailVmSandbox, TensorlakeSandbox, TenkiSandbox, BoxdSandbox, CoreWeaveSandbox, DaytonaSandbox, BoatSandbox, - Agent37Sandbox]) + Agent37Sandbox, Kosa8Sandbox]) def test_a_sandbox_runs_linux_amd64_unless_its_provider_sets_another(sandbox): assert sandbox.platform == "linux/amd64" diff --git a/tst/unit/providers/sandbox_providers/test_config_sandbox_providers.py b/tst/unit/providers/sandbox_providers/test_config_sandbox_providers.py index 0b1d7004a..94b784986 100644 --- a/tst/unit/providers/sandbox_providers/test_config_sandbox_providers.py +++ b/tst/unit/providers/sandbox_providers/test_config_sandbox_providers.py @@ -14,6 +14,7 @@ from agent_env.providers.sandbox_providers.daytona.config import Settings as DaytonaSettings from agent_env.providers.sandbox_providers.daytona.provider import DaytonaSandboxProvider from agent_env.providers.sandbox_providers.e2b.provider import E2BSandboxProvider +from agent_env.providers.sandbox_providers.kosa8.provider import Kosa8SandboxProvider from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandboxProvider from agent_env.providers.sandbox_providers.modal_vm_sandbox import ModalVmSandboxProvider from agent_env.providers.sandbox_providers.sail_vm.provider import SailVmSandboxProvider @@ -360,6 +361,33 @@ def test_boxd_missing_api_key_is_a_config_error(monkeypatch, tmp_path): build_sandbox_provider("boxd") +def test_kosa8_builtin_receives_interpolated_key_and_region(monkeypatch, tmp_path): + cfg = _write_config(tmp_path, """ + [sandbox.providers.kosa8.config] + api_key = "env:KOSA8_TEST_API_KEY" + region = "eu" + """) + monkeypatch.setenv("AGENT_ENV_CONFIG", str(cfg)) + monkeypatch.setenv("KOSA8_TEST_API_KEY", "resolved-test-key") + + provider = build_sandbox_provider("kosa8") + + assert isinstance(provider, Kosa8SandboxProvider) + assert provider._api._api_key == "resolved-test-key" + assert provider._region == "eu" + + +def test_kosa8_missing_api_key_is_a_config_error(monkeypatch, tmp_path): + cfg = _write_config(tmp_path, """ + [sandbox.providers.kosa8.config] + region = "eu" + """) + monkeypatch.setenv("AGENT_ENV_CONFIG", str(cfg)) + + with pytest.raises(ConfigError, match="requires a non-empty 'api_key'"): + build_sandbox_provider("kosa8") + + def test_coreweave_builtin_receives_an_interpolated_key(monkeypatch, tmp_path): cfg = _write_config(tmp_path, """ [sandbox.providers.coreweave.config] diff --git a/tst/unit/test_capabilities.py b/tst/unit/test_capabilities.py index 44ad7b3d9..a760eb1db 100644 --- a/tst/unit/test_capabilities.py +++ b/tst/unit/test_capabilities.py @@ -151,7 +151,8 @@ def build(spec): monkeypatch.setattr("agent_env.providers.sandbox_providers.sandbox_provider.build_sandbox_provider", build) -_CONFIGURED_PROVIDERS = pytest.mark.parametrize("provider", ["e2b", "sail_vm", "tensorlake", "tenki", "boxd", "coreweave", "daytona"]) +_CONFIGURED_PROVIDERS = pytest.mark.parametrize("provider", ["e2b", "sail_vm", "tensorlake", "tenki", "boxd", "coreweave", "daytona", + "kosa8"]) @_CONFIGURED_PROVIDERS diff --git a/tst/util/capabilities.py b/tst/util/capabilities.py index de622a5ee..fcbdf763b 100644 --- a/tst/util/capabilities.py +++ b/tst/util/capabilities.py @@ -23,8 +23,8 @@ MODEL_ENDPOINT = "model_endpoint_configured" #: The remote sandbox providers (``modal``, ``modal_vm``, ``e2b``, ``sail_vm``, ``tensorlake``, ``tenki``, -#: ``vercel``, ``boxd``, ``coreweave``, ``daytona``, ``boat``, ``agent37``) need credentials the resolved config may not -#: carry; the local default never does. +#: ``vercel``, ``boxd``, ``coreweave``, ``daytona``, ``boat``, ``agent37``, ``kosa8``) need +#: credentials the resolved config may not carry; the local default never does. REMOTE_SANDBOX = "remote_sandbox" #: The A2A agent a ``deploy_agent`` step without an id resolves to (``default_a2a_agent_id``); the @@ -122,17 +122,17 @@ def skip_without_model_endpoint() -> pytest.MarkDecorator: def remote_sandbox_is_available(provider: str) -> bool: """Whether the resolved config can build the ``modal`` / ``modal_vm`` / ``e2b`` / ``sail_vm`` / - ``tensorlake`` / ``tenki`` / ``vercel`` / ``boxd`` / ``coreweave`` / ``daytona`` / ``boat`` / ``agent37`` sandbox provider, credentials included. + ``tensorlake`` / ``tenki`` / ``vercel`` / ``boxd`` / ``coreweave`` / ``daytona`` / ``boat`` / ``agent37`` / ``kosa8`` sandbox provider, credentials included. Modal: any failure to resolve the credentials answers False. E2B, Sail, Tensorlake, Tenki, Vercel, boxd, - CoreWeave, Daytona, boat and Agent37: building the provider resolves ``[sandbox.providers..config]`` and its ``secret:`` references; + CoreWeave, Daytona, boat, Agent37 and kosa8: building the provider resolves ``[sandbox.providers..config]`` and its ``secret:`` references; only a ``ConfigError`` (absent or incomplete config, or the provider's extra not installed) answers False, any other failure answers True and lets the test fail on the real problem, as ``model_endpoint_is_configured`` does. Vercel, which builds without credentials, also needs them in its config or the environment.""" - if provider not in ("modal", "modal_vm", "e2b", "sail_vm", "tensorlake", "tenki", "vercel", "boxd", "coreweave", "daytona", "boat", "agent37"): + if provider not in ("modal", "modal_vm", "e2b", "sail_vm", "tensorlake", "tenki", "vercel", "boxd", "coreweave", "daytona", "boat", "agent37", "kosa8"): raise ValueError(f"unknown remote sandbox provider {provider!r}") - if provider in ("e2b", "sail_vm", "tensorlake", "tenki", "vercel", "boxd", "coreweave", "daytona", "boat", "agent37"): + if provider in ("e2b", "sail_vm", "tensorlake", "tenki", "vercel", "boxd", "coreweave", "daytona", "boat", "agent37", "kosa8"): from agent_env.config.errors import ConfigError from agent_env.providers.sandbox_providers.sandbox_provider import build_sandbox_provider From af89ebabca3512e1e7d6b70644aef6f0b124d3f3 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 16:46:55 -0800 Subject: [PATCH 2/3] fix(sandbox): kosa8 creates a restricted sandbox under its allow list The allow list now goes with the create, so kosa8 enforces it before the create answers and the VM never runs more open than asked; a create kosa8 refuses for its allow list (an egress error code, or 501) is a policy it can't enforce, so a fallback chain moves on. The PUT after boot, and the API call behind it, are gone. Co-Authored-By: Claude Opus 5.5 --- .../sandbox_providers/kosa8/README.md | 10 +++--- .../sandbox_providers/kosa8/provider.py | 33 ++++++++++--------- .../sandbox_providers/kosa8/sandbox.py | 5 --- .../sandbox_providers/kosa8_fakes.py | 8 ++--- .../kosa8_sandbox_provider_test.py | 24 +++++++++----- 5 files changed, 40 insertions(+), 40 deletions(-) diff --git a/src/agent_env/providers/sandbox_providers/kosa8/README.md b/src/agent_env/providers/sandbox_providers/kosa8/README.md index e0ea557df..1c8acd6a4 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/README.md +++ b/src/agent_env/providers/sandbox_providers/kosa8/README.md @@ -83,10 +83,10 @@ All keys go under `[sandbox.providers.kosa8.config]`. Unknown keys are refused. `tunnel_urls`. It serves HTTP and WebSocket with no platform authentication, like other providers' tunnels; the random part is the only secret. - **Egress:** allow-all, or an allow list of at most 256 hostnames, `*.` wildcards and IPv4 addresses or ranges. kosa8 - enforces it on the host, outside the VM, so one list covers `dockerd` and every container. It is applied right after - the sandbox is running, before anything runs in it. IPv6 entries are refused with `NetworkPolicyUnsupportedError` - before anything is created; a list kosa8 itself refuses (or an organization policy that does not allow it) deletes - the sandbox and raises the same error, so a fallback chain moves on. + enforces it on the host, outside the VM, so one list covers `dockerd` and every container. The list goes with the + create, so it is in force before kosa8 answers and the sandbox never runs more open than asked. IPv6 entries are + refused with `NetworkPolicyUnsupportedError` before anything is created; a list kosa8 itself refuses (or an + organization policy that does not allow it) fails the create with the same error, so a fallback chain moves on. - **Wildcards:** `*.example.com` covers every name under `example.com` but not `example.com` itself. - **kosa8's own hosts:** `*.kosa8labs.com` is added to every allow list, so a restricted agent can reach the environments it talks to. @@ -96,7 +96,7 @@ All keys go under `[sandbox.providers.kosa8.config]`. Unknown keys are refused. ## Cleanup -- A sandbox whose setup fails after it is created (boot, egress, ports, Docker readiness) is deleted. +- A sandbox whose setup fails after it is created (boot, ports, Docker readiness) is deleted. - If a create fails after kosa8 may have made the sandbox, or its caller is cancelled, the provider finds it by its unique `agentenv-` name and deletes it. - Whatever else happens, `ttl_s` removes the sandbox at the sandbox's `timeout`. diff --git a/src/agent_env/providers/sandbox_providers/kosa8/provider.py b/src/agent_env/providers/sandbox_providers/kosa8/provider.py index 8ea41cc43..42089f523 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/provider.py +++ b/src/agent_env/providers/sandbox_providers/kosa8/provider.py @@ -183,8 +183,9 @@ async def create_vm( env: dict[str, str] | None = None, ) -> Kosa8Sandbox: """Create a kosa8 microVM that runs Docker, with a public URL for each of ``exposed_ports``. ``timeout`` is the - sandbox's ``ttl_s``, its hard maximum lifetime. Sandboxes boot the configured image, so a per-call ``image`` is - refused rather than ignored; ``boot_mode`` and ``env`` have no kosa8 equivalent here and are ignored.""" + sandbox's ``ttl_s``, its hard maximum lifetime. An allow list goes with the create, so it is in force before the + VM answers. Sandboxes boot the configured image, so a per-call ``image`` is refused rather than ignored; + ``boot_mode`` and ``env`` have no kosa8 equivalent here and are ignored.""" if image is not None: raise ValueError("kosa8 sandboxes boot the configured Docker-capable image; a per-call image is unsupported") if boot_mode is not None: @@ -215,13 +216,13 @@ async def create_vm( } if self._region: body["region"] = self._region - created = await self._create(body) + if effective_policy.restricts_egress: + body["egress"] = {"allow": egress_entries(effective_policy)} + created = await self._create_with_policy(body) sandbox_id = created["id"] sandbox = Kosa8Sandbox(self._api, sandbox_id, tunnel_urls={}, network_policy=effective_policy) try: await self._wait_until_running(created) - if effective_policy.restricts_egress: - await self._set_egress(sandbox_id, egress_entries(effective_policy)) sandbox.network_policy = policy_from_enforced(await self._api.enforced_egress(sandbox_id)) sandbox.tunnel_urls = {port: await self._api.open_port(sandbox_id, port) for port in ports} logger.info( @@ -236,6 +237,17 @@ async def create_vm( await _settle(self._delete_quietly(sandbox_id)) raise + async def _create_with_policy(self, body: dict[str, Any]) -> dict[str, Any]: + """The create, with an allow list kosa8 refuses (an entry it can't parse, a host without egress controls, an + org policy that doesn't allow it) raised as a policy it can't enforce, so a fallback chain moves on.""" + try: + return await self._create(body) + except Kosa8Error as exc: + if "egress" not in body or ("egress" not in exc.code and exc.status_code != 501): + raise + raise NetworkPolicyUnsupportedError(f"kosa8 refused the egress allow list {body['egress']['allow']}: " + f"{exc}") from exc + async def _create(self, body: dict[str, Any]) -> dict[str, Any]: """Await the create. When it fails or its caller is cancelled, the sandbox it may have made anyway is deleted once it settles, found by its unique name if its answer was lost.""" @@ -280,17 +292,6 @@ async def _wait_until_running(self, sandbox: dict[str, Any]) -> None: interval = min(interval * 1.5, longest) sandbox = await self._api.get_sandbox(sandbox["id"]) - async def _set_egress(self, sandbox_id: str, allow: list[str]) -> None: - """Apply the allow list on the host, before anything runs in the sandbox. One kosa8 refuses (an entry it can't - parse, a host without egress controls, an org policy that doesn't allow it) is a policy it can't enforce, so a - fallback chain moves on.""" - try: - await self._api.set_egress(sandbox_id, allow) - except Kosa8Error as exc: - if exc.status_code not in (400, 403, 501): - raise - raise NetworkPolicyUnsupportedError(f"kosa8 refused the egress allow list {allow}: {exc}") from exc - async def create_sandbox( self, *, diff --git a/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py index 81fb9f543..47cc40c7b 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py +++ b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py @@ -162,11 +162,6 @@ async def delete_sandbox(self, sandbox_id: str) -> None: raise logger.info("kosa8 sandbox %s was already gone at terminate", sandbox_id) - async def set_egress(self, sandbox_id: str, allow: list[str]) -> None: - """Let the sandbox reach only ``allow``; nothing at all when it is empty.""" - body: dict[str, Any] = {"allow": allow} if allow else {"internet": False} - await self._call("PUT", f"/v1/sandboxes/{sandbox_id}/egress", json=body) - async def enforced_egress(self, sandbox_id: str) -> str: """The policy kosa8 enforces on the sandbox, compiled: ``any``, ``deny``, ``allow:…[;deny:…]`` or ``block:…``. It is the org's default when the sandbox has none of its own.""" diff --git a/tst/unit/providers/sandbox_providers/kosa8_fakes.py b/tst/unit/providers/sandbox_providers/kosa8_fakes.py index 793217c52..f8089d1b5 100644 --- a/tst/unit/providers/sandbox_providers/kosa8_fakes.py +++ b/tst/unit/providers/sandbox_providers/kosa8_fakes.py @@ -53,7 +53,6 @@ def __init__(self) -> None: self.exec_answers: list[ExecAnswer] = [] self.exec_result: Callable[[list[str]], ExecAnswer] = lambda argv: {"exit": 0} self.create_answer: httpx.Response | Exception | None = None - self.egress_answer: httpx.Response | None = None self.org_default = "any" self.boot_polls = 1 @@ -105,6 +104,8 @@ def _create(self, body: dict[str, Any]) -> httpx.Response: sandbox_id = f"sbx_{len(self.created):08d}" self.sandboxes[sandbox_id] = {"id": sandbox_id, "state": "creating", "name": body.get("name"), "template": "base", "polls": 0} + if "egress" in body: + self.egress[sandbox_id] = f"allow:{','.join(body['egress']['allow'])}" if self.create_answer is not None: raise self.create_answer return httpx.Response(202, json={"sandbox": self._view(self.sandboxes[sandbox_id]), "host_ms": 4}) @@ -124,11 +125,6 @@ def _sandbox(self, request: httpx.Request, sandbox: dict[str, Any]) -> httpx.Res return httpx.Response(200, json={"sandbox": self._view(sandbox)}) def _egress(self, request: httpx.Request, sandbox: dict[str, Any]) -> httpx.Response: - if request.method == "PUT": - if self.egress_answer is not None: - return self.egress_answer - body = json.loads(request.content) - self.egress[sandbox["id"]] = f"allow:{','.join(body['allow'])}" if body.get("allow") else "deny" enforced = self.egress.get(sandbox["id"], self.org_default) return httpx.Response(200, json={"egress": {"enforced": enforced}}) diff --git a/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py index 9272ddda5..ae18addbc 100644 --- a/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py +++ b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py @@ -135,7 +135,6 @@ async def test_create_vm_boots_a_docker_sandbox_with_a_lifetime_and_a_public_url 9000: "https://9000-00000001.kosa8labs.com"} assert all(preview["public"] for preview in api.previews["sbx_00000001"].values()) assert sandbox.network_policy == NetworkPolicy() - assert api.requests_to("PUT", "/v1/sandboxes/sbx_00000001/egress") == [] assert api.execs == [] @@ -154,11 +153,12 @@ async def test_create_vm_starts_docker_for_the_gateway(api): @pytest.mark.asyncio -async def test_create_vm_applies_an_allow_list_with_kosa8s_hosts_and_reports_it(api): +async def test_create_vm_creates_the_sandbox_under_an_allow_list_with_kosa8s_hosts_and_reports_it(api): policy = NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",), allow_cidrs=("203.0.113.0/24",)) sandbox = await _provider(api).create_vm(network_policy=policy, setup_for_gateway=False) - [put] = api.requests_to("PUT", "/v1/sandboxes/sbx_00000001/egress") - allow = sandbox_module.json.loads(put.content)["allow"] + [body] = api.created + allow = body["egress"]["allow"] + assert api.requests_to("PUT", "/v1/sandboxes/sbx_00000001/egress") == [] assert allow[0] == "pypi.org" and allow[-1] == "203.0.113.0/24" assert "*.kosa8labs.com" in allow and "*.boxd.sh" in allow assert sandbox.network_policy.restricts_egress @@ -173,14 +173,22 @@ async def test_an_org_default_policy_is_what_the_sandbox_reports(api): assert sandbox.network_policy == NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",)) -@pytest.mark.parametrize("status", [400, 403, 501]) +@pytest.mark.parametrize(("status", "code"), [(400, "invalid_egress"), (403, "egress_not_allowed"), (501, "unsupported")]) @pytest.mark.asyncio -async def test_an_allow_list_kosa8_refuses_deletes_the_sandbox_and_is_unsupported(api, status): - api.egress_answer = error(status, "invalid_egress") +async def test_a_create_kosa8_refuses_for_its_allow_list_is_unsupported(api, status, code): + api.create_answer = error(status, code) with pytest.raises(NetworkPolicyUnsupportedError, match="refused the egress allow list"): await _provider(api).create_vm(network_policy=NetworkPolicy(mode=ALLOWLIST, allow_hosts=("a.com",)), setup_for_gateway=False) - assert api.deleted == ["sbx_00000001"] + assert api.sandboxes == {} and api.deleted == [] + + +@pytest.mark.parametrize("policy", [None, NetworkPolicy(mode=ALLOWLIST, allow_hosts=("a.com",))]) +@pytest.mark.asyncio +async def test_a_create_refused_for_anything_else_is_raised_as_is(api, policy): + api.create_answer = error(403, "quota_exceeded") + with pytest.raises(Kosa8Error, match="quota_exceeded"): + await _provider(api).create_vm(network_policy=policy, setup_for_gateway=False) @pytest.mark.asyncio From 6d1dc942b8cafb295f231a4b877209328ce1e494 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 17:03:59 -0800 Subject: [PATCH 3/3] fix(sandbox): a kosa8 sandbox pushes a file whose host its policy denies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit kosa8 compiles an org's deny list into `block:…`, or `;deny:…` after an allow list, which a NetworkPolicy can't carry; read as allow-all, it let the sandbox try to curl a signed URL kosa8's host blocks, failing the load instead of pushing the bytes over exec. The sandbox now keeps the denied entries beside its policy, from the create and from a reconnect, and downloads only from a host its policy allows and nothing denies. Co-Authored-By: Claude Opus 5.5 --- .../sandbox_providers/kosa8/README.md | 3 +- .../sandbox_providers/kosa8/provider.py | 15 +++---- .../sandbox_providers/kosa8/sandbox.py | 45 +++++++++++++------ .../kosa8_sandbox_provider_test.py | 13 ++++++ .../sandbox_providers/kosa8_sandbox_test.py | 31 ++++++++++++- 5 files changed, 83 insertions(+), 24 deletions(-) diff --git a/src/agent_env/providers/sandbox_providers/kosa8/README.md b/src/agent_env/providers/sandbox_providers/kosa8/README.md index 1c8acd6a4..8b50f0099 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/README.md +++ b/src/agent_env/providers/sandbox_providers/kosa8/README.md @@ -91,7 +91,8 @@ All keys go under `[sandbox.providers.kosa8.config]`. Unknown keys are refused. - **kosa8's own hosts:** `*.kosa8labs.com` is added to every allow list, so a restricted agent can reach the environments it talks to. - **Organization policy:** an organization's default egress policy applies to sandboxes that set none, and the - sandbox's `network_policy` reports what kosa8 enforces. A deny-only policy reads as allow-all. + sandbox's `network_policy` reports what kosa8 enforces. A deny-only policy reads as allow-all; the sandbox keeps + its denies, and a file whose signed URL is on a denied host is pushed over exec rather than downloaded. - **Reconnect:** `get_sandbox` restores the ports and the applied policy from kosa8. ## Cleanup diff --git a/src/agent_env/providers/sandbox_providers/kosa8/provider.py b/src/agent_env/providers/sandbox_providers/kosa8/provider.py index 42089f523..4ff528697 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/provider.py +++ b/src/agent_env/providers/sandbox_providers/kosa8/provider.py @@ -24,7 +24,6 @@ Kosa8Api, Kosa8Error, Kosa8Sandbox, - policy_from_enforced, ) from agent_env.providers.sandbox_providers.sandbox import NetworkPolicy, NetworkPolicyUnsupportedError from agent_env.providers.sandbox_providers.sandbox_provider import SandboxProvider, apply_default_attribution @@ -223,7 +222,7 @@ async def create_vm( sandbox = Kosa8Sandbox(self._api, sandbox_id, tunnel_urls={}, network_policy=effective_policy) try: await self._wait_until_running(created) - sandbox.network_policy = policy_from_enforced(await self._api.enforced_egress(sandbox_id)) + sandbox.enforce(await self._api.enforced_egress(sandbox_id)) sandbox.tunnel_urls = {port: await self._api.open_port(sandbox_id, port) for port in ports} logger.info( "kosa8 sandbox started: id=%s name=%s size=%s disk_gb=%s ttl_s=%s ports=%s attribution=%s", @@ -319,13 +318,11 @@ async def create_sandbox( async def get_sandbox(self, sandbox_id: str) -> Kosa8Sandbox: """Reconnect, restoring the public URLs and the applied egress policy.""" - sandbox = await self._api.get_sandbox(sandbox_id) - return Kosa8Sandbox( - self._api, - sandbox["id"], - tunnel_urls=await self._api.open_ports(sandbox["id"]), - network_policy=policy_from_enforced(await self._api.enforced_egress(sandbox["id"])), - ) + found = await self._api.get_sandbox(sandbox_id) + sandbox = Kosa8Sandbox(self._api, found["id"], tunnel_urls=await self._api.open_ports(found["id"]), + network_policy=None) + sandbox.enforce(await self._api.enforced_egress(found["id"])) + return sandbox async def terminate_sandbox(self, sandbox_id: str) -> None: await self._api.delete_sandbox(sandbox_id) diff --git a/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py index 47cc40c7b..1f3d09b1f 100644 --- a/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py +++ b/src/agent_env/providers/sandbox_providers/kosa8/sandbox.py @@ -240,7 +240,7 @@ def _origin(url: str) -> str: def policy_from_enforced(enforced: str) -> NetworkPolicy: """The egress policy a compiled kosa8 policy applies. ``block:…`` lets everything out but a deny list, which an - allowlist can't express, so it reads as allow-all.""" + allowlist can't express, so it reads as allow-all; ``denied_entries`` keeps the denies.""" if enforced == "deny": return NetworkPolicy(mode=NetworkMode.ALLOWLIST) if enforced.startswith("allow:"): @@ -253,13 +253,28 @@ def policy_from_enforced(enforced: str) -> NetworkPolicy: return NetworkPolicy() +def denied_entries(enforced: str) -> tuple[str, ...]: + """What a compiled kosa8 policy denies: a ``block:…`` list, or the ``;deny:…`` after an allow list. A + ``NetworkPolicy`` can't carry either, so the sandbox keeps them beside it.""" + if enforced.startswith("block:"): + listed = enforced.removeprefix("block:") + elif ";deny:" in enforced: + listed = enforced.split(";deny:", 1)[1] + else: + return () + return tuple(entry for entry in listed.split(",") if entry) + + def allows_host(policy: NetworkPolicy, host: str) -> bool: - """Whether ``policy`` lets the sandbox reach ``host`` by kosa8's rules: an exact name, a ``*.domain`` entry, which - covers every name under ``domain`` but not ``domain`` itself, or an address in a listed address or range.""" - if not policy.restricts_egress: - return True + """Whether ``policy`` lets the sandbox reach ``host`` by kosa8's rules.""" + return not policy.restricts_egress or matches_host((*policy.allow_hosts, *policy.allow_cidrs), host) + + +def matches_host(entries: tuple[str, ...], host: str) -> bool: + """Whether a kosa8 entry names ``host``: an exact name, a ``*.domain`` entry, which covers every name under + ``domain`` but not ``domain`` itself, or an address in a listed address or range.""" host = host.lower().rstrip(".") - for entry in policy.allow_hosts: + for entry in entries: entry = entry.lower().rstrip(".") if entry == host or (entry.startswith("*.") and host.endswith(entry[1:])): return True @@ -267,11 +282,7 @@ def allows_host(policy: NetworkPolicy, host: str) -> bool: address = ipaddress.ip_address(host) except ValueError: return False - return any( - address in ipaddress.ip_network(entry, strict=False) - for entry in (*policy.allow_cidrs, *policy.allow_hosts) - if _is_address(entry) - ) + return any(address in ipaddress.ip_network(entry, strict=False) for entry in entries if _is_address(entry)) def _is_address(entry: str) -> bool: @@ -323,8 +334,14 @@ def __init__( self.vnc_url = None self.tunnel_urls = tunnel_urls self.network_policy = network_policy + self.denied_hosts: tuple[str, ...] = () self._staging_ready = False + def enforce(self, enforced: str) -> None: + """Take the policy kosa8 enforces, compiled: what it allows as ``network_policy``, and what it denies.""" + self.network_policy = policy_from_enforced(enforced) + self.denied_hosts = denied_entries(enforced) + async def terminate(self) -> None: await self._api.delete_sandbox(self.sandbox_id) @@ -383,11 +400,13 @@ async def setup_vm_for_gateway(self, exposed_ports: list[int] | None = None) -> await self.wait_for_vm() def _can_download(self, url: str | None) -> bool: - """Whether the sandbox can fetch ``url`` itself; an unknown policy counts as no.""" + """Whether the sandbox can fetch ``url`` itself: its policy allows the host and nothing denies it. An unknown + policy counts as no.""" if url is None or self.network_policy is None: return False host = urlparse(url).hostname - return host is not None and allows_host(self.network_policy, host) + return (host is not None and allows_host(self.network_policy, host) + and not matches_host(self.denied_hosts, host)) async def _download_object_to_vm(self, object_url: str, vm_path: str) -> None: """Curl a signed URL the policy admits; push anything else over exec, which needs no egress.""" diff --git a/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py index ae18addbc..9807090c1 100644 --- a/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py +++ b/tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py @@ -171,6 +171,19 @@ async def test_an_org_default_policy_is_what_the_sandbox_reports(api): api.org_default = "allow:pypi.org;deny:gist.github.com" sandbox = await _provider(api).create_vm(setup_for_gateway=False) assert sandbox.network_policy == NetworkPolicy(mode=ALLOWLIST, allow_hosts=("pypi.org",)) + assert sandbox.denied_hosts == ("gist.github.com",) + + +@pytest.mark.asyncio +async def test_an_org_deny_list_survives_a_reconnect(api): + api.org_default = "block:*.amazonaws.com" + provider = _provider(api) + created = await provider.create_vm(setup_for_gateway=False) + reconnected = await _provider(api).get_sandbox(created.sandbox_id) + for sandbox in (created, reconnected): + assert sandbox.network_policy == NetworkPolicy() + assert sandbox.denied_hosts == ("*.amazonaws.com",) + assert not sandbox._can_download("https://bucket.s3.amazonaws.com/x?sig=1") @pytest.mark.parametrize(("status", "code"), [(400, "invalid_egress"), (403, "egress_not_allowed"), (501, "unsupported")]) diff --git a/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py b/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py index 4bf3ee5f9..b6e28c24f 100644 --- a/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py +++ b/tst/unit/providers/sandbox_providers/kosa8_sandbox_test.py @@ -6,7 +6,13 @@ import pytest from agent_env.providers.sandbox_providers.kosa8 import sandbox as sandbox_module -from agent_env.providers.sandbox_providers.kosa8.sandbox import Kosa8Api, Kosa8Error, Kosa8Sandbox, allows_host +from agent_env.providers.sandbox_providers.kosa8.sandbox import ( + Kosa8Api, + Kosa8Error, + Kosa8Sandbox, + allows_host, + denied_entries, +) from agent_env.providers.sandbox_providers.sandbox import NetworkMode, NetworkPolicy from tst.unit.providers.sandbox_providers.kosa8_fakes import API_KEY, FakeKosa8, command_of, error, frames @@ -142,3 +148,26 @@ def test_allows_host_follows_kosa8s_matching(policy, host, allowed): ]) def test_the_sandbox_downloads_only_what_its_policy_admits(api, policy, url, fetches): assert _sandbox(api, policy)._can_download(url) is fetches + + +@pytest.mark.parametrize(("enforced", "denied"), [ + ("any", ()), + ("deny", ()), + ("allow:pypi.org", ()), + ("allow:*.amazonaws.com;deny:secret.s3.amazonaws.com,10.0.0.0/8", ("secret.s3.amazonaws.com", "10.0.0.0/8")), + ("block:*.amazonaws.com", ("*.amazonaws.com",)), +]) +def test_denied_entries_are_what_a_compiled_policy_denies(enforced, denied): + assert denied_entries(enforced) == denied + + +@pytest.mark.parametrize(("enforced", "url", "fetches"), [ + ("block:*.amazonaws.com", "https://bucket.s3.amazonaws.com/x?sig=1", False), + ("block:gist.github.com", "https://bucket.s3.amazonaws.com/x?sig=1", True), + ("allow:*.amazonaws.com;deny:bucket.s3.amazonaws.com", "https://bucket.s3.amazonaws.com/x", False), + ("allow:*.amazonaws.com;deny:other.s3.amazonaws.com", "https://bucket.s3.amazonaws.com/x", True), +]) +def test_a_host_the_enforced_policy_denies_is_pushed_rather_than_downloaded(api, enforced, url, fetches): + sandbox = _sandbox(api) + sandbox.enforce(enforced) + assert sandbox._can_download(url) is fetches