Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions sage/gateway/being_gate_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -1555,6 +1555,95 @@ def run_budget_s(now: Optional[float] = None) -> tuple:
return int(left), "the time left in this beat"


def host_user_site(minor: Optional[int] = None) -> str:
"""The seat user's Python user site for python3.<minor> (default: this process's minor), e.g.
~/.local/lib/python3.12/site-packages, realpath'd, or "" when there is none.

THE BOX READS IT, READ-ONLY (dp, 2026-11-16, SAGE #701 option 2). `run` and `request_run`
imported different packages: on cbp, sklearn and torch live only in the user site, so the seat's
host run imported them and the box could not. The being saw the box's answer every beat and
spent two days filing installer scripts and scope asks for ~/.local/bin to close a gap no
install could close. Binding the user site read-only into the box makes the two places agree,
so the cheap path (run) and the correct path import the same packages.

WHAT IT ADDS TO THE BOX (Nova, #741 review): package code AND package data, read-only. A .pth
file there runs its `import` lines when the box's python starts, so this is a wider code
surface than the base image, not only more module names. It runs as the box's code does:
no network, no home, no write outside the box's tmpfs and the being's grants
(test_run_user_site_pth.py measures that from inside bubblewrap). Anything secret a package
keeps beside its code is readable by a run; a seat that keeps such a package in its user
site should set SAGE_RUN_USER_SITE=0, which turns the bind off."""
import os
import site
import sys
if os.environ.get("SAGE_RUN_USER_SITE", "1") == "0":
return ""
n = sys.version_info.minor if minor is None else minor
try:
base = site.getuserbase()
except Exception:
return ""
if not base:
return ""
p = os.path.realpath(os.path.join(base, "lib", f"python3.{n}", "site-packages"))
return p if os.path.isdir(p) else ""


_BOX_MINOR: dict = {}


def box_python_minor(interp: Optional[str] = None) -> Optional[int]:
"""The minor version of the python the box runs ({interp}/bin/python3), asked of that binary
once per process; None when it cannot say.

WHY ASK IT (Nova, #741 review): the box runs {interp}/bin/python3, and interp comes from this
process's sys.executable. Those are the same python on cbp (/usr/bin/python3 -> 3.12), but a
gateway started as python3.11 on a host whose python3 is 3.12 would bind 3.11's user site at
the 3.11 path, which the box's 3.12 never reads: no error, and run and request_run disagree
again. Asking the binary makes the bind match the interpreter that reads it."""
import os
import subprocess
import sys
interp = interp or os.path.dirname(os.path.dirname(sys.executable))
if interp not in _BOX_MINOR:
try:
out = subprocess.run([f"{interp}/bin/python3", "-I", "-c",
"import sys; print(sys.version_info[0], sys.version_info[1])"],
capture_output=True, text=True, timeout=20,
stdin=subprocess.DEVNULL)
major, minor = (int(x) for x in out.stdout.split())
_BOX_MINOR[interp] = minor if major == 3 and out.returncode == 0 else None
except Exception:
_BOX_MINOR[interp] = None
return _BOX_MINOR[interp]


def box_user_site(interp_minor: Optional[int] = None) -> str:
"""Where Python inside the box looks for its user site: HOME is /tmp there, so
/tmp/.local/lib/python3.N/site-packages. Binding the host's user site AT THIS PATH (not at its
own path plus PYTHONPATH) lets site.py treat it as the user site it is, .pth files included."""
import sys
n = sys.version_info.minor if interp_minor is None else interp_minor
return f"/tmp/.local/lib/python3.{n}/site-packages"


def user_site_bind(interp: Optional[str] = None) -> str:
"""The bwrap fragment that shows the host user site to the box, or "" when there is none.
Both ends use the box interpreter's own minor version, so the directory bound is the one that
interpreter's site.py reads and its packages were built for. Must come AFTER `--tmpfs /tmp`
(a later mount masks an earlier one)."""
import shlex
if os.environ.get("SAGE_RUN_USER_SITE", "1") == "0":
return ""
minor = box_python_minor(interp)
if minor is None:
return ""
p = host_user_site(minor)
if not p:
return ""
return f" --ro-bind {shlex.quote(p)} {shlex.quote(box_user_site(minor))}"


def run_mem_cap_bytes() -> int:
import os
try:
Expand Down Expand Up @@ -1989,6 +2078,8 @@ def run_command(args: dict, ctx: Optional[dict] = None) -> str:
f"{RUN_ETC_BINDS}"
f" --ro-bind {interp} {interp}"
f" --proc /proc --dev /dev --size {RUN_TMP_BYTES} --tmpfs /tmp"
# the host user site, read-only, where the box's python looks for it (SAGE #701)
f"{user_site_bind(interp)}"
f"{wt_bind}"
f"{grant_binds}"
# Writable in there: these two size-limited tmpfs, and what the being's grants reach.
Expand Down
12 changes: 11 additions & 1 deletion sage/gateway/run_census.py
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,12 @@ def site_dirs() -> List[str]:
f"/usr/lib/{ver}/dist-packages"):
if p not in out:
out.append(p)
# the user site is in the box too now (SAGE #701), so a `pip install --user` re-measures
from sage.gateway import being_gate_client as bgc
m = bgc.box_python_minor(_interp())
us = bgc.host_user_site(m) if m is not None else ""
if us and us not in out:
out.append(us)
return [p for p in out if os.path.isdir(p)]


Expand All @@ -138,12 +144,16 @@ def box_command(stage: str) -> List[str]:
f"{bgc.RUN_ETC_BINDS}"
f" --ro-bind {shlex.quote(interp)} {shlex.quote(interp)}"
" --proc /proc --dev /dev --tmpfs /tmp"
# the host user site, as run binds it (SAGE #701)
f"{bgc.user_site_bind(interp)}"
f" --ro-bind {shlex.quote(stage)} /work"
" --unshare-pid --unshare-net --unshare-ipc --unshare-uts"
" --new-session --die-with-parent"
" --setenv HOME /tmp --setenv PYTHONUTF8 1 --setenv PYTHONDONTWRITEBYTECODE 1"
f" --setenv PATH {shlex.quote(interp)}/bin:/usr/bin:/bin"
f" --chdir /work {shlex.quote(interp)}/bin/python3 -I /work/probe.py")
# No -I: it disables the user site, and run's own interpreter line has no -I, so a probe
# under -I measured a box `run` is not (SAGE #701). /work holds only probe.py.
f" --chdir /work {shlex.quote(interp)}/bin/python3 /work/probe.py")


def measure(modules=DEFAULT_MODULES, tools=TOOLS, runner=subprocess.run) -> Dict:
Expand Down
42 changes: 42 additions & 0 deletions sage/gateway/tests/test_being_gate_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -1141,6 +1141,11 @@ def _assert_every_bind_is_judged_or_plumbing(calls):
from sage.gateway.being_gate_client import RUN_ETC_BINDS
plumbing = {"/usr", "/lib", "/lib64", "/bin", "/etc/alternatives", interp}
plumbing |= {t for t in RUN_ETC_BINDS.split() if t.startswith("/")} # fixed system config
# the host user site is box plumbing by operator decision (dp, 2026-11-16, SAGE #701 option 2):
# package code, read-only, like /usr. Judging it as the being's read would refuse every run.
from sage.gateway.being_gate_client import host_user_site
if host_user_site():
plumbing.add(host_user_site())
for src in _line_bind_sources(line):
if src in plumbing or src.startswith(STAGE_ROOT + "-"):
continue
Expand Down Expand Up @@ -1236,3 +1241,40 @@ def test_a_target_that_means_the_tests_folder_is_told_to_use_tests(tmp_path):
with pytest.raises(ValueError) as e:
check_command({"target": "nosuite"}, ctx)
assert "just 'tests'" not in str(e.value)


# --- SAGE #701 option 2 (dp, 2026-11-16): the host user site is in the run box, read-only, where the
# box's python looks for it, so `run` and `request_run` import the same packages.

def test_the_user_site_is_bound_read_only_after_tmp_where_the_box_looks(tmp_path, monkeypatch):
import shlex
import sage.gateway.being_gate_client as bgc
site_dir = tmp_path / "site-packages"; site_dir.mkdir()
monkeypatch.setattr(bgc, "host_user_site", lambda minor=None: str(site_dir))
monkeypatch.setattr(bgc, "box_python_minor", lambda interp=None: 12)
monkeypatch.setattr(bgc, "run_sandbox_kind", lambda: "bwrap")
home = tmp_path / "home"; (home / "scratch").mkdir(parents=True)
(home / "scratch" / "s.py").write_text("print(1)\n")
line = bgc.run_command({"path": "scratch/s.py"}, {"memory_root": str(home), "member": "t"})
toks = shlex.split(line)
i = toks.index(str(site_dir))
assert toks[i - 1] == "--ro-bind", "the user site must never be writable from the box"
assert toks[i + 1] == bgc.box_user_site(12)
assert toks.index("/tmp") < i, "bound after --tmpfs /tmp, or the tmpfs masks it"


def test_the_user_site_bind_can_be_switched_off(monkeypatch):
import sage.gateway.being_gate_client as bgc
monkeypatch.setenv("SAGE_RUN_USER_SITE", "0")
assert bgc.host_user_site() == "" and bgc.user_site_bind() == ""


def test_the_census_box_binds_the_user_site_and_does_not_isolate_it_away(tmp_path, monkeypatch):
import sage.gateway.being_gate_client as bgc
from sage.gateway import run_census
site_dir = tmp_path / "site-packages"; site_dir.mkdir()
monkeypatch.setattr(bgc, "host_user_site", lambda minor=None: str(site_dir))
monkeypatch.setattr(bgc, "box_python_minor", lambda interp=None: 12)
cmd = run_census.box_command(str(tmp_path))
assert str(site_dir) in cmd and bgc.box_user_site(12) in cmd
assert "-I" not in cmd, "-I disables the user site; run's own line has no -I"
175 changes: 175 additions & 0 deletions sage/gateway/tests/test_run_user_site_pth.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
"""An adversarial .pth in the host user site runs inside the box, under the box's limits.

Nova's containment caveat on #741 (SAGE #701 option 2): binding the host user site into the run
box adds package code and data, and a .pth file there executes its `import` lines whenever the
box's python starts. So the user site is a code surface, not only a list of module names. These
tests put a hostile .pth in a fake user site and run a real `run` through bubblewrap. The .pth
does its worst at interpreter start, before the being's script runs, and reports from inside:

* it ran (so the tests measure something);
* it cannot write into the user site it came from (read-only bind) or delete from it;
* it cannot reach the network;
* it cannot see the seat's home, the being's home, or a host file outside the box's mounts;
* it does not inherit the seat's environment;
* a file it writes under /tmp lands in the box's tmpfs, never on the host.

The host side checks the same facts after the run: the user site is byte-identical and nothing
appeared outside it.
"""
import os
import site
import sys
import types
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parents[3]))

from sage.gateway import being_gate_client as B # noqa: E402
from sage.gateway.being_gate_client import BeingIntent # noqa: E402

needs_bwrap = pytest.mark.skipif(B.run_sandbox_kind() != "bwrap", reason="no usable bubblewrap here")

PROBE = '''\
import os, socket, sys
def _say(k, v):
sys.stdout.write("PTH " + k + ": " + str(v) + "\\n"); sys.stdout.flush()
def _try(k, fn):
try:
fn(); _say(k, "REACHED")
except Exception as e:
_say(k, "denied " + type(e).__name__)
here = os.path.dirname(os.path.abspath(__file__))
_say("ran-in", here)
_try("write-site", lambda: open(os.path.join(here, "planted.py"), "w").write("x"))
_try("delete-site", lambda: os.remove(os.path.join(here, "pthprobe.py")))
_try("chmod-site", lambda: os.chmod(os.path.join(here, "pthprobe.py"), 0o777))
_try("net", lambda: socket.create_connection(("1.1.1.1", 53), timeout=2))
_try("net-dns", lambda: socket.getaddrinfo("example.com", 80))
for k, p in [("seat-home", SEAT_HOME), ("being-home", BEING_HOME), ("host-file", HOST_FILE)]:
_say(k, os.path.exists(p))
_say("secret-env", os.environ.get("SAGE_PTH_SECRET"))
_try("write-host-path", lambda: open(HOST_DROP, "w").write("x"))
'''


def _user_site(tmp_path, minor):
base = tmp_path / "userbase"
sp = base / "lib" / f"python3.{minor}" / "site-packages"
sp.mkdir(parents=True)
return base, sp


def _snapshot(d: Path):
return {p.relative_to(d): (p.read_bytes(), p.stat().st_mode)
for p in sorted(d.rglob("*")) if p.is_file()}


def _dispatcher(home):
from sage.gateway.hestia_dispatch import HestiaF1aDispatcher as D
d = D.__new__(D); d.memory_root = str(home); d.member = "test-being"
d.worktree = None; d.workspace = None
d._verdict = types.SimpleNamespace(command=None, granted=(), granted_reach=())
d._call = lambda name, args: {"actionId": "w-run"}
return d


@needs_bwrap
def test_a_hostile_pth_runs_inside_the_box_and_reaches_nothing(tmp_path, monkeypatch):
tmp_path = tmp_path.resolve()
minor = B.box_python_minor()
assert minor is not None, "the box interpreter must answer its own version"
base, sp = _user_site(tmp_path, minor)
home = tmp_path / "inst"; (home / "scratch").mkdir(parents=True)
(home / "journal.md").write_text("mine\n")
host_file = tmp_path / "outside" / "secret.txt"
host_file.parent.mkdir(); host_file.write_text("S\n")
host_drop = tmp_path / "outside" / "dropped.txt"
seat_home = str(Path.home().resolve())
consts = (f"SEAT_HOME = {seat_home!r}\nBEING_HOME = {str(home / 'journal.md')!r}\n"
f"HOST_FILE = {str(host_file)!r}\nHOST_DROP = {str(host_drop)!r}\n")
(sp / "pthprobe.py").write_text(consts + PROBE)
(sp / "zz-hostile.pth").write_text("import pthprobe\n")
(sp / "fakepkg").mkdir(); (sp / "fakepkg" / "__init__.py").write_text("VALUE = 7\n")
monkeypatch.setattr(site, "getuserbase", lambda: str(base))
monkeypatch.setenv("SAGE_PTH_SECRET", "s3cret")
before = _snapshot(sp)

(home / "scratch" / "s.py").write_text("import fakepkg\nprint('script-sees', fakepkg.VALUE)\n")
r = _dispatcher(home)._do_run(BeingIntent("run", {"path": "scratch/s.py"}))
assert r.ok, r.error
out = r.result["stdout"]

# it ran, from the bound path, before the script, and the script imports from the same site
assert f"PTH ran-in: {B.box_user_site(minor)}" in out, out
assert out.index("PTH ran-in") < out.index("script-sees 7"), out
assert "REACHED" not in out, out
for k in ("write-site", "delete-site", "chmod-site", "net", "net-dns", "write-host-path"):
assert f"PTH {k}: denied" in out, (k, out)
for k in ("seat-home", "being-home", "host-file"):
assert f"PTH {k}: False" in out, (k, out)
assert "PTH secret-env: None" in out, out
# and on the host: the user site is unchanged, and nothing landed outside the box
assert _snapshot(sp) == before
assert not host_drop.exists()


@needs_bwrap
def test_a_pth_write_under_tmp_stays_in_the_box(tmp_path, monkeypatch):
"""/tmp inside the box is its own tmpfs, so a .pth that writes there writes nowhere real."""
tmp_path = tmp_path.resolve()
minor = B.box_python_minor()
base, sp = _user_site(tmp_path, minor)
# Directly in /tmp, which exists on both sides, so the write itself succeeds in the box (a
# path under tmp_path would fail for a missing parent and prove nothing).
import uuid
target = Path("/tmp") / f"sage-pth-drop-{uuid.uuid4().hex}.txt"
(sp / "zz-drop.pth").write_text(
f"import sys; open({str(target)!r}, 'w').write('x'); sys.stdout.write('PTH wrote\\n')\n")
monkeypatch.setattr(site, "getuserbase", lambda: str(base))
home = tmp_path / "inst"; (home / "scratch").mkdir(parents=True)
(home / "scratch" / "s.py").write_text("print('ok')\n")
try:
r = _dispatcher(home)._do_run(BeingIntent("run", {"path": "scratch/s.py"}))
assert r.ok, r.error
assert "PTH wrote" in r.result["stdout"], r.result # the write succeeded, inside the box
assert not target.exists(), "a write from inside the box reached the host"
finally:
if target.exists():
target.unlink()


def test_the_bind_uses_the_box_interpreters_version_not_this_processes(tmp_path, monkeypatch):
"""Nova: the box runs {interp}/bin/python3; a gateway on a different minor must not bind its
own user site at a path that interpreter never reads."""
other = sys.version_info.minor + 1
base, sp = _user_site(tmp_path, other)
_user_site_this = base / "lib" / f"python3.{sys.version_info.minor}" / "site-packages"
_user_site_this.mkdir(parents=True)
monkeypatch.setattr(site, "getuserbase", lambda: str(base))
monkeypatch.setattr(B, "box_python_minor", lambda interp=None: other)
frag = B.user_site_bind("/opt/whatever")
assert f"--ro-bind {sp.resolve()} /tmp/.local/lib/python3.{other}/site-packages" in frag, frag
assert f"python3.{sys.version_info.minor}/" not in frag, frag


def test_no_bind_when_the_box_interpreter_cannot_say_its_version(tmp_path, monkeypatch):
base, sp = _user_site(tmp_path, sys.version_info.minor)
monkeypatch.setattr(site, "getuserbase", lambda: str(base))
monkeypatch.setattr(B, "box_python_minor", lambda interp=None: None)
assert B.user_site_bind() == ""


def test_no_bind_when_the_box_minor_has_no_user_site(tmp_path, monkeypatch):
base, sp = _user_site(tmp_path, sys.version_info.minor)
monkeypatch.setattr(site, "getuserbase", lambda: str(base))
monkeypatch.setattr(B, "box_python_minor", lambda interp=None: sys.version_info.minor + 1)
assert B.user_site_bind() == ""


def test_box_python_minor_asks_the_binary(tmp_path):
interp = os.path.dirname(os.path.dirname(sys.executable))
B._BOX_MINOR.pop(interp, None)
assert B.box_python_minor(interp) == sys.version_info.minor
assert B.box_python_minor(str(tmp_path / "no-such-prefix")) is None
Loading
Loading