Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions packages/client/src/promise/generated/types.ts

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

28 changes: 28 additions & 0 deletions packages/core/src/config/normalize.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import { ConfigPlugin } from "@opencode/schema/config/plugin"
import { ConfigPolicy } from "@opencode/schema/config/policy"
import { ConfigProvider } from "@opencode/schema/config/provider"
import { ConfigReference } from "@opencode/schema/config/reference"
import { ConfigSandbox } from "@opencode/schema/config/sandbox"
import { ConfigExperimental } from "@opencode/schema/config/experimental"
import { Permission } from "@opencode/schema/permission"
import { ConfigAgentV1 } from "../v1/config/agent.js"
Expand Down Expand Up @@ -197,6 +198,7 @@ export function normalize(input: unknown): Result {
normalizeWatcher(input, encoded, diagnostics)
normalizeFormatter(input, encoded, diagnostics)
normalizeLsp(input, encoded, diagnostics)
normalizeSandbox(input, encoded, diagnostics)

const model = own(input, "model")
? decodeValue(ConfigModel.Selection, input.model, ["model"], diagnostics)
Expand Down Expand Up @@ -231,6 +233,32 @@ export function normalize(input: unknown): Result {
return { type: "normalized", encoded, diagnostics }
}

// A malformed sandbox block must not switch the sandbox off: it is a security control, so unlike other settings it is
// never dropped. Invalid input resolves to an enabled sandbox, keeping the fields that are valid and taking the
// strictest value for the rest.
function normalizeSandbox(input: Record<string, unknown>, encoded: Record<string, unknown>, diagnostics: Diagnostic[]) {
if (!own(input, "sandbox")) return
const value = decodeEncoded(Info.fields.sandbox, input.sandbox, ["sandbox"], [])
if (value !== undefined) {
overlay(encoded, "sandbox", value, ["sandbox"], diagnostics)
return
}
invalid(["sandbox"], diagnostics)
const raw = isRecord(input.sandbox) ? input.sandbox : {}
const mode = decodeEncoded(ConfigSandbox.Mode, raw.mode, ["sandbox", "mode"], [])
const network = decodeEncoded(ConfigSandbox.Network, raw.network, ["sandbox", "network"], [])
// Roots only widen what the sandbox can reach, so each is kept when it decodes on its own.
const writable = decodeEncoded(ConfigSandbox.Roots, raw.writable_roots, ["sandbox", "writable_roots"], [])
const readable = decodeEncoded(ConfigSandbox.Roots, raw.readable_roots, ["sandbox", "readable_roots"], [])
encoded.sandbox = {
enabled: true,
mode: mode ?? "read-only",
network: network ?? "deny",
...(writable === undefined ? {} : { writable_roots: writable }),
...(readable === undefined ? {} : { readable_roots: readable }),
}
}

function normalizeSkills(input: Record<string, unknown>, encoded: Record<string, unknown>, diagnostics: Diagnostic[]) {
if (!own(input, "skills")) return
if (Array.isArray(input.skills)) {
Expand Down
247 changes: 247 additions & 0 deletions packages/core/src/sandbox.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,247 @@
export * as Sandbox from "./sandbox.js"

import { existsSync, lstatSync, realpathSync } from "fs"
import { tmpdir } from "os"
import path from "path"
import { Schema } from "effect"
import type { Entry } from "@opencode/schema/config"
import type { ConfigSandbox } from "@opencode/schema/config/sandbox"
import { which } from "./util/which.js"

/**
* OS-level sandbox for agent shell commands. The command is wrapped, never reimplemented: bubblewrap on Linux and
* sandbox-exec (Seatbelt) on macOS confine the shell and everything it starts. Nothing here runs a process or
* touches the filesystem except to locate the backend and resolve symlinks, so the wrapping is plain data.
*
* Filesystem: everything is readable, and only the workspace (plus temporary directories) is writable, or nothing
* with `read-only`. Network: denied unless the policy allows it. An enabled sandbox never falls back to running
* the command unconfined.
*/

export interface Policy {
readonly mode: ConfigSandbox.Mode
readonly network: ConfigSandbox.Network
/** Extra directories a `workspace-write` sandbox may write to. */
readonly writableRoots?: readonly string[]
/** Extra directories mounted read-only. */
readonly readableRoots?: readonly string[]
}

export interface Command {
readonly program: string
readonly args: readonly string[]
}

export class UnavailableError extends Schema.TaggedError<UnavailableError>()("Sandbox.UnavailableError", {
reason: Schema.String,
}) {
override get message() {
return `Sandbox is enabled but unavailable: ${this.reason}. The command was not run. Fix the sandbox, or set sandbox.enabled to false.`
}
}

export interface WrapInput {
readonly policy: Policy
readonly command: Command
readonly cwd: string
/** The one directory a `workspace-write` sandbox may write to. */
readonly workspace: string
/** Remote workspaces run commands elsewhere, where this host's sandbox does not apply. */
readonly remote?: boolean
readonly platform?: NodeJS.Platform
/** Finds an executable. Defaults to a PATH lookup. */
readonly find?: (name: string) => string | undefined
}

/**
* The sandbox settings of every config layer, lowest priority first, merged field by field. A layer that sets only
* `network` cannot drop `enabled` from a lower layer, and the security settings are monotonic: once any layer
* enables the sandbox, selects `"read-only"`, or denies the network, a later layer cannot loosen it. Only roots are
* additive grants, because a project may legitimately need more writable directories.
*/
export function merge(entries: readonly Entry[]): ConfigSandbox.Info | undefined {
const layers = entries.flatMap((entry) =>
entry.type === "document" && entry.info.sandbox ? [entry.info.sandbox] : [],
)
if (layers.length === 0) return undefined
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] ?? [])

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.

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?

return all.length === 0 ? undefined : [...new Set(all)]
}
const enabled = layers.some((layer) => layer.enabled === true) ? true : pick("enabled")
const mode = layers.some((layer) => layer.mode === "read-only") ? "read-only" : pick("mode")
const network = layers.some((layer) => layer.network === "deny") ? "deny" : pick("network")
return {
enabled,
mode,
network,
writable_roots: roots("writable_roots"),
readable_roots: roots("readable_roots"),
} as ConfigSandbox.Info
}

// The policy a workspace runs under, fixed when it first asks for a command. Pinning it means a config file that a
// confined command creates or rewrites cannot change the policy of the running process: the sandbox settings of a
// workspace are read once, like a command-line flag, and changing them needs a restart. Without the pin, a
// workspace-write command could write an opencode.json that grants itself network access or extra roots on its next
// invocation.
const policies = new Map<string, Policy | undefined>()

/**
* The policy for a workspace, pinned on first use. `entries` is read only when the workspace has no policy yet.
*/
export function policy(entries: readonly Entry[], workspace: string): Policy | undefined {
const key = canonical(workspace)
if (!policies.has(key)) policies.set(key, resolve(merge(entries)))
return policies.get(key)
}

/** Test helper: forget every pinned workspace policy. */
export function resetPolicies() {
policies.clear()
}

/**
* 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

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.

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.


/** The policy to enforce, or undefined when the sandbox is not enabled. Unset `network` takes the strictest value (deny); an unset `mode` takes the schema default `workspace-write`, which is NOT the strictest mode (`read-only` is). */
export function resolve(config: ConfigSandbox.Info | undefined): Policy | undefined {
if (config?.enabled !== true) return undefined
return {
mode: config.mode ?? "workspace-write",
network: config.network ?? "deny",
...(config.writable_roots?.length ? { writableRoots: config.writable_roots } : {}),
...(config.readable_roots?.length ? { readableRoots: config.readable_roots } : {}),
}
}

export function wrap(input: WrapInput): Command | UnavailableError {
const platform = input.platform ?? process.platform
if (input.remote)
return new UnavailableError({ reason: "the sandbox cannot confine commands that run in a remote workspace" })
if (platform !== "linux" && platform !== "darwin")
return new UnavailableError({ reason: `no sandbox backend exists for ${platform}` })
const name = platform === "linux" ? "bwrap" : "sandbox-exec"
const program = (input.find ?? find)(name)
if (!program)
return new UnavailableError({
reason: `${name} was not found${platform === "linux" ? " (install bubblewrap)" : ""}`,
})
const workspace = canonical(input.workspace)
const args = platform === "linux" ? bwrapArgs(input, workspace) : seatbeltArgs(input, workspace)
return { program, args: [...args, "--", input.command.program, ...input.command.args] }
}

// Extra roots resolve against the workspace and are canonical, like the workspace itself.
function roots(list: readonly string[] | undefined, workspace: string) {
return [...new Set((list ?? []).map((root) => canonical(path.resolve(workspace, root))))]
}

export function bwrapArgs(input: Pick<WrapInput, "policy" | "cwd">, workspace: string) {
const writable = input.policy.mode === "workspace-write" ? roots(input.policy.writableRoots, workspace) : []
const readable = roots(input.policy.readableRoots, workspace)
// Binds go after the workspace bind so they stay read-only inside it. Only regular files and directories that
// 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 =

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.

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'.

input.policy.mode === "workspace-write"
? // A writable root that does not exist is not mounted, so there is nothing in it to protect.
[workspace, ...writable.filter((root) => existsSync(root))].flatMap((base) =>
PROTECTED.flatMap((name) => {
const target = path.join(base, name)
const stat = lstatSync(target, { throwIfNoEntry: false })
return stat && !stat.isSymbolicLink() ? ["--ro-bind", target, target] : []
}),
)
: []
return [
"--die-with-parent",
"--new-session",
// Every namespace, including the network. `--share-net` below joins the host's again only when allowed.
"--unshare-all",
...(input.policy.network === "allow" ? ["--share-net"] : []),
"--ro-bind",
"/",
"/",
"--dev",
"/dev",
"--proc",
"/proc",
// Private and ephemeral, so even a read-only sandbox has scratch space that never reaches the host.
"--tmpfs",
"/tmp",
// After the tmpfs, so a workspace under /tmp stays the real directory (writable in workspace-write mode,
// read-only otherwise — either way it must still be the real directory and not the fresh tmpfs).
...readable.flatMap((root) => ["--ro-bind-try", root, root]),
...(input.policy.mode === "workspace-write"
? ["--bind", workspace, workspace]
: ["--ro-bind-try", workspace, workspace]),
...writable.flatMap((root) => ["--bind-try", root, root]),
...protectedPaths,
"--chdir",
input.cwd,
]
}

// Directories are passed as `-D` parameters and read with `(param ...)`, so no path is ever spliced into the profile.
export function seatbeltProfile(policy: Policy) {
const writable = policy.mode === "workspace-write" ? (policy.writableRoots ?? []) : []
return [
"(version 1)",
"(deny default)",
"(allow process-exec)",
"(allow process-fork)",
"(allow signal (target self))",
"(allow process-info* (target same-sandbox))",
"(allow sysctl-read)",
"(allow mach-lookup)",
"(allow ipc-posix-shm)",
"(allow user-preference-read)",
"(allow pseudo-tty)",
"(allow file-read*)",
'(allow file-write* (literal "/dev/null") (literal "/dev/dtracehelper") (regex #"^/dev/tty"))',
...(policy.mode === "workspace-write"
? [
'(allow file-write* (subpath (param "WORKSPACE")) (subpath (param "TMPDIR")) (subpath "/private/tmp"))',
...writable.map((_, index) => `(allow file-write* (subpath (param "WRITABLE_${index}")))`),
// Last, so it wins: the files that configure the sandbox stay read-only inside every writable directory.
...["WORKSPACE", ...writable.map((_, index) => `WRITABLE_${index}`)].map(
(param) =>
`(deny file-write* ${PROTECTED.map((name) => `(subpath (string-append (param "${param}") "/${name}"))`).join(" ")})`,
),
]
: []),
...(policy.network === "allow" ? ["(allow network*)"] : []),
].join("\n")
}

function seatbeltArgs(input: Pick<WrapInput, "policy">, workspace: string) {
const writable = input.policy.mode === "workspace-write" ? roots(input.policy.writableRoots, workspace) : []
return [
"-p",
// Indexes line up with the roots the profile refers to, which resolve here the same way.
seatbeltProfile({ ...input.policy, writableRoots: writable }),
"-D",
`WORKSPACE=${workspace}`,
"-D",
`TMPDIR=${canonical(tmpdir())}`,
...writable.flatMap((root, index) => ["-D", `WRITABLE_${index}=${root}`]),
]
}

function canonical(directory: string) {
// Seatbelt and bind mounts match real paths, so a symlinked workspace (macOS /var -> /private/var) must resolve.
return existsSync(directory) ? realpathSync(directory) : directory
}

function find(name: string) {
// macOS ships sandbox-exec at a fixed path; prefer it over whatever PATH holds.
if (name === "sandbox-exec" && existsSync("/usr/bin/sandbox-exec")) return "/usr/bin/sandbox-exec"
return which(name) ?? undefined
}
Loading
Loading