Skip to content

fix(sandbox): skip a leaf absent under a mask the launcher already placed - #15564

Merged
buluoray merged 1 commit into
mainfrom
fix/sandbox-nested-mask-absent
Oct 1, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/sandbox-nested-mask-absent

Conversation

@buluoray

@buluoray buluoray commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Sandboxed spawns succeed again on hosts where a hidden leaf sits under a directory the same launcher hides, so the kiro-cli readiness probe passes and Settings loads.

Since #15252 landed, every readiness probe spawn on my host is refused with:

sandbox: BLOCKED -- cannot pin /home/rayrayxu/.kiro/crew/diag to mask it: the object a pass
established at this name has vanished (it is absent), so the mask cannot cover it and whatever
is recreated there would be exposed.

gateway.log carries it every 30 seconds; KAS managed MCP initialization failed: kirocrew-core: failed (backend gone: exit rc=1) follows from the same refusal; /api/models answers 503 and the Settings page shows Failed to load config. The diag directory is present and the gateway is writing to it the whole time.

Why it matters

Every operator whose sandbox tier hides a directory that is itself an ancestor of a listed leaf is hit. The readiness probe always is: kiro_prerequisite passes the whole data home (~/.kiro/crew) in extra_hidden_dirs, and every _CREW_HIDDEN_LEAVES entry lives under it. With the probe refused the CLI is reported unverified, the model list is unavailable, and Settings cannot render its config panel. No sandbox level short of lowering it clears the refusal.

Not a goal

  • Changing what the identity pin refuses for a name that is NOT under one of this launcher's own masks -- a moved object, a swapped-in decoy, a planted link all refuse exactly as fix(sandbox): re-land the launcher mask identity pin, skipping its own stand-in #15252 left them.
  • Changing which paths the readiness probe hides, or the builder's lexical subtraction of nested REQUIRED_MASK_TARGETS.
  • Any change to _verify_masked_name or the read-only seal loop.

What changed (motivation → approach → change)

Root cause. _pin_mount_path judges an absent name by its carried expectation: a pass recorded an object here, nothing is here now, so the object moved -- refuse. That is right for a name nothing else covers. But the mask list carries a leaf together with a directory above it. The directory loop masks ~/.kiro/crew by binding an empty stand-in over it; from then on ~/.kiro/crew/diag is absent from every look at its name. The file loop is offered every directory entry too (files_json = files + hidden_dirs) and always runs after the directory loop, so it reaches diag, opens the parent (the stand-in), finds no diag, sees an expectation carried, and refuses. The builder already subtracts nested targets from REQUIRED_MASK_TARGETS for this exact reason ("absent because my parent's mask covers me"), but that subtraction never applied to the carried expectations #15252 added, and it could not: it is lexical against the mask list, while the second spelling of a masked directory (a symlinked $HOME) is not in that list.

Approach. Decide it against the filesystem, at the pin, the way #15252 decides the second-spelling case. The launcher records in _MASKED_NAMES every name it has confirmed reaches one of its own stand-ins: each directory mask after its read-back (_verify_masked_name), the nested re-hide, the ssh mask, and each second spelling the pin finds already covered. When a name is absent -- the leaf itself, or the directory holding it -- _covered_by_own_mask walks the name's proper ancestors; if one is recorded, that ancestor is resolved again NOW and must still reach the recorded stand-in. Names rather than identities, because the second spelling of a masked directory has no mount of its own and no expectation to compare a stand-in against, yet covers the leaves under it. A recorded ancestor that no longer reaches its stand-in refuses the leaf rather than walking higher. A link at the ancestor is accepted only when it is the link the pin itself followed, as the read-back accepts it. A private window met on the way up ends the walk with a refusal: the window mounts the real tree back over the stand-in read-write, so a leaf beneath it (apps/meetings/data/edits under the apps/meetings/data window) resolves into the real tree and no stand-in above covers it -- the launcher records every window it binds in _BOUND_WINDOWS for exactly this test.

Change. src/kiro_crew/sandbox.py (launcher template): _MASKED_NAMES, _BOUND_WINDOWS, _covered_by_own_mask, the check ahead of both absence refusals in _pin_mount_path, the four mask recording sites and the window recording site. docs/system-specs/modules/security.md gains the paragraph that states the invariant and the residual it does not cover.

Backwards compatibility

Compatible: the only behaviour that changes is an absent name whose ancestor verifiably reaches this launcher's own stand-in, which today refuses the spawn and now skips as the already-masked leaf it is. Every other absence, and every present-but-changed occupant, takes exactly the branch it took before.

Tests

test/test_sandbox_mount_pinned_target.py, against the shipped pin lifted from the built script:

  • test_a_leaf_absent_under_a_directory_this_launcher_masked_skips -- a leaf and a deeper leaf under a masked parent skip in both absence branches, in the dir loop's kind and the file loop's kind, and as a required target.
  • test_an_absent_leaf_skips_only_when_the_ancestor_still_reaches_its_stand_in -- the two controls: no recorded name refuses has vanished; a recorded name whose ancestor now reaches a different directory refuses has vanished.
  • test_the_directory_loop_records_every_name_it_masks -- the shipped loops write the record, after the read-back, for the credential-dir and ssh masks, and every recorded stand-in is one this launcher registered.
  • test_a_leaf_absent_inside_a_bound_window_is_not_covered_by_the_mask_above -- edits renamed away between the window bind and the nested re-hide refuses has vanished; the same absence with no window bound skips.
  • test_the_directory_loop_records_every_window_it_binds -- the shipped loop records a bound window and its mask root.
  • test_a_second_spelling_that_reaches_this_launchers_own_stand_in_skips now also asserts the covered spelling is recorded.

Mutation check, baseline green first, each mutation classified red / green / broken: removing the leaf-absent skip, removing the parent-absent skip, trusting the record without re-resolving, dropping the dir-loop record, dropping the second-spelling record, stopping the ancestor walk at the parent, dropping the window check, and dropping the window record each turn at least one test red (eight mutations, all red, baseline green). test/test_sandbox*.py: 2088 passed, 1 pre-existing failure (test_kill_broadcast_denied_targeted_allowed_e2e, red on unmodified main in this environment too).

Manual verification

Against the REAL launcher on the affected host (symlinked $HOME, /home/u -> /local/home/u), sandboxed_spawn_argv(["/usr/bin/env", "/bin/true"], mode="standard", extra_hidden_dirs=(~/.kiro/crew, ~/.kirocrew)) -- the probe's exact shape -- run without the systemd-run scope: rc 1 with the refusal above on main, rc 0 on this branch. Inside the fixed sandbox ls -A ~/.kiro/crew | wc -l prints 0 and both ~/.kiro/crew/diag and /local/home/u/.kiro/crew/diag answer No such file or directory, while the host diag holds 3 entries: the masks hold, the leak the refusal guards against is not opened.

Related Issues

Regression from #15252 (re-land of #13715). No issue filed.

Pattern harvest

Rule candidate: review-prompt
Pattern: a fail-closed check on "name absent" added to a loop whose earlier iterations legitimately remove names (mask-then-list-under-it); the new refusal must be tested with the list shapes real callers pass (extra_hidden_dirs = whole data home), not only with a single leaf.

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

Contribution License Agreement

@buluoray
buluoray requested a review from a team as a code owner September 30, 2026 20:43
@buluoray
buluoray requested a review from kyleseaman September 30, 2026 20:43
@buluoray
buluoray force-pushed the fix/sandbox-nested-mask-absent branch 2 times, most recently from ae5da10 to 56224a5 Compare September 30, 2026 21:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of ac627010d595eeed38cbe25c866424524536154e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the second-spelling record key (sandbox.py:8950) is normalized like the walk's dirname-derived keys — a trailing-slash key silently keeps the refusal.

[DESIGN-REVIEWED] ac62701

Description read

[DESCRIPTION-READ] 9d274df937accfa2c0cb6a03a3be9316397c707c89cb79606bc67fbd58855161

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of ac627010d595eeed38cbe25c866424524536154e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the one premise that rules out the smaller fix: that a symlinked-$HOME second spelling is truly absent from the mask list, so the builder's existing lexical subtraction (sandbox.py:8229-8238) could not simply be extended to carried expectations.

What this change ships

Inventory (7 items) — 7 justified

Intent: make sandboxed spawns succeed again when a hidden leaf sits under a directory the same launcher already masked — a FIX (regression from #15252, reproduced in the description and pinned by tests that fail on base).

  1. Readiness-probe spawns no longer refuse at ~/.kiro/crew/diag; /api/models and Settings recover — justified
  2. The launcher records each name it confirmed masked and re-resolves the ancestor before skipping an absent leaf — justified
  3. A leaf absent inside a bound private window still refuses (the walk stops at _BOUND_WINDOWS) — justified
  4. The second spelling of a masked directory now covers leaves listed under it — justified
  5. A required mask target absent under a placed mask skips instead of killing the spawn — justified
  6. security.md gains the invariant paragraph in the same commit — justified
  7. Tests: both absence branches, two refusal controls, recording of masks and windows — justified

[FIRST-PRINCIPLES-REVIEWED] ac62701

Description read

[DESCRIPTION-READ] c359d23f90ec18646242dcf6fa8f82ce3fc1e8c736a818cc985bcaed57d847a5

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of ac627010d595eeed38cbe25c866424524536154e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ac62701

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ac627010d595eeed38cbe25c866424524536154e: <one-sentence reason>

…aced

#15252 made an absent name that a pre-spawn pass recorded an occupant for
refuse the spawn, so a protected object moved between the pass and the
pin fails closed. A mask list also carries a leaf together with a
directory above it: the readiness probe hides the whole data home while
every crew hidden leaf under it stays listed. Once the directory's
stand-in is bound, the leaf is absent from every later look at its name,
and the file loop -- offered every directory entry, always after the
directory loop -- reached ~/.kiro/crew/diag with its expectation still
carried, read the absence as the object having vanished, and refused.
Every probe spawn failed, /api/models answered 503 and Settings showed
"Failed to load config".

The launcher now records every name it has confirmed reaches one of its
own stand-ins (each mask it mounts and reads back, and each second
spelling the pin finds already covered), and an absent name skips when a
proper ancestor is recorded there and, resolved again now, still reaches
that stand-in. Names rather than identities, because the second spelling
of a masked directory has no mount of its own and no expectation to
compare against. A recorded ancestor that no longer reaches its stand-in
refuses the leaf rather than walking higher.

Reproduced against the real launcher on a host with a symlinked $HOME:
standard mode with the probe's extra_hidden_dirs refused before and exits
0 after, with the data home and both spellings of diag unreachable inside
the sandbox.
@buluoray
buluoray force-pushed the fix/sandbox-nested-mask-absent branch from 56224a5 to ac62701 Compare September 30, 2026 22:01
@buluoray

Copy link
Copy Markdown
Contributor Author

Disposition for GPT 5.6 F1 on 56224a503c (_covered_by_own_mask, private windows) — fixed in ac627010d5.

The finding is correct and I verified the mechanism before changing anything: the window bind (opening private window) lands before the nested re-hide pins apps/meetings/data/edits, so a leaf renamed away in between is absent while its contents sit live inside the read-write window. The lexical ascent then reached the recorded data-home mask, which does not cover anything beneath the window, and the skip sat ahead of both require_present and the carried-occupant refusal.

Fix: the launcher now records every window it binds (_BOUND_WINDOWS, written right after the window mount) and the ascent returns False the moment it meets one, so the leaf falls through to the vanished-object refusal exactly as it did before this PR. Recorded rather than derived from PRIVATE_DIRS, so only a window actually mounted back ends the walk.

Pinned by test_a_leaf_absent_inside_a_bound_window_is_not_covered_by_the_mask_above (the renamed-edits scenario refuses has vanished; the control with no bound window skips) and test_the_directory_loop_records_every_window_it_binds (the shipped loop writes the record). Mutations: removing the window check and removing the window record each redden a named test; the six earlier mutations still do; baseline green, 44 passed. The real-launcher reproduction (probe shape, symlinked $HOME) still exits 0 with the data home masked.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed ac627010d595eeed38cbe25c866424524536154e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ac62701

Verdict parsed from the review's SHA-scoped output markers for commit ac627010d595eeed38cbe25c866424524536154e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ac627010d595eeed38cbe25c866424524536154e: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@buluoray
buluoray merged commit 1e3885a into main Oct 1, 2026
99 of 105 checks passed
@buluoray
buluoray deleted the fix/sandbox-nested-mask-absent branch October 1, 2026 00:14
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 2026
bolichen97 added a commit that referenced this pull request Oct 1, 2026
Two tests on main fail in the macOS backend suite, each for its own
reason.

- test_terminal_commands.py::TestRunProbe::
  test_the_environment_is_an_allowlist_not_a_filtered_inherit finds
  KIROCREW_SANDBOX_TOOL in the probe child's environment. #15528 stamps
  that marker on every tree spawned through sandboxed_spawn_argv on
  purpose, because the runtime reconciler reads it back from the child.
  So it joins the named sandbox_injected set, with a leaked- sentinel in
  the parent like GRADLE_OPTS has, which keeps the check honest: the
  chokepoint overwrites the name, and a parent value must never reach
  the child under it. The test runs only where a live sandbox backend
  exists. GitHub's Linux runners have none, so the Linux shards skip it.

- test_sandbox_mount_pinned_target.py::
  test_the_directory_loop_records_every_window_it_binds, added by
  #15564, drives the private-window walk. That walk opens each component
  with bare os.O_PATH, which only Linux has, so the test raised
  AttributeError on Darwin. It now carries the file's _LINUX_LINK_PIN
  skip marker, like the other cases that need O_PATH.

Failing job (macOS shard 4 of the PR #15309 run):
https://github.com/kirodotdev/KiroCrew/actions/runs/36798238474/job/110167010707
iamwhatever pushed a commit that referenced this pull request Oct 1, 2026
#15680)

Two tests on main fail in the macOS backend suite, each for its own
reason.

- test_terminal_commands.py::TestRunProbe::
  test_the_environment_is_an_allowlist_not_a_filtered_inherit finds
  KIROCREW_SANDBOX_TOOL in the probe child's environment. #15528 stamps
  that marker on every tree spawned through sandboxed_spawn_argv on
  purpose, because the runtime reconciler reads it back from the child.
  So it joins the named sandbox_injected set, with a leaked- sentinel in
  the parent like GRADLE_OPTS has, which keeps the check honest: the
  chokepoint overwrites the name, and a parent value must never reach
  the child under it. The test runs only where a live sandbox backend
  exists. GitHub's Linux runners have none, so the Linux shards skip it.

- test_sandbox_mount_pinned_target.py::
  test_the_directory_loop_records_every_window_it_binds, added by
  #15564, drives the private-window walk. That walk opens each component
  with bare os.O_PATH, which only Linux has, so the test raised
  AttributeError on Darwin. It now carries the file's _LINUX_LINK_PIN
  skip marker, like the other cases that need O_PATH.

Failing job (macOS shard 4 of the PR #15309 run):
https://github.com/kirodotdev/KiroCrew/actions/runs/36798238474/job/110167010707
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants