Skip to content

feat(sandbox): operator read-only paths with write exceptions - #28535

Merged
bolichen97 merged 1 commit into
mainfrom
fix/5974-sandbox-write-allowlist
Nov 11, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/5974-sandbox-write-allowlist

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

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/c protected from agent writes while one folder on it, Documents, stays writable. Today their only route is agent.sandbox: off plus 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

  • A whole-filesystem write allowlist ("everything else read-only"). / is refused; a full allowlist is a possible follow-up.
  • A governance-mandated list in security_policy.json. The keys are operator config only.
  • Enforcement where Kiro Crew applies no sandbox of its own: agent.sandbox: off, a macOS spawn delegated to kiro-cli's internal sandbox, Windows.
  • A Settings UI for the keys. They are set in config.json.
  • Any change to what the crew masks, seals or carve-outs cover.

What changed (motivation → approach → change)

Two new agent keys, both empty by default:

Key Effect
agent.sandbox_readonly_paths Absolute directories the agent may read but never write
agent.sandbox_readonly_exceptions Directories strictly inside one of those that stay writable
{"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_layer validates the entries and writable_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 as SECURITY: ignoring agent.sandbox_readonly_.... On Linux the new launcher stage seal_operator_readonly binds each read-only entry over itself recursively, remounts it and every mount below it read-only (so /mnt/c under /mnt is 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 through KiroCrewConfig.load(), which can write config.json back after the pre-spawn pass recorded its identity; each document is read with read_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 mode 000) 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. A mountinfo record 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_argv logs 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.py and sandbox_launcher_parts/mask_stages.py (the launcher stage), sandbox_argv.py and sandbox_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.py and config/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 in ci.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 + Documents shape 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 rewrite config.json, and keeps the last layer (with a warning) when config.json or config.local.json stops parsing, or, in a fresh process, applies config.json's entries when only config.local.json is 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; mountinfo parsing.
  • 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 with EROFS, 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's profiles ceiling stays EROFS. The drive test fails on main and passes here.
  • Updated pins: the launcher stage order, the _mount_or_die site 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 under unshare -rm with a tmpfs mounted below the read-only directory and an exception inside that tmpfs: the directory and the tmpfs both returned EROFS, 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

  • 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

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox.py

  • src/kiro_crew/sandbox_argv.py

  • src/kiro_crew/sandbox_launcher_parts/mask_stages.py

  • src/kiro_crew/sandbox_launcher_program.py

  • src/kiro_crew/sandbox_plan.py

  • src/kiro_crew/sandbox_seatbelt.py

  • src/kiro_crew/sandbox_tiers.py

  • src/kiro_crew/sandbox_workspace.py

  • src/kiro_crew/sandbox_wrap.py

  • @dodgeblaster posted a complete reasoning template for afede1e.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: c387dc8
  • What rule changed: Two new operator config keys, agent.sandbox_readonly_paths and agent.sandbox_readonly_exceptions, add an optional read-only layer to the OS sandbox: listed directories become read-only to the agent, and exceptions strictly inside them stay writable. No existing mask, seal or carve-out changes.
  • Before -> after (what was allowed/blocked, now): Before: every path outside Kiro Crew's own masks and seals was writable to the agent per normal Unix permissions. After, with the keys unset (default): identical plan, launcher payload and Seatbelt profile. After, with the keys set: writes into a listed directory fail (EROFS on Linux, a Seatbelt write deny on macOS), writes into its exceptions land, and every crew mask and seal is applied on top of the layer and still wins.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): Breaks commands. An operator who lists the project, the data home or an agent state directory gets an agent that cannot write there. The layer only removes write access and cannot re-open a crew-hidden or crew-sealed path, so no secret leaks. A launcher mount that cannot be made read-only refuses the spawn (fail closed). The worst failure-open case is a refused exception mount, which leaves that path read-only.
  • Evidence checked (which sandbox result proves it): test/test_sandbox_readonly_layer_real_sandbox.py under the real namespace sandbox on Linux, all 3 tiers: a write into the read-only dir gives EROFS and nothing is written, the exception write lands, an unlisted sibling stays writable, nested levels alternate RO/RW as configured, and an exception naming the data home's profiles ceiling stays EROFS. The drive test fails on origin/main and passes on this head. Manual unshare -rm probe with a tmpfs mounted below the read-only dir: the dir and the tmpfs gave EROFS, and an exception inside the tmpfs was writable. macOS: renderer tests on the Seatbelt rule order (shallowest first, then rename guards, then crew rules). Not run on a real Mac.
  • No regression:
    • Tools still work (which tools/commands were run, result): The real-sandbox child (python open/write) ran under the launcher at standard/cc/strict and exited 0 with the expected per-path results. test_pinned_order_real_sandbox.py (an existing real-sandbox suite) passed alongside it, 11 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): The keys default to []. test_an_unset_config_renders_the_same_launcher_as_explicitly_empty_keys, test_unset_keys_* and test_unset_keys_leave_the_same_directory_writable (real sandbox) check it. The payload keys are omitted when empty, so an unset host's launcher is unchanged. The crew carve-out validation is unchanged (test_the_crew_carve_outs_are_validated_exactly_as_before). Reading the keys does not rewrite config.json (test_reading_the_keys_does_not_rewrite_config_json).
    • Existing tests (which suites passed on this head): test_sandbox_plan, test_sandbox_launcher_program(+_parts, _pinned_mounts), test_sandbox_argv_launcher_plan, test_sandbox_governance_mask, test_sandbox_seal_locked_flags, test_sandbox_mount_checked, test_sandbox_refactor_facade, test_crew_container_config_isolation and test_config_json_seal_survives_gateway_write all passed. The local related-test run's remaining reds reproduce identically on clean origin/main on this host (enterprise profile / nested-sandbox environment). CI is the full run.
  • How to undo: Remove both keys from config.json (or set them to []); new sessions then get the old sandbox exactly. To remove the code, revert this single commit.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision afede1ef121f6866a6221d3646303b529995b582 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of afede1ef121f6866a6221d3646303b529995b582 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The aws_control built-in's supervisor/backend.py gets an in-place edit. If apps/adoption-pins.json pins that app, the change must land in its app repository first and the PR must name it (App repo: …).

[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 .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 Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of afede1ef121f6866a6221d3646303b529995b582 — 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 does not.

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

  • Item 6 — rides along: _quoted now escapes backslashes for every Seatbelt path, crew rules included. That partly contradicts "Unset renders the same … profile as before" for crew paths that contain a \. Subtraction: drop the os.sep == "/" branch from this PR and send it with its own defect report.

What this change ships

Inventory (8 items) — 6 justified

Intent: let an operator stop the agent writing a chosen tree (for example /mnt/c on WSL2) while one folder inside it stays writable, enforced by the kernel. This is an ADDITION.

  1. New agent.sandbox_readonly_paths key, empty by default, read-only bind (Linux) or Seatbelt deny (macOS) — justified
  2. New agent.sandbox_readonly_exceptions key, re-opening subfolders strictly inside an entry — justified
  3. Unsafe entries (/, relative, inside crew masks) skipped with a SECURITY warning — justified
  4. An unparseable config keeps the last layer this process read, applied raw without load() — justified
  5. Windows logs once that the keys are not enforced — justified
  6. Seatbelt path quoting escapes backslashes on every rule — rides along, changes the existing crew-rule rendering
  7. Changing either key rebuilds the warm pool — justified
  8. sandbox_workspace._literal_ancestor_guards now calls sandbox_plan.path_ancestor_guards — rides along, leaves one implementation instead of two

[FIRST-PRINCIPLES-REVIEWED] afede1e

Description read

[DESCRIPTION-READ] 5a9427b7c83dc06551284d5cd6a97254a449ab1f069b426a4af3a8d1d2e63837

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 Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] afede1e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt afede1ef121f6866a6221d3646303b529995b582 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] afede1e

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable afede1ef121f6866a6221d3646303b529995b582 false-positive: <reason, 20 to 500 characters>

@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from c387dc8 to 8032778 Compare November 2, 2026 22:08
@dodgeblaster

dodgeblaster commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: configured_readonly_layer read config raw through a helper that swallowed parse errors

  • span=d39a62321323 An unreadable config silently drops the read-only boundary

fixed in 8032778: configured_readonly_layer now reads config.local.json and config.json itself and tells an absent file from one that exists but does not parse (or whose agent value is not an object).
An unreadable document keeps the last fully readable layer this process computed and logs a SECURITY warning naming the file, so a typo or torn write after any earlier spawn cannot drop the boundary.
With no earlier read in this process the layer stays unset, with the same SECURITY warning; it does not refuse the spawn, since that would break every spawn on hosts that never set these keys.
Pinned by test_truncated_config_keeps_the_last_readonly_layer, test_unparseable_config_without_a_cached_layer_warns and test_unparseable_overlay_keeps_the_last_readonly_layer; the first fails on c387dc8.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 8032778
  • What rule changed: Two new operator config keys, agent.sandbox_readonly_paths and agent.sandbox_readonly_exceptions, add an optional read-only layer to the OS sandbox: listed directories become read-only to the agent, and exceptions strictly inside them stay writable. No existing mask, seal or carve-out changes.
  • Before -> after (what was allowed/blocked, now): Before: every path outside Kiro Crew's own masks and seals was writable to the agent per normal Unix permissions. After, with the keys unset (default): identical plan, launcher payload and Seatbelt profile. After, with the keys set: writes into a listed directory fail (EROFS on Linux, a Seatbelt write deny on macOS), writes into its exceptions land, and every crew mask and seal is applied on top of the layer and still wins.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): Breaks commands. An operator who lists the project, the data home or an agent state directory gets an agent that cannot write there. The layer only removes write access and cannot re-open a crew-hidden or crew-sealed path, so no secret leaks. A launcher mount that cannot be made read-only refuses the spawn (fail closed). The worst failure-open case is a refused exception mount, which leaves that path read-only.
  • Evidence checked (which sandbox result proves it): test/test_sandbox_readonly_layer_real_sandbox.py under the real namespace sandbox on Linux, all 3 tiers: a write into the read-only dir gives EROFS and nothing is written, the exception write lands, an unlisted sibling stays writable, nested levels alternate RO/RW as configured, and an exception naming the data home's profiles ceiling stays EROFS. The drive test fails on origin/main and passes on this head. Manual unshare -rm probe with a tmpfs mounted below the read-only dir: the dir and the tmpfs gave EROFS, and an exception inside the tmpfs was writable. macOS: renderer tests on the Seatbelt rule order (shallowest first, then rename guards, then crew rules). Not run on a real Mac.
  • No regression:
    • Tools still work (which tools/commands were run, result): The real-sandbox child (python open/write) ran under the launcher at standard/cc/strict and exited 0 with the expected per-path results. test_pinned_order_real_sandbox.py (an existing real-sandbox suite) passed alongside it, 11 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): The keys default to []. test_an_unset_config_renders_the_same_launcher_as_explicitly_empty_keys, test_unset_keys_* and test_unset_keys_leave_the_same_directory_writable (real sandbox) check it. The payload keys are omitted when empty, so an unset host's launcher is unchanged. The crew carve-out validation is unchanged (test_the_crew_carve_outs_are_validated_exactly_as_before). Reading the keys does not rewrite config.json (test_reading_the_keys_does_not_rewrite_config_json). A config.json or config.local.json that stops parsing keeps the last layer this process read and logs a SECURITY warning (test_truncated_config_keeps_the_last_readonly_layer, test_unparseable_overlay_keeps_the_last_readonly_layer).
    • Existing tests (which suites passed on this head): test_sandbox_plan, test_sandbox_launcher_program(+_parts, _pinned_mounts), test_sandbox_argv_launcher_plan, test_sandbox_governance_mask, test_sandbox_seal_locked_flags, test_sandbox_mount_checked, test_sandbox_refactor_facade, test_crew_container_config_isolation and test_config_json_seal_survives_gateway_write all passed. The local related-test run's remaining reds reproduce identically on clean origin/main on this host (enterprise profile / nested-sandbox environment). CI is the full run.
  • How to undo: Remove both keys from config.json (or set them to []); new sessions then get the old sandbox exactly. To remove the code, revert this single commit.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: Seatbelt _quoted escaped double quotes but not backslashes

  • span=ca42d2c14d5b Escape backslashes before rendering operator paths

fixed in a3f7b12: _quoted now escapes backslashes before double quotes, so every path written into a Seatbelt "..." literal, operator and crew alike, stays one literal and decodes back to the exact path; no path can close its string early or inject rules.
Every other path interpolation in the profile already goes through _quoted or json.dumps.
Pinned by test_seatbelt_operator_paths_stay_single_string_literals (paths ending in a backslash and containing a quote, round-tripped through every quoted literal on balanced lines) and test_seatbelt_crew_home_with_backslash_stays_single_string_literals; the first fails on 8032778.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: a3f7b12
  • What rule changed: Two new operator config keys, agent.sandbox_readonly_paths and agent.sandbox_readonly_exceptions, add an optional read-only layer to the OS sandbox: listed directories become read-only to the agent, and exceptions strictly inside them stay writable. No existing mask, seal or carve-out changes.
  • Before -> after (what was allowed/blocked, now): Before: every path outside Kiro Crew's own masks and seals was writable to the agent per normal Unix permissions. After, with the keys unset (default): identical plan, launcher payload and Seatbelt profile. After, with the keys set: writes into a listed directory fail (EROFS on Linux, a Seatbelt write deny on macOS), writes into its exceptions land, and every crew mask and seal is applied on top of the layer and still wins.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): Breaks commands. An operator who lists the project, the data home or an agent state directory gets an agent that cannot write there. The layer only removes write access and cannot re-open a crew-hidden or crew-sealed path, so no secret leaks. A launcher mount that cannot be made read-only refuses the spawn (fail closed). The worst failure-open case is a refused exception mount, which leaves that path read-only.
  • Evidence checked (which sandbox result proves it): test/test_sandbox_readonly_layer_real_sandbox.py under the real namespace sandbox on Linux, all 3 tiers: a write into the read-only dir gives EROFS and nothing is written, the exception write lands, an unlisted sibling stays writable, nested levels alternate RO/RW as configured, and an exception naming the data home's profiles ceiling stays EROFS. The drive test fails on origin/main and passes on this head. Manual unshare -rm probe with a tmpfs mounted below the read-only dir: the dir and the tmpfs gave EROFS, and an exception inside the tmpfs was writable. macOS: renderer tests on the Seatbelt rule order (shallowest first, then rename guards, then crew rules). Not run on a real Mac.
  • No regression:
    • Tools still work (which tools/commands were run, result): The real-sandbox child (python open/write) ran under the launcher at standard/cc/strict and exited 0 with the expected per-path results. test_pinned_order_real_sandbox.py (an existing real-sandbox suite) passed alongside it, 11 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): The keys default to []. test_an_unset_config_renders_the_same_launcher_as_explicitly_empty_keys, test_unset_keys_* and test_unset_keys_leave_the_same_directory_writable (real sandbox) check it. The payload keys are omitted when empty, so an unset host's launcher is unchanged. The crew carve-out validation is unchanged (test_the_crew_carve_outs_are_validated_exactly_as_before). Reading the keys does not rewrite config.json (test_reading_the_keys_does_not_rewrite_config_json). A config.json or config.local.json that stops parsing keeps the last layer this process read and logs a SECURITY warning (test_truncated_config_keeps_the_last_readonly_layer, test_unparseable_overlay_keeps_the_last_readonly_layer).
    • Existing tests (which suites passed on this head): test_sandbox_plan, test_sandbox_launcher_program(+_parts, _pinned_mounts), test_sandbox_argv_launcher_plan, test_sandbox_governance_mask, test_sandbox_seal_locked_flags, test_sandbox_mount_checked, test_sandbox_refactor_facade, test_crew_container_config_isolation and test_config_json_seal_survives_gateway_write all passed. The local related-test run's remaining reds reproduce identically on clean origin/main on this host (enterprise profile / nested-sandbox environment). CI is the full run.
  • How to undo: Remove both keys from config.json (or set them to []); new sessions then get the old sandbox exactly. To remove the code, revert this single commit.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules (same-dir), src/kiro_crew/dashboard/chat_handlers.py and several sandbox/test helpers this PR imports since the previous head was built (b1b0bb6 -> 7da2cbb); the push also carries the fix for span ca42d2c14d5b. CI re-running.

@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from a3f7b12 to a837b12 Compare November 2, 2026 23:54
@dodgeblaster

dodgeblaster commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: seal_operator_readonly pinned every mountinfo point below a read-only entry

  • span=3bd597d58c48 A mount the namespace cannot reach refuses every spawn

fixed in a837b12: seal_operator_readonly now skips a mount point below a read-only entry that it cannot stat (a root-only directory above it, a mount that went away), like an absent entry. The agent cannot reach such a mount either, so nothing is left writable.
A reachable mount that will not go read-only still refuses the spawn.
Pinned by test_a_mount_the_namespace_cannot_reach_is_skipped_not_refused, which uses a mode-000 directory above the mount and fails on a3f7b12.

@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 Nov 2, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: seal_operator_readonly skipped an unreachable submount, then re-opened the exception holding it

  • span=62de971c6401 A write exception can expose a skipped writable submount

fixed in 82afa38: seal_operator_readonly records every mount point below a read-only entry that it skipped as unreachable, and leaves any write exception that holds one read-only, with a launcher warning naming both. Unaffected exceptions still re-open.
A skipped point outside every exception stays behind the entry's read-only mount, where a chmod to restore traversal fails with EROFS, so it cannot be reached.
Pinned by test_an_exception_with_an_unreachable_mount_stays_read_only (no bind or rw remount of the affected exception; a sibling exception still re-opened), which fails on a837b12.

@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from a837b12 to 82afa38 Compare November 3, 2026 00:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 3, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

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 [100%] with no failure at 02:35:54 and was cancelled at 02:36 by the job's 40-minute timeout-minutes cap in platform-tests.yml, before pytest printed its summary. In the first run, shard 2 did the same: 39227 passed at 38:46, then cancelled. These are wall-clock caps on slow macOS runners, not test failures, and this diff adds no macOS-run test that takes measurable time: the launcher and real-sandbox tests skip off Linux.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 4, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from 82afa38 to d56905a Compare November 4, 2026 16:09
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_crew_container_config_isolation.py (#29526 shortened its docstrings), which conflicted with this PR's one-bullet addition to test_no_sandbox_setting_is_forced_to_a_permissive_value. Base 865d8d2b74 -> 32a43272d6. Kept main's version of the file and re-applied only this PR's lines (the list-valued setting rule, folded into main's shorter docstring, plus the existing elif branch). Still one commit, same 22 files; related suites pass locally (774 passed). New head d56905a9c4.

@github-actions github-actions Bot removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 4, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 7, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from 2a9ed38 to 8c4f7cf Compare November 7, 2026 11:01
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Fix pushed for the GPT 6.1 finding on 2a9ed3898b (mask_stages.py:476, a mountinfo record hidden by a later mount over its parent was remounted by a name that is no mount point, so EINVAL refused every spawn). New head 8c4f7cf5c5, still one commit, same 22 files, no rebase.

  • seal_operator_readonly now reads each pinned descriptor's mount ID from /proc/self/fdinfo and compares it with the IDs mountinfo lists at that point (_mount_ids_at, _mount_id_of). A record the name no longer reaches is skipped as unreachable, exactly like a mount behind a root-only directory: it is never remounted, and an exception containing it stays read-only with the existing warning. A stacked mount still matches its top ID and is sealed; an unreadable ID is judged as reached, so the remount runs and fails closed as before. Device numbers were not used because st_dev can differ from the mountinfo device on some filesystems (btrfs subvolumes), which would skip a visible mount and leave it writable.
  • test_a_hidden_mount_record_is_skipped_not_refused fails with the check disabled; test_an_unreadable_mount_id_is_judged_as_reached and test_a_descriptor_s_mount_id_is_the_one_mountinfo_lists_for_its_mount pin the fallback and the parser. Security spec and PR description updated.
  • Also fixed: the real-sandbox test's mode-000 skip condition called os.geteuid() at collection, which Windows lacks (the New-test stability (windows-latest) red).
  • Backend Tests shard 2 (Linux, Windows, macOS) fails on test_security_gate_liveness.py's line budget, which is red on main's own CI too; this PR does not touch that package.
  • Locally 2056 related tests pass, lint and mypy clean.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from 8c4f7cf to cdb315a Compare November 7, 2026 11:58
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from cdb315a to ac5eee9 Compare November 7, 2026 17:49
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/5974-sandbox-write-allowlist branch from ac5eee9 to 2de5be7 Compare November 7, 2026 18:56
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased: base a3fb5af23d -> 21597a3254 (no conflicts), to pick up read_endorsed_config_text from #31066 for the GPT 6.1 and Opus 5.5 findings on ac5eee97a1 (sandbox_tiers.py:1205): configured_readonly_layer read both config documents with plain read_config_text, so an agent that rewrote or deleted config.json after a gateway rename-save detached its per-file bind could drop the operator's read-only layer for later spawns.

  • Both documents now read through read_endorsed_config_text, as the loader reads them; where the bind can detach, a tampered, deleted or unreadable file reads as its gateway-endorsed copy.
  • test_an_agent_rewrite_after_a_rename_save_keeps_the_endorsed_layer (rewrite and delete, enforcement on) fails on ac5eee97a1 with an empty layer and passes here.
  • Security spec and the reader's docstring updated. Still one commit, same 22 files; locally 2273 related tests pass (sandbox suites, real-sandbox tests, test_config_json_bom.py, test_config_pending.py), black/isort/flake8/mypy clean. New head 2de5be7f84.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Fix pushed for the Opus 5.5 finding on 2de5be7f84 (sandbox_seatbelt.py:81: on macOS the agent could move a write exception aside and plant a symlink to a read-only sibling under its name, which the next plan would re-open). New head 013894c0b0, still one commit, same 22 files, no rebase. GPT 6.1 passed 2de5be7f84, so its config-read finding is cleared.

  • Seatbelt: each exception's own name now takes a file-write* literal deny after the allows, in every spelling the plan carries, so the directory cannot be renamed or replaced; writes inside it are other paths and stay allowed.
  • Planner, both backends: an exception whose path passes through a symlink below its read-only entry is refused (its canonical path is not the entry's canonical path plus the same suffix), so a planted link re-opens nothing. A symlinked root above the entry (macOS /tmp) is not judged.
  • test_seatbelt_denies_writes_to_an_exception_s_own_name_after_its_allow and test_an_exception_reached_through_a_link_below_its_entry_is_refused (both backends) fail on 2de5be7f84; test_an_entry_under_a_symlinked_root_keeps_its_exceptions is the control. Not run on a real Mac; the Seatbelt half is checked on the rendered profile.
  • Locally 2088 related tests pass; black/isort/flake8/mypy clean; security spec and PR description updated.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Fix pushed for the First Principles 5.5 blocker on 013894c0b0 (ancestor-guard walk shipped twice). New head f133fefa0d, still one commit, no rebase.

  • One implementation remains: sandbox_workspace._literal_ancestor_guards now delegates to sandbox_plan.path_ancestor_guards (a function-local import, so the facade's name set is unchanged and there is no import cycle; sandbox_workspace already imports from sandbox_plan). src/kiro_crew/sandbox_workspace.py is therefore the PR's 23rd file; the change there is that body only.
  • Behaviour is preserved for every crew caller: same guards, same order, no new seal, mask or refusal, nothing loosened. test_the_crew_and_operator_ancestor_guards_are_one_walk checks both names against the pre-dedupe walk on shared-ancestor, trailing-slash, root and empty inputs, and the existing sandbox_workspace callers' tests (test_sandbox_argv_launcher_plan.py, test_sandbox_argv_profile.py, test_sandbox_protected_name_holds.py, the facade tests) pass unchanged.
  • The note on item 6 (the last-good-layer cache) is not addressed in this push; it is advisory and left for the maintainer.
  • Backend Tests shards 5 and 6 (Linux, Windows, macOS) on the previous head failed in test_held_note_turn_starts.py and test_dashboard_server_composition_contract.py, which fail on main's own CI too; this PR does not touch those areas.
  • Locally 2189 related tests pass; black/isort/flake8/mypy clean.

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
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: afede1e
  • What rule changed: Two new operator config keys, agent.sandbox_readonly_paths and agent.sandbox_readonly_exceptions, add an optional read-only layer to the OS sandbox: listed directories become read-only to the agent, and exceptions strictly inside them stay writable. No existing mask, seal or carve-out changes. Seatbelt path quoting now also escapes backslashes on POSIX hosts.
  • Before -> after (what was allowed/blocked, now): Before: every path outside Kiro Crew's own masks and seals was writable to the agent per normal Unix permissions. After, with the keys unset (default): identical plan, launcher payload and Seatbelt profile. After, with the keys set: writes into a listed directory fail (EROFS on Linux, a Seatbelt write deny on macOS), writes into its exceptions land, and every crew mask and seal is applied on top of the layer and still wins. A path containing a backslash can no longer end its Seatbelt string early.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): Breaks commands. An operator who lists the project, the data home or an agent state directory gets an agent that cannot write there. The layer only removes write access and cannot re-open a crew-hidden or crew-sealed path, so no secret leaks. A launcher mount that cannot be made read-only refuses the spawn (fail closed). A refused exception mount leaves that path read-only.
  • Evidence checked (which sandbox result proves it): test/test_sandbox_readonly_layer_real_sandbox.py under the real namespace sandbox on Linux, all 3 tiers: a write into the read-only dir gives EROFS, the exception write lands, an unlisted sibling stays writable, nested levels alternate RO/RW as configured, and an exception naming the data home's profiles ceiling stays EROFS. The drive test fails on origin/main and passes on this head. A read-only entry whose parent the agent made mode 000 stays in the plan and is still sealed (test_a_locked_parent_does_not_drop_the_read_only_entry_below_it: the child restores the parent's mode and its write gets EROFS; it got ok on ffb5635). A mountinfo record hidden by a later mount over its parent is skipped by mount ID rather than remounted by a name that is no mount point (test_a_hidden_mount_record_is_skipped_not_refused). On Linux the parents of a read-only entry that the agent could rename are pinned, so a rename gets EBUSY and the next session still seals the real tree (test_the_agent_cannot_rename_a_read_only_entry_s_parent; the rename succeeded on 8c4f7cf). Both config documents are read as the loader reads them (read_endorsed_config_text), so an agent that rewrites or deletes config.json after a rename-save cannot drop the layer for later spawns (test_an_agent_rewrite_after_a_rename_save_keeps_the_endorsed_layer, which fails on ac5eee9). 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 swapping an exception for a link to a read-only sibling re-opens nothing (tests fail on 2de5be7). sandbox_workspace._literal_ancestor_guards now delegates to sandbox_plan.path_ancestor_guards (one implementation); crew callers get identical guards in the same order (test_the_crew_and_operator_ancestor_guards_are_one_walk, plus the existing sandbox_workspace callers' tests unchanged). Seatbelt: renderer tests on rule order and on quoting round-trips. Not run on a real Mac.
  • No regression:
    • Tools still work (which tools/commands were run, result): the real-sandbox child ran at standard/cc/strict and exited 0 with the expected per-path results; test_pinned_order_real_sandbox.py and test_seal_parent_pin_real_sandbox.py (main's fix: hold sandbox read-only guards in place #30783 seal-parent pins, which now run after the operator layer) passed alongside it.
    • Backward compatible (old config / old data / old callers still work, how checked): keys default to []; test_unset_keys_* and the real-sandbox control check it; payload keys are omitted when empty; crew carve-out validation unchanged; reading the keys does not rewrite config.json; an unparseable config keeps the last fully read layer with a SECURITY warning, and a fresh process with a broken config.local.json still applies config.json's entries (test_unparseable_overlay_without_a_cached_layer_applies_config_json, which fails on ee5ed96).
    • Existing tests (which suites passed on this head): test_sandbox_plan, test_sandbox_launcher_program, test_sandbox_argv_launcher_plan, test_sandbox_governance_mask, test_sandbox_mount_checked, test_sandbox_refactor_facade, test_crew_container_config_isolation, test_config_json_seal_survives_gateway_write, plus CI on this head.
  • How to undo: Remove both keys from config.json (or set them to []); new sessions then get the old sandbox exactly. To remove the code, revert this single commit.

@bolichen97 bolichen97 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.

Approve on afede1e. I read the whole diff (2865 lines), tests included. This fixes #5974.

  • Strictness check:
    • agent.sandbox_readonly_paths / agent.sandbox_readonly_exceptions are operator config in config.json, empty by default. Empty plans no layer, emits no operator_* 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.json is 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_carveouts checks).
    • / and entries holding the launcher's stand-in roots are refused with a SECURITY log.
  • 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_guards gives the same set.
    • _quoted now 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.

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

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Configurable write-scope boundary in native agent sandbox

2 participants