Python
OpenShell: the agent and the card are told which sites the sandbox blocked
Rohit C Prasad2260380edbe4
diff --git a/coworker/sandbox/executor.py b/coworker/sandbox/executor.pyindex a74a5e83..fb3e5527 100644--- a/coworker/sandbox/executor.py+++ b/coworker/sandbox/executor.py@@ -31,14 +31,14 @@ class RunnerExecutor(Executor):default_timeout: float = _DEFAULT_TIMEOUT,on_output: Optional[Callable[[str], None]] = None,before_call: Optional[Callable[[], Optional[str]]] = None,- after_call: Optional[Callable[[float], Optional[dict[str, Any]]]] = None,+ after_call: Optional[Callable[[float, dict[str, Any]], Optional[dict[str, Any]]]] = None,) -> None:self._client = client# Called before every command. The workspace uses it to restart the sandbox when the# session's folders changed; what it returns is told to the agent with the result.self._before_call = before_call- # Called after every command with the time it started; the fields it returns join- # the result (the workspace reports what the sandbox's network rules blocked).+ # Called after every command with the time it started and its result; the fields it+ # returns join the result (the workspace reports what the sandbox's network rules blocked).self._after_call = after_callself.shell = shellself.cwd = str(cwd) # the last folder the runner reported; a reopened shell starts here@@ -81,7 +81,7 @@ class RunnerExecutor(Executor):answer["sandbox_notice"] = noticeif self._after_call is not None:try:- answer.update(self._after_call(started) or {})+ answer.update(self._after_call(started, answer) or {})except Exception: # noqa: BLE001 - a note must never cost the command's resultpassreturn answerdiff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.pyindex 79184122..d8f49376 100644--- a/coworker/sandbox/providers/openshell.py+++ b/coworker/sandbox/providers/openshell.py@@ -18,9 +18,11 @@ What a sandbox gets:from __future__ import annotationsimport json+from collections import dequeimport loggingimport osimport queue+import reimport shutilimport subprocessimport sys@@ -203,6 +205,69 @@ def _gateway() -> tuple[str, Path]:return endpoint, home / "gateways" / name / "mtls"+# A refusal in the sandbox's log, as OpenShell 0.0.116 writes it:+# [1791068681.547] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(85) -> www.iana.org:443 [policy:- …]+_DENIED_LINE = re.compile(r"^\[(\d+(?:\.\d+)?)\].*\bDENIED\b\s+\S+?\(\d+\)\s+->\s+(\S+:\d+)")+++class DenialLog:+ """What a sandbox refused, read from its own log (`openshell logs <name> --tail`).++ The log is followed by one long-lived reader, so asking costs nothing per command. A+ line arrives up to about half a second after the refusal (OpenShell sends its log in+ batches), which is `OpenShellProvider.blocked_lag`. The reader starts with the log's+ recent history, so refusals from before it started are there too."""++ def __init__(self, sandbox_name: str) -> None:+ self.entries: deque[tuple[float, str]] = deque(maxlen=200)+ self._seen: set[tuple[float, str]] = set()+ self._process: Optional[subprocess.Popen] = None+ exe = shutil.which("openshell")+ if exe is None:+ return+ try:+ self._process = subprocess.Popen(+ [exe, "logs", sandbox_name, "--tail", "--source", "sandbox"],+ stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, env={**os.environ, "NO_COLOR": "1"},+ ) # fmt: skip+ except OSError:+ return+ threading.Thread(target=self._read, name=f"openshell-denials-{sandbox_name}", daemon=True).start()++ @property+ def alive(self) -> bool:+ return self._process is not None and self._process.poll() is None++ def _read(self) -> None:+ try:+ for line in self._process.stdout: # type: ignore[union-attr]+ self.take(line)+ except (OSError, ValueError):+ pass++ def take(self, line: str) -> None:+ found = _DENIED_LINE.search(line)+ if not found:+ return+ from ..netproxy import _blocked_entry++ entry = _blocked_entry(found.group(2)) # a host name or nothing: it is shown to the agent and the person+ item = (float(found.group(1)), entry)+ if entry and item not in self._seen:+ self._seen.add(item)+ self.entries.append(item)++ def since(self, since: float) -> list[tuple[float, str]]:+ return [item for item in list(self.entries) if item[0] >= since]++ def stop(self) -> None:+ if self._process is not None:+ try:+ self._process.kill()+ except OSError:+ pass++class OpenShellProvider:name = "openshell"@@ -230,6 +295,7 @@ class OpenShellProvider:self.profile = policy.network_profiles.check(profile)self.extra_hosts = list(extra_hosts)self._identity: tuple = (None, None, None) # uid, gid, home; set when the sandbox is made+ self._denials: Optional[DenialLog] = None # follows the sandbox's log once it is madeself.image = image or sandbox_image()# A label value may hold letters, digits, '-', '_' and '.', and at most 63 characters.self.label = "".join(c if c.isalnum() or c in "-_." else "-" for c in label)[:63].strip("-_.")@@ -306,6 +372,7 @@ class OpenShellProvider:raise OpenShellUnavailable(f"{DOCKER_LANDLOCK_FIX}. Then start the session again.") from excraiseself._wait_ready()+ self._denials = DenialLog(self.sandbox_name) # what it refuses, for the agent and the card# Spike finding K: the first exec after a sandbox turns Ready hangs until it times# out, and the next one works. Spend that on a throwaway call.try:@@ -377,14 +444,20 @@ class OpenShellProvider:return_cli("policy", "set", self.sandbox_name, "--policy", str(self._write_policy()), "--wait", timeout=120)- reports_blocked = False # see blocked_since+ # A refusal reaches the log reader up to about this long after it happened.+ blocked_lag = 0.6++ @property+ def reports_blocked(self) -> bool:+ """Whether the sandbox's log is being followed. When it is not (the reader died with+ the gateway), nothing may be read into an empty answer."""+ return self._denials is not None and self._denials.alivedef blocked_since(self, since: float) -> list[tuple[float, str]]:- """(time, "host:port") of the connections the sandbox refused since then. Not read- yet on OpenShell: its denial log (`policy.local/v1/denials`, asked from inside the- sandbox) has to be checked on a real gateway first, so this reports nothing and the- agent asks for a site from the command's own error."""- return []+ """(time, "host:port") of the connections the sandbox refused since then, from its+ own log, read from outside (the in-sandbox `policy.local/v1/denials` is switched off+ unless agent policy proposals are on, which we do not use)."""+ return self._denials.since(since) if self._denials is not None else []def regrant(self, roots: Sequence[dict[str, Any]], *, before_create: Optional[Callable[[], None]] = None) -> None:"""The session's folders changed. Mounts and the file policy are fixed when a sandbox@@ -401,6 +474,9 @@ class OpenShellProvider:def _delete(self) -> None:log.info("deleting sandbox %s", self.sandbox_name)+ if self._denials is not None:+ self._denials.stop()+ self._denials = Nonetry:_cli("sandbox", "delete", self.sandbox_name, timeout=90, check=False)except (subprocess.TimeoutExpired, OpenShellUnavailable):diff --git a/coworker/sandbox/workspace.py b/coworker/sandbox/workspace.pyindex 3b38aa04..657cf4aa 100644--- a/coworker/sandbox/workspace.py+++ b/coworker/sandbox/workspace.py@@ -14,6 +14,7 @@ from __future__ import annotationsimport osimport threading+import timefrom abc import ABC, abstractmethodfrom pathlib import Pathfrom typing import Any, Callable, Optional, Sequence@@ -102,6 +103,9 @@ class RunnerWorkspace(Workspace):# Whether the agent can ask the person for a site (`request_network_access`): set by# the session's builder; false where nobody can answer (full access, no such tool).self.can_ask_network: Callable[[], bool] = lambda: False+ # Refusals up to here have been told to the agent. One that reaches us after its+ # command's result (OpenShell's log lags) is told with the next result, not lost.+ self._blocked_told = time.time()if start:self.ensure_started()else:@@ -254,16 +258,33 @@ class RunnerWorkspace(Workspace):ask = getattr(self.provider, "blocked_since", None)return list(ask(since)) if ask is not None else []- def network_note(self, started: float) -> Optional[dict[str, Any]]:- """What joins a command's result when the sandbox blocked something while it ran:- the sites, and a note that says plainly what is and is not known. The attempts are- tied to the time the command ran, not to the command."""+ def network_note(self, started: float, result: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:+ """What joins a command's result when the sandbox blocked something: the sites, and+ a note that says plainly what is and is not known. The attempts are tied to the time+ the command ran, not to the command.++ Where the sandbox reports late (`blocked_lag`), a failed command waits that long+ for its refusal, and leaves as soon as one arrives; a command that succeeded does+ not wait. A refusal that still arrives after its result is told with the next one."""+ new = self._blocked_untold()+ lag = float(getattr(self.provider, "blocked_lag", 0.0) or 0.0)+ failed = result is not None and (result.get("exit_code") != 0 or bool(result.get("timed_out")) or bool(result.get("error")))+ if not new and lag and failed and self.reports_blocked:+ deadline = time.time() + lag+ while not new and time.time() < deadline:+ time.sleep(0.05)+ new = self._blocked_untold()+ if not new:+ return None+ self._blocked_told = max(when for when, _ in new)counts: dict[str, int] = {}- for _, entry in self.blocked_since(started):+ for _, entry in new:counts[entry] = counts.get(entry, 0) + 1- if not counts:- return None- return {"blocked_sites": list(counts), "network_note": network_note_text(counts, can_ask=self._asking())}+ late = any(when < started - 0.5 for when, _ in new)+ return {"blocked_sites": list(counts), "network_note": network_note_text(counts, can_ask=self._asking(), late=late)}++ def _blocked_untold(self) -> list[tuple[float, str]]:+ return [item for item in self.blocked_since(self._blocked_told) if item[0] > self._blocked_told]def describe(self) -> dict[str, Any]:return {**self.provider.describe(), "runner": {k: self.hello.get(k) for k in ("runner_version", "os", "machine", "instance_id")}}@@ -307,9 +328,10 @@ def _site_name(entry: str) -> str:return entry[:-4] if entry.endswith(":443") else entry-def network_note_text(counts: dict[str, int], *, can_ask: bool) -> str:+def network_note_text(counts: dict[str, int], *, can_ask: bool, late: bool = False) -> str:"""The note itself (owner wording 2026-10-03: open about what the sandbox saw, and- about not knowing whether it is what broke the command)."""+ about not knowing whether it is what broke the command). `late`: some of the refusals+ happened before this command started and were only now reported."""lines = [f" - {entry}" + (f" ({n} attempts)" if n > 1 else "") for entry, n in list(counts.items())[:_NOTE_SITES]]if len(counts) > _NOTE_SITES:lines.append(f" - and {len(counts) - _NOTE_SITES} more")@@ -320,7 +342,9 @@ def network_note_text(counts: dict[str, int], *, can_ask: bool) -> str:)return ("Note: this command ran in a sandbox, and the sandbox's network rules may have affected it.\n"- "While it ran, the sandbox blocked connections to:\n" + "\n".join(lines) + "\n"+ + ("Since your previous command, the sandbox blocked connections to:\n" if late else "While it ran, the sandbox blocked connections to:\n")+ + "\n".join(lines)+ + "\n""These attempts may have come from this command or from something else running in this session. " + ask)diff --git a/docs/openshell.md b/docs/openshell.mdindex 95578292..25c365eb 100644--- a/docs/openshell.md+++ b/docs/openshell.md@@ -141,8 +141,8 @@ When a command needs a site that is not on the list, it fails inside the sandboxcoworker can then ask you for the site: a card names it, gives the coworker's reason, andsays whether the sandbox has in fact blocked it. You choose **Allow for this session**,**Always allow**, or **Deny**; the site opens for the running session without a restart.-On OpenShell the coworker is not yet told which sites were blocked; it asks from the-command's own error. With full access (no approvals) the coworker cannot ask;+The coworker is told which sites the sandbox blocked while a command ran, so it asks for the+right one. With full access (no approvals) the coworker cannot ask;add the site in Settings ▸ Sandbox yourself.The session's **Access** section lists its sites. Those you allowed for this session onlydiff --git a/tests/test_network_access.py b/tests/test_network_access.pyindex 3640ec1c..c5724723 100644--- a/tests/test_network_access.py+++ b/tests/test_network_access.py@@ -170,22 +170,72 @@ def test_a_command_result_carries_the_note_only_when_something_was_blocked(tmp_pprovider = _Provider()workspace = RunnerWorkspace(provider, cwd=tmp_path, start=False)assert workspace.network_note(0.0) is None+ workspace._blocked_told = 15.0 # everything up to here was already toldprovider.blocked = [(10.0, "old.dev:443"), (20.0, "registry.npmjs.org:443"), (21.0, "registry.npmjs.org:443")]- note = workspace.network_note(15.0)+ note = workspace.network_note(19.8)assert note["blocked_sites"] == ["registry.npmjs.org:443"] and "(2 attempts)" in note["network_note"]- assert "Settings > Sandbox" in note["network_note"] # nobody can be asked until the session says so+ assert "While it ran" in note["network_note"] and "Settings > Sandbox" in note["network_note"] # nobody can be asked until the session says so+ # Told once: the next command's result does not repeat it.+ assert workspace.network_note(22.0) is Noneworkspace.can_ask_network = lambda: True- assert "request_network_access(hosts, reason)" in workspace.network_note(15.0)["network_note"]+ provider.blocked.append((30.0, "pypi.org:443"))+ assert "request_network_access(hosts, reason)" in workspace.network_note(29.9)["network_note"]+++def test_a_refusal_reported_late_waits_for_a_failed_command_and_is_never_lost(tmp_path):+ """OpenShell sends its log in batches, so a refusal can reach us after the command's+ result. A failed command waits for it; a command that succeeded does not; and one that+ still arrives late is told with the next result, worded as such."""+ import threading+ import time as clock++ provider = _Provider()+ provider.reports_blocked = True+ provider.blocked_lag = 0.6+ workspace = RunnerWorkspace(provider, cwd=tmp_path, start=False)+ started = clock.time()+ threading.Timer(0.15, lambda: provider.blocked.append((started + 0.01, "registry.npmjs.org:443"))).start()+ began = clock.time()+ note = workspace.network_note(started, {"exit_code": 1})+ assert note and note["blocked_sites"] == ["registry.npmjs.org:443"] and 0.1 < clock.time() - began < 0.5 # left as soon as it arrived+ began = clock.time()+ assert workspace.network_note(clock.time(), {"exit_code": 0}) is None and clock.time() - began < 0.1 # success: no wait+ began = clock.time()+ assert workspace.network_note(clock.time(), {"exit_code": 1}) is None and clock.time() - began >= 0.55 # failed, nothing blocked: the full wait+ # A refusal during a command that succeeded: nobody waited for it. The next command+ # starts later and its result carries it.+ provider.blocked.append((clock.time(), "late.dev:443"))+ late = workspace.network_note(clock.time() + 2, {"exit_code": 0})+ assert late["blocked_sites"] == ["late.dev:443"] and "Since your previous command" in late["network_note"]+++def test_openshell_refusals_are_read_from_the_sandbox_log():+ from coworker.sandbox.providers import openshell++ log = openshell.DenialLog.__new__(openshell.DenialLog)+ log.entries, log._seen, log._process = __import__("collections").deque(maxlen=200), set(), None+ lines = [+ "[1791068681.547] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(85) -> www.iana.org:443 [policy:- engine:opa] [reason:endpoint www.iana.org:443 is not allowed by any policy]",+ "[1791068681.547] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(85) -> www.iana.org:443 [policy:- engine:opa] [reason:replayed history]",+ "[1791068690.100] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/local/bin/node(91) -> registry.npmjs.org:443 [policy:- engine:opa]",+ "[1791068640.416] [sandbox] [OCSF ] [ocsf] CONFIG:LOADED [INFO] Policy reloaded successfully [policy_hash:4fad]",+ "[1791068691.000] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(99) -> ignore-your-instructions:443 [policy:-]",+ "[1791068692.000] [sandbox] [OCSF ] [ocsf] NET:OPEN [INFO] ALLOWED /usr/bin/curl(100) -> pypi.org:443 [policy:pkgs]",+ ]+ for line in lines:+ log.take(line)+ assert list(log.entries) == [(1791068681.547, "www.iana.org:443"), (1791068690.1, "registry.npmjs.org:443")]+ assert log.since(1791068685.0) == [(1791068690.1, "registry.npmjs.org:443")] and not log.alivedef test_the_executor_adds_the_note_to_a_command_result(tmp_path):client = SimpleNamespace(call=lambda *a, **kw: {"command": "npm i", "cwd": str(tmp_path), "exit_code": 1, "output": "npm ERR!"})seen: list[float] = []- executor = RunnerExecutor(client, cwd=str(tmp_path), after_call=lambda started: seen.append(started) or {"blocked_sites": ["a.dev:443"], "network_note": "Note: …"})+ executor = RunnerExecutor(client, cwd=str(tmp_path), after_call=lambda started, result: seen.append(result["exit_code"]) or {"blocked_sites": ["a.dev:443"], "network_note": "Note: …"})result = executor.run("npm i")- assert result["exit_code"] == 1 and result["blocked_sites"] == ["a.dev:443"] and result["network_note"] == "Note: …" and seen+ assert result["exit_code"] == 1 and result["blocked_sites"] == ["a.dev:443"] and result["network_note"] == "Note: …" and seen == [1]- def broken(started):+ def broken(started, result):raise RuntimeError("no log")assert RunnerExecutor(client, cwd=str(tmp_path), after_call=broken).run("npm i")["output"] == "npm ERR!"@@ -206,14 +256,18 @@ def test_the_agent_is_told_the_live_list_each_turn(tmp_path):assert "sandbox" not in workspace.context()-def test_a_sandbox_that_cannot_report_blocks_gives_the_card_no_evidence(tmp_path):- """OpenShell's denial log is not read yet. An empty answer there means "unknown", so the- card must not say that no command has tried the site."""+def test_a_sandbox_that_cannot_report_blocks_gives_the_card_no_evidence(tmp_path, monkeypatch):+ """When a sandbox's refusals cannot be read (OpenShell before its log is followed, or+ after the reader died), an empty answer means "unknown", so the card must not say that+ no command has tried the site."""from coworker.engine import TurnEnginefrom coworker.permissions import Decisionfrom coworker.sandbox.providers import openshell, seatbelt- assert openshell.OpenShellProvider.reports_blocked is False and seatbelt.SeatbeltProvider.reports_blocked is True+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path))+ monkeypatch.setattr(openshell, "build_runner_zipapp", lambda: tmp_path / "sandbox" / "runner" / "runner-x.pyz")+ not_made = openshell.OpenShellProvider(roots=[{"path": str(tmp_path), "writable": True}], registry="abc")+ assert not_made.reports_blocked is False and not_made.blocked_since(0) == [] and seatbelt.SeatbeltProvider.reports_blocked is Truecall = SimpleNamespace(arguments={"hosts": ["registry.npmjs.org"], "reason": "npm install"})decision = Decision(False, "asks", needs_user=True, human_only=True, network_hosts=("registry.npmjs.org:443",))