control-tower 6.0.0__py3-none-any.whl

control_tower/sandbox/docker.py

@@ -0,0 +1,685 @@
+"""Compose rewriting that shapes a Control Tower sample for Inspect's Docker sandbox."""
+
+import hashlib
+import json
+import logging
+import os
+import re
+import subprocess
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import yaml
+from inspect_ai.util import SandboxEnvironmentSpec, is_dockerfile
+
+from control_tower.environments.internet_simulator.constants import (
+    INTERNET_SIMULATOR_PROXY_SERVICE_NAME,
+    INTERNET_SIMULATOR_SERVICE_NAME,
+)
+from control_tower.environments.internet_simulator.runtimes.docker import (
+    EXPOSED_SERVICES_VOLUME,
+    SIMULATOR_EGRESS_NETWORK,
+    exposed_services_proxy_service,
+    simulator_service,
+)
+from control_tower.utils.env import EnvVar
+from control_tower.utils.paths import cache_dir, find_repo_root
+from control_tower.utils.versioning import (
+    REPO_DIGEST_FORMAT,
+    expand_compose_vars,
+)
+from ct_setting_sdk.env.constants import AGENT_DIR
+from ct_setting_sdk.env.internet_simulator.config import InternetSimulatorConfig
+from ct_setting_sdk.errors import StateError, ValidationError
+
+if TYPE_CHECKING:
+    from control_tower.environments.remote.process import EnvProcess
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+def compose_file(spec: SandboxEnvironmentSpec) -> Path | None:
+    """The compose file a ``docker`` spec names, or None for a Dockerfile or any other sandbox.
+
+    Raises:
+        ValidationError: The compose path is relative, so it would resolve against Control Tower's cwd.
+    """
+    config = spec.config
+    if spec.type != "docker" or not isinstance(config, str) or is_dockerfile(config):
+        return None
+    if not Path(config).is_absolute():
+        raise ValidationError(
+            f"The docker sandbox's compose path {config!r} must be absolute"
+        )
+    return Path(config)
+
+
+def uses_published_images() -> bool:
+    """Whether ``CONTROL_TOWER_IMAGES`` is ``pull`` or ``offline``: run the
+    published env images by tag instead of building them locally (the fleet sets
+    ``pull`` on every worker)."""
+    return EnvVar().images != "build"
+
+
+def _relative_path(value: object) -> bool:
+    return (
+        isinstance(value, str)
+        and not Path(value).is_absolute()
+        and not value.startswith(("$", "~", "git@"))
+        and "://" not in value
+    )
+
+
+def absolutize_compose_paths(compose_data: dict[str, Any], base_dir: Path) -> None:
+    """Rewrite the relative host paths compose resolves against its file's directory to absolute ones."""
+
+    def absolute(value: str) -> str:
+        return str((base_dir / value).resolve())
+
+    for service in (compose_data.get("services") or {}).values():
+        if not isinstance(service, dict):
+            continue
+        build = service.get("build")
+        if _relative_path(build):
+            service["build"] = absolute(build)
+        elif isinstance(build, dict):
+            if _relative_path(build.get("context")):
+                build["context"] = absolute(build["context"])
+            contexts = build.get("additional_contexts")
+            for name, context in (
+                contexts if isinstance(contexts, dict) else {}
+            ).items():
+                if _relative_path(context) and not context.startswith("service:"):
+                    contexts[name] = absolute(context)
+        volumes = service.get("volumes")
+        for index, volume in enumerate(volumes if isinstance(volumes, list) else []):
+            # Short-syntax sources are host paths only when they start with "."; bare names are named volumes.
+            if isinstance(volume, str) and volume.startswith("."):
+                source, _, rest = volume.partition(":")
+                volumes[index] = (
+                    f"{absolute(source)}:{rest}" if rest else absolute(source)
+                )
+            elif (
+                isinstance(volume, dict)
+                and volume.get("type") == "bind"
+                and _relative_path(volume.get("source"))
+            ):
+                volume["source"] = absolute(volume["source"])
+        env_files = service.get("env_file")
+        if _relative_path(env_files):
+            service["env_file"] = absolute(env_files)
+        for index, entry in enumerate(env_files if isinstance(env_files, list) else []):
+            if _relative_path(entry):
+                env_files[index] = absolute(entry)
+            elif isinstance(entry, dict) and _relative_path(entry.get("path")):
+                entry["path"] = absolute(entry["path"])
+        extends = service.get("extends")
+        if isinstance(extends, dict) and _relative_path(extends.get("file")):
+            extends["file"] = absolute(extends["file"])
+    for section in ("configs", "secrets"):
+        for entry in (compose_data.get(section) or {}).values():
+            if isinstance(entry, dict) and _relative_path(entry.get("file")):
+                entry["file"] = absolute(entry["file"])
+
+
+_temp_compose_sources: dict[Path, Path] = {}
+
+
+def compose_source_dir(compose_path: Path) -> Path:
+    """The env directory a compose came from, following written temp composes back to their source."""
+    return _temp_compose_sources.get(compose_path, compose_path.parent)
+
+
+def compose_cache_dir() -> Path:
+    """This checkout's directory for generated composes, so live orphan cleanup can tell its own apart."""
+    return cache_dir(
+        "compose", hashlib.md5(str(find_repo_root()).encode()).hexdigest()[:8]
+    )
+
+
+def write_temp_compose(
+    compose_path: Path, tag: str, compose_data: dict[str, Any]
+) -> Path:
+    """Write a transformed compose into CT's cache, named by tag and source-path hash, with host paths
+    made absolute; replaced atomically since concurrent evals on one host share it."""
+    source_dir = compose_source_dir(compose_path)
+    absolutize_compose_paths(compose_data, source_dir)
+    path_hash = hashlib.md5(str(compose_path).encode()).hexdigest()[:8]
+    temp_path = env_compose_cache_dir(source_dir) / f"compose-{tag}-{path_hash}.yml"
+    fd, staged = tempfile.mkstemp(prefix=f"{temp_path.name}.", dir=temp_path.parent)
+    with os.fdopen(fd, "w") as f:
+        yaml.dump(compose_data, f, default_flow_style=False)
+    os.replace(staged, temp_path)
+    _temp_compose_sources[temp_path] = source_dir
+    return temp_path
+
+
+def env_compose_cache_dir(source_dir: Path) -> Path:
+    """The cache folder for one env's generated composes."""
+    env_dir = (
+        compose_cache_dir() / hashlib.md5(str(source_dir).encode()).hexdigest()[:8]
+    )
+    env_dir.mkdir(exist_ok=True)
+    return env_dir
+
+
+_MANIFEST_DIGEST_FORMAT = "{{json .Manifest.Digest}}"
+_image_digests: dict[str, str | None] = {}
+_image_digest_errors: dict[str, str] = {}
+
+
+def resolve_image_digest(image_ref: str, timeout: int = 120) -> str | None:
+    """Return ``repo@sha256:...`` for a ``repo:tag`` reference, or ``None`` when
+    the image has no registry digest (local-only) or buildx is unavailable.
+    Under ``CONTROL_TOWER_IMAGES=offline`` a local image without a registry
+    digest resolves to ``image_ref`` itself.
+
+    Resolved once per reference per process; subsequent samples reuse the cache.
+
+    Args:
+        image_ref: The ``repo:tag`` reference to resolve.
+        timeout: Seconds to wait for the registry before giving up.
+
+    Raises:
+        StateError: ``CONTROL_TOWER_IMAGES`` is ``offline`` and the image is
+            not in the local Docker image store.
+    """
+    if "@sha256:" in image_ref:
+        return image_ref
+    if image_ref in _image_digests:
+        return _image_digests[image_ref]
+    if EnvVar().images == "offline":
+        inspected = subprocess.run(
+            ["docker", "image", "inspect", "--format", REPO_DIGEST_FORMAT, image_ref],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if inspected.returncode != 0:
+            raise StateError(
+                f"Image {image_ref} is not in the local Docker image store and "
+                "CONTROL_TOWER_IMAGES is offline; run `ct settings pull-images` with internet first."
+            )
+        local = inspected.stdout.strip()
+        _image_digests[image_ref] = local if "@sha256:" in local else image_ref
+        return _image_digests[image_ref]
+
+    name, _, tag = image_ref.rpartition(":")
+    if not name or "/" in tag:
+        _image_digests[image_ref] = None
+        return None
+
+    digest: str | None = None
+    error: list[str] = []
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "buildx",
+                "imagetools",
+                "inspect",
+                image_ref,
+                "--format",
+                _MANIFEST_DIGEST_FORMAT,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode == 0:
+            sha = result.stdout.strip().strip('"')
+            if sha.startswith("sha256:"):
+                digest = f"{name}@{sha}"
+            else:
+                error = [f"inspect returned no manifest digest: {sha!r}"]
+        else:
+            error = result.stderr.strip().splitlines()
+    except (OSError, subprocess.SubprocessError) as exc:
+        digest = None
+        error = [str(exc)]
+
+    if digest is None:
+        _image_digest_errors[image_ref] = error[-1] if error else "no registry digest"
+        logger.warning(
+            "Could not resolve a registry digest for %s; leaving the tag in place%s",
+            image_ref,
+            f" ({error[-1]})" if error else "",
+        )
+    _image_digests[image_ref] = digest
+    return digest
+
+
+def strip_build_sections(compose_path: Path, image_tag: str | None) -> Path:
+    """Remove 'build' sections and pin mutable image tags to digests.
+
+    Returns the path to the transformed compose. Each service ``image`` is
+    resolved to ``repo@sha256:...`` so per-sample cache reuse cannot serve a
+    stale ``latest``; images already digest-pinned or without a registry digest
+    keep their original reference. ``ENV_IMAGE_TAG_<ENV>`` reads ``image_tag``.
+
+    Services that build a single-segment image name (no registry or namespace,
+    e.g. BashArena's per-task ``bash-arena-default-<task_id>:latest``) keep
+    their ``build`` section: such names can only come from a local build —
+    ``docker.io/library/*`` is reserved for official images — so stripping the
+    build would leave an unpullable reference.
+    """
+    compose_data = yaml.safe_load(compose_path.read_text())
+
+    for service_config in (compose_data.get("services") or {}).values():
+        if not isinstance(service_config, dict):
+            continue
+        had_build_section = "build" in service_config
+        image = service_config.get("image")
+        if had_build_section and isinstance(image, str) and "/" not in image:
+            continue
+        service_config.pop("build", None)
+        if not isinstance(image, str):
+            continue
+        if had_build_section:
+            service_config["pull_policy"] = "missing"
+        tag_keys = re.findall(r"\$\{(ENV_IMAGE_TAG_\w+)", image)
+        image_ref = expand_compose_vars(
+            image, dict.fromkeys(tag_keys, image_tag) if image_tag else None
+        )
+        pinned = resolve_image_digest(image_ref)
+        if pinned is None and tag_keys and image_tag:
+            raise StateError(
+                f"Could not resolve the env image {image_ref}: "
+                f"{_image_digest_errors.get(image_ref, 'no registry digest')}. Set "
+                f"CONTROL_TOWER_IMAGES=build to build locally, or set {tag_keys[0]} to a published tag."
+            )
+        service_config["image"] = pinned or image_ref
+
+    return write_temp_compose(compose_path, "nobuild", compose_data)
+
+
+# `$$` escapes; `${NAME}` and `${NAME:?err}` require a value, the default and alternate forms don't.
+_HOST_READ = re.compile(r"\$\$|\$\{([A-Za-z_]\w*)(:?[-?+])?|\$([A-Za-z_]\w*)")
+_NESTED_READ = re.compile(r"\$\{[A-Za-z_]\w*:?[-?+](?:\$\$|[^}$])*\$(?:\{|[A-Za-z_])")
+# Compose fills COMPOSE_PROJECT_NAME itself; which image to pull is CT's choice, from its environment.
+_NOT_SETTING_READ = re.compile(r"COMPOSE_PROJECT_NAME|ENV_IMAGE_(?:TAG|REPO)_\w+")
+
+
+def compose_reads(
+    compose_path: Path, values: Mapping[str, str], values_file: Path
+) -> set[str]:
+    """Every setting variable the compose file reads from the host: a ``$NAME`` or ``${NAME...}``
+    anywhere, or a bare ``environment`` entry.
+
+    Raises:
+        ValidationError: The file reads a ``CT_*`` variable, which Control Tower reserves, or
+            nests a read in another's default.
+        StateError: A required variable has no value in ``values``, read from ``values_file``, or
+            the env still keeps a ``.env`` beside its compose file.
+    """
+    source = compose_source_dir(compose_path)
+    if (stale := source / ".env").is_file():
+        raise StateError(
+            f"{stale} is no longer read: move its values to {values_file}."
+        )
+    names: set[str] = set()
+    required: set[str] = set()
+
+    def scan(node: Any) -> None:
+        if isinstance(node, str):
+            if _NESTED_READ.search(node):
+                raise ValidationError(
+                    f"The compose file in {source} nests a variable in another's default "
+                    f"({node!r}), which Control Tower does not read."
+                )
+            for match in _HOST_READ.finditer(node):
+                if name := match[1] or match[3]:
+                    names.add(name)
+                    if match[2] is None or "?" in match[2]:
+                        required.add(name)
+        elif isinstance(node, list):
+            for item in node:
+                scan(item)
+        elif isinstance(node, dict):
+            for item in node.values():
+                scan(item)
+
+    compose_data = yaml.safe_load(compose_path.read_text())
+    for service in (compose_data.get("services") or {}).values():
+        environment = (service or {}).get("environment") or {}
+        bare = (
+            {entry for entry in environment if "=" not in entry}
+            if isinstance(environment, list)
+            else {key for key, value in environment.items() if value is None}
+        )
+        names |= bare
+        required |= bare
+    scan(compose_data)
+    names = {name for name in names if not _NOT_SETTING_READ.fullmatch(name)}
+    if reserved := sorted(name for name in names if name.startswith("CT_")):
+        raise ValidationError(
+            f"The compose file in {source} reads {', '.join(reserved)}; Control Tower reserves "
+            "CT_* variables."
+        )
+    if missing := sorted((names & required) - values.keys()):
+        raise StateError(
+            f"No value for {', '.join(missing)}, which the compose file in {source} requires: "
+            f"put each in {values_file}."
+        )
+    return names
+
+
+_compose_env_tokens: dict[tuple[tuple[str, str], ...], str] = {}
+
+
+def patch_compose_for_env_values(
+    compose_path: Path, values: Mapping[str, str], values_file: Path
+) -> Path:
+    """Give every setting variable the compose file reads the value in ``values``,
+    through a ``CT_ENV_<token>_NAME`` copy in this process's environment, so no value is written
+    to disk and the host's own variables never reach the file.
+
+    Raises:
+        ValidationError: See ``compose_reads``.
+        StateError: See ``compose_reads``.
+    """
+    compose_data = yaml.safe_load(compose_path.read_text())
+    names = compose_reads(compose_path, values, values_file)
+    if not names:
+        return compose_path
+    values = {name: values[name] for name in names if name in values}
+    token = _compose_env_tokens.setdefault(
+        tuple(sorted(values.items())), str(len(_compose_env_tokens))
+    )
+    for name, value in values.items():
+        os.environ[f"CT_ENV_{token}_{name}"] = value
+
+    def point(match: re.Match[str]) -> str:
+        name = match[1] or match[3]
+        if name not in names:
+            return match[0]
+        return match[0].replace(name, f"CT_ENV_{token}_{name}", 1)
+
+    def rewrite(node: Any) -> Any:
+        if isinstance(node, str):
+            return _HOST_READ.sub(point, node)
+        if isinstance(node, list):
+            return [rewrite(item) for item in node]
+        if isinstance(node, dict):
+            return {key: rewrite(item) for key, item in node.items()}
+        return node
+
+    for service in compose_data["services"].values():
+        environment = (service or {}).get("environment")
+        if isinstance(environment, list):
+            environment = {
+                name: value if sep else None
+                for name, sep, value in (entry.partition("=") for entry in environment)
+            }
+        if environment:
+            service["environment"] = {
+                key: "${" + key + "}" if value is None and key in names else value
+                for key, value in environment.items()
+            }
+    return write_temp_compose(compose_path, f"env-{token}", rewrite(compose_data))
+
+
+def patch_compose_for_no_internet(compose_path: Path) -> Path:
+    """Make every project network internal with an isolated gateway.
+
+    Docker enforces this from the host, so root in the container cannot undo it.
+    The sample's internet simulator keeps a bridge of its own and is the only path out.
+    """
+    compose_data = yaml.safe_load(compose_path.read_text())
+    if "include" in compose_data:
+        raise ValueError(
+            f"Compose file {compose_path} uses include:, which merges after this "
+            "scan; --no-internet cannot isolate what it cannot see."
+        )
+    services: dict[str, dict[str, Any] | None] = compose_data.get("services") or {}
+    networks: dict[str, dict[str, Any] | None] = compose_data.get("networks") or {}
+
+    for service_name, service in services.items():
+        service = service or {}
+        if "extends" in service:
+            raise ValueError(
+                f"Compose file {compose_path}: service {service_name!r} uses extends:, "
+                "which merges after this scan; --no-internet cannot isolate what it "
+                "cannot see."
+            )
+        mode = service.get("network_mode")
+        if mode is not None and not (
+            isinstance(mode, str) and (mode == "none" or mode.startswith("service:"))
+        ):
+            raise ValueError(
+                f"Compose file {compose_path}: service {service_name!r} uses "
+                f"network_mode: {mode}, which --no-internet cannot isolate."
+            )
+    for network_name, network in networks.items():
+        network = network or {}
+        if network.get("external") or network.get("name"):
+            raise ValueError(
+                f"Compose file {compose_path}: network {network_name!r} is external "
+                "or has a fixed name; --no-internet can only isolate networks the "
+                "project owns."
+            )
+        if network.get("driver", "bridge") != "bridge":
+            raise ValueError(
+                f"Compose file {compose_path}: network {network_name!r} uses the "
+                f"{network['driver']} driver; --no-internet isolates bridge networks only."
+            )
+
+    for service in services.values():
+        service = service or {}
+        if "network_mode" in service:
+            continue
+        if "default" in (service.get("networks") or ["default"]):
+            networks.setdefault("default", None)
+    if not networks:
+        return compose_path
+    # gateway_mode isolated also closes the host's own address on the bridge.
+    compose_data["networks"] = {
+        name: {
+            **(network or {}),
+            "internal": True,
+            "driver_opts": {
+                **((network or {}).get("driver_opts") or {}),
+                "com.docker.network.bridge.gateway_mode_ipv4": "isolated",
+                "com.docker.network.bridge.gateway_mode_ipv6": "isolated",
+            },
+        }
+        for name, network in networks.items()
+    }
+
+    return write_temp_compose(compose_path, "no-internet", compose_data)
+
+
+def patch_compose_for_internet_simulator(
+    compose_path: Path,
+    internet_simulator: InternetSimulatorConfig,
+    *,
+    allow_internet: bool,
+) -> Path:
+    """Add the sample's internet simulator, aliased to its personas, and an nginx service for its
+    exposed services on the networks the simulator and their targets join. Without internet access
+    the simulator joins every project network and keeps a bridge of its own to reach upstream APIs.
+
+    Raises:
+        ValidationError: An exposed service targets a host that is not a service of the compose file,
+            or seed assets are declared without a ``default`` service to take them from.
+    """
+    compose_data = yaml.safe_load(compose_path.read_text())
+    services: dict[str, Any] = compose_data["services"]
+    if internet_simulator.seed_assets_from and "default" not in services:
+        raise ValidationError(
+            f"seed_assets_from is taken from the default service, which {compose_path} does not declare."
+        )
+    aliases = sorted(internet_simulator.personas)
+    if allow_internet:
+        joined: dict[str, Any] = {internet_simulator.network: {"aliases": aliases}}
+    else:
+        joined = {
+            name: {"aliases": aliases} for name in compose_data.get("networks") or {}
+        }
+        joined[SIMULATOR_EGRESS_NETWORK] = {}
+        compose_data.setdefault("networks", {})[SIMULATOR_EGRESS_NETWORK] = None
+    added: dict[str, Any] = {}
+    if internet_simulator.exposed_services:
+        targets = {
+            target.split(":", 1)[0]
+            for target in internet_simulator.exposed_services.values()
+        }
+        if missing := {
+            domain: target
+            for domain, target in internet_simulator.exposed_services.items()
+            if target.split(":", 1)[0] not in services
+        }:
+            raise ValidationError(
+                f"exposed_services maps {missing} to services that {compose_path} does not declare."
+            )
+        proxy_networks = (set(joined) - {SIMULATOR_EGRESS_NETWORK}).union(
+            *(services[target].get("networks") or ["default"] for target in targets)
+        )
+        added[INTERNET_SIMULATOR_PROXY_SERVICE_NAME] = exposed_services_proxy_service(
+            internet_simulator.exposed_services, sorted(proxy_networks)
+        )
+        compose_data["volumes"] = {
+            **(compose_data.get("volumes") or {}),
+            EXPOSED_SERVICES_VOLUME: None,
+        }
+    added[INTERNET_SIMULATOR_SERVICE_NAME] = {
+        **simulator_service(internet_simulator, services),
+        "networks": joined,
+    }
+    services.update(added)
+    digest = hashlib.sha256(json.dumps(added, sort_keys=True).encode()).hexdigest()
+    return write_temp_compose(
+        compose_path, f"internet-simulator-{digest[:8]}", compose_data
+    )
+
+
+def _image_exists_locally(image: str) -> bool:
+    """Check whether a Docker image exists locally."""
+    result = subprocess.run(
+        ["docker", "image", "inspect", image],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+def _pre_populate_mount(image: str, mount_dir: Path, compose_path: Path) -> None:
+    """Copy the image's AGENT_DIR contents into the host mount directory, for WSL.
+
+    Starts no container; an image missing locally is built with ``docker compose build``.
+    """
+    mount_path = Path(mount_dir).resolve()
+    mount_path.mkdir(parents=True, exist_ok=True)
+    if any(mount_path.iterdir()):
+        return
+
+    resolved_image = expand_compose_vars(image)
+
+    if not _image_exists_locally(resolved_image):
+        print(
+            f"Image {resolved_image} not found locally, building...",
+        )
+        subprocess.run(
+            [
+                "docker",
+                "compose",
+                "-f",
+                str(Path(compose_path).resolve()),
+                "build",
+                "default",
+            ],
+            check=True,
+        )
+
+    print(f"Pre-populating mount from image {resolved_image}...")
+    container_id = subprocess.run(
+        ["docker", "create", resolved_image],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+
+    try:
+        subprocess.run(
+            ["docker", "cp", f"{container_id}:{AGENT_DIR}/.", str(mount_path)],
+            check=True,
+        )
+    finally:
+        subprocess.run(["docker", "rm", container_id], capture_output=True)
+
+    print(f"Pre-populated {mount_path} from {image}")
+
+
+def patch_compose_for_mount(compose_path: Path, mount_dir: Path) -> Path:
+    """Bind ``mount_dir`` writable at ``AGENT_DIR`` in the ``default`` service, filled from its image first when
+    empty, and opt the compose out of Inspect's writable host mount check."""
+    compose_data = yaml.safe_load(compose_path.read_text())
+    service = (compose_data.get("services") or {}).get("default")
+    if service is None:
+        raise ValidationError(
+            f"Compose file {compose_path} has no 'default' service to mount into"
+        )
+    if image := service.get("image"):
+        _pre_populate_mount(image, mount_dir, compose_path)
+    mount_spec = f"{mount_dir.resolve()}:{AGENT_DIR}"
+    volumes = service.get("volumes") or []
+    if mount_spec not in volumes:
+        volumes.append(mount_spec)
+    service["volumes"] = volumes
+    sandbox_settings = compose_data.get("x-inspect_docker_sandbox") or {}
+    sandbox_settings["unsafe_allow_writable_host_mounts"] = True
+    compose_data["x-inspect_docker_sandbox"] = sandbox_settings
+    tag = f"mount-{hashlib.md5(mount_spec.encode()).hexdigest()[:8]}"
+    return write_temp_compose(compose_path, tag, compose_data)
+
+
+def sample_sandbox_spec(
+    spec: SandboxEnvironmentSpec,
+    *,
+    allow_internet: bool = False,
+    internet_simulator: InternetSimulatorConfig | None = None,
+    mount_dir: Path | None = None,
+    values_from: "EnvProcess | None" = None,
+    image_tag: str | None = None,
+) -> SandboxEnvironmentSpec:
+    """The sandbox a sample starts: a Docker compose spec rewritten for the network policy, the
+    sample's internet simulator, the setting values of ``values_from`` and a mount, and any other sandbox's
+    spec unchanged.
+
+    Raises:
+        ValidationError: A flag asks for a compose rewrite that ``spec`` has no compose file for.
+        StateError: See ``compose_reads``.
+    """
+    current = compose_file(spec)
+    if current is None:
+        unenforceable = [
+            flag
+            for flag, requested in (
+                ("--no-internet", not allow_internet),
+                ("--mount-dir", mount_dir is not None),
+            )
+            if requested
+        ]
+        if unenforceable:
+            raise ValidationError(
+                f"{' and '.join(unenforceable)} {'needs' if len(unenforceable) == 1 else 'need'} "
+                f"a Docker compose file to rewrite, and the {spec.type!r} sandbox has none. "
+                "Pass --internet to accept that sandbox's own network policy."
+            )
+        return spec
+    if uses_published_images():
+        current = strip_build_sections(current, image_tag)
+    if not allow_internet:
+        current = patch_compose_for_no_internet(current)
+    if internet_simulator is not None:
+        current = patch_compose_for_internet_simulator(
+            current, internet_simulator, allow_internet=allow_internet
+        )
+    if values_from is not None:
+        current = patch_compose_for_env_values(
+            current, values_from.values, values_from.values_file
+        )
+    if mount_dir is not None:
+        current = patch_compose_for_mount(current, mount_dir)
+    return SandboxEnvironmentSpec(type=spec.type, config=str(current))