Skip to content

feat(sandbox): let an edition grant credential files to agent spawns - #15829

Closed
mrbeag wants to merge 1 commit into
kirodotdev:mainfrom
mrbeag:feat/sandbox-credential-grants
Closed

mrbeag wants to merge 1 commit into
kirodotdev:mainfrom
mrbeag:feat/sandbox-credential-grants

Conversation

@mrbeag

@mrbeag mrbeag commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let an edition give an agent session read-only access to specific credential files (for example ~/.docker/config.json) while the sandbox keeps the rest of their directory hidden.

The sandbox hides credential directories such as ~/.docker from agent sessions. A downstream edition that needs an agent to use one of those files today has to disable the sandbox or carry its own launcher patches. There is no narrow, per-file way to grant access.

This adds an optional SandboxPolicy.credential_file_grants() -> List[str] method. The edition owns consent, duration and grant storage; core validates the paths and supplies the Linux namespace mechanism. Default and legacy adapters grant nothing.

Why it matters

Without it, an edition whose users need agents to run authenticated tools (an image pull from a private registry, for example) can only turn the sandbox off or patch core. Both widen the agent's access far beyond the one file it needs, and patching core breaks on every upgrade.

Not a goal

  • Consent UI, grant duration or grant storage: those stay in the edition.
  • Credential-helper stores (credsStore / credHelpers).
  • Backends other than Linux namespaces: they keep the files hidden, as today.
  • Changing the existing sensitive-path checks on model file tools.
  • Granting directories, or anything outside a masked credential directory.

What changed (motivation → approach → change)

Hidden credential directories → let the edition name individual files, resolved once per spawn, and restore only those files as read-only snapshots inside the namespace → the changes below.

  • Resolve grants once per ACP spawn, off-loop, in the shared acp/launch.py path. Client and runtime supply the resolver through LaunchTools.
  • Thread extra_secret_files through the sandbox wrapper and namespace planner. Accept normalized HOME-relative file names, reject crew data homes and kiro trees, and fail closed on malformed adapter results.
  • Pair each file with its innermost masking directory. Drop grants outside all masks or inside private windows. A secret grant takes precedence over an expose copy of the same path.
  • Read granted files before masking with O_NOFOLLOW, descriptor type checks and a 256 KiB limit.
  • Restore snapshots through the staged launcher onto a namespace-private tmpfs. Walk placeholders without following links, pin and verify the target, seal mounts read-only, nosuid, nodev and noexec, verify the restored name, and detach staging.
  • Update the platform contract and add planner, launcher-stage and wrapper tests. Existing launcher fixtures declare the new payload keys.

The implementation follows upstream's current planner/staged-launcher/shared-ACP-launch design. The branch contains one conventional commit.

Backwards compatibility

Compatible: every new parameter defaults to empty, and the default edition and companions without the method grant nothing, so sandboxed spawns behave exactly as on main.

Removes nothing: the change only adds an opt-in way to expose named files; every directory that is masked today stays masked unless an edition grants a file inside it.

Tests

Local validation of the published code tree:

  • Credential grant tests: 48 passed, including execution of the real launcher stages with controlled mount helpers.
  • ACP client/runtime suites: 1,450 passed, on both the PR and pristine upstream.
  • Sandbox, launcher, plan, mount-check, golden and platform suites were compared with pristine upstream. The same 15 failures occurred on both because the test process runs inside an existing sandbox; the PR introduced no additional failures in that comparison.
  • black, isort, flake8 and mypy passed.

The author/committer amendment preserves the exact tested tree: 4404e71a512bd92f01389b8362018a5e1b4a2e53. CI on the published head remains required.

Manual verification

Passed on 2026-10-09 in a real Linux user/mount namespace, outside the nested agent sandbox. The test used a throwaway HOME, a generated test login, and a password-protected registry bound to 127.0.0.1:5055; personal credentials were not used.

Control without a grant:

  • ~/.docker was empty.
  • Authenticated image pull was refused.
  • No host-visible copy of the test login was found while the sandbox ran.

With .docker/config.json granted:

  • Only config.json was visible.
  • The snapshot was readable and read-only.
  • Authenticated image pull succeeded.
  • No host-visible copy of the test login was found while the sandbox ran, scanning /run/user/<uid>, /dev/shm and /tmp.

Related Issues

Supersedes the mechanism half of #6663 (closed). Related: #9131, #9010.

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 (local comparison completed; CI pending)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

7 similar comments
@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 1, 2026
@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

5 similar comments
@dwu96

dwu96 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@dwu96

dwu96 commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@mrbeag
mrbeag force-pushed the feat/sandbox-credential-grants branch from bd36bc1 to 14774a4 Compare October 9, 2026 09:51
@mrbeag
mrbeag marked this pull request as ready for review October 9, 2026 09:52
@mrbeag
mrbeag requested review from a team and KiroCrewCaptain as code owners October 9, 2026 09:52
@mrbeag
mrbeag requested a review from bolichen97 October 9, 2026 09:52
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 9, 2026
The sandbox hides whole credential homes (~/.docker, ~/.kube, ...) from
every agent. That is the right default, but a deployment whose operators
want agents to pull from a private registry has no lever short of turning
the sandbox off, and no edition can add one without patching the launcher.

Add SandboxPolicy.credential_file_grants(): an edition names
$HOME-relative files to restore for one ACP agent spawn. The core
resolves it off-loop on every spawn (never cached), refuses anything under
the crew data home or the kiro trees, and the Linux namespace launcher
restores each granted file as a read-only snapshot on a tmpfs private to
the sandbox's mount namespace -- not the host-visible stand-in that
extra_expose_files copies into -- while the rest of the hidden parent stays
hidden. Reads use O_NOFOLLOW with type and size checked on the opened
descriptor. Seatbelt and Windows drop the grant with a warning.

The Default adapter grants nothing and a companion without the method
grants nothing, so the public edition is unchanged. Consent, duration and
storage of a grant stay with the edition.
@mrbeag
mrbeag force-pushed the feat/sandbox-credential-grants branch from 14774a4 to 25df576 Compare October 13, 2026 11:27
@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 Oct 13, 2026
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 13, 2026
@mrbeag mrbeag closed this Oct 14, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants