Files
stack/packages/seat/src/sandbox.mjs
T

362 lines
24 KiB
JavaScript

// The confinement a managed role session runs in (#1586). The runner and
// everything it starts, the harness and every shell the harness opens, run
// inside a bubblewrap mount namespace built from an empty root. The session
// sees only the binds below, each at its own host path so session.json's
// paths mean the same inside and out:
//
// read-only /usr, /etc and the host's /bin, /lib, /lib64, /sbin links;
// the repository files the runner loads; the adapter; for pi
// the repository's node_modules, for Claude Code its pinned
// binary; node when it lives outside /usr; the broker socket,
// the launch socket for the role that may launch, and the
// host's git socket for a role holding git.push.working or
// review.verdict (#1587)
// read-write the instance's workspace and the run directory, except the
// run's bundle/ and session.json, which stay read-only
// private /tmp (the run's tmp/), HOME (the run's home/), /dev, /proc
//
// The environment adds HOME, TMPDIR and the role's git identity
// (gitIdentity() below).
//
// Nothing else exists inside: no data root, no other workspace or run
// directory, no ~/.config, ~/.mosaic or ~/.ssh, no checkout beyond the
// runner's files. The root is remounted read-only, so a write anywhere but
// a read-write bind fails. The session keeps a user and PID namespace (the
// runner is pid 1, as before) and an IPC namespace. The runner dies with the
// bwrap process outside, as it did with unshare's --kill-child: setpriv
// gives it SIGKILL as its parent-death signal. bwrap's own --die-with-parent
// isn't used, because it also kills bwrap when the host dies, and a session
// outlives a host that died hard (the next host recovers it). The network,
// abstract Unix sockets and the host UID are not confined
// (packages/harness/README.md, "Limits").
//
// There is no unconfined fallback: a bwrap that is missing or fails refuses
// the launch (sandbox-unavailable).
import { spawnSync } from "node:child_process";
import { existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { ID_PATTERN } from "../../organization/src/vocabulary.mjs";
export const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
export const BWRAP = "/usr/bin/bwrap";
const KILL_WITH_PARENT = ["/usr/bin/setpriv", "--pdeathsig", "KILL", "--"];
// What the runner imports, and the three files the harness starts from the
// bundle's settings (claude-gate, mcp-server, pi-extension) with theirs.
// packages/seat/tests/sandbox.test.mjs walks the imports and fails when one
// is missing here.
export const RUNNER_FILES = Object.freeze([
"packages/harness/src/runner.mjs",
"packages/harness/src/failure-notice.mjs",
// Row 331: fixed output-exists marker; writes only within the existing run directory.
"packages/harness/src/first-output.mjs",
"packages/harness/src/gate.mjs",
"packages/harness/src/tools.mjs",
"packages/harness/src/git-tools.mjs",
"packages/harness/src/claude-gate.mjs",
"packages/harness/src/mcp-server.mjs",
"packages/harness/src/pi-extension.mjs",
"packages/bus/src/client.mjs",
"packages/bus/src/broker.mjs",
"packages/bus/src/refusals.mjs",
"packages/organization/src/rails.mjs",
"packages/organization/src/autonomy.mjs",
"packages/bus/src/autonomy-state.mjs",
"packages/bus/src/proxy-page-vocabulary.mjs",
// Row 331 r5: parsing only; common.mjs and PIN remain outside the sandbox.
"packages/model-proxy/src/validation.mjs",
"packages/bus/src/address.mjs",
"packages/bus/src/landing.mjs",
"packages/organization/src/vocabulary.mjs",
"packages/plugins/src/kinds.mjs",
"packages/library/src/reply-protocol.mjs",
"packages/processing-control/src/state.mjs",
"packages/tasks/src/requirements.mjs",
].map((p) => join(REPO, p)));
const SYSTEM_LINKS = ["/bin", "/lib", "/lib64", "/sbin"];
const NAMESPACES = ["--unshare-user", "--unshare-pid", "--unshare-ipc", "--as-pid-1"];
// The system part every session gets, and the probe runs: /usr, the host's
// links into it, /etc, a private /dev and /proc, and node when it lives
// outside /usr.
function systemBinds(node = process.execPath) {
const out = [{ kind: "ro", src: "/usr", why: "the system's programs and libraries: sh, node, git, coreutils" }];
for (const p of SYSTEM_LINKS) {
let st;
try {
st = lstatSync(p);
} catch {
continue;
}
if (st.isSymbolicLink()) out.push({ kind: "symlink", src: readlinkSync(p), dest: p, why: `the host's ${p} link into /usr` });
else out.push({ kind: "ro", src: p, why: `the host's ${p}, which isn't a link into /usr` });
}
out.push(
{ kind: "ro", src: "/etc", why: "name resolution, CA certificates, passwd for the user's name" },
{ kind: "dev", dest: "/dev", why: "a private /dev with null, zero, urandom and a pty" },
{ kind: "proc", dest: "/proc", why: "the session's own PID namespace; node and the shell read /proc/self" },
);
const real = realpathSync(node);
if (!real.startsWith("/usr/")) out.push({ kind: "ro", src: real, dest: node, why: "node, which runs the runner and the gate, lives outside /usr" });
return out;
}
// The binds for one session, in mount order; each says why the session
// needs it. paths: the run directory, the instance's workspace, the adapter,
// the harness module's mounts (row 65: its mounts(), [{ src, dest, why }],
// read-only), the broker socket, the launch socket (null for a role that may
// not launch), the git socket (null for a role that neither pushes nor
// reviews), the thread's session store (session.mjs threadStore() or
// sessionStore(), or null) and node. workspaceDest (row 269) is where the
// workspace shows inside the sandbox when that isn't its host path: a legacy
// thread session's, so its harness finds the cwd its history recorded.
// `hidden` (#1873 A3) lists directories inside the workspace the session may not see: a project
// checkout a launch before this one made, in a project that now excludes or refuses the instance.
// Each gets an empty tmpfs over it, so its files stay on the host, untouched, and out of sight.
// Each must be a real directory: a tmpfs mounted at a symlink would land on the link's target.
// `readOnly` adds files, for tests only.
export function binds({ runDir, workspace, workspaceDest = null, hidden = [], adapter, harnessMounts = [], brokerSocket, launchSocket = null, gitSocket = null, threadStore = null, node = process.execPath, readOnly = [] }) {
const out = systemBinds(node);
for (const f of RUNNER_FILES) out.push({ kind: "ro", src: f, why: "a repository file the runner loads" });
out.push({ kind: "ro", src: adapter, why: "the harness adapter the runner starts each turn" });
for (const m of harnessMounts) out.push({ kind: "ro", src: m.src, ...(m.dest ? { dest: m.dest } : {}), why: m.why });
out.push({ kind: "ro", src: brokerSocket, why: "the broker socket the runner claims and calls through" });
if (launchSocket) out.push({ kind: "ro", src: launchSocket, why: "the launch socket, for the role whose launch tool calls it" });
if (gitSocket) out.push({ kind: "ro", src: gitSocket, why: "the host's git socket, for push_working and fetch_review, and land_work" });
for (const f of readOnly) out.push({ kind: "ro", src: f, why: "a test fixture" });
out.push(
{ kind: "rw", src: workspace, ...(workspaceDest && workspaceDest !== workspace ? { dest: workspaceDest } : {}), why: "the instance's workspace, where the harness works" },
...hidden.map((h) => {
const inside = relative(workspace, h);
if (!inside || inside.startsWith("..") || isAbsolute(inside)) throw new Error(`hidden path ${h} is not inside the workspace`);
let real = false;
try { real = lstatSync(h).isDirectory(); } catch { real = false; }
if (!real) throw new Error(`hidden path ${h} is not a directory`);
return { kind: "tmpfs", dest: join(workspaceDest ?? workspace, inside), why: "a project checkout this launch may not see, covered by an empty tmpfs" };
}),
{ kind: "rw", src: runDir, why: "the run directory: turns/, session/, tools.sock, turn.done, home/, tmp/" },
{ kind: "ro", src: join(runDir, "bundle"), why: "the run's bundle stays as the host wrote it" },
{ kind: "ro", src: join(runDir, "session.json"), why: "the session file stays as the host wrote it" },
{ kind: "rw", src: join(runDir, "tmp"), dest: "/tmp", why: "a private /tmp, on disk in the run directory" },
);
// Row 121: only this thread's store, and only its two directories.
if (threadStore) {
out.push(
{ kind: "rw", src: threadStore.session, why: "the thread's session directory, kept across its runs (MOSAIC_SESSION_DIR)" },
{ kind: "rw", src: threadStore.projects, dest: join(runDir, "home", ".claude", "projects"), why: "the thread's Claude Code transcripts, kept across its runs" },
);
}
return out;
}
function argsOf(list) {
const args = [];
for (const b of list) {
if (b.kind === "ro") args.push("--ro-bind", b.src, b.dest ?? b.src);
else if (b.kind === "rw") args.push("--bind", b.src, b.dest ?? b.src);
else if (b.kind === "symlink") args.push("--symlink", b.src, b.dest);
else if (b.kind === "dev") args.push("--dev", b.dest);
else if (b.kind === "proc") args.push("--proc", b.dest);
else if (b.kind === "tmpfs") args.push("--tmpfs", b.dest);
}
return args;
}
// The run's home/ and tmp/, made before the spawn: binds need their sources.
// A thread run also needs the mount point for its transcripts.
export function prepareRun(runDir, { threadStore = null } = {}) {
for (const d of ["home", "tmp"]) mkdirSync(join(runDir, d), { recursive: true, mode: 0o700 });
if (threadStore) mkdirSync(join(runDir, "home", ".claude", "projects"), { recursive: true, mode: 0o700 });
}
// The git identity a session commits under (#1598): the role instance's
// name, and <instance>@<business>.mosaic.invalid, a domain that can't
// receive mail. It goes in the environment, so a clone's config needs no
// user.name or user.email key, which would keep the clone at the next launch
// (checkout.mjs, allowed()). Both ids must be business ids.
export function gitIdentity({ business, role }) {
for (const [what, id] of [["business", business], ["role", role]]) {
if (typeof id !== "string" || !ID_PATTERN.test(id)) throw new Error(`git identity: ${what} ${JSON.stringify(id)} isn't an id`);
}
const email = `${role}@${business}.mosaic.invalid`;
return { GIT_AUTHOR_NAME: role, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: role, GIT_COMMITTER_EMAIL: email };
}
// The full command line for `command` inside the sandbox. HOME is the run's
// home/, empty at the start; the harness makes what it needs there. The git
// identity is the role's, for the business it runs in.
export function sandboxArgv(list, runDir, command, { business, role, bwrap = BWRAP }) {
const identity = Object.entries(gitIdentity({ business, role })).flatMap(([k, v]) => ["--setenv", k, v]);
return [bwrap, ...NAMESPACES, ...argsOf(list), "--remount-ro", "/", "--setenv", "HOME", join(runDir, "home"), "--setenv", "TMPDIR", "/tmp", ...identity, "--chdir", runDir, "--", ...KILL_WITH_PARENT, ...command];
}
// #1873 triage-fences: what a model route may hand a hosted session, checked before the host
// writes anything and again in hostedBinds. The adapter and each mount's source must be a clean
// absolute path whose real path lies under one of the harness module's install roots, named under
// that same root, and outside every protected path: the data root, the config directory and HOME
// the caller passes, the run directory, ALWAYS_PROTECTED, and any path with a segment that
// contains "secret" in any case. A protected path counts in its own spelling and its real path, and
// a source may neither lie inside one nor contain one. The bind's source is the real path, so a
// link swapped after the check cannot steer it. A mount's dest (its source when it names none) is
// never /tmp, the run directory or a system bind's dest, nor inside or around one, never a parent
// of or equal to a runner file, the adapter or node, and never in or around another mount's dest.
// At most HOSTED_MOUNTS_MAX mounts. A refusal is a HostedRouteError naming its fence, never a path.
// `codeRoot` is the stack's own code and `codeHolder` the one protected path that may hold it:
// HOME, when the stack runs from a copy or a worktree under it. That path does not refuse a source
// whose named and real paths both lie in the code root. Every other check still applies to it, and
// no other protected path, the run directory or ALWAYS_PROTECTED is ever set aside. A code root in
// or around the run directory or ALWAYS_PROTECTED, in either path's spelling or real path, is refused.
export const HOSTED_MOUNTS_MAX = 8;
const ROOTS_MAX = 16;
const PATH_MAX = 4096;
const ALWAYS_PROTECTED = Object.freeze(["/srv/mosaic", "/proc", "/sys", "/dev", "/run", "/root", "/boot"]);
const MOUNT_KEYS = Object.freeze(["src", "dest", "why"]);
export class HostedRouteError extends Error {
constructor(fence, message) {
super(`hosted binds: ${message}`);
this.code = "hosted-binds-refused";
this.fence = fence;
}
}
const refuseRoute = (fence, message) => { throw new HostedRouteError(fence, message); };
// Absolute, already normal (no "..", ".", "//" or trailing slash), not "/", no NUL.
const cleanPath = (p) => typeof p === "string" && p.length > 1 && p.length <= PATH_MAX && !p.includes("\0") && isAbsolute(p) && resolve(p) === p;
const within = (child, parent) => child === parent || child.startsWith(parent + "/");
const overlaps = (a, b) => within(a, b) || within(b, a);
const secretPath = (p) => p.split("/").some((seg) => /secret/i.test(seg));
const realOr = (p) => { try { return realpathSync(p); } catch { return p; } };
const plainObject = (o) => o !== null && typeof o === "object" && !Array.isArray(o) && [Object.prototype, null].includes(Object.getPrototypeOf(o));
// `alsoFixed` is a test hook: it adds stand-in fixed paths and never removes a shipped one.
export function checkHostedRoute({ adapter, harnessMounts, installRoots, protectedPaths, codeRoot = null, codeHolder = null, runDir, node = process.execPath, alsoFixed = [] }) {
if (!cleanPath(runDir)) refuseRoute("protected", "the run directory is not a clean absolute path");
if (!Array.isArray(protectedPaths)) refuseRoute("protected", "no protected paths were given");
if (!Array.isArray(alsoFixed)) refuseRoute("protected", "the added fixed paths are not a list");
// Lists are copied once, so a Proxy cannot answer one length to a check and another to the map.
protectedPaths = Array.from(protectedPaths);
// Each guarded entry: its spellings, and whether a source in the code root is clear of it. The
// fixed paths and the run dir never hold the code. Their spellings are looked up once, here, and
// serve both the code-root check and their guards, so the two always see the same real path.
const fixed = [...ALWAYS_PROTECTED, ...Array.from(alsoFixed), runDir].map((p) => {
if (!cleanPath(p)) refuseRoute("protected", "a protected path is not a clean absolute path");
return { spellings: [p, realOr(p)], holdsCode: false };
});
let code = null;
if (codeRoot !== null) {
if (!cleanPath(codeRoot)) refuseRoute("protected", "the code root is not a clean absolute path");
if (!protectedPaths.includes(codeHolder)) refuseRoute("protected", "the code root's holder is not a protected path");
code = [codeRoot, realOr(codeRoot)];
if (code.some((c) => fixed.some((g) => g.spellings.some((s) => overlaps(c, s))))) refuseRoute("protected", "the code root is in or around a path that is never set aside");
}
const guarded = [...fixed];
for (const p of protectedPaths) {
if (!cleanPath(p)) refuseRoute("protected", "a protected path is not a clean absolute path");
const spellings = [p, realOr(p)];
const holdsCode = p === codeHolder && code !== null && spellings.some((g) => code.some((c) => c !== g && within(c, g)));
guarded.push({ spellings, holdsCode });
}
if (!Array.isArray(installRoots)) refuseRoute("roots", "the harness module declares no usable install roots");
installRoots = Array.from(installRoots);
if (installRoots.length === 0 || installRoots.length > ROOTS_MAX) refuseRoute("roots", "the harness module declares no usable install roots");
const roots = installRoots.map((r) => {
if (!cleanPath(r)) refuseRoute("roots", "an install root is not a clean absolute path");
let real;
try { real = realpathSync(r); } catch { refuseRoute("roots", "an install root is missing"); }
if (real === "/" || !statSync(real).isDirectory()) refuseRoute("roots", "an install root is not a directory");
return { named: r, real };
});
const source = (src, fence, what) => {
if (!cleanPath(src)) refuseRoute(fence, `${what} is not a clean absolute path`);
let real;
try { real = realpathSync(src); } catch { refuseRoute(fence, `${what} is missing`); }
if (!roots.some((r) => (within(src, r.named) || within(src, r.real)) && within(real, r.real))) refuseRoute(fence, `${what} is not under an install root`);
const inCode = code !== null && code.some((c) => within(src, c)) && within(real, code[1]);
if (guarded.some((g) => !(g.holdsCode && inCode) && [src, real].some((p) => g.spellings.some((s) => overlaps(p, s))))) refuseRoute(fence, `${what} is in or around a protected path`);
if ([src, real].some(secretPath)) refuseRoute(fence, `${what} is in a secrets path`);
return real;
};
const adapterReal = source(adapter, "adapter", "the adapter");
if (!statSync(adapterReal).isFile()) refuseRoute("adapter", "the adapter is not a file");
if (!Array.isArray(harnessMounts)) refuseRoute("mounts", `a hosted session takes at most ${HOSTED_MOUNTS_MAX} harness mounts`);
harnessMounts = Array.from(harnessMounts);
if (harnessMounts.length > HOSTED_MOUNTS_MAX) refuseRoute("mounts", `a hosted session takes at most ${HOSTED_MOUNTS_MAX} harness mounts`);
const apart = ["/tmp", runDir, ...systemBinds(node).map((b) => b.dest ?? b.src)];
const kept = [...RUNNER_FILES, adapter, node];
const dests = [];
const mounts = harnessMounts.map((m, i) => {
const what = `harness mount ${i + 1}`;
if (!plainObject(m) || Object.keys(m).some((k) => !MOUNT_KEYS.includes(k))) refuseRoute("mounts", `${what} is not { src, dest, why }`);
// Each field is read once, so a getter cannot answer one value to a check and another to the bind.
const { src, dest: named, why } = m;
if (typeof why !== "string" || !why || why.length > 256) refuseRoute("mounts", `${what} is not { src, dest, why }`);
if (named !== undefined && !cleanPath(named)) refuseRoute("mount-dest", `${what}'s dest is not a clean absolute path`);
const real = source(src, "mount-src", what);
const dest = named ?? src;
if (apart.some((p) => overlaps(dest, p)) || kept.some((p) => within(p, dest)) || dests.some((d) => overlaps(dest, d))) refuseRoute("mount-dest", `${what}'s dest would cover a path the session needs`);
dests.push(dest);
return { src: real, dest, why };
});
return { adapter: { src: adapterReal, dest: adapter }, mounts };
}
// #1873 triage-host: the binds for a session the Console hosts in no organization (Triage). It
// gets the system part, the runner's files, the adapter and the harness module's mounts like any
// session, and from the data root exactly two directories: its own `runDir` read-write, and
// `healthDir` read-only over runDir/work/health, inside the workspace the read tools' gate allows. The run's bundle/, session.json and the relay socket the runner
// calls through stay read-only inside it, and its tmp/ is /tmp. There is no workspace, broker,
// launch or git socket, thread store or org root. Each source inside runDir must be what the host
// just made there, never a link the session left: bwrap resolves a bind's source on the host.
// The adapter and the mounts pass checkHostedRoute against `installRoots`, `protectedPaths` and
// `codeRoot` with its `codeHolder` here too; without install roots nothing binds.
export function hostedBinds({ runDir, healthDir, adapter, harnessMounts = [], installRoots, protectedPaths, codeRoot = null, codeHolder = null, relaySocket, node = process.execPath, readOnly = [] }) {
if (relaySocket !== join(runDir, "relay.sock")) throw new Error("hosted binds: the relay socket must be the run directory's relay.sock");
const healthDest = join(runDir, "work", "health");
for (const p of [runDir, healthDir, join(runDir, "bundle"), join(runDir, "tmp"), join(runDir, "work"), healthDest]) {
let st;
try { st = lstatSync(p); } catch { throw new Error(`hosted binds: ${p === healthDir ? "the health directory" : relative(runDir, p) || "the run directory"} is missing`); }
if (st.isSymbolicLink() || !st.isDirectory()) throw new Error(`hosted binds: ${p === healthDir ? "the health directory" : relative(runDir, p) || "the run directory"} is not a directory`);
}
for (const [p, ok] of [[join(runDir, "session.json"), (st) => st.isFile()], [relaySocket, (st) => st.isSocket()]]) {
let st;
try { st = lstatSync(p); } catch { throw new Error(`hosted binds: ${relative(runDir, p)} is missing`); }
if (!ok(st)) throw new Error(`hosted binds: ${relative(runDir, p)} is not what the host made`);
}
const route = checkHostedRoute({ adapter, harnessMounts, installRoots, protectedPaths, codeRoot, codeHolder, runDir, node });
const out = systemBinds(node);
for (const f of RUNNER_FILES) out.push({ kind: "ro", src: f, why: "a repository file the runner loads" });
out.push({ kind: "ro", src: route.adapter.src, ...(route.adapter.src !== adapter ? { dest: adapter } : {}), why: "the harness adapter the runner starts each turn" });
for (const m of route.mounts) out.push({ kind: "ro", src: m.src, ...(m.dest !== m.src ? { dest: m.dest } : {}), why: m.why });
for (const f of readOnly) out.push({ kind: "ro", src: f, why: "a test fixture" });
out.push(
{ kind: "rw", src: runDir, why: "the session's own state: turns/, session/, work/, tools.sock, turn.done, home/, tmp/" },
{ kind: "ro", src: healthDir, dest: healthDest, why: "the health snapshots the Console writes, read-only, inside the workspace the read tools reach" },
{ kind: "ro", src: join(runDir, "bundle"), why: "the run's bundle stays as the host wrote it" },
{ kind: "ro", src: join(runDir, "session.json"), why: "the session file stays as the host wrote it" },
{ kind: "ro", src: relaySocket, why: "the host's relay, the only broker the runner reaches" },
{ kind: "rw", src: join(runDir, "tmp"), dest: "/tmp", why: "a private /tmp, on disk in the run directory" },
);
return out;
}
// The command line for a hosted session: as sandboxArgv, with no git identity, since a hosted
// session belongs to no organization and holds no git verb.
export function hostedArgv(list, runDir, command, { bwrap = BWRAP } = {}) {
return [bwrap, ...NAMESPACES, ...argsOf(list), "--remount-ro", "/", "--setenv", "HOME", join(runDir, "home"), "--setenv", "TMPDIR", "/tmp", "--chdir", runDir, "--", ...KILL_WITH_PARENT, ...command];
}
// Whether bwrap runs here at all: the namespaces and the system binds, then
// setpriv and `true`. Returns null, or why not.
export function sandboxProblem({ bwrap = BWRAP } = {}) {
// #1873: names the sandbox, never the binary's host path; a launch refusal carries this text.
if (!existsSync(bwrap)) return "the sandbox (bwrap) is missing";
const r = spawnSync(bwrap, [...NAMESPACES, ...argsOf(systemBinds()), "--remount-ro", "/", "--", ...KILL_WITH_PARENT, "/usr/bin/true"], { encoding: "utf8", timeout: 10000 });
if (r.status === 0) return null;
const why = (r.stderr ?? "").trim().split("\n")[0] || (r.error ? r.error.code : `exit ${r.status ?? r.signal}`);
return `the sandbox (bwrap) failed: ${why}`;
}