Repository navigation
feat(core): add opt-in OS-level shell sandbox - #63599
alexm-redhat wants to merge 1 commit into
Conversation
Wrap shell tool commands with bubblewrap on Linux and sandbox-exec on macOS. The sandbox supports read-only and workspace-write modes, denies the network by default, and fails closed when the backend is unavailable. A `sandbox: false` call requires the separate `shell_unsandboxed` permission, which defaults to ask, so approving a command never approves leaving the sandbox. Sandbox settings are pinned per workspace on first use. Amalgamator was used for AI assistance (https://github.com/amalgamator-ai/amalgamator) Signed-off-by: Alexander Matveev <amatveev@redhat.com>
There was a problem hiding this comment.
The bubblewrap wrapper does what it says on Linux, but the sandbox still has an escape that survives a restart. I installed bubblewrap and ran Sandbox.wrap in workspace-write mode: writes outside the workspace and outbound TCP were blocked, and an existing opencode.json stayed read-only. I couldn't run the macOS profile or OpenCode end-to-end. As the description says, this is a core feature that CONTRIBUTING.md wants design-approved first, so the overall approach needs a maintainer's decision.
Public API (all additions, backwards compatible; the sandbox is off unless enabled):
- a new
sandboxconfig key withenabled,mode,network,writable_rootsandreadable_roots, plus the generated OpenAPI spec and client types; - a new
shell_unsandboxedpermission, set toaskin the default agent ruleset; - a new optional
sandboxboolean input on theshelltool.
Concerns:
- A confined command can plant an escape for the next start (blocking). Only config files that already exist are bound read-only. In a fresh workspace, a sandboxed command created
.opencode/plugins/evil.tsand anopencode.jsonwith{"sandbox":{"network":"allow","writable_roots":["/"]}};.claude/and.agents/are config sources too and aren't protected. After a restart the plugin runs inside OpenCode with no sandbox, and the policy is widened. Pinning only covers the current process. See the inline comments. - Repo config can loosen the user's sandbox. A project
opencode.jsoncan turn network on when the user's config leaves it unset (the default), and can add writable roots. A cloned repository shouldn't be able to widen the sandbox the user enabled. - It confines more than the shell tool. The wrap happens in
Shell.Service, so the user's own!shell commands and plugin shells run confined too, with noshell_unsandboxedway out. If that's intended, the description and docs should say so; otherwise the decision belongs in the tool path. - Policy is kept in a module-level
Map. It's process-wide state outside the Effect services, keyed by directory and never cleared (it needs aresetPoliciestest hook). It would fit better as part of a Location-scoped service. - The live network test is brittle. It counts interfaces in
/proc/net/dev, and on my kernel the new namespace had 9 tunnel devices (tunl0,gre0, …), so the test failed while the network was in fact blocked. Testing an actual connection attempt would be more reliable. - The base is behind
dev, which has recent changes topackages/core/src/shell.ts(#63409, #62978), so this may need a rebase.
| * Workspace paths a sandboxed command can never write, even in `workspace-write`: the files that configure the | ||
| * sandbox. Otherwise a confined command could write `{"sandbox":{"enabled":false}}` and run unconfined next time. | ||
| */ | ||
| export const PROTECTED = ["opencode.json", "opencode.jsonc", ".opencode"] as const |
There was a problem hiding this comment.
This list leaves out other config sources: .claude and .agents are discovered as config directories too (config/discovery.ts). Also, it only protects paths that already exist (see protectedPaths below). In a workspace without them, a confined command could create .opencode/plugins/evil.ts and opencode.json with {"sandbox":{"network":"allow","writable_roots":["/"]}}; I reproduced this with bubblewrap. On the next start the plugin runs inside OpenCode, outside any sandbox. Absent config paths need protecting as well (e.g. mount a read-only empty placeholder, or deny creating them), and probably .git/hooks too, as other workspace-write sandboxes do.
| // already exist are bound: bubblewrap has to create a mount point for a missing target, which would leave an | ||
| // empty file in the workspace behind, and it refuses to mount on a symlink destination at all. An absent or | ||
| // symlinked config path is workspace content a command may create or replace, like any other file. | ||
| const protectedPaths = |
There was a problem hiding this comment.
Skipping absent and symlinked paths is where the escape above gets in. Pinning stops a planted config from affecting this process, but not the next one, so here 'absent' has to mean 'cannot be created', not 'ordinary workspace content'.
| const pick = <K extends keyof ConfigSandbox.Info>(key: K) => | ||
| layers.findLast((layer) => layer[key] !== undefined)?.[key] | ||
| const roots = <K extends "writable_roots" | "readable_roots">(key: K) => { | ||
| const all = layers.flatMap((layer) => layer[key] ?? []) |
There was a problem hiding this comment.
Roots add up across layers, and network: "allow" from a project layer wins whenever no layer says deny. The schema default is deny, but the user usually leaves it unset. So a cloned repository's opencode.json can widen a sandbox the user turned on, both network and writable roots. Should widening settings only be accepted from global, system or managed config?
| // Pinned per workspace on first use, so config written by a confined command cannot change this process's | ||
| // policy. Fails closed: an enabled sandbox that cannot confine the command stops it from running at all. | ||
| const entries = yield* config.entries() | ||
| const policy = Sandbox.policy(entries, location.directory) |
There was a problem hiding this comment.
The sandbox is applied in Shell.Service, which SessionShell.start (the user's own ! commands) and plugins also use. Those get confined with no way to opt out, because only the tool can pass unsandboxed. The description says the sandbox applies only to the shell tool. Either the caller should decide (e.g. the tool asks for confinement explicitly), or the docs need to say user commands are confined too. Also, the per-workspace pin is a module-level Map that is never cleared; it would fit better as part of a Location-scoped service than as process-global state.
| } | ||
| }) | ||
|
|
||
| test("denies the network by default and shares it only when allowed", () => |
There was a problem hiding this comment.
This fails on hosts whose new network namespace has tunnel devices (tunl0, gre0, sit0…): I got 9 instead of 0 here, although outbound connections did fail with 'Network is unreachable'. Checking an actual connection attempt (e.g. to a local listener started outside the sandbox) would test the actual behaviour and not depend on the kernel's modules.
|
@rekram1-node would be good to get a sanity check. If the change makes sense and whether it is interesting for the project. Happy to adjust whether needed. |
|
@rekram1-node a quick feedback would be helpful. |
Issue for this PR
Addresses the sandboxed-execution part of #48411.
Type of change
What does this PR do?
Adds an opt-in OS-level sandbox for the
shelltool. When enabled, shell commands are wrapped in bubblewrap on Linux orsandbox-execon macOS, with a read-only or workspace-write filesystem, network denied by default, and fail-closed behavior when the backend is missing.{ "sandbox": { "enabled": true, "mode": "workspace-write", "network": "deny" }, }The sandbox applies only to shell commands. Leaving it requires the separate
shell_unsandboxedpermission (askby default), so approving a command never approves escaping the sandbox. Policy is pinned per workspace on first use; changing sandbox settings needs a restart. Existing config files are bound read-only; absent or symlinked config paths stay ordinary workspace content.This is a core feature and
CONTRIBUTING.mdasks for design approval before implementation. The branch is prepared for that review; happy to adjust the approach.How did you verify your code works?
cd packages/core && bun run typecheckcd packages/core && bun test test/sandbox.test.ts test/shell-daemon.test.ts test/shell-sandbox-spawner.test.ts test/tool-shell.test.ts test/config/normalization.test.ts test/agent.test.tscd packages/schema && bun testcd packages/protocol && bun run check:generatedpackages/coresuite: 7,132 pass, 350 skip, 23 pre-existing failures, zero new (bun run test).Screenshots / recordings
Not a UI change.
Checklist
Amalgamator was used for AI assistance (https://github.com/amalgamator-ai/amalgamator)
Added by the opencode bot (AI-generated).
Related: #48411, #2242
Public API: adds the
sandboxconfig key, theshell_unsandboxedpermission and an optionalsandboxinput on the shell tool (backwards compatible, off by default)