Linux view: reproduce a grant's link chain, so a venv python starts - #99

Description

Bug fix, no interface change. No box.toml key, CLI flag, record field, telemetry name, or pub use changes, and RECORD_VERSION stays 21. The change is internal to the Linux namespace view in containment.

On Linux, a virtualenv python as [agent] command (or [tool.<name>] command) does not start. decisions.md already says Box execs a program through its link, so that CPython finds pyvenv.cfg, and grants the link's target. The Linux view did not keep that promise for a chain of more than one link. A venv's bin/python -> python3 -> /usr/local/bin/python3 -> python3.13 failed in two ways:

• When the venv is granted: the venv bind brings in its own two links, but the middle hop /usr/local/bin/python3 is in no grant and is not in the view. exec fails with ENOENT.
• When it is not: the view bound the spelling as a second file. The program then runs as that spelling, so /proc/self/exe and the loader's $ORIGIN name the venv's bin. The python.org build carries RUNPATH $ORIGIN/../lib, so libpython3.13.so.1.0 is not found. Box's closure walk had expanded $ORIGIN against the identity, so the walk and the loader disagreed.

The view now reproduces each link that a grant's lookup traverses, with the host's text, and binds only the identity. The kernel then walks the same chain in the view that it walks on the host.

Load-bearing decisions:

1. A link node is a host link whose parent is canonical. /bin/sh on merged-/usr lstat's as a link because /usr/bin/sh is one, but /bin is itself a link, so a copy of it in a real /bin would dangle. Such a spelling, reached through a linked ancestor directory, keeps its bind as today. This is the residual, recorded in decisions.md. A command never reaches it, because canonical_route makes its directory canonical first.
2. A link that a directory bind brings in is left to that bind. Only links outside every bind are created, in the staging tmpfs.
3. An entry spelled beneath a link is planned at the host's resolution of it. The first version refused such entries. That refused every tool on merged-/usr: a tool's /lib read root is a link there, and the loader's program header names /lib/ld-linux-*.so.1. A mountpoint is never made through a link, because that could lead into a bind and onto the host. Refusals are re-spelled too, so a denial stays in force.
4. W^X holds across the merge. When a re-spelled entry meets an entry at its resolution, a dependency (loader or library) is dropped, a grant replaces a dependency, and two grants keep their union. A dependency never adds exec to a writable grant.
5. The link text in the view is the text the grant judged. A link whose text no longer leads to a node that the grant recorded is refused at plan time. A link on the read-only root cannot be changed by the workload. A link under the writable /tmp can be replaced, but only after the trampoline's exec, and the workload can already make links there to anything in its view.

Out of scope (follow-ups):

• [FEATURE] Linux filesystem grants for Python data-science stacks (dlopen'd libraries, venv interpreter) #30 part B: dlopened extension modules still need hand-written exec grants (site-packages, and lib-dynload on python.org builds). That needs a design call against the decisions.md rule that Box derives no exec literal from a runtime's dependency graph, so I will propose it on [FEATURE] Linux filesystem grants for Python data-science stacks (dlopen'd libraries, venv interpreter) #30 first.
• Links under the kernel's own filesystems (/proc/self) fail closed when the view is set up, not with a named refusal at plan time. Box never grants these.

For maintainers: as an outside contributor, my CI and Auto Strands Review runs wait for approval (action_required / manual-approval). Could someone approve them? Thanks.

Related Issues

Part A of #30 (the issue stays open for part B).
Related: #21 / #40 (x86_64)

Type of Change

Bug fix

Testing

• Fork CI (run): every job green, including Unit Tests on ubuntu-latest (x86_64) and macos-latest, both Containment / Deterministic legs (ubuntu-24.04-arm, macos-latest), Lint, and Verdict. The first run (38056671462) failed one x86_64 unit test, a_read_root_on_a_loader_directory_is_bound_executable_and_read_only. It expected the loader directory bound at its spelling, but on ubuntu-latest that spelling is the link /lib64 -> usr/lib64, which the view now reproduces as a link. 05f3592 checks the bind at the identity instead. I reproduced the failure on aarch64 by adding a /lib64 link, and the suite passes with and without it.
• Tests that fail on main and pass here:
  • contains_exec_target_linux.rs::a_program_through_a_link_chain_runs_as_its_identity: on main, /proc/self/exe is the spelling.
  • contains_exec_target_linux.rs::a_link_chain_leaving_a_bound_tree_execs: on main, exec fails with ENOENT.
  • box_direct_filesystem.rs::a_venv_shaped_command_runs_as_its_identity: on main, the run exits 4.
  • The chain in each test is a copy of readlink, so CI needs no Python.
• Plan tests (view.rs): each hop planned as a link, hops inside a bound tree, a shared hop planned once, a hop under a read-only empty directory, entries and refusals beneath a link, the real /lib on merged-/usr, the four W^X merge cases, a retargeted link, and the linked-ancestor residual.
• Linux aarch64 locally (finch, rust:1-bookworm, privileged):
  • strands-box-containment: all tests pass.
  • strands-box: 885 pass. The 38 failures are in suites that fail the same way on main in that environment, measured by swapping main's view.rs back in: runtime_mcp_start 4, native_egress_mcp 5, runtime_mcp_policy_staging 25, box_shell signalled binary 1, run::hardening 2, box_direct_filesystem rename EBUSY 1.
• Manual acceptance in python:3.13-slim (aarch64), which CI cannot show:
  • A python.org venv and a Debian venv python start as [agent] command, with and without a read grant on the venv. With the grant, sys.prefix is the venv.
  • numpy 2.5.3, pandas 3.0.6, and requests import from the venv, with hand-written exec grants on site-packages and lib-dynload (part B removes the need for these).
• I ran cargo fmt --all and the just clippy gate.
• Not run locally: the other workspace crates, because none depends on containment and the full build did not fit the local disk (CI runs them). Also not run: Kata.

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• My changes generate no new warnings

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

🤖 Generated with Claude Code