Skip to content

fix(sandbox): seal the scratch root stand-in around its windows - #32964

Open
shubhamkurkure wants to merge 1 commit into
kirodotdev:mainfrom
shubhamkurkure:fix/sandbox-seal-scratch-root-stand-in
Open

shubhamkurkure wants to merge 1 commit into
kirodotdev:mainfrom
shubhamkurkure:fix/sandbox-seal-scratch-root-stand-in

Conversation

@shubhamkurkure

@shubhamkurkure shubhamkurkure commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Linux, a sandboxed write under the scratch root outside the process's own scratch windows fails with an error, as it already does on macOS, instead of reporting success and losing the file.

Inside the Linux namespace sandbox the scratch root is an empty tmpfs stand-in, mounted read-write, with only the process's own directory and its session tree's directory bound back from disk. A write to any other <scratch root>/<name>/... (a stale $KIROCREW_SCRATCH from before a gateway restart, another session's path, a typo) succeeds into that stand-in. No other process sees the file at that path, the host does not have it on disk, and it is discarded with the stand-in when the writer exits. In the reported incident an agent staged a brief for its sub-agents at its old scratch path; the write succeeded and the sub-agents got No such file or directory.

Why it matters

Agents are told to stage briefs and manifests for their sub-agents under $KIROCREW_SCRATCH, and that path changes on every gateway restart while the old one stays in the transcript. On Linux the mistake is silent: the agent believes the work is staged, the sub-agents start without it, and the bytes are gone minutes later. macOS returns EPERM for the same write, so the agent sees the wrong path at once.

Not a goal

What changed (motivation → approach → change)

A write outside the scratch windows lands in a stand-in nobody else sees, and is lost. The launcher seals only caller opt-in masks (seal_windowless_masks) without a window, and the scratch root is a tier mask that always has windows.

The windows are the only places a sandboxed process writes under the root, so the stand-in can be read-only; the windows are separate mounts and stay read-write.

The change, by file:

  • src/kiro_crew/sandbox_leaves.py: _CREW_SEALED_MASK_LEAVES names the scratch leaf; src/kiro_crew/sandbox.py lists it for type checkers.
  • src/kiro_crew/sandbox_argv.py: _live_plan_host lists its spellings (both $HOME ones and a relocated data home) in PlanHost.sealed_mask_dirs.
  • src/kiro_crew/sandbox_plan.py: the namespace planner marks a matching mask Mask.seal_around_windows and emits seal_windowed_masks.
  • src/kiro_crew/sandbox_launcher_program.py reads the key, and when no stand-in root qualifies pick_stand_in_root pins the launcher's own temp directory outside every tree it hides or seals. So an inherited TMPDIR cannot leave fix(sandbox): keep the scratch window when the host empties the stand-in roots #31730's stage in a masked tree or end the launch. A bound window is the last resort; with nothing left the launch refuses. An operator read-only directory is avoided but never refused: the layer would keep a read-only copy of the stage there. src/kiro_crew/sandbox_launcher_parts/mask_stages.py seals a listed mask after every window bind, with the same MS_REMOUNT|MS_BIND|MS_RDONLY call and re-asserted nosuid/nodev/noexec. A mask that contains the root (a data home under ~/.aws or ~/.ssh) does not cover the seal: the root is placed ahead of its containers and bound back on top of each, windows included, and sealed again. Containment counts the written spelling and realpath, read before any mount, so linked containers count too. The stand-in's own entry, on the stage or a host root, gets the sealed mount bound over it. After the stage is retired, confirm_sealed_roots refuses unless each root is its read-only stand-in, windows intact, with no writable path left. A metadata read it cannot make refuses too. run_child pins the seals' parents before it mounts the stage: a recursive pin placed after copies the stage, and the copy keeps every stand-in writable at its host path past the cover and the detach, which reach the stage by descriptor. A parent inside the operator's read-only layer (feat(sandbox): operator read-only paths with write exceptions #28535) is pinned on top of it, so a write exception around it stays writable. With KIROCREW_SANDBOX_MOUNT_REPORT=1, which only the real-kernel tests set, report_mount_view writes what each sealed path reaches to stderr.
  • src/kiro_crew/sandbox_launcher_parts/exec_lockdown.py: scrub_env drops a TMPDIR, TMP, TEMP or KIRO_CHAT_LOG_FILE that names the sealed root outside every bound window. Such a value comes from a skipped window, or is an inherited spelling that main's drop (fix(gateway): drop an inherited agent scratch temp at gateway start #32308, paths as written) misses, such as a link or alias. Without it tools use /tmp instead of hitting EROFS. KIROCREW_SCRATCH is kept. Both checks apply one rule (_held_in): a value is inside a tree when its written (normalized, alias-folded) or its resolved spelling is, and a relative one is read from the directory that resolves it.
  • .github/workflows/ci.yml: test_scratch_root_seal_real_sandbox.py and test_scratch_root_seal_locked_flags_real_sandbox.py join the namespace-sandbox job, after fix(sandbox): keep the scratch window when the host empties the stand-in roots #31730's and feat(sandbox): operator read-only paths with write exceptions #28535's lines, as test_coverage_omit_contract.py requires.
  • docs/system-specs/modules/security.md describes all of it.

Backwards compatibility

Breaking: a sandboxed create under the Linux scratch root outside the process's windows (a directory, a file, mkdir -p of a stale path) now fails with EROFS. It used to report success and lose the bytes. Every tier masks the scratch root, so every Linux spawn now takes this remount. If the kernel refuses it, the spawn is refused through _mount_or_die, the launcher's fail-closed rule for any control it cannot put in place. seal_readonly already makes the same remount call on every spawn (on the home filesystem), and granted script crons already make it on a stand-in. A host that refuses the private stand-in stage's tmpfs, or whose stage will not detach, keeps running as on main: the sealed root's stand-in entry, on the host root or on the stage, is covered with the root's read-only mount, and the spawn refuses only if that cover cannot be placed or a writable path to the stand-in remains.

The seals' parents are now pinned before the private stand-in stage and the window stages are mounted, not after them. Only a stage under a pinned parent sees a difference: the launcher's temp directory under the data home's renameable parents, or the own-window fallback (production's /run/user/<uid> and /dev/shm are outside every pin). There main's later pin copies the stage, so main leaves a second, writable path to every stand-in and window stage after the detach and keeps the stage's host directory; the new order leaves neither. Nothing else about the pins changes: the same directories, the same recursive binds, before every seal, and a parent whose pin lands inside the operator's read-only layer (#28535) is pinned after that layer, as on main. A credential-masking app's own folder stays where #34339 put it, pinned after every mask, so a stage made inside it is copied with the sealed entry already covered. A process outside the sandbox that retargets a link between the two pin calls is outside what the pins defend against, and the seals still fail closed.

Writer sweep on origin/main @ 716a6a4 (#33378 names each allocation by its token alone; where it lives is unchanged): every allocator under the root runs in the gateway (agent_scratch.allocate_scratch from acp/launch.py:launch, acp/runtime_spawn_launch.py:_allocate_private_state, cron_script_child_env._allocate_cron_scratch, the deepseek and strands gate probes, platform/update_fetch._prepare_isolated_fetch; agent_scratch.sweep_dead_scratch from the gateway's maintenance wake, which #38066 and #38244 changed only in what it removes), and so does the scratch-tree index writer #30062 added (agent_scratch_trees.record_tree, abandon_tree and drop_other_row, from session_allocation_parts/get_or_create.py, which replace scratch/.trees.json through atomic_write and a .tmp beside it). Every sandboxed writer writes inside a window: agent_scratch.scratch_env points TMPDIR, TMP, TEMP and KIRO_CHAT_LOG_FILE at the process's own directory and KIROCREW_SCRATCH at it or the tree's. A spawn that copies the gateway's environment without a window (kiro-cli chat --list-models in dashboard/handlers/agents.py:_fetch_kiro_catalog) gets an inherited temp or log path under the root dropped: main's gateway-start drop takes the spelling as written, and scrub_env takes a linked or alias spelling. kiro-cli 3.1.0 also exits 0 with the same output when its log or temp directory is unwritable. Dev Fleet's sandboxed git only reads a worktree recorded under the root and refuses it (apps/builtins/dev_fleet/scratch_worktrees.py); the git worktree remove it suggests runs behind test -d, which in a sandbox passes only inside the session's own window. The other readers of the root only read it (diagnostics, messaging/outbound_files, dashboard/remote_dispatch_headroom, dashboard/chat_turn/recipient, whatsapp/turn_renderer). An app's credentialMasks (#32652, and since #36346 a whole directory) name paths under apps/<app>/data/, never under the root. The index is a hidden leaf: inside the sandbox it is under the sealed stand-in, which does not list it, and #36327 pins its parent, the root itself, before the stand-in is mounted on it.

Reader: src/kiro_crew/acp/launch.py:launch -- chat -- the own and tree directories are windows and stay read-write (test_scratch_root_seal_real_sandbox.py)
Reader: src/kiro_crew/subagent_manager/run_turn.py:_run_inner_impl -- subagent -- the shared tree is a window a second sandboxed process reads (test_scratch_root_seal_real_sandbox.py)
Reader: src/kiro_crew/acp/runtime_spawn_launch.py:_allocate_private_state -- chat -- the private-state directory is a window (test_scratch_root_seal.py::test_no_window_is_remounted_read_only)
Reader: src/kiro_crew/cron_script.py:run_script_sandboxed -- cron -- the run's directory is a window, and without one the run's temp dir is the gateway's (test_scratch_root_seal.py::test_a_windowless_scratch_root_is_sealed_once)
Reader: src/kiro_crew/cron_script.py:run_command_sandboxed -- cron -- same window as the script cron (test_scratch_root_seal_real_sandbox.py)
Reader: src/kiro_crew/dashboard/handlers/agents.py:_fetch_kiro_catalog -- chat -- an inherited temp or log path under the root is dropped (test_scratch_root_seal.py::test_an_inherited_temp_path_under_the_sealed_root_is_dropped)

Tests

  • test/test_scratch_root_seal.py:
    • Planner: the scratch root is sealed around its windows on a literal host, under the folded data-home spelling, in the live plan for each tier with and without seal_hidden_dirs, and for a relocated data home and a patched leaf table. A lifted root, a partial lift by a visible directory below it, an unlisted mask and the caller opt-in are unchanged. Seatbelt carries no flag and still denies the write.
  • test/test_scratch_root_seal_containers.py (moved out of the file above to keep it under the 2,000-line cap):
    • Containing mask: with the container after the root, before it, or ~/.ssh, with and without windows, the root stays sealed on top, its windows writable and the container's tree hidden; each window is bound once, the recursive re-attach lands on the root and is sealed again, a re-attach that misses the root refuses, and without a container nothing is held or re-attached. The same holds for a container reached only through a link (a linked ~/.aws before or after the root, a linked ~/.ssh, a data home or $HOME reached through a link): one rule decides containment and the part below from the written or the resolved spellings, read before the first mount, and a crew leaf or a crew file mask after a linked container still refuses, as on main.
    • Operator layer: a write exception at the root, a window, a path below the root or a directory holding it is refused on both backends.
    • Last check: a ~/.ssh link moved aside while its spelling is read and put back before it is masked ends in a refusal; so do a root covered by a later mount, a seal that is not read-only, a window that is gone or another directory, a stand-in entry left open or still writable, and a cover that cannot be placed. A detached stage, a stage that will not detach, and a closed entry pass, as does every layout above; run_child pins the seals' parents right before the stage and confirms right after retiring it. The autouse read-back sits on _floor_monkeypatch, so a test-local undo() keeps it (checked without undoing the shared stack).
    • Launcher: one read-only remount on the stand-in, after both window binds and carrying the stand-in's locked nosuid/nodev/noexec, and none on a window. A windowless root is sealed once, an unlisted mask keeps the windowed exemption, and a payload without the key makes no remount through place_masks. A full place_masks run leaves only the two window mount points in the stand-in.
    • Launcher temp: with no stand-in root and TMPDIR naming the root itself or a directory below it, the private stage is made outside the root and its host directory is gone once the masks are placed (without the pin it is made under the root, as on main). With the stage refused, the masks after the seal still land, where without the pin the next create raised EACCES (the root) or ENOENT (below it). The launcher's stand-ins land outside the root, its windows, a sealed path, every other mask and, on the strict tier, ~/.ssh, also when the value is spelled through a crew-home alias or a plain symlink to the data home, or is relative (TMPDIR=.); a link outside every tree that points out stays outside; a cached value is cleared; with a stand-in root, tempfile is never asked. With nothing outside usable, the own window holds the launcher's temp; a mask inside the window, a linked window and the working directory are never taken, and the launch refuses with a remedy that scratch_env does not overwrite.
    • Spelling classes: one table per guard, a row per class (relative, ., .., trailing, doubled and leading doubled slashes, crew-home alias, symlink into, out of and inside a window into the root, a missing path, a symlinked parent), on the root and on the window side.
    • Environment: inherited temp and log paths under the root are dropped, roots and windows compared normalized, alias spellings folded and symlinked spellings resolved, and values in a window, outside the root, KIROCREW_SCRATCH and an unsealed or absent mask are kept. A skipped unvouched window is sealed over and its temp dropped.
  • test/test_scratch_root_seal_app_masks.py: with an app declaring credentialMasks (feat(app-kit): let an app's manifest mask its own credential files #32652), the live plan in every tier lists the declared files after the scratch root and seals only the root, as without the declaration; the app's own backend lift leaves the root sealed; and the launcher run on that plan places the root, seals it once with both windows writable, and masks the declared file, without moving any mask.
  • test/test_sandbox_masked_dir_readonly.py: an opted-in mask with a window keeps its writable stand-in; one in seal_windowed_masks is sealed after its window bind.
  • test/test_scratch_root_seal_real_sandbox.py (namespace-sandbox CI job, every tier, relocated and $HOME/.kiro/crew data homes, and a data home under ~/.aws with the .aws mask after the root (Codex) and before it (strict, cc); with ~/.aws a link, all three refuse at a crew leaf before running, as on main): mkdir, file create and a stale makedirs fail with EROFS; both windows stay writable; stat, listdir and realpath work; another process sees the shared write, a respawn its own, the host both. An inherited stale TMP and log path are dropped and tempfile falls back. The mount over the root is checked to be read-only and, when the private stage was used, a tmpfs that kept nosuid/nodev (otherwise it carries the stand-in root's own bits). With no stand-in root and only the own window usable (the rendered launcher's tempfile limited to the temp variables), the window holds the stage, stays writable and keeps nothing of it. The plan names no stand-in root, so the launcher's own temp directory under tmp_path holds its private stage and nothing is made in /dev/shm. Under a real kernel the last check passes the Codex layout and refuses it with the re-attach removed; with the stage refused, a write through the stand-in's own entry fails with EROFS, as it does on a stage left mounted, and a stage left mounted in the own window is out of the agent's reach. Namespace-free tests check the payload, where the launcher makes its first stand-in, the edited launchers and the one-line edit. Every launch sets KIROCREW_SANDBOX_MOUNT_REPORT=1 and prints its whole stderr, so a failure shows the uncut sandbox: BLOCKED line and the launcher's mount report. The mount sequence of test_scratch_root_seal_stage_mounts.py is run on the kernel, pinned first and pinned after, and must give the model's answers. With an operator read-only entry over the scratch root (the data home, or tmp_path, which holds the stage too) the windows stay writable and shared and every other create fails with EROFS; a seal parent inside an operator write exception, two levels in or a link, keeps its write access; with the system temp directory inside an operator entry, the own window holds the stage, nothing of it is in that directory or mounted below it, and the one mount at it is the layer's own read-only bind of it. With scratch/.trees.json and a .tmp beside it on disk, the plan pins the root, and inside neither is listed, the index cannot be read and a write to either fails with EROFS, while mountinfo shows the sealed stand-in on top of the root's own pin; the host copy is unchanged, and the test process, playing the gateway, then replaces and reads it.
  • test/test_scratch_root_seal_stage_mounts.py: a model of the kernel's mount table next to the renaming fakes (a bind leaves its source's entry, the read-only flag is per mount, a recursive bind copies the mounts below it, a descriptor keeps naming the mount it was opened on, a detach takes the mounts below it, rmdir of a mount point is EBUSY), checked on a short mount sequence. run_child over a stage under a seal parent: a stage that detaches leaves no path to the stand-in and no host directory, and one that will not detach, or a refused stage, leaves the entry read-only. With the pins after the stage, the first two refuse with the message the real kernel gave. The mount report is written only when asked, also on a refusal. The model also lists its mounts as mountinfo and gives each descriptor's mount ID, which the operator's layer reads. With agent.sandbox_readonly_paths set, a seal parent two levels inside a write exception, a pinned link inside one, and a parent spelled through a link into the drive keep the exception writable (pinned under the layer, the first and third stay read-only and the second leaves the whole exception read-only); an entry over the scratch root, or over the stage too, leaves the root sealed, its windows writable and no writable mount of the stage. Which pins land inside the layer is read once, so a link retargeted between the two pin calls still leaves its parent pinned once. With no stand-in root, a temp candidate inside an operator read-only directory, or inside one of its write exceptions, is passed over for one outside it, which leaves no copy of the stage mounted at its host path; with only such candidates the stage still goes there and the spawn runs; an operator entry inside the scratch root does not make it a candidate; and with the system default inside an entry, the own window is taken. On the live plan, which pins the scratch root itself as the parent of the hidden scratch/.trees.json (fix(scratch): resume a conversation into the scratch tree it had #30062, fix(sandbox): pin the parents of every hidden crew-home leaf #36327), the root's pin is placed before the stage, or on top of the layer when an operator entry holds the data home or the stage too, and the sealed stand-in sits on it: the index and a .tmp beside it reach only the read-only stand-in, which does not list them, the windows stay writable, no copy of the stage is writable and the host's index is unchanged, whether the stage detaches, stays mounted or is refused.
  • test/test_tmpdir_helpers.py: the shared-temp ratchet also fails on a temp dir made directly in /dev/shm.
  • test/test_scratch_root_seal_locked_flags_real_sandbox.py (namespace-sandbox CI job): on a flag-locked tmpfs in nested namespaces, the windowed seal lands and its window stays writable (skips where namespaces are unavailable). It reuses the stages of test/test_sandbox_seal_locked_flags.py, which is unchanged and stays off the job.
  • test/test_sandbox_launcher_program.py and test/test_sandbox_argv_launcher_plan.py: the stage lists put the pin in run_child, before the stage, and the pins inside the operator's layer right after it.
  • test/test_sandbox_refactor_generated_programs.py, test/test_sandbox_launcher_program.py, test/test_sandbox_refactor_facade.py: the golden payload, the payload helper and the facade inventory carry the new key and name; the fake libc's read-only remounts read back as read-only (read_back_read_only_remounts); test/test_sandbox_mount_checked.py counts the new guarded bind.
  • test/test_sandbox_mount_pinned_target.py: a failed fstat on either pin of a stand-in (the identity, and the sealed root's entry) refuses with the BLOCKED line naming it, and closes the descriptor once.
  • test/test_scratch_root_seal_stage_mounts.py: through run_child, an EIO from each identity or mount-flag read the seal adds (a staged window, the stand-in reached by name as its entry is covered and at the last check, the entry at the last check, both read-only flags) refuses with the BLOCKED line naming that path, closes its descriptor once and execs nothing; with none failing the agent is exec'd.
  • test/test_sandbox_launcher_symlinked_protected_name.py: every read of a sealed root by its name goes through _reach_stand_in, whose exact body and callers the ratchet checks by AST, and planted opens, a dropped identity check, an unlisted caller, an unchecked result, a missing read-only check, and a failed identity read passed off as no path or left open each make it fail.

Determinism of the new and changed tests (test_scratch_root_seal_stage_mounts.py, test_scratch_root_seal_containers.py, test_scratch_root_seal_real_sandbox.py, test_sandbox_argv_launcher_plan.py): 20 runs at -n0, then 10 at -n 4 --dist loadgroup --max-worker-restart=2 with test_sandbox_launcher_program.py, test_sandbox_mount_checked.py and test_sandbox_stand_in_private_stage.py as co-tenants, all green; one shuffled order of their 163 tests (seed 32446) green. test_scratch_root_seal_app_masks.py: 20 runs at -n0, then 10 at -n 4 --dist loadgroup --max-worker-restart=2 with test_app_credential_masks.py, test_scratch_root_seal_containers.py and test_sandbox_launcher_program.py as co-tenants, all green. The operator-layer and temp-fallback tests (-k "operator or read_once or every_candidate_inside or inside_a_masked_tree or leaves_the_stage_to_the_own_window" in test_scratch_root_seal_stage_mounts.py and test_scratch_root_seal_containers.py): 20 runs at -n0, then 10 at -n 8 --dist loadgroup --max-worker-restart=2 with test_sandbox_launcher_program.py, test_sandbox_readonly_layer.py and test_sandbox_mount_checked.py as co-tenants, all green. The hidden-index test (-k hidden_index in test_scratch_root_seal_stage_mounts.py, 5 cases): 20 runs at -n0, then 10 at -n 4 --dist loadgroup --max-worker-restart=2 with test_scratch_root_seal_real_sandbox.py, test_sandbox_hidden_leaf_parent_pins.py and test_scratch_root_seal_containers.py as co-tenants, all green; one shuffled order of the 88 tests of test_scratch_root_seal_stage_mounts.py and test_scratch_root_seal_real_sandbox.py (seed 20614) green. The new real-kernel test runs only on a kernel with user namespaces: the namespace-sandbox job and the owner's run.

Proof: PROVEN test/test_sandbox_launcher_program.py::test_a_child_run_takes_every_stage_once_in_order, test/test_sandbox_launcher_symlinked_protected_name.py::test_the_sealed_root_read_is_the_only_open_outside_the_pin_and_is_checked, test/test_sandbox_masked_dir_readonly.py::test_an_opted_in_windowed_mask_listed_to_seal_around_its_windows_is_sealed, test/test_sandbox_mount_checked.py::test_every_tier_routes_all_eight_mounts_through_the_guard, test/test_sandbox_mount_checked.py::test_break_arm_reintroduce_raw_is_caught_by_the_tier_sweep (head 5202c4b)

Gate proof: tree 42365e9dd768; ran 24; skipped none

Manual verification

The real-kernel tests cannot run inside an agent sandbox, which has no user namespaces. They and the issue's two-process e2e test (which fails on main) are run from a host terminal against this head by an owner-check script, which also runs every file on the namespace-sandbox CI step; that run's verdict is reported on this PR.

Related Issues

Closes #31844

Sibling sweep

Swept: git grep -n "extra_private_dirs=" -- src/ (every window producer; all windows sit under the scratch root) and the hidden leaves with a writable stand-in and a possible in-sandbox writer
Sibling: src/kiro_crew/sandbox_leaves.py:311 -- tracked in #22653
Sibling: src/kiro_crew/work_root.py -- not affected -- no sandboxed code writes under work, no window or env var names it; left for a follow-up issue
Swept: git diff origin/main HEAD -- src/kiro_crew/sandbox_launcher_parts/ | grep '^+' | grep -n 'stat' (every fstat, fstatvfs or stat this diff adds, for a failed read that escapes as a bare OSError instead of the BLOCKED line #34181 set for a stand-in's pin). Changed: the stand-in pin (pinned_mounts.py:736, used at mask_stages.py:771 and pinned_mounts.py:761), a staged window's identity (mask_stages.py:247), _reach_stand_in (738), and both read-only flag reads (1429, 1482). Not affected: the window stat in confirm_sealed_roots (1449) already refuses by path in its own handler, and the mount report (1531) only prints a failed read, behind a variable only tests set. Reads already on main are left as they are.
Swept: every mount run_child places before seal_operator_readonly (#28535), which the layer's recursive bind copies and remounts read-only: the seals' parent pins, the stand-in stage and the window stages. Changed: a pin that lands inside the layer is placed on top of it (_pinned_inside_layer). Changed too: the fallback stage, which the layer copies read-only with its window stages when it is under an entry, is made outside every entry when another place is usable (_pin_tempdir_outside_masks). Not affected: the stage on /run/user/<uid> or /dev/shm, since the plan refuses an entry holding either.
Swept: git grep -n '"scratch/' -- src/kiro_crew/sandbox_leaves.py (every hidden crew-home leaf under the sealed root, whose parent #36327 now pins with the seals' parents). Not affected: scratch/.trees.json (#30062), the only one, has the root itself as its parent; that pin is placed before the stage, or on top of the operator's layer, and the sealed stand-in is mounted on it, so the seal, its windows and the cover hold and the index stays out of reach (test_scratch_root_seal_stage_mounts.py, and on a real kernel test_scratch_root_seal_real_sandbox.py).
Sibling: src/kiro_crew/sandbox_launcher_parts/mask_stages.py -- changed here
Sibling: src/kiro_crew/sandbox_launcher_parts/pinned_mounts.py -- changed here

Pattern harvest

Rule candidate: review-prompt
Pattern: a bind-mask stand-in left writable where no sandboxed process needs to write, so a stray write reports success and is lost with the namespace

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@shubhamkurkure
shubhamkurkure requested a review from Zedmor November 8, 2026 06:19
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 8, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 8, 2026
@shubhamkurkure
shubhamkurkure force-pushed the fix/sandbox-seal-scratch-root-stand-in branch from 3a49906 to 5542997 Compare November 9, 2026 23:11
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 9, 2026
@shubhamkurkure

Copy link
Copy Markdown
Contributor Author

Hi @bolichen97 and @Zedmor, when you have a moment, would you mind reviewing this PR? It covers part of #31844: on Linux, a sandboxed write under the scratch root outside the process's own scratch windows now fails with an error, as it already does on macOS, instead of reporting success and losing the file. I checked it on a real Linux kernel as well as in the unit tests. It merges cleanly with current main.

Please let me know if you would like anything changed. Thank you for your time!

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 10, 2026
@shubhamkurkure
shubhamkurkure force-pushed the fix/sandbox-seal-scratch-root-stand-in branch from 5542997 to 9eba656 Compare November 10, 2026 21:57
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 10, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 25% chance that this change introduces a defect, above the 12% limit for approving on its own.

On Linux the PR makes the scratch root's stand-in read-only after each process's own windows are bound back, so a write outside them fails with EROFS instead of being lost, as on macOS. I checked the planner flag, the remount after the window binds, the re-attach when the root sits inside ~/.aws or ~/.ssh, and the final refuse-unless-sealed check. I also checked the temp and log variable drop, the earlier pin order and every writer under the scratch root. All writers run in the gateway or write inside the process's own windows; I found no concrete regression or fail-open path. Not blocking: the kernel-level tests had not run in CI on this head (workflows awaiting approval), the Sensitive Change Review failure is a missing template, and one file sits just under the 1,600-line split target.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 537774d779 · 6971 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@shubhamkurkure
shubhamkurkure force-pushed the fix/sandbox-seal-scratch-root-stand-in branch from 9eba656 to f11ef4e Compare November 11, 2026 17:52
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 11, 2026
@shubhamkurkure
shubhamkurkure force-pushed the fix/sandbox-seal-scratch-root-stand-in branch from f11ef4e to 537774d Compare November 14, 2026 23:20
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 14, 2026
On Linux the scratch root is masked by an empty tmpfs stand-in, and a
spawn's own directory and its session tree's directory are bound back
inside it as private windows. The stand-in stayed writable, so a write
to any other path under the root (a stale $KIROCREW_SCRATCH, another
session's path) reported success, was invisible to every other process
and to the host, and was discarded with the stand-in after the writer
exited. The macOS Seatbelt profile already denies that write.

The planner now marks the scratch root's mask seal_around_windows (the
leaves in sandbox_leaves._CREW_SEALED_MASK_LEAVES, in every spelling
_live_plan_host lists) and carries it to the launcher as
seal_windowed_masks. The launcher remounts that stand-in read-only
after it binds every window. The windows are separate mounts and stay
read-write, so such a write now fails with EROFS. A mask that contains
the root (a data home under ~/.aws inside the .aws mask a Codex session
or the strict and cc tiers place, or ~/.ssh on the strict tier) does not
cover the seal: the root is placed ahead of its containers, and once
each container is placed the sealed root, windows included, is bound
back on top of it recursively and sealed again. Containment is judged
by the written spelling and by realpath, both read before the first
mount, so a ~/.aws or ~/.ssh that is a link, or a data home reached
through one, counts as a container too. The stand-in's own entry, on
the private stand-in stage or on a host root when the stage is refused,
is covered with the sealed root's read-only mount. Once the stage is
retired, the launcher opens each sealed root by its name and refuses
the spawn unless it is the sealed stand-in it mounted there, read-only,
with each window still the directory staged for it, and no writable
path left through the stand-in's own entry. A stage that will not
detach keeps its warning.

With no stand-in root, the launcher pins its own temp directory outside
every tree it hides or seals (every mask, every seal, and ~/.ssh on the
strict tier) before it makes its private stand-in stage, so an inherited
TMPDIR under the scratch root cannot leave the stage behind in the
host's tree or, when the stage is refused, end the launch. A window the
launcher will bind is used only when nothing outside those trees is
usable, the working directory never is, and with nothing left the launch
refuses, naming /run/user/<uid>, /dev/shm and /tmp as the fix. An
operator read-only directory (agent.sandbox_readonly_paths) is avoided
too but never refused: its layer copies a stage below it read-only,
write exceptions included, and that copy would stay at the stage's host
path, so it is taken only by a last pass, when no earlier pass accepted
tempfile's pick. scrub_env drops a TMPDIR, TMP, TEMP or
KIRO_CHAT_LOG_FILE that names the sealed root outside every bound
window, so tools that write there unasked use their own default instead
of failing. Both checks apply one rule: an empty value is skipped, a
relative one is read from the directory that resolves it (the launcher's
for the pin, the child's for the drop), and the value is judged as
written, normalized and folded through crew_home_aliases as the planner
folds the masks and windows, and as realpath resolves it, so a value
inside a tree under either spelling counts as inside. The caller opt-in
seal (seal_windowless_masks) is unchanged. The masks an app declares in
credentialMasks are files under its own data directory, listed after the
scratch root and never sealed, so they leave the seal, its order and its
windows as they are.

The seals' parents are now pinned before the private stand-in stage is
mounted, not after it. A pin is a recursive bind, so a later one copies
a stage below a pinned parent (a temp directory under the data home's
parents, or the own-window fallback), and the copy keeps every stand-in
writable at its host path past the cover and the stage's detach, which
reach the stage by descriptor. A parent whose pin lands inside the
operator's read-only layer (agent.sandbox_readonly_paths) is pinned on
top of that layer instead, like every crew mount there: the layer has
made every mount below it read-only, a copy of the stage included, and a
pin under it would be copied read-only too, so a write exception around
it (a parent of a read-only entry nested in one) would lose its write
access. With KIROCREW_SANDBOX_MOUNT_REPORT=1, which only the real-kernel
tests set, the launcher writes what each sealed path reaches to stderr.
The in-process tests gain a model of the kernel's mount table, with its
mountinfo and mount IDs, which the real-kernel tests check against the
kernel. The real-kernel tests join the namespace-sandbox CI job: the
scratch-root seal with its stand-ins in the launcher's own temp
directory under the test's tmp_path, and the seal on a flag-locked tmpfs
in nested namespaces.

The scratch-tree index (scratch/.trees.json) is a hidden crew-home
leaf, so the scratch root itself is among the pinned parents, and the
sealed stand-in is mounted on that pin. Inside the sandbox the index and
its .tmp staging files are not listed, not readable and not writable,
and the gateway keeps reading and replacing them on disk. The model and
the real-kernel tests check that layout.
@shubhamkurkure
shubhamkurkure force-pushed the fix/sandbox-seal-scratch-root-stand-in branch from 537774d to 5202c4b Compare November 18, 2026 16:33
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Linux sandbox: a write under the scratch root outside the process's windows succeeds into a throwaway tmpfs (stale $KIROCREW_SCRATCH loses the file)

2 participants