Skip to content

fix(sandbox): seal gateway_id read-only inside the sandbox - #18407

Merged
iamwhatever merged 1 commit into
mainfrom
fix/gateway-id-protected-leaf
Oct 9, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/gateway-id-protected-leaf

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A process inside the sandbox can no longer replace gateway_id, the id this gateway compares to refuse a Remote Crew chain that loops back to itself.

<data-home>/gateway_id had no sandbox disposition: no rule in sandbox.py named it, and the data-home root is writable in-sandbox. So an agent's shell could rewrite the file and choose this gateway's identity. The read path was already hardened in #13936; the write was not. The maintainer decision on #14210 (2026-09-28) was to add the disposition as defence in depth.

Why it matters

The cycle guard trusts this id. A process that can choose it can choose whether a chaining loop is detected. Today the only reader is careful; a later reader would inherit nothing. Sealing the file makes the guarantee structural.

Not a goal

  • No change to the read path (gateway_identity._read_id) or to how the id is minted.
  • No change for processes that run as the operator outside the sandbox.
  • Not closing the symlink-at-a-protected-leaf limit tracked in Launcher mask mounts follow a symlink planted at a protected leaf, leaving the name replaceable #13802; this leaf inherits it like every other sealed leaf.
  • Not sealing the gateway_id.lock sidecar: only the unsandboxed gateway takes it.
  • Not changing how the mint writes: _install_fresh_id creates its temp file beside the id in the data home, which stays writable, so a sandboxed process that links or holds that temp inode during a mint is not stopped by this seal. Closing that needs a mint from a directory the sandbox cannot write, a change to gateway_identity.py.

What changed (motivation → approach → change)

Symptom: a sandboxed shell could write the gateway's identity file. Cause: the file was on none of the three sandbox dispositions or the agent file-tool floors. Change: give it the READONLY disposition, the same treatment as the other sealed ceilings.

  • sandbox._CREW_READONLY_LEAVES gains gateway_id. READONLY, not HIDDEN: the id is random and already served on /api/health, so reads stay open.
  • sandbox._CREW_CHILD_READABLE_LEAVES gains it, so a foreign harness's child may read it (nothing secret in it).
  • The Linux spawn (_materialize_sealable_ceilings) now mints the real id before sealing (_mint_gateway_id_before_seal), skipping an absent data home. The id is minted lazily on first read and the seal cannot bind an absent name. A pre-created {} stub would not do: the gateway's later mint would rename over the bound name, which detaches the bind in a running sandbox.
  • _WRITE_PROTECTED_HOME_PATHS in src/kiro_crew/security/paths.py gains it, so agent file tools refuse a write and still allow a read. It joins the existing gateway-written MCP block, whose comment is rewritten to cover it, so the security package stays inside its line budget.
  • test/test_sandbox_protected_name_holds.py's leaf-only ratchet records the new root-level leaf (+3 per tier, one per data-home spelling), with its reason, the way earlier root leaves were added.
  • docs/system-specs/modules/instances.md cycle-guard paragraph names the seal.

Design calls I made: the write-only tool tier rather than the read+write sensitive_home_dirs floor, because a read reveals nothing the health endpoint does not already serve; and minting before the seal, because without it a fresh Linux install stays writable until the first health read.

Backwards compatibility

Compatible: every writer of gateway_id is the unsandboxed gateway (gateway_identity._install_fresh_id, reached from the /api/health handler and the tunnel manager's cycle guard), and reads are unchanged.

Reader: src/kiro_crew/dashboard/handlers/core.py:_liveness_payload -- gateway process, not sandboxed -- reads the live file, which the spawn may now have minted first (test_the_spawn_mints_the_real_id_before_sealing)
Reader: src/kiro_crew/instances/ssh_tunnel_manager.py:SshTunnelManager._chain_cycle_reason -- gateway process, not sandboxed -- same read and mint, unchanged

Tests

New test/test_gateway_id_sandbox_seal.py (23 cases):

  • the leaf is READONLY, not HIDDEN or VISIBLE, and classified child-readable;
  • Linux namespace plan seals it read-only and does not mask it, every mode and both data-home spellings;
  • macOS Seatbelt profile denies write/link and not read, every mode and spelling;
  • agent file tools refuse a write and allow a read;
  • in-sandbox write refusal: the launcher's seal stage, driven with the recording libc, binds the file over itself and remounts it MS_RDONLY;
  • spawn: mints a real id before sealing; never pre-creates a stub; never overwrites an existing id; never scaffolds an absent data home.

Red-first: on origin/main the new cases fail; prove.py --base origin/main reports PROVEN with the production hunks reverted. Determinism: 5 repeated runs and a shuffled order (seed 14210), all passed. Existing suites pinning the same lists or the spawn path (governance mask, gateway identity, health API, Remote Crew chaining, security, and every test naming these constants or namespace_argv: 49 files) 5961 passed.

Manual verification

Not run on a real OS sandbox: this host's shell is itself inside a Kiro Crew sandbox, where a nested sandbox is refused by design, and no macOS host was available. The Linux seal stage is covered through the launcher program with a recording libc, and the Seatbelt rule through the rendered profile. CI Backend Tests (namespace sandbox) runs the spawn path in a real namespace.

Related Issues

Closes #14210

Tracking: Taskei CREW-20099

Pattern harvest

Not generalizable: the class (a crew-home trust root with no disposition) is already caught for read+write-floor leaves by test_sandbox_governance_mask; this leaf was on no floor at all, so only a per-leaf decision could place it.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 9, 2026 08:48
@iamwhatever
iamwhatever requested a review from buluoray October 9, 2026 08:48
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox.py

  • src/kiro_crew/security/paths.py

  • @iamwhatever posted a complete reasoning template for 7d3711d.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7d3711de36240d6aae0d904ff569d899b4195266 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7d3711de36240d6aae0d904ff569d899b4195266 — 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

Check that #14210 really carries the 2026-09-28 maintainer decision the description cites. Under AGENTS.md's sandbox-scope rule, that decision is the only thing that authorizes adding this seal.

What this change ships

Inventory (6 items) — 6 justified

Intent: stop a process inside the sandbox from rewriting this gateway's identity file, which the Remote Crew loop guard trusts. This is a FIX.

  1. A sandboxed shell can no longer write, replace or link gateway_id (Linux read-only bind, macOS Seatbelt deny) — justified
  2. A foreign harness's child may still read gateway_id (classified child-readable, not withheld) — justified
  3. The agent's file tools refuse a write to gateway_id and still allow a read — justified
  4. On Linux, a sandbox spawn now mints the gateway id before sealing, instead of waiting for the first health read — justified
  5. The leaf-only ratchet counts grow by 3 per tier — justified
  6. The cycle-guard paragraph in the instances spec names the seal and the unsealed temp file the mint writes — justified

[FIRST-PRINCIPLES-REVIEWED] 7d3711d

Description read

[DESCRIPTION-READ] 32e7a6f65769b11db2e5f58885588d24fedcd5e22be0104029d2b61430371d65

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 Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that a corrupt gateway_id gets re-minted before the seal, not while a sandbox is already running.

gateway_id() replaces an invalid file with os.replace. If the bind were already active at that point, the mount would detach and the running sandbox would keep the old inode. _mint_gateway_id_before_seal runs before each spawn's mounts, so a new spawn always seals the repaired file.

[DESIGN-REVIEWED] 7d3711d

Description read

[DESCRIPTION-READ] 31b4cb22adb693d59c835bd762cb9935db251c929c1e3302a8ad9c0909f9a555

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 Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 7d3711de36240d6aae0d904ff569d899b4195266 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7d3711d

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

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7d3711d

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

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

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- 🟡 CONCERNS

Which legitimate operations does 7d3711de36240d6aae0d904ff569d899b4195266 newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: the reviewer's own judgement; no confirmed regression.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 11 classified, 0 newly refused, 11 still allowed.
  • ubuntu-latest (platform posix): 11 classified, 0 newly refused, 11 still allowed.
  • windows-latest (platform windows): 6 classified, 0 newly refused, 6 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: CONCERNS

TIGHTENING: The gateway_id leaf was added to the read-only sandbox mounts, to the agent file-tool write fence, and to a new pre-seal mint call. Hunks: sandbox._CREW_READONLY_LEAVES += "gateway_id"; security/paths.py for leaf in ("mcp-launch-approvals", "mcp/resolved", "gateway_id"); _materialize_sealable_ceilings now calls _mint_gateway_id_before_seal(). -- The one threat it refuses is a sandboxed process writing the id the Remote Crew cycle guard compares. In the diff's words, "a sandboxed writer would choose whether a loop is detected."

ADJUDICATED: 15 candidates, 0 confirmed newly-refused. The diff changes none of the three shell tiers (sensitive-bash, exfil, deny-rules). The rows probe whether those tiers still let through reads of the leaf, the health probe that publishes the id, crew-home listings, a write to a sibling file whose name starts with gateway_id, and the new test module.

PLATFORM COVERAGE: Rows were written for three spellings:

  • posix: ~/.kiro/crew/gateway_id, the legacy ~/.kirocrew/gateway_id prefix and $KIROCREW_HOME/gateway_id. These are the three crew-home spellings the new path list and tests assume.
  • windows: %USERPROFILE%\.kiro\crew\gateway_id (cmd type, dir), PowerShell Get-Content $env:USERPROFILE\..., and a pytest path with \ separators. These cover the drive and separator spelling of the same _CREW_HOME_PREFIXES join.
  • any: the /api/health probe and a python -c read of gateway_id(create=False).

One assumed platform has no shell spelling. The Linux bind-mount seal and the macOS seatbelt deny file-write* are host-specific, and nothing about them can be expressed as a shell row (see below).

UNADJUDICATED:

  • Guard 1: the agent file-tool write fence. hooks.on_tool_call → gate_tiers edit tier → edit_target_candidates(...) → is_sensitive_write_path(wpath) (src/kiro_crew/hook_runtime/gate_tiers.py:546) → _SENSITIVE_HOME_DIRS + _WRITE_PROTECTED_HOME_PATHS, which now includes <prefix>/gateway_id. The classifier only judges shell command lines, so no verdict exists for this fence. These are the edit inputs I would have submitted:
    • an edit to ~/.kiro/crew/gateway_id.bak, ~/.kiro/crew/gateway_ids/notes.md or ~/.kirocrew/gateway_identity.md. These test whether the prefix match over-reaches into siblings whose names start with the same string.
    • an edit to the workspace file ./gateway_id or src/kiro_crew/gateway_identity.py. A developer editing the identity module must not be fenced.
    • a Windows edit to C:\Users\me\.kiro\crew\gateway_id_notes.txt.
  • Guard 2: sandbox mount and seatbelt. The spawn plan goes _spawn_plan → plan.readonly → sandbox_launcher_program.seal_readonly (bind plus MS_REMOUNT|MS_BIND|MS_RDONLY) on Linux, and _build_seatbelt_profile (deny file-write* (literal|subpath ...)) on macOS. The mint runs from _materialize_sealable_ceilings → _mint_gateway_id_before_seal → gateway_identity.gateway_id(). Legitimate inputs with no verdict:
    • The first spawn on a fresh install where config_dir() exists but no id file does. The mint writes a temp file in the data home before sealing. The doc concedes that file "is not sealed".
    • A spawn that runs _materialize_sealable_ceilings on a host whose crew home is read-only to the gateway. The mint has to fail quietly, and only logger.debug records it.
    • An agent tool inside a running sandbox that reads ~/.kiro/crew/gateway_id after the host-side gateway replaced it. The PR states the bind detaches in that case, so the read would see a stale id.
    • On macOS, the subpath deny now covers anything under ~/.kiro/crew/gateway_id/ as well. That only matters if a tool ever creates a directory at that name.

None of these pass through the shell composite, so the empty adjudicated set says nothing about them.

[SCOPE-REVIEWED] 7d3711d

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: f56a46d
  • What rule changed: gateway_id (the data-home file holding this gateway's random identity) joins three sandbox lists in src/kiro_crew/sandbox.py (_CREW_READONLY_LEAVES, _CREW_CHILD_READABLE_LEAVES, _CREW_PRECREATE_READONLY_FILE_LEAVES) and the agent file-tool write floor _WRITE_PROTECTED_HOME_PATHS in src/kiro_crew/security/paths.py. It is additive only: no rule is removed or loosened.
  • Before -> after (what was allowed/blocked, now): Before, a sandboxed process and the agent file tools could both read AND write <data-home>/gateway_id. After, reads stay allowed everywhere. Writes are refused by the Linux namespace (read-only bind), by macOS Seatbelt (deny file-write* / deny file-link), and by the agent file-edit gate. On Linux, an absent id is pre-created as {} before a spawn so the bind has a name to seal.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): A sandboxed process that needed to write the id would fall back to its own process-local id. No sandboxed process writes it: the only writer is the unsandboxed gateway (gateway_identity._install_fresh_id, reached from /api/health and the tunnel manager's cycle guard). Nothing is masked and no secret is involved. The {} stub reads as "no id", the same as an absent file, and the gateway's mint replaces it with a real id.
  • Evidence checked (which sandbox result proves it): test/test_gateway_id_sandbox_seal.py, 24 cases. The Linux _spawn_plan puts the path in readonly and not in sensitive_dirs for standard/cc/strict and both data-home spellings. The launcher seal stage, driven with RecordingLibc, binds the file over itself and remounts it MS_REMOUNT|MS_BIND|MS_RDONLY. The Seatbelt profile has the write/link deny and no read deny. Red-first: 21 of 24 fail on origin/main. prove.py --base origin/main reports PROVEN. Not run on a real OS sandbox: the authoring shell is itself sandboxed (a nested sandbox is refused), and no macOS host was available.
  • No regression:
    • Tools still work (which tools/commands were run, result): security.is_sensitive_path is False for the leaf, so agent reads are unchanged, and is_sensitive_write_path is True. gateway_id() and gateway_id(create=False) behave as before on a real id and treat the stub as absent (tests test_the_stub_reads_as_no_id, test_the_gateway_replaces_the_stub_with_a_real_id). An existing id is never overwritten by precreation (test_an_existing_id_is_never_overwritten).
    • Backward compatible (old config / old data / old callers still work, how checked): An install with an existing id keeps it. Precreation only creates an absent name. Both readers (dashboard/handlers/core.py:_liveness_payload, instances/ssh_tunnel_manager.py:SshTunnelManager._chain_cycle_reason) run in the gateway process, outside the sandbox, and read the live file.
    • Existing tests (which suites passed on this head): Locally, the 30 test files that pin these constants (including test_sandbox_governance_mask.py, test_gateway_identity.py, test_api_health.py, test_security.py, test_security_posture.py) gave 4641 passed, 2 skipped. On this head, CI Backend Tests (namespace sandbox), Backend Tests (crew container), the IPv6 shards, Integration, both E2E gateway boots, CodeQL and Static Ratchet are green. The main Backend shards are still running when this is posted.
  • How to undo: Revert the PR. That removes gateway_id from the four lists. A {} stub left on disk is harmless: the next gateway_id() call replaces it with a real id.

@iamwhatever
iamwhatever force-pushed the fix/gateway-id-protected-leaf branch from f56a46d to 5496880 Compare October 9, 2026 09:09
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 5496880
  • What rule changed: gateway_id (the data-home file holding this gateway's random identity) joins three sandbox lists in src/kiro_crew/sandbox.py (_CREW_READONLY_LEAVES, _CREW_CHILD_READABLE_LEAVES, _CREW_PRECREATE_READONLY_FILE_LEAVES) and the agent file-tool write floor _WRITE_PROTECTED_HOME_PATHS in src/kiro_crew/security/paths.py. It is additive only: no rule is removed or loosened.
  • Before -> after (what was allowed/blocked, now): Before, a sandboxed process and the agent file tools could both read AND write <data-home>/gateway_id. After, reads stay allowed everywhere. Writes are refused by the Linux namespace (read-only bind), by macOS Seatbelt (deny file-write* / deny file-link), and by the agent file-edit gate. On Linux, the spawn path (_materialize_sealable_ceilings) mints the real id before sealing, so the bound inode is the one the gateway keeps; a {} stub is the backstop when that mint cannot write.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): A sandboxed process that needed to write the id would fall back to its own process-local id. No sandboxed process writes it: the only writer is the unsandboxed gateway (gateway_identity._install_fresh_id, reached from /api/health and the tunnel manager's cycle guard). Nothing is masked and no secret is involved. The {} stub reads as "no id", the same as an absent file, and the gateway's mint replaces it with a real id.
  • Evidence checked (which sandbox result proves it): test/test_gateway_id_sandbox_seal.py, 25 cases. The Linux _spawn_plan puts the path in readonly and not in sensitive_dirs for standard/cc/strict and both data-home spellings. The launcher seal stage, driven with RecordingLibc, binds the file over itself and remounts it MS_REMOUNT|MS_BIND|MS_RDONLY. The Seatbelt profile has the write/link deny and no read deny. Red-first: the new cases fail on origin/main. prove.py --base origin/main reports PROVEN. Not run on a real OS sandbox: the authoring shell is itself sandboxed (a nested sandbox is refused), and no macOS host was available.
  • No regression:
    • Tools still work (which tools/commands were run, result): security.is_sensitive_path is False for the leaf, so agent reads are unchanged, and is_sensitive_write_path is True. gateway_id() and gateway_id(create=False) behave as before on a real id and treat the stub as absent (tests test_the_stub_reads_as_no_id, test_the_gateway_replaces_the_stub_with_a_real_id). An existing id is never overwritten by the spawn (test_an_existing_id_is_never_overwritten); a fresh one is minted before the seal (test_the_spawn_mints_the_real_id_before_sealing).
    • Backward compatible (old config / old data / old callers still work, how checked): An install with an existing id keeps it. The spawn only mints or creates an absent name. Both readers (dashboard/handlers/core.py:_liveness_payload, instances/ssh_tunnel_manager.py:SshTunnelManager._chain_cycle_reason) run in the gateway process, outside the sandbox, and read the live file.
    • Existing tests (which suites passed on this head): Locally on this head, the 49 test files that pin these constants or drive namespace_argv (including test_sandbox_governance_mask.py, test_sandbox_absent_ceiling_seal.py, test_gateway_identity.py, test_api_health.py, test_remote_crew_chaining.py, test_security.py) gave 5963 passed, 7 skipped. On the previous head f56a46d, CI Backend Tests (namespace sandbox), Backend Tests (crew container), Integration, both E2E gateway boots and CodeQL were green; CI for this head is running.
  • How to undo: Revert the PR. That removes gateway_id from the four lists. A {} stub left on disk is harmless: the next gateway_id() call replaces it with a real id.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: span=356c4e6acf32 sealed stub replaced by the later mint (src/kiro_crew/sandbox.py:1612)

Outcome: fixed in 5496880, the smaller fix the finding named.
_materialize_sealable_ceilings now calls _mint_gateway_id_before_seal(), which mints the real id through gateway_identity.gateway_id() before the file loop runs. The sealed inode is the one the gateway keeps, and the id never changes after minting, so no later os.replace lands on the bound name.
The {} precreation entry stays only as a backstop for a data home the mint cannot write.
Tests: test_the_spawn_mints_the_real_id_before_sealing (a real id is on disk after the spawn step, and gateway_id(create=False) agrees) and test_a_mint_that_cannot_write_still_leaves_a_sealable_name.

@iamwhatever
iamwhatever force-pushed the fix/gateway-id-protected-leaf branch from 5496880 to 3cddd88 Compare October 9, 2026 09:31
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: span=e68041441c1c remove the {} stub backstop (src/kiro_crew/sandbox.py)

Outcome: fixed in 3cddd88 by taking the subtraction as written.
gateway_id is no longer in _CREW_PRECREATE_READONLY_FILE_LEAVES, and _mint_gateway_id_before_seal() is called unconditionally (it skips an absent data home itself, so no install is scaffolded).
The four stub tests are deleted; test_the_leaf_is_not_precreated_as_a_stub pins the removal and test_an_absent_data_home_is_not_scaffolded pins the skip.
Residual: if the spawn-time mint cannot write, the name stays absent and unsealed on Linux, which is the state on main today.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 3cddd88
  • What rule changed: gateway_id (the data-home file holding this gateway's random identity) joins two sandbox lists in src/kiro_crew/sandbox.py (_CREW_READONLY_LEAVES, _CREW_CHILD_READABLE_LEAVES) and the agent file-tool write floor _WRITE_PROTECTED_HOME_PATHS in src/kiro_crew/security/paths.py. It is additive only: no rule is removed or loosened.
  • Before -> after (what was allowed/blocked, now): Before, a sandboxed process and the agent file tools could both read AND write <data-home>/gateway_id. After, reads stay allowed everywhere. Writes are refused by the Linux namespace (read-only bind), by macOS Seatbelt (deny file-write* / deny file-link), and by the agent file-edit gate. On Linux, the spawn path (_materialize_sealable_ceilings) mints the real id before sealing, so the bound inode is the one the gateway keeps. An absent data home is not scaffolded.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): A sandboxed process that needed to write the id would fall back to its own process-local id. If the spawn-time mint cannot write, the name stays absent and unsealed on Linux, as it is on main today. No sandboxed process writes it: the only writer is the unsandboxed gateway (gateway_identity._install_fresh_id, reached from /api/health and the tunnel manager's cycle guard). Nothing is masked and no secret is involved.
  • Evidence checked (which sandbox result proves it): test/test_gateway_id_sandbox_seal.py, 23 cases. The Linux _spawn_plan puts the path in readonly and not in sensitive_dirs for standard/cc/strict and both data-home spellings. The launcher seal stage, driven with RecordingLibc, binds the file over itself and remounts it MS_REMOUNT|MS_BIND|MS_RDONLY. The Seatbelt profile has the write/link deny and no read deny. Red-first: the new cases fail on origin/main. prove.py --base origin/main reports PROVEN. Not run on a real OS sandbox: the authoring shell is itself sandboxed (a nested sandbox is refused), and no macOS host was available.
  • No regression:
    • Tools still work (which tools/commands were run, result): security.is_sensitive_path is False for the leaf, so agent reads are unchanged, and is_sensitive_write_path is True. gateway_id() and gateway_id(create=False) are unchanged (test/test_gateway_identity.py passes). An existing id is never overwritten by the spawn (test_an_existing_id_is_never_overwritten); a fresh one is minted before the seal (test_the_spawn_mints_the_real_id_before_sealing).
    • Backward compatible (old config / old data / old callers still work, how checked): An install with an existing id keeps it. The spawn only mints or creates an absent name. Both readers (dashboard/handlers/core.py:_liveness_payload, instances/ssh_tunnel_manager.py:SshTunnelManager._chain_cycle_reason) run in the gateway process, outside the sandbox, and read the live file.
    • Existing tests (which suites passed on this head): Locally on this head, the 49 test files that pin these constants or drive namespace_argv (including test_sandbox_governance_mask.py, test_sandbox_absent_ceiling_seal.py, test_gateway_identity.py, test_api_health.py, test_remote_crew_chaining.py, test_security.py) gave 5961 passed, 7 skipped. On the earlier head f56a46d, CI Backend Tests (namespace sandbox), Backend Tests (crew container), Integration, both E2E gateway boots and CodeQL were green; CI for this head is running.
  • How to undo: Revert the PR. That removes gateway_id from the four lists. An id the spawn minted stays valid; it is the same id the gateway would have minted on its first read.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 9, 2026
@iamwhatever
iamwhatever force-pushed the fix/gateway-id-protected-leaf branch from 3cddd88 to 7d3711d Compare October 9, 2026 10:01
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 7d3711d
  • What rule changed: gateway_id (the data-home file holding this gateway's random identity) joins two sandbox lists in src/kiro_crew/sandbox.py (_CREW_READONLY_LEAVES, _CREW_CHILD_READABLE_LEAVES) and the agent file-tool write floor _WRITE_PROTECTED_HOME_PATHS in src/kiro_crew/security/paths.py (folded into the existing gateway-written MCP entry, net zero lines). test/test_sandbox_protected_name_holds.py records the new root-level leaf on its leaf-only ratchet (+3 per tier). It is additive only: no rule is removed or loosened.
  • Before -> after (what was allowed/blocked, now): Before, a sandboxed process and the agent file tools could both read AND write <data-home>/gateway_id. After, reads stay allowed everywhere. Writes are refused by the Linux namespace (read-only bind), by macOS Seatbelt (deny file-write* / deny file-link), and by the agent file-edit gate. On Linux, the spawn path (_materialize_sealable_ceilings) mints the real id before sealing, so the bound inode is the one the gateway keeps. An absent data home is not scaffolded.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): A sandboxed process that needed to write the id would fall back to its own process-local id. If the spawn-time mint cannot write, the name stays absent and unsealed on Linux, as it is on main today. No sandboxed process writes it: the only writer is the unsandboxed gateway (gateway_identity._install_fresh_id, reached from /api/health and the tunnel manager's cycle guard). Nothing is masked and no secret is involved.
  • Evidence checked (which sandbox result proves it): test/test_gateway_id_sandbox_seal.py, 23 cases. The Linux _spawn_plan puts the path in readonly and not in sensitive_dirs for standard/cc/strict and both data-home spellings. The launcher seal stage, driven with RecordingLibc, binds the file over itself and remounts it MS_REMOUNT|MS_BIND|MS_RDONLY. The Seatbelt profile has the write/link deny and no read deny. Red-first: the new cases fail on origin/main. prove.py --base origin/main reports PROVEN. Not run on a real OS sandbox: the authoring shell is itself sandboxed (a nested sandbox is refused), and no macOS host was available.
  • No regression:
    • Tools still work (which tools/commands were run, result): security.is_sensitive_path is False for the leaf, so agent reads are unchanged, and is_sensitive_write_path is True. gateway_id() and gateway_id(create=False) are unchanged (test/test_gateway_identity.py passes). An existing id is never overwritten by the spawn (test_an_existing_id_is_never_overwritten); a fresh one is minted before the seal (test_the_spawn_mints_the_real_id_before_sealing).
    • Backward compatible (old config / old data / old callers still work, how checked): An install with an existing id keeps it. The spawn only mints or creates an absent name. Both readers (dashboard/handlers/core.py:_liveness_payload, instances/ssh_tunnel_manager.py:SshTunnelManager._chain_cycle_reason) run in the gateway process, outside the sandbox, and read the live file.
    • Existing tests (which suites passed on this head): Locally on this head, the 49 test files that pin these constants or drive namespace_argv (including test_sandbox_governance_mask.py, test_sandbox_absent_ceiling_seal.py, test_gateway_identity.py, test_api_health.py, test_remote_crew_chaining.py, test_security.py) gave 5961 passed, 7 skipped; after the fold, test_security_gate_liveness.py, test_sandbox_protected_name_holds.py, test_security.py and every test naming the write floor passed (1372 + 2340). On the earlier head f56a46d, CI Backend Tests (namespace sandbox), Backend Tests (crew container), Integration, both E2E gateway boots and CodeQL were green; CI for this head is running.
  • How to undo: Revert the PR. That removes gateway_id from the four lists. An id the spawn minted stays valid; it is the same id the gateway would have minted on its first read.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 9, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. This implements the #14210 decision as specified: an in-sandbox write to gateway_id is refused, and the read path is unchanged.

Verified

  • The gateway is the only writer. The only writer of the file is gateway_identity._install_fresh_id. It is reached from the health handler and the tunnel manager, both in the gateway process, and from the new pre-seal mint in the spawning process. No sandboxed reader needs write access, so READONLY is the right disposition.
  • Real Linux namespace sandbox, fresh data home:
    • On this head, the spawn mints the id first. Inside the sandbox the file reads normally, and writing, renaming or deleting it are all refused. The gateway's value is unchanged afterwards.
    • On the base tree, the same rename and delete succeed.
  • Every guard is pinned. Reverting any one of these turns a named test in test_gateway_id_sandbox_seal.py or the governance-mask classification red:
    • the READONLY entry
    • the pre-seal mint call
    • the file-tool write floor
    • the child-readable classification
  • Spec updated. The instances.md cycle-guard paragraph is updated in the same change.

Non-blocking follow-ups

  • If the pre-seal mint ever fails, gateway_id() falls back quietly and the Linux seal has no name to bind for that spawn. It is not reachable in practice: the mint runs before any sandbox exists, and once the file is valid and sealed it is never re-minted. A warning, rather than a debug line, when the leaf is still absent after the mint would make the case visible.
  • The temp-file residual named in the description is a reasonable separate item if the owner wants it closed.

CI on this head: 96 success, 10 skipped, no failures. Auto-merge is off, so this approval does not merge the PR.

@iamwhatever
iamwhatever merged commit b777c7a into main Oct 9, 2026
113 of 121 checks passed
@iamwhatever
iamwhatever deleted the fix/gateway-id-protected-leaf branch October 9, 2026 19:46
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.

sandbox: decide whether gateway_id carries a protected-name disposition (read path already hardened)

2 participants