Repository navigation
feat(sandbox): operator read-only paths with write exceptions - #28535
Conversation
Sensitive Change ReviewSensitive files changed:
|
Sensitive change review
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the operator turns this narrowing layer on, it reuses the existing mount and Seatbelt machinery, it is ordered under every crew rule, and with the keys unset it builds the same plan as main. Notes
[DESIGN-REVIEWED] afede1e Description read[DESCRIPTION-READ] 2963551be5802682b671b208913bad02d79f7468787722c434eb6e32054c035e 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The new keys are empty by default, the defect comes from linked issue #5974, and the PR reuses the sandbox's existing carve-out and ancestor-guard code instead of building a new allowlist. Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: let an operator stop the agent writing a chosen tree (for example
[FIRST-PRINCIPLES-REVIEWED] afede1e Description read[DESCRIPTION-READ] 5a9427b7c83dc06551284d5cd6a97254a449ab1f069b426a4af3a8d1d2e63837 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
c387dc8 to
8032778
Compare
|
self-added: yes
|
Sensitive change review
|
8032778 to
a3f7b12
Compare
|
self-added: no
|
Sensitive change review
|
a3f7b12 to
a837b12
Compare
|
self-added: no
|
|
self-added: yes
|
a837b12 to
82afa38
Compare
|
macOS Tests (on demand) on 82afa38: shards 2-6 passed on the full re-run (e.g. shard 5: 37373 passed; shard 6: 44292 passed). Shard 1 reached |
82afa38 to
d56905a
Compare
|
Rebased: main moved in |
2a9ed38 to
8c4f7cf
Compare
|
Fix pushed for the GPT 6.1 finding on
|
8c4f7cf to
cdb315a
Compare
cdb315a to
ac5eee9
Compare
ac5eee9 to
2de5be7
Compare
|
Rebased: base
|
|
Fix pushed for the Opus 5.5 finding on
|
|
Fix pushed for the First Principles 5.5 blocker on
|
Add agent.sandbox_readonly_paths and agent.sandbox_readonly_exceptions: directories the sandboxed agent may read but never write, and directories inside those that stay writable (e.g. /mnt/c read-only with /mnt/c/Users/<me>/Documents writable). The OS sandbox enforces both: a recursive read-only bind, with every mount below it remounted read-only, in the Linux namespace launcher, and a write deny in the macOS Seatbelt profile. The layer only narrows. It reuses the plan's read-only seal and the carve-out checks: writable_carveouts() accepts an exception only strictly inside an operator read-only entry and never over a crew mask or seal. Crew rules also win by order, because the launcher applies the layer before every crew mount and Seatbelt emits it before every crew rule. Both keys live in config.json, already a READONLY crew leaf, and are read raw so the plan never rewrites that file. Unset renders the same plan, launcher and profile as before. Windows has no backend, so the keys are reported as not enforced. Fixes #5974
Sensitive change review
|
bolichen97
left a comment
There was a problem hiding this comment.
Approve on afede1e. I read the whole diff (2865 lines), tests included. This fixes #5974.
- Strictness check:
agent.sandbox_readonly_paths/agent.sandbox_readonly_exceptionsare operator config inconfig.json, empty by default. Empty plans no layer, emits nooperator_*payload keys, mounts nothing in the launcher, and leaves the Seatbelt profile unchanged. The tests pin each, so off equals main.- The restriction only exists where the operator asks for it. That's the operator's own choice, not added strictness.
- The keys are read raw from the endorsed config text, never through
KiroCrewConfig.load().config.jsonis already a read-only crew leaf, so the agent can't edit its own boundary.
- Crew rules always win:
- The layer lands before every crew seal, mask and carve-out.
- An exception must be strictly inside an accepted entry, not through a symlink below it, and outside every crew mask, seal and ceiling (the
writable_carveoutschecks). /and entries holding the launcher's stand-in roots are refused with aSECURITYlog.
- Linux: each entry is bound recursively and remounted read-only, and so is each mount below it. A mount that can't be reached is skipped. Any exception containing such a mount stays read-only. A reachable mount that won't go read-only refuses the spawn. Parents are pinned like crew seals.
- macOS: deny and allow rules are emitted shallowest first. Literal guards cover each entry's ancestors and each exception's own name.
- Shared-code refactors, behaviour-neutral for main:
seal_readonly's bind, pin and remount body moved unchanged into_seal_path, with the same identity checks and BLOCK exit.path_ancestor_guardsgives the same set._quotednow also escapes backslashes on POSIX, so a path holding one stays a single SBPL literal. That's a fix, and it's tested.
- There is no regex. Windows logs once that the layer is unenforced. The real-sandbox suite is added to CI.
- All 109 checks are green, and nobody else has an open change request.
Problem / Motivation
Goal: Let an operator make chosen directories read-only to the sandboxed agent, with writable exceptions inside them, enforced by the OS sandbox.
The native sandbox hides credential paths and seals Kiro Crew's own governance files, but an operator has no way to say "the agent may read this tree but never write it". The reporter of #5974 runs WSL2, where AppArmor is unavailable and firejail refuses to nest inside our user namespace. They want the Windows drive at
/mnt/cprotected from agent writes while one folder on it,Documents, stays writable. Today their only route isagent.sandbox: offplus an external wrapper, which loses the credential masking.Why it matters
Anyone running Kiro Crew on a shared machine or WSL can only rely on the semantic approval gate to stop a write into a tree they care about, and one misclicked approval is enough. A kernel-enforced read-only directory closes that gap without giving up the built-in sandbox. Maintainers routed #5974 as RFC-worthy; this PR is the narrow first step the maintainer chose (read-only paths with exceptions), not the full write allowlist.
Not a goal
/is refused; a full allowlist is a possible follow-up.security_policy.json. The keys are operator config only.agent.sandbox: off, a macOS spawn delegated to kiro-cli's internal sandbox, Windows.config.json.What changed (motivation → approach → change)
Two new
agentkeys, both empty by default:agent.sandbox_readonly_pathsagent.sandbox_readonly_exceptions{"agent": {"sandbox_readonly_paths": ["/mnt/c"], "sandbox_readonly_exceptions": ["/mnt/c/Users/<you>/Documents"]}}The approach reuses machinery the sandbox already has instead of building an allowlist.
sandbox_plan.operator_readonly_layervalidates the entries andwritable_carveouts()accepts an exception only strictly inside an operator read-only entry, never holding or inside a crew mask or seal. Refused entries are logged asSECURITY: ignoring agent.sandbox_readonly_.... On Linux the new launcher stageseal_operator_readonlybinds each read-only entry over itself recursively, remounts it and every mount below it read-only (so/mnt/cunder/mntis covered), then re-opens each exception like a crew carve-out. On macOS the Seatbelt profile gets write and hardlink denies for each entry and an allow for each exception, emitted shallowest path first so a nested level decides over the one holding it (as Linux mount order does), then literal rename guards on each entry and its ancestors. A mount below a read-only entry that the launcher's namespace cannot reach is skipped rather than refusing the spawn, and an exception holding such a mount stays read-only. Seatbelt path quoting escapes backslashes on hosts where they are a filename character.Crew rules always win, by order as well as by those checks: the launcher applies this layer before every crew seal, mask and carve-out, and the Seatbelt profile emits it before every crew rule. Both keys live in
config.json, which is already a READONLY crew leaf, so the agent can read its boundary but not edit it, and no keystone or leaf disposition changes. The plan reads the keys raw (sandbox_tiers.configured_readonly_layer) rather than throughKiroCrewConfig.load(), which can writeconfig.jsonback after the pre-spawn pass recorded its identity; each document is read withread_endorsed_config_text, as the loader reads it, so an agent that rewrites or deletes the file after a rename-save cannot drop the layer for later spawns. A config file that exists but cannot be parsed keeps the last layer this process read whole, with a SECURITY warning; a process that has none applies the entries of the files that do parse, as the config loader does, so a typo cannot silently drop the boundary. A read-only entry the gateway cannot probe for any reason but absence (a parent the agent made mode000) stays in the plan rather than being dropped as not a directory, so the launcher still seals it, or refuses the spawn if it cannot pin it. Amountinforecord below an entry that a later mount over its parent has hidden is skipped (its name reaches a different mount ID), so it neither refuses every spawn nor leaves a containing exception writable. On Linux each accepted read-only entry's parents that the agent could rename join the crew seals' parent pins (a refused entry pins nothing). On macOS each exception's own name takes a literal write deny, and on both backends an exception reached through a symlink below its read-only entry is refused, so an exception cannot be swapped for a link to a read-only sibling, so a rename between sessions cannot move the real tree away from the name the next session seals (Seatbelt already denies that rename). Unset renders the same plan, launcher payload and profile as before. On Windows,wrap_argvlogs once that the keys are not enforced. The crew container (supervisor/backend.py) states both keys as empty, like every other sandbox key. Code:sandbox_plan.py(validation),sandbox_seatbelt.py,sandbox_launcher_program.pyandsandbox_launcher_parts/mask_stages.py(the launcher stage),sandbox_argv.pyandsandbox_tiers.py(reading the keys),sandbox_wrap.py(the Windows warning),sandbox.py(facade names),sandbox_workspace.py(its literal ancestor-guard walk now delegates to the plan's, so one implementation remains),config/sections_agent.pyandconfig/loader_builders.py(the keys),session_parts/config_apply.py(a change rebuilds the warm pool, which carries its sandbox). Docs:docs/system-specs/modules/security.md,src/kiro_crew/docs/configuration.md,config-baseline.json. The real-sandbox test joins the namespace-sandbox CI job inci.yml.Backwards compatibility
Compatible: both keys default to empty, which plans and renders exactly what main does, and no existing key, value or caller changes.
Removes nothing: the change adds an opt-in narrowing layer; every crew mask, seal and carve-out keeps its current coverage and order relative to the others.
Tests
test/test_sandbox_readonly_layer.py: unset keys plan no layer and leave the payload and profile unchanged; the/mnt/c+Documentsshape on both renderers; nested levels on Seatbelt (a read-only entry inside an exception, an exception inside that) with rename guards after every allow; canonical-only spelling on Linux, both spellings on Seatbelt; refusals (exception outside or equal to its entry, exception reopening a crew ceiling, inside a tier mask, inside a crew-guard entry,/, relative, missing, an entry holding the launcher's stand-in roots); crew carve-out validation unchanged; the live adapter reads the keys, expands~, does not rewriteconfig.json, and keeps the last layer (with a warning) whenconfig.jsonorconfig.local.jsonstops parsing, or, in a fresh process, appliesconfig.json's entries when onlyconfig.local.jsonis broken; the loader coerces both keys; the Windows warning fires once and only when set. Launcher stage with a recording libc: recursive bind, read-only remount of the entry and each mount below it, exception reopened read-write, a failed submount remount refuses the spawn, a failed exception mount fails open, the layer lands before crew seals;mountinfoparsing.test/test_sandbox_readonly_layer_real_sandbox.py(namespace-sandbox CI job): under the real sandbox at all three tiers, a write into the read-only directory fails withEROFS, a write into its exception lands, an unlisted sibling stays writable, nested levels alternate read-only and writable as configured, and an exception naming the data home'sprofilesceiling staysEROFS. The drive test fails on main and passes here._mount_or_diesite count (11 → 12), the facade's moved-name table, and the crew container's sandbox-key ratchet (a list-valued sandbox key must be forced to its default).Manual verification
Ran the real-sandbox tests locally under the namespace launcher (11 passed with
test_pinned_order_real_sandbox.py). Ran a manual probe underunshare -rmwith a tmpfs mounted below the read-only directory and an exception inside that tmpfs: the directory and the tmpfs both returnedEROFS, the exception inside the tmpfs accepted the write. macOS Seatbelt was not run by hand; its rules are covered by the renderer tests.Related Issues
Fixes #5974
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)