Skip to content
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.py
index 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_call
self.shell = shell
self.cwd = str(cwd) # the last folder the runner reported; a reopened shell starts here
@@ -81,7 +81,7 @@ class RunnerExecutor(Executor):
answer["sandbox_notice"] = notice
if 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 result
pass
return answer
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.py
index 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 annotations
import json
+from collections import deque
import logging
import os
import queue
+import re
import shutil
import subprocess
import 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 made
self.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 exc
raise
self._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.alive
def 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 = None
try:
_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.py
index 3b38aa04..657cf4aa 100644
--- a/coworker/sandbox/workspace.py
+++ b/coworker/sandbox/workspace.py
@@ -14,6 +14,7 @@ from __future__ import annotations
import os
import threading
+import time
from abc import ABC, abstractmethod
from pathlib import Path
from 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.md
index 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 sandbox
coworker can then ask you for the site: a card names it, gives the coworker's reason, and
says 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 only
diff --git a/tests/test_network_access.py b/tests/test_network_access.py
index 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_p
provider = _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 told
provider.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 None
workspace.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.alive
def 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 TurnEngine
from coworker.permissions import Decision
from 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 True
call = 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",))