Skip to content

Commit f162205

Browse files
fix(sandbox): bootstrap Docker workspace before removal binding (#5210)
* fix(sandbox): bootstrap Docker workspace before removal binding * test(sandbox): isolate Docker removal client lifecycle coverage * fix(sandbox): preserve Docker workspace user ownership * fix(sandbox): check removal eligibility before workspace bootstrap
1 parent 71306bf commit f162205

4 files changed

Lines changed: 312 additions & 4 deletions

File tree

‎src/agents/sandbox/sandboxes/docker.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1639,7 +1639,9 @@ async def create(
16391639
assert container_id is not None
16401640
service = self._removal_service
16411641
if service is not None:
1642-
await run_blocking_workspace_io(lambda: service.bind_new(container, manifest))
1642+
await run_blocking_workspace_io(
1643+
lambda: service._bind_new(container, manifest, bootstrap_workspace=True)
1644+
)
16431645
snapshot_id = str(session_id)
16441646
snapshot_instance = resolve_snapshot(snapshot, snapshot_id)
16451647
state = DockerSandboxSessionState(
@@ -1816,7 +1818,9 @@ async def resume(
18161818
if service is not None:
18171819
container.start()
18181820
await run_blocking_workspace_io(
1819-
lambda: service.bind_new(container, state.manifest)
1821+
lambda: service._bind_new(
1822+
container, state.manifest, bootstrap_workspace=True
1823+
)
18201824
)
18211825

18221826
inner = DockerSandboxSession(

‎src/agents/sandbox/sandboxes/docker_removal.py‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,13 @@
99
existing recursive removal and snapshot restoration behavior.
1010
1111
The service requires a trusted image, Docker 26+ with its builtin seccomp profile,
12-
and the runc runtime. Workspaces and path-only grant roots must exist in the image.
12+
and the runc runtime. For new client sessions, the service checks container eligibility,
13+
then creates a missing workspace and its parents using the trusted image's default
14+
user before binding, as normal session startup does.
15+
Path-only grant roots must exist at binding time;
16+
the client does not create unrelated grant directories.
1317
Read-only host bind mounts are supported outside the private workspace. Writable
14-
shared mounts, additional capabilities, user namespaces, and missing roots are excluded.
18+
shared mounts, additional capabilities, user namespaces, and missing grant roots are excluded.
1519
The application must exclusively own container lifecycle and Docker API access;
1620
other host administrators are trusted. A service/worker transport failure leaves
1721
the container paused. Before manually resuming it, stop all service workers.
@@ -269,6 +273,11 @@ def _paused(
269273

270274
def bind_new(self, container: Container, manifest: Manifest) -> None:
271275
"""Bind before a newly created session is returned to its trusted application."""
276+
self._bind_new(container, manifest, bootstrap_workspace=False)
277+
278+
def _bind_new(
279+
self, container: Container, manifest: Manifest, *, bootstrap_workspace: bool
280+
) -> None:
272281
with self._lock:
273282
if self._closed:
274283
raise ValueError("Docker removal service is closed")
@@ -287,6 +296,21 @@ def bind_new(self, container: Container, manifest: Manifest) -> None:
287296

288297
_validate_docker_path_grants(manifest)
289298
_assert_existing_container_path_grants_match(container, manifest)
299+
if bootstrap_workspace:
300+
# Reject unsupported mounts and security settings before an image
301+
# symlink could redirect mkdir into a shared host directory.
302+
self._state(container)
303+
# Only the client requests bootstrap, for fresh containers before
304+
# application workloads run. Preserve the image's default user.
305+
result = container.exec_run(
306+
cmd=["mkdir", "-p", "--", manifest.root],
307+
user="",
308+
workdir="/",
309+
stdout=False,
310+
stderr=False,
311+
)
312+
if result.exit_code != 0:
313+
raise RuntimeError("Unable to create Docker workspace before removal binding")
290314
worker: _Worker | None = None
291315
with self._paused(
292316
container, lambda: worker is not None and worker.uncertain

‎tests/sandbox/_docker_removal_helpers.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,9 @@ def service(
7979
limits.update(getattr(request, "param", {}))
8080
instance = DockerRemovalService(**limits)
8181
container = RecordingContainer()
82+
monkeypatch.setattr(
83+
container, "exec_run", Mock(return_value=SimpleNamespace(exit_code=0)), raising=False
84+
)
8285
worker = RecordingWorker(container)
8386
monkeypatch.setattr(instance, "_state", lambda _: (123, "incarnation"))
8487
monkeypatch.setattr(docker_removal, "_Worker", lambda _: worker)
Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
"""Docker client lifecycle tests with simulated transport and real filesystem binding."""
2+
3+
from __future__ import annotations
4+
5+
import os
6+
from collections.abc import Iterator
7+
from contextlib import ExitStack
8+
from pathlib import Path
9+
from types import SimpleNamespace
10+
from typing import Any
11+
from unittest.mock import Mock
12+
13+
import pytest
14+
15+
from agents.sandbox import Manifest, SandboxPathGrant
16+
from agents.sandbox.errors import WorkspaceArchiveWriteError
17+
from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions
18+
from agents.sandbox.sandboxes.docker_removal import DockerRemovalService
19+
20+
from . import _docker_removal_helpers as removal_helpers
21+
from ._docker_removal_helpers import RecordingContainer, RecordingWorker, session
22+
23+
service = removal_helpers.service
24+
worker_code = pytest.importorskip(
25+
"agents.sandbox.sandboxes._docker_removal_worker", exc_type=ImportError
26+
)
27+
28+
29+
@pytest.fixture
30+
def client_lifecycle(
31+
service: tuple[DockerRemovalService, RecordingContainer, RecordingWorker],
32+
monkeypatch: pytest.MonkeyPatch,
33+
tmp_path: Path,
34+
) -> Iterator[tuple[DockerSandboxClient, DockerRemovalService, Any, RecordingWorker]]:
35+
manager, container, worker = service
36+
client = DockerSandboxClient(manager.docker_client, removal_service=manager)
37+
monkeypatch.setattr(client, "get_container", lambda _: None)
38+
monkeypatch.setattr(container, "start", lambda: None, raising=False)
39+
monkeypatch.setattr(container, "remove", Mock(), raising=False)
40+
owners: dict[Path, str] = {}
41+
42+
def create_container(**kwargs: Any) -> RecordingContainer:
43+
# Docker's daemon creates its working directory before startup.
44+
if workdir := kwargs.get("working_dir"):
45+
root = Path(workdir)
46+
if not root.exists():
47+
root.mkdir(parents=True)
48+
owners[root] = "0:0"
49+
return container
50+
51+
manager.docker_client.containers.create.side_effect = create_container
52+
53+
def exec_run(
54+
cmd: list[str], *, user: str = "", demux: bool = False, **kwargs: Any
55+
) -> SimpleNamespace:
56+
effective_user = user or container.attrs["Config"]["User"]
57+
target = Path(cmd[-1])
58+
exit_code = 0
59+
if cmd[:3] == ["mkdir", "-p", "--"]:
60+
if not target.exists():
61+
target.mkdir(parents=True)
62+
owners[target] = effective_user
63+
elif cmd[:2] == ["test", "-d"]:
64+
exit_code = 0 if target.is_dir() else 1
65+
elif cmd[0] == "touch":
66+
# A daemon-created 0755 workspace is not writable by the image user.
67+
if owners.get(target.parent, effective_user) != effective_user:
68+
exit_code = 1
69+
else:
70+
target.touch()
71+
else:
72+
raise AssertionError(f"Unexpected test command: {cmd}")
73+
return SimpleNamespace(exit_code=exit_code, output=(b"", b"") if demux else b"")
74+
75+
monkeypatch.setattr(container, "exec_run", exec_run)
76+
# The real worker enters the container root. Model that root on tmp_path's
77+
# filesystem, which may differ from the host root (for example, tmpfs /tmp).
78+
# Keep canonicalization, open/fstat, and descriptor identity checks real.
79+
root_stat = tmp_path.stat()
80+
81+
def container_stat(path: Any, *args: Any, **kwargs: Any) -> os.stat_result:
82+
return root_stat if path == "/" else os.stat(path, *args, **kwargs)
83+
84+
worker_os = SimpleNamespace(**vars(os))
85+
worker_os.stat = container_stat
86+
# Exercise real O_PATH on Linux; other Unix hosts use read-only descriptors.
87+
worker_os.O_PATH = getattr(os, "O_PATH", os.O_RDONLY)
88+
monkeypatch.setattr(worker_code, "os", worker_os)
89+
with ExitStack() as bindings:
90+
original_request = worker.request
91+
92+
def request(**data: Any) -> dict[str, Any]:
93+
response = original_request(**data)
94+
if data["operation"] == "bind":
95+
bound = bindings.enter_context(worker_code._bind_paths(data["paths"]))
96+
response["paths"] = bound.paths
97+
return response
98+
99+
monkeypatch.setattr(worker, "request", request)
100+
try:
101+
yield client, manager, container, worker
102+
finally:
103+
manager.close()
104+
105+
106+
@pytest.mark.asyncio
107+
@pytest.mark.parametrize("resume", [False, True])
108+
@pytest.mark.parametrize("workspace_setup", ["missing", "existing", "ancestor_grant"])
109+
async def test_client_bootstraps_workspace_before_strict_binding(
110+
client_lifecycle: tuple[DockerSandboxClient, DockerRemovalService, Any, RecordingWorker],
111+
tmp_path: Path,
112+
resume: bool,
113+
workspace_setup: str,
114+
) -> None:
115+
client, manager, container, worker = client_lifecycle
116+
root = tmp_path / "nested" / "workspace"
117+
if workspace_setup == "existing":
118+
root.mkdir(parents=True)
119+
(root / "keep.txt").write_text("existing contents")
120+
grants = (
121+
(SandboxPathGrant(path=str(root.parent), read_only=True),)
122+
if workspace_setup == "ancestor_grant"
123+
else ()
124+
)
125+
configured = Manifest(root=str(root), extra_path_grants=grants)
126+
state = session(manager, container, configured).state
127+
state.container_id = "missing-container"
128+
if resume:
129+
wrapped = await client.resume(state)
130+
else:
131+
wrapped = await client.create(
132+
manifest=configured, options=DockerSandboxClientOptions(image="trusted-image")
133+
)
134+
assert root.is_dir()
135+
manager.assert_bound(container, configured)
136+
assert not wrapped._inner.state.workspace_root_ready
137+
result = await wrapped.exec("touch", str(root / "created.txt"), shell=False)
138+
assert result.ok()
139+
assert (root / "created.txt").is_file()
140+
if workspace_setup == "existing":
141+
assert (root / "keep.txt").read_text() == "existing contents"
142+
with pytest.raises(WorkspaceArchiveWriteError):
143+
await wrapped.rm(str(root), recursive=True)
144+
if grants:
145+
with pytest.raises(WorkspaceArchiveWriteError):
146+
await wrapped.rm(str(root.parent), recursive=True)
147+
assert not worker.removed
148+
149+
150+
@pytest.mark.asyncio
151+
@pytest.mark.parametrize("resume", [False, True])
152+
async def test_client_bootstrap_does_not_create_missing_grant_roots(
153+
client_lifecycle: tuple[DockerSandboxClient, DockerRemovalService, Any, RecordingWorker],
154+
tmp_path: Path,
155+
resume: bool,
156+
) -> None:
157+
client, manager, container, worker = client_lifecycle
158+
root = tmp_path / "workspace"
159+
grant = tmp_path / "external"
160+
configured = Manifest(root=str(root), extra_path_grants=(SandboxPathGrant(path=str(grant)),))
161+
state = session(manager, container, configured).state
162+
state.container_id = "missing-container"
163+
state.workspace_root_ready = True
164+
original_session_id = state.session_id
165+
with pytest.raises(FileNotFoundError):
166+
if resume:
167+
await client.resume(state)
168+
else:
169+
await client.create(
170+
manifest=configured, options=DockerSandboxClientOptions(image="trusted-image")
171+
)
172+
assert root.is_dir()
173+
assert not grant.exists()
174+
assert not manager._bindings
175+
container.remove.assert_called_once_with(force=True)
176+
assert "close" in container.events
177+
if resume:
178+
assert state.container_id == "missing-container"
179+
assert state.session_id == original_session_id
180+
assert state.workspace_root_ready
181+
182+
183+
@pytest.mark.asyncio
184+
@pytest.mark.parametrize("resume", [False, True])
185+
async def test_failed_workspace_bootstrap_cleans_up_before_binding(
186+
client_lifecycle: tuple[DockerSandboxClient, DockerRemovalService, Any, RecordingWorker],
187+
monkeypatch: pytest.MonkeyPatch,
188+
tmp_path: Path,
189+
resume: bool,
190+
) -> None:
191+
client, manager, container, worker = client_lifecycle
192+
configured = Manifest(root=str(tmp_path / "workspace"))
193+
state = session(manager, container, configured).state
194+
state.container_id = "missing-container"
195+
state.workspace_root_ready = True
196+
original_session_id = state.session_id
197+
monkeypatch.setattr(container, "exec_run", Mock(return_value=SimpleNamespace(exit_code=1)))
198+
with pytest.raises(RuntimeError, match="Unable to create Docker workspace"):
199+
if resume:
200+
await client.resume(state)
201+
else:
202+
await client.create(
203+
manifest=configured, options=DockerSandboxClientOptions(image="trusted-image")
204+
)
205+
assert not manager._bindings
206+
assert not worker.calls
207+
container.remove.assert_called_once_with(force=True)
208+
if resume:
209+
assert state.container_id == "missing-container"
210+
assert state.session_id == original_session_id
211+
assert state.workspace_root_ready
212+
213+
214+
@pytest.mark.asyncio
215+
@pytest.mark.parametrize("resume", [False, True])
216+
@pytest.mark.parametrize("mount_kind", ["host_grant", "image_volume"])
217+
async def test_ineligible_mount_is_rejected_before_bootstrap_writes(
218+
client_lifecycle: tuple[DockerSandboxClient, DockerRemovalService, Any, RecordingWorker],
219+
monkeypatch: pytest.MonkeyPatch,
220+
tmp_path: Path,
221+
resume: bool,
222+
mount_kind: str,
223+
) -> None:
224+
client, manager, container, worker = client_lifecycle
225+
shared = tmp_path / "shared"
226+
shared.mkdir()
227+
(shared / "keep.txt").write_text("host contents")
228+
alias = tmp_path / "image-workspace"
229+
alias.symlink_to(shared, target_is_directory=True)
230+
configured = Manifest(
231+
root=str(alias / "build"),
232+
extra_path_grants=(
233+
(SandboxPathGrant(path=str(shared), host_path=str(shared)),)
234+
if mount_kind == "host_grant"
235+
else ()
236+
),
237+
)
238+
container.attrs["Mounts"] = [
239+
{
240+
"Type": "bind" if mount_kind == "host_grant" else "volume",
241+
"Destination": str(shared),
242+
"Source": str(shared),
243+
"RW": True,
244+
"Propagation": "rprivate",
245+
}
246+
]
247+
container.attrs["HostConfig"] = {}
248+
container.attrs["State"].update(Running=True, Pid=123, StartedAt="incarnation")
249+
manager.docker_client.info.return_value = {
250+
"SecurityOptions": ["name=seccomp,profile=builtin"],
251+
"DefaultRuntime": "runc",
252+
}
253+
manager.docker_client.version.return_value = {"Version": "26.0.0"}
254+
monkeypatch.setattr(manager, "_state", DockerRemovalService._state.__get__(manager))
255+
execute = Mock(wraps=container.exec_run)
256+
monkeypatch.setattr(container, "exec_run", execute)
257+
state = session(manager, container, configured).state
258+
state.container_id = "missing-container"
259+
state.workspace_root_ready = True
260+
original_session_id = state.session_id
261+
with pytest.raises(ValueError, match="shared host paths|private container"):
262+
if resume:
263+
await client.resume(state)
264+
else:
265+
await client.create(
266+
manifest=configured, options=DockerSandboxClientOptions(image="trusted-image")
267+
)
268+
assert sorted(path.name for path in shared.iterdir()) == ["keep.txt"]
269+
assert (shared / "keep.txt").read_text() == "host contents"
270+
execute.assert_not_called()
271+
assert not worker.calls
272+
assert not manager._bindings
273+
container.remove.assert_called_once_with(force=True)
274+
if resume:
275+
assert state.container_id == "missing-container"
276+
assert state.session_id == original_session_id
277+
assert state.workspace_root_ready

0 commit comments

Comments
 (0)