@capybara-hq/device 0.0.0-stage → 0.1.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +2 -0
- package/README.md +103 -2
- package/bin/capybara-device.mjs +11 -0
- package/dist/api.d.ts +33 -0
- package/dist/api.js +48 -0
- package/dist/args.d.ts +39 -0
- package/dist/args.js +93 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.js +93 -0
- package/dist/client.d.ts +39 -0
- package/dist/client.js +340 -0
- package/dist/command-log.d.ts +17 -0
- package/dist/command-log.js +28 -0
- package/dist/commands/drain.d.ts +2 -0
- package/dist/commands/drain.js +5 -0
- package/dist/commands/login.d.ts +20 -0
- package/dist/commands/login.js +132 -0
- package/dist/commands/logout.d.ts +13 -0
- package/dist/commands/logout.js +36 -0
- package/dist/commands/policy.d.ts +15 -0
- package/dist/commands/policy.js +74 -0
- package/dist/commands/service.d.ts +17 -0
- package/dist/commands/service.js +97 -0
- package/dist/commands/signal.d.ts +2 -0
- package/dist/commands/signal.js +18 -0
- package/dist/commands/start.d.ts +16 -0
- package/dist/commands/start.js +73 -0
- package/dist/commands/status.d.ts +2 -0
- package/dist/commands/status.js +32 -0
- package/dist/commands/stop.d.ts +2 -0
- package/dist/commands/stop.js +5 -0
- package/dist/exec/docker.d.ts +120 -0
- package/dist/exec/docker.js +673 -0
- package/dist/exec/fs-helper.d.ts +12 -0
- package/dist/exec/fs-helper.js +85 -0
- package/dist/exec/os.d.ts +80 -0
- package/dist/exec/os.js +398 -0
- package/dist/exec/procs.d.ts +11 -0
- package/dist/exec/procs.js +67 -0
- package/dist/exec/shared.d.ts +71 -0
- package/dist/exec/shared.js +240 -0
- package/dist/exec/types.d.ts +34 -0
- package/dist/exec/types.js +9 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/pid.d.ts +6 -0
- package/dist/pid.js +36 -0
- package/dist/policy.d.ts +42 -0
- package/dist/policy.js +97 -0
- package/dist/server-ops.d.ts +10 -0
- package/dist/server-ops.js +74 -0
- package/dist/service/launchd.d.ts +17 -0
- package/dist/service/launchd.js +59 -0
- package/dist/service/systemd.d.ts +5 -0
- package/dist/service/systemd.js +28 -0
- package/dist/state.d.ts +40 -0
- package/dist/state.js +117 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +11 -0
- package/package.json +42 -3
|
@@ -0,0 +1,673 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
3
|
+
import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { join, resolve } from "node:path";
|
|
5
|
+
import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
|
|
6
|
+
import { effectiveEgress } from "../policy.js";
|
|
7
|
+
import { EXEC_MARKER } from "./procs.js";
|
|
8
|
+
import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
|
|
9
|
+
import { DeviceOpError } from "./types.js";
|
|
10
|
+
/** The version of the published sandbox images this program runs commands in. */
|
|
11
|
+
export const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
|
|
12
|
+
export const SANDBOX_IMAGE = `ghcr.io/capybara-hq/capybara-sandbox:${SANDBOX_IMAGE_TAG}`;
|
|
13
|
+
/** The image's `sandbox` user. */
|
|
14
|
+
const IMAGE_USER = "1000:1000";
|
|
15
|
+
/**
|
|
16
|
+
* The user commands run as. On Linux the bind-mounted environment directory belongs to the host user,
|
|
17
|
+
* so the container runs as that uid:gid (never root: a root host user falls back to the image's user).
|
|
18
|
+
* Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
|
|
19
|
+
*/
|
|
20
|
+
export function containerUser(platform = process.platform, uid = process.getuid?.(), gid = process.getgid?.()) {
|
|
21
|
+
if (platform !== "linux" || uid === undefined || gid === undefined || uid === 0)
|
|
22
|
+
return IMAGE_USER;
|
|
23
|
+
return `${uid}:${gid}`;
|
|
24
|
+
}
|
|
25
|
+
const SPEC_LABEL = "capybara.device.spec";
|
|
26
|
+
/** A file operation in the container that takes longer than this is killed. */
|
|
27
|
+
const FILE_OP_TIMEOUT_S = 30;
|
|
28
|
+
const ROOTS = DEFAULT_SANDBOX_ROOTS;
|
|
29
|
+
/** Container name of an environment. */
|
|
30
|
+
export function containerName(environmentId) {
|
|
31
|
+
return `capybara-device-${environmentId}`;
|
|
32
|
+
}
|
|
33
|
+
/** Runs `docker <args>` to completion (not a command of the environment). */
|
|
34
|
+
function docker(args, o = {}) {
|
|
35
|
+
return new Promise((resolvePromise, reject) => {
|
|
36
|
+
const child = spawn("docker", args, { stdio: [o.input ? "pipe" : "ignore", "pipe", "pipe"] });
|
|
37
|
+
const out = [];
|
|
38
|
+
const err = [];
|
|
39
|
+
let size = 0;
|
|
40
|
+
const max = o.maxBytes ?? 64 * 1024 * 1024;
|
|
41
|
+
child.stdout?.on("data", (b) => {
|
|
42
|
+
if (size < max)
|
|
43
|
+
out.push(b);
|
|
44
|
+
size += b.length;
|
|
45
|
+
});
|
|
46
|
+
child.stderr?.on("data", (b) => err.push(b));
|
|
47
|
+
if (child.stdin) {
|
|
48
|
+
child.stdin.on("error", () => { });
|
|
49
|
+
child.stdin.end(Buffer.from(o.input));
|
|
50
|
+
}
|
|
51
|
+
const timer = o.timeoutMs !== undefined ? setTimeout(() => child.kill("SIGKILL"), o.timeoutMs) : undefined;
|
|
52
|
+
child.once("error", (e) => {
|
|
53
|
+
if (timer)
|
|
54
|
+
clearTimeout(timer);
|
|
55
|
+
reject(e);
|
|
56
|
+
});
|
|
57
|
+
child.once("close", (code) => {
|
|
58
|
+
if (timer)
|
|
59
|
+
clearTimeout(timer);
|
|
60
|
+
resolvePromise({ code, stdout: Buffer.concat(out), stderr: Buffer.concat(err) });
|
|
61
|
+
});
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
/** Whether the docker CLI can reach a daemon, and why not. */
|
|
65
|
+
export async function dockerAvailability() {
|
|
66
|
+
try {
|
|
67
|
+
const r = await docker(["info", "--format", "{{.ServerVersion}}"], { timeoutMs: 10_000 });
|
|
68
|
+
if (r.code === 0)
|
|
69
|
+
return { ok: true };
|
|
70
|
+
const why = r.stderr.toString("utf8").trim().split("\n")[0] ?? "";
|
|
71
|
+
return { ok: false, reason: `Docker is not available${why ? `: ${why}` : ""}` };
|
|
72
|
+
}
|
|
73
|
+
catch {
|
|
74
|
+
return { ok: false, reason: "the docker command was not found" };
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
/** Kills the processes whose `CAPYBARA_EXEC` is `$1` exactly, or starts with `$2` (when `$1` is empty). */
|
|
78
|
+
const KILL_SCRIPT = `m=$1; pre=$2; for round in 1 2; do for e in /proc/[0-9]*/environ; do
|
|
79
|
+
p=\${e%/environ}; p=\${p#/proc/}; [ "$p" = "$$" ] && continue
|
|
80
|
+
if [ -n "$m" ]; then tr '\\0' '\\n' < "$e" 2>/dev/null | grep -qxF "${EXEC_MARKER}=$m" && kill -9 "$p" 2>/dev/null
|
|
81
|
+
else tr '\\0' '\\n' < "$e" 2>/dev/null | grep -q "^${EXEC_MARKER}=$pre" && kill -9 "$p" 2>/dev/null; fi
|
|
82
|
+
done; done; exit 0`;
|
|
83
|
+
/**
|
|
84
|
+
* The command wrapper. The host sends a random nonce on stdin; the wrapper keeps it in a shell
|
|
85
|
+
* variable, runs the command (stdin `/dev/null`), then writes one final line on stderr with the
|
|
86
|
+
* nonce and the exit status. `docker exec` itself ends only when every process holding its
|
|
87
|
+
* output (a background child) has closed it, so the host reads the status from this line instead.
|
|
88
|
+
* The command cannot suppress the line (the wrapper writes it after waiting) and never sees the
|
|
89
|
+
* nonce; a forged line without it is ordinary output.
|
|
90
|
+
*/
|
|
91
|
+
const EXEC_WRAPPER = 'read -r n; /bin/bash -c "$1" </dev/null; s=$?; printf \'\\nCAPYBARA-DONE:%s:%d:END\\n\' "$n" "$s" >&2; exit $s';
|
|
92
|
+
/** The pids limit of a container (as the cloud sandbox). */
|
|
93
|
+
const PIDS_LIMIT = 1024;
|
|
94
|
+
/** The shared prologue of the file scripts: `under` checks a real path against the three roots. */
|
|
95
|
+
const FILE_PROLOGUE = `under() { case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac; return 1; }
|
|
96
|
+
`;
|
|
97
|
+
// Exit codes of the file scripts.
|
|
98
|
+
const E_MISSING = 10;
|
|
99
|
+
const E_OUTSIDE = 11;
|
|
100
|
+
const E_NOT_FILE = 12;
|
|
101
|
+
const E_FAIL = 13;
|
|
102
|
+
const E_DANGLING = 14;
|
|
103
|
+
const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
|
|
104
|
+
under "$r" || exit ${E_OUTSIDE}
|
|
105
|
+
[ -d "$r" ] && exit ${E_MISSING}
|
|
106
|
+
[ -f "$r" ] || exit ${E_NOT_FILE}
|
|
107
|
+
head -c "$2" -- "$r"`;
|
|
108
|
+
const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
|
|
109
|
+
under "$r" || exit ${E_OUTSIDE}
|
|
110
|
+
if [ -d "$r" ]; then printf '%s d' "$(stat -c %s -- "$r")"; else printf '%s f' "$(stat -c %s -- "$r")"; fi`;
|
|
111
|
+
const WRITE_SCRIPT = `${FILE_PROLOGUE}p=$1; d=$(dirname -- "$p"); a=$d
|
|
112
|
+
while [ ! -e "$a" ] && [ "$a" != / ]; do a=$(dirname -- "$a"); done
|
|
113
|
+
ra=$(realpath -e -- "$a" 2>/dev/null) || exit ${E_FAIL}
|
|
114
|
+
under "$ra" || exit ${E_OUTSIDE}
|
|
115
|
+
mkdir -p -- "$d" || exit ${E_FAIL}
|
|
116
|
+
rp=$(realpath -e -- "$d" 2>/dev/null) || exit ${E_FAIL}
|
|
117
|
+
under "$rp" || exit ${E_OUTSIDE}
|
|
118
|
+
f="$rp/$(basename -- "$p")"
|
|
119
|
+
if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING}; under "$r" || exit ${E_OUTSIDE}; f=$r; fi
|
|
120
|
+
if [ -e "$f" ] && [ ! -f "$f" ]; then exit ${E_NOT_FILE}; fi
|
|
121
|
+
cat > "$f" || exit ${E_FAIL}`;
|
|
122
|
+
/**
|
|
123
|
+
* Runs every command with `docker exec` in one long-lived container of the published sandbox
|
|
124
|
+
* image: the environment directory's workspace, skills (read only) and tmp are mounted at
|
|
125
|
+
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
126
|
+
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
127
|
+
* host); the skills directory, which commands cannot write, is accessed from the host with the
|
|
128
|
+
* same real-path checks as the OS executor. Network: none unless the effective egress is
|
|
129
|
+
* non-empty, then the default bridge (Docker mode has no domain allowlist).
|
|
130
|
+
*/
|
|
131
|
+
export class DockerExecutor {
|
|
132
|
+
opts;
|
|
133
|
+
mode = "docker";
|
|
134
|
+
roots = ROOTS;
|
|
135
|
+
name;
|
|
136
|
+
dir;
|
|
137
|
+
hostRoots;
|
|
138
|
+
guard;
|
|
139
|
+
hostFiles;
|
|
140
|
+
/** Marks every process of this environment's commands: `<dirKey>.<tag>`. */
|
|
141
|
+
dirKey;
|
|
142
|
+
running = new Set();
|
|
143
|
+
chain = Promise.resolve();
|
|
144
|
+
ready = false;
|
|
145
|
+
/** The container has the default bridge (commands may reach the network). */
|
|
146
|
+
netOpen = false;
|
|
147
|
+
inflight = 0;
|
|
148
|
+
queue = [];
|
|
149
|
+
pumping = false;
|
|
150
|
+
dirty = false;
|
|
151
|
+
constructor(opts) {
|
|
152
|
+
this.opts = opts;
|
|
153
|
+
const dir = resolve(opts.dir);
|
|
154
|
+
this.dir = existsSync(dir) ? realpathSync(dir) : dir;
|
|
155
|
+
this.hostRoots = osRoots(this.dir);
|
|
156
|
+
this.guard = new RootGuard(this.dir, this.hostRoots);
|
|
157
|
+
this.hostFiles = new HostFiles(this.hostRoots);
|
|
158
|
+
this.name = containerName(opts.environmentId);
|
|
159
|
+
this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
|
|
160
|
+
}
|
|
161
|
+
async ensureRoot() {
|
|
162
|
+
return this.guard.ensure();
|
|
163
|
+
}
|
|
164
|
+
markerOf(tag) {
|
|
165
|
+
return `${this.dirKey}.${tag}`;
|
|
166
|
+
}
|
|
167
|
+
serial(f) {
|
|
168
|
+
const next = this.chain.then(f, f);
|
|
169
|
+
this.chain = next.catch(() => { });
|
|
170
|
+
return next;
|
|
171
|
+
}
|
|
172
|
+
async inspect() {
|
|
173
|
+
const r = await docker(["inspect", "--type", "container", this.name]);
|
|
174
|
+
if (r.code !== 0)
|
|
175
|
+
return null;
|
|
176
|
+
return JSON.parse(r.stdout.toString("utf8"))[0] ?? null;
|
|
177
|
+
}
|
|
178
|
+
wanted() {
|
|
179
|
+
return [
|
|
180
|
+
{ source: this.hostRoots.workspace, dest: ROOTS.workspace, rw: true },
|
|
181
|
+
{ source: this.hostRoots.skills, dest: ROOTS.skills, rw: false },
|
|
182
|
+
{ source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
|
|
183
|
+
];
|
|
184
|
+
}
|
|
185
|
+
/** Every `docker run` flag of the container except its name and spec label. */
|
|
186
|
+
runArgs() {
|
|
187
|
+
const { policy } = this.opts;
|
|
188
|
+
return [
|
|
189
|
+
"--init",
|
|
190
|
+
"--read-only",
|
|
191
|
+
"--user",
|
|
192
|
+
containerUser(),
|
|
193
|
+
"--cap-drop",
|
|
194
|
+
"ALL",
|
|
195
|
+
"--security-opt",
|
|
196
|
+
"no-new-privileges:true",
|
|
197
|
+
"--pids-limit",
|
|
198
|
+
String(PIDS_LIMIT),
|
|
199
|
+
"--workdir",
|
|
200
|
+
ROOTS.workspace,
|
|
201
|
+
"--label",
|
|
202
|
+
`capybara.device.environment=${this.opts.environmentId}`,
|
|
203
|
+
...this.wanted().flatMap((m) => [
|
|
204
|
+
"--mount",
|
|
205
|
+
`type=bind,source=${m.source},target=${m.dest}${m.rw ? "" : ",readonly"}`,
|
|
206
|
+
]),
|
|
207
|
+
...(policy.cpu !== null ? ["--cpus", String(policy.cpu)] : []),
|
|
208
|
+
...(policy.memoryMb !== null
|
|
209
|
+
? ["--memory", `${policy.memoryMb}m`, "--memory-swap", `${policy.memoryMb}m`]
|
|
210
|
+
: []),
|
|
211
|
+
"--entrypoint",
|
|
212
|
+
"sleep",
|
|
213
|
+
SANDBOX_IMAGE,
|
|
214
|
+
"infinity",
|
|
215
|
+
];
|
|
216
|
+
}
|
|
217
|
+
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
218
|
+
specHash() {
|
|
219
|
+
return createHash("sha256").update(JSON.stringify(this.runArgs())).digest("hex").slice(0, 16);
|
|
220
|
+
}
|
|
221
|
+
matches(c) {
|
|
222
|
+
return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
|
|
223
|
+
}
|
|
224
|
+
async mustDocker(args, what) {
|
|
225
|
+
const r = await docker(args);
|
|
226
|
+
if (r.code !== 0) {
|
|
227
|
+
throw new DeviceOpError("error", `${what} failed: ${r.stderr.toString("utf8").trim().slice(0, 500)}`);
|
|
228
|
+
}
|
|
229
|
+
return r;
|
|
230
|
+
}
|
|
231
|
+
/** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
|
|
232
|
+
async ensureContainer() {
|
|
233
|
+
if (this.ready)
|
|
234
|
+
return;
|
|
235
|
+
if (!existsSync(this.dir)) {
|
|
236
|
+
throw new DeviceOpError("error", "the environment directory is gone");
|
|
237
|
+
}
|
|
238
|
+
for (const r of Object.values(this.hostRoots)) {
|
|
239
|
+
if (r.includes(",")) {
|
|
240
|
+
throw new DeviceOpError("error", `the environment directory ${this.dir} contains a comma`);
|
|
241
|
+
}
|
|
242
|
+
mkdirSync(r, { recursive: true });
|
|
243
|
+
}
|
|
244
|
+
let c = await this.inspect();
|
|
245
|
+
if (c !== null && (!this.matches(c) || !(await this.seesHostRoots(c)))) {
|
|
246
|
+
await this.mustDocker(["rm", "-f", this.name], "removing the old container");
|
|
247
|
+
c = null;
|
|
248
|
+
}
|
|
249
|
+
if (c === null) {
|
|
250
|
+
await this.mustDocker([
|
|
251
|
+
"run",
|
|
252
|
+
"-d",
|
|
253
|
+
"--name",
|
|
254
|
+
this.name,
|
|
255
|
+
"--label",
|
|
256
|
+
`${SPEC_LABEL}=${this.specHash()}`,
|
|
257
|
+
...this.runArgs(),
|
|
258
|
+
], "creating the container");
|
|
259
|
+
// Created on the default bridge (a container created with `none` cannot join it later).
|
|
260
|
+
this.netOpen = true;
|
|
261
|
+
}
|
|
262
|
+
else {
|
|
263
|
+
if (!c.State.Running)
|
|
264
|
+
await this.mustDocker(["start", this.name], "starting the container");
|
|
265
|
+
this.netOpen = "bridge" in (await this.inspectNetworks());
|
|
266
|
+
}
|
|
267
|
+
this.ready = true;
|
|
268
|
+
}
|
|
269
|
+
/**
|
|
270
|
+
* Whether a reused container's mounts still show this directory's roots: after the directory was
|
|
271
|
+
* removed and recreated (`login` again), a Linux bind mount still holds the deleted one.
|
|
272
|
+
*/
|
|
273
|
+
async seesHostRoots(c) {
|
|
274
|
+
if (!c.State.Running)
|
|
275
|
+
await this.mustDocker(["start", this.name], "starting the container");
|
|
276
|
+
const probe = `.capybara-mount-probe-${randomBytes(8).toString("hex")}`;
|
|
277
|
+
const checks = this.wanted();
|
|
278
|
+
try {
|
|
279
|
+
for (const m of checks)
|
|
280
|
+
writeFileSync(join(m.source, probe), "");
|
|
281
|
+
const script = checks.map((m) => `[ -e ${m.dest}/${probe} ]`).join(" && ");
|
|
282
|
+
const r = await docker(["exec", this.name, "/bin/sh", "-c", script], { timeoutMs: 10_000 });
|
|
283
|
+
return r.code === 0;
|
|
284
|
+
}
|
|
285
|
+
finally {
|
|
286
|
+
for (const m of checks)
|
|
287
|
+
rmSync(join(m.source, probe), { force: true });
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
async inspectNetworks() {
|
|
291
|
+
const c = await this.inspect();
|
|
292
|
+
return c?.NetworkSettings.Networks ?? {};
|
|
293
|
+
}
|
|
294
|
+
async setNet(open) {
|
|
295
|
+
await this.mustDocker(["network", open ? "connect" : "disconnect", "bridge", this.name], open ? "enabling the network" : "disabling the network");
|
|
296
|
+
this.netOpen = open;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* Waits until the container exists with the wanted network state and counts the caller as
|
|
300
|
+
* running. Callers are served in arrival order: once one needs the other network state, later
|
|
301
|
+
* callers for the current state queue behind it, so it is not starved.
|
|
302
|
+
*/
|
|
303
|
+
acquire(open, signal) {
|
|
304
|
+
signal.throwIfAborted();
|
|
305
|
+
return new Promise((resolveWait, rejectWait) => {
|
|
306
|
+
const w = {
|
|
307
|
+
open,
|
|
308
|
+
dead: false,
|
|
309
|
+
counted: false,
|
|
310
|
+
resolve: resolveWait,
|
|
311
|
+
reject: rejectWait,
|
|
312
|
+
};
|
|
313
|
+
const onAbort = () => {
|
|
314
|
+
w.dead = true;
|
|
315
|
+
this.dequeue(w);
|
|
316
|
+
rejectWait(signal.reason);
|
|
317
|
+
};
|
|
318
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
319
|
+
const done = w.resolve;
|
|
320
|
+
w.resolve = () => {
|
|
321
|
+
signal.removeEventListener("abort", onAbort);
|
|
322
|
+
done();
|
|
323
|
+
};
|
|
324
|
+
this.queue.push(w);
|
|
325
|
+
this.pump();
|
|
326
|
+
});
|
|
327
|
+
}
|
|
328
|
+
pump() {
|
|
329
|
+
if (this.pumping) {
|
|
330
|
+
this.dirty = true;
|
|
331
|
+
return;
|
|
332
|
+
}
|
|
333
|
+
this.pumping = true;
|
|
334
|
+
void this.drain().finally(() => {
|
|
335
|
+
this.pumping = false;
|
|
336
|
+
if (this.dirty)
|
|
337
|
+
this.pump();
|
|
338
|
+
});
|
|
339
|
+
}
|
|
340
|
+
dequeue(w) {
|
|
341
|
+
const i = this.queue.indexOf(w);
|
|
342
|
+
if (i >= 0)
|
|
343
|
+
this.queue.splice(i, 1);
|
|
344
|
+
}
|
|
345
|
+
async drain() {
|
|
346
|
+
do {
|
|
347
|
+
this.dirty = false;
|
|
348
|
+
while (this.queue.length > 0) {
|
|
349
|
+
const w = this.queue[0];
|
|
350
|
+
if (w.dead) {
|
|
351
|
+
this.dequeue(w);
|
|
352
|
+
continue;
|
|
353
|
+
}
|
|
354
|
+
let served;
|
|
355
|
+
try {
|
|
356
|
+
served = await this.serial(async () => {
|
|
357
|
+
await this.ensureContainer();
|
|
358
|
+
if (w.dead)
|
|
359
|
+
return true;
|
|
360
|
+
if (this.netOpen !== w.open) {
|
|
361
|
+
// Commands run with the other network state: wait for them.
|
|
362
|
+
if (this.inflight > 0)
|
|
363
|
+
return false;
|
|
364
|
+
await this.setNet(w.open);
|
|
365
|
+
}
|
|
366
|
+
this.inflight++;
|
|
367
|
+
w.counted = true;
|
|
368
|
+
return true;
|
|
369
|
+
});
|
|
370
|
+
}
|
|
371
|
+
catch (e) {
|
|
372
|
+
// An abort while being served already removed it; never remove another waiter.
|
|
373
|
+
this.dequeue(w);
|
|
374
|
+
if (!w.dead)
|
|
375
|
+
w.reject(e);
|
|
376
|
+
continue;
|
|
377
|
+
}
|
|
378
|
+
if (!served)
|
|
379
|
+
break;
|
|
380
|
+
this.dequeue(w);
|
|
381
|
+
if (w.dead) {
|
|
382
|
+
// Aborted while being served: give back the slot if it was counted.
|
|
383
|
+
if (w.counted)
|
|
384
|
+
this.inflight--;
|
|
385
|
+
continue;
|
|
386
|
+
}
|
|
387
|
+
w.resolve();
|
|
388
|
+
}
|
|
389
|
+
} while (this.dirty);
|
|
390
|
+
}
|
|
391
|
+
release() {
|
|
392
|
+
this.inflight--;
|
|
393
|
+
this.pump();
|
|
394
|
+
}
|
|
395
|
+
/** A docker-level failure that means the container vanished: the next call recreates it. */
|
|
396
|
+
noteFailure(stderr) {
|
|
397
|
+
if (/No such container|is not running|is restarting/i.test(stderr))
|
|
398
|
+
this.ready = false;
|
|
399
|
+
}
|
|
400
|
+
async exec(args, signal) {
|
|
401
|
+
signal.throwIfAborted();
|
|
402
|
+
const cwd = this.containerPath(args.cwd ?? ROOTS.workspace);
|
|
403
|
+
const env = {
|
|
404
|
+
HOME: ROOTS.workspace,
|
|
405
|
+
TERM: "dumb",
|
|
406
|
+
...args.env,
|
|
407
|
+
TMPDIR: ROOTS.tmp,
|
|
408
|
+
[EXEC_MARKER]: this.markerOf(args.tag),
|
|
409
|
+
};
|
|
410
|
+
for (const k of Object.keys(env)) {
|
|
411
|
+
if (!ENV_NAME_RE.test(k))
|
|
412
|
+
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
413
|
+
}
|
|
414
|
+
const open = effectiveEgress(this.opts.policy, args.limits).length > 0;
|
|
415
|
+
await this.acquire(open, signal);
|
|
416
|
+
try {
|
|
417
|
+
signal.throwIfAborted();
|
|
418
|
+
return await this.run(args, cwd, env, signal);
|
|
419
|
+
}
|
|
420
|
+
finally {
|
|
421
|
+
this.release();
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
run(args, cwd, env, signal) {
|
|
425
|
+
const nonce = randomBytes(16).toString("hex");
|
|
426
|
+
return new Promise((resolvePromise, reject) => {
|
|
427
|
+
const child = spawn("docker", [
|
|
428
|
+
"exec",
|
|
429
|
+
"-i",
|
|
430
|
+
"--workdir",
|
|
431
|
+
cwd,
|
|
432
|
+
...Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
|
|
433
|
+
this.name,
|
|
434
|
+
"/bin/bash",
|
|
435
|
+
"-c",
|
|
436
|
+
EXEC_WRAPPER,
|
|
437
|
+
"capybara-exec",
|
|
438
|
+
args.command,
|
|
439
|
+
], { stdio: ["pipe", "pipe", "pipe"] });
|
|
440
|
+
child.stdin?.on("error", () => { });
|
|
441
|
+
child.stdin?.end(`${nonce}\n`);
|
|
442
|
+
const sentinel = Buffer.from(`\nCAPYBARA-DONE:${nonce}:`);
|
|
443
|
+
const entry = { tag: args.tag, killed: false, child };
|
|
444
|
+
this.running.add(entry);
|
|
445
|
+
const cap = new OutputCap(args.maxOutputBytes);
|
|
446
|
+
const dockerErr = [];
|
|
447
|
+
let timedOut = false;
|
|
448
|
+
let exit;
|
|
449
|
+
let settled = false;
|
|
450
|
+
let grace;
|
|
451
|
+
const kill = () => {
|
|
452
|
+
if (exit === undefined)
|
|
453
|
+
entry.killed = true;
|
|
454
|
+
void this.killMarker(this.markerOf(args.tag)).then(() => {
|
|
455
|
+
// The docker client normally ends with the command; never leave it behind.
|
|
456
|
+
setTimeout(() => child.kill("SIGKILL"), 1000).unref();
|
|
457
|
+
});
|
|
458
|
+
};
|
|
459
|
+
const timer = setTimeout(() => {
|
|
460
|
+
if (exit === undefined)
|
|
461
|
+
timedOut = true;
|
|
462
|
+
kill();
|
|
463
|
+
}, args.timeoutMs);
|
|
464
|
+
const onAbort = () => kill();
|
|
465
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
466
|
+
const cleanup = () => {
|
|
467
|
+
clearTimeout(timer);
|
|
468
|
+
if (grace)
|
|
469
|
+
clearTimeout(grace);
|
|
470
|
+
// A background child may keep the client attached: it is not needed any more.
|
|
471
|
+
child.kill("SIGKILL");
|
|
472
|
+
signal.removeEventListener("abort", onAbort);
|
|
473
|
+
this.running.delete(entry);
|
|
474
|
+
};
|
|
475
|
+
const finish = () => {
|
|
476
|
+
if (settled || exit === undefined)
|
|
477
|
+
return;
|
|
478
|
+
settled = true;
|
|
479
|
+
cleanup();
|
|
480
|
+
child.stdout?.destroy();
|
|
481
|
+
child.stderr?.destroy();
|
|
482
|
+
if (status === undefined && pending.length > 0)
|
|
483
|
+
cap.push("stderr", pending);
|
|
484
|
+
const stderr = cap.text("stderr");
|
|
485
|
+
if (exit.code === 126 || exit.code === 125 || exit.code === 1) {
|
|
486
|
+
this.noteFailure(Buffer.concat(dockerErr).toString("utf8"));
|
|
487
|
+
}
|
|
488
|
+
resolvePromise({
|
|
489
|
+
exitCode: entry.killed || timedOut ? null : (exit.code ?? 128),
|
|
490
|
+
stdout: cap.text("stdout"),
|
|
491
|
+
stderr,
|
|
492
|
+
truncated: cap.truncated,
|
|
493
|
+
timedOut,
|
|
494
|
+
});
|
|
495
|
+
};
|
|
496
|
+
child.stdout?.on("data", (b) => cap.push("stdout", b));
|
|
497
|
+
// stderr carries the wrapper's final status line; hold back a tail that might begin it.
|
|
498
|
+
let pending = Buffer.alloc(0);
|
|
499
|
+
let status;
|
|
500
|
+
const onStderr = (b) => {
|
|
501
|
+
if (dockerErr.length < 64)
|
|
502
|
+
dockerErr.push(b);
|
|
503
|
+
if (status !== undefined) {
|
|
504
|
+
status = Buffer.concat([status, b]);
|
|
505
|
+
}
|
|
506
|
+
else {
|
|
507
|
+
const data = Buffer.concat([pending, b]);
|
|
508
|
+
const at = data.indexOf(sentinel);
|
|
509
|
+
if (at >= 0) {
|
|
510
|
+
cap.push("stderr", data.subarray(0, at));
|
|
511
|
+
pending = Buffer.alloc(0);
|
|
512
|
+
status = data.subarray(at + sentinel.length);
|
|
513
|
+
}
|
|
514
|
+
else {
|
|
515
|
+
const keep = Math.min(data.length, sentinel.length - 1);
|
|
516
|
+
cap.push("stderr", data.subarray(0, data.length - keep));
|
|
517
|
+
pending = data.subarray(data.length - keep);
|
|
518
|
+
}
|
|
519
|
+
}
|
|
520
|
+
if (status !== undefined && exit === undefined) {
|
|
521
|
+
const m = /^(\d+):END\n/.exec(status.toString("latin1"));
|
|
522
|
+
if (m) {
|
|
523
|
+
exit = { code: Number(m[1]), sig: null };
|
|
524
|
+
grace = setTimeout(finish, PIPE_GRACE_MS);
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
};
|
|
528
|
+
child.stderr?.on("data", onStderr);
|
|
529
|
+
child.once("error", (e) => {
|
|
530
|
+
if (settled)
|
|
531
|
+
return;
|
|
532
|
+
settled = true;
|
|
533
|
+
cleanup();
|
|
534
|
+
reject(e);
|
|
535
|
+
});
|
|
536
|
+
child.once("exit", (code, sig) => {
|
|
537
|
+
if (exit !== undefined)
|
|
538
|
+
return;
|
|
539
|
+
exit = { code, sig };
|
|
540
|
+
grace = setTimeout(finish, PIPE_GRACE_MS);
|
|
541
|
+
});
|
|
542
|
+
child.once("close", () => finish());
|
|
543
|
+
});
|
|
544
|
+
}
|
|
545
|
+
/** `path` made absolute and normalized; refused unless lexically under a root. */
|
|
546
|
+
containerPath(path) {
|
|
547
|
+
if (!path.startsWith("/"))
|
|
548
|
+
throw policyError(`${path} is not an absolute path`);
|
|
549
|
+
const p = resolve(path);
|
|
550
|
+
const roots = Object.values(ROOTS);
|
|
551
|
+
if (!roots.some((r) => isUnder(p, r))) {
|
|
552
|
+
throw policyError(`${path} is outside the environment's roots (${roots.join(", ")})`);
|
|
553
|
+
}
|
|
554
|
+
return p;
|
|
555
|
+
}
|
|
556
|
+
/** The host path of a /skills path (the skills directory is mounted read only). */
|
|
557
|
+
skillsHostPath(p) {
|
|
558
|
+
return join(this.hostRoots.skills, p.slice(ROOTS.skills.length));
|
|
559
|
+
}
|
|
560
|
+
inSkills(p) {
|
|
561
|
+
return isUnder(p, ROOTS.skills);
|
|
562
|
+
}
|
|
563
|
+
/** Runs one file script in the container; `null` for a missing file. */
|
|
564
|
+
async fileOp(script, path, arg2, input) {
|
|
565
|
+
// A file operation does not need the network; it runs on whichever state the container has.
|
|
566
|
+
await this.serial(() => this.ensureContainer());
|
|
567
|
+
const r = await docker([
|
|
568
|
+
"exec",
|
|
569
|
+
...(input !== undefined ? ["-i"] : []),
|
|
570
|
+
this.name,
|
|
571
|
+
"timeout",
|
|
572
|
+
"-s",
|
|
573
|
+
"KILL",
|
|
574
|
+
String(FILE_OP_TIMEOUT_S),
|
|
575
|
+
"/bin/sh",
|
|
576
|
+
"-c",
|
|
577
|
+
script,
|
|
578
|
+
"capybara-file",
|
|
579
|
+
path,
|
|
580
|
+
arg2,
|
|
581
|
+
], {
|
|
582
|
+
...(input !== undefined && { input }),
|
|
583
|
+
timeoutMs: (FILE_OP_TIMEOUT_S + 5) * 1000,
|
|
584
|
+
});
|
|
585
|
+
return this.fileResult(r, path);
|
|
586
|
+
}
|
|
587
|
+
fileResult(r, path) {
|
|
588
|
+
switch (r.code) {
|
|
589
|
+
case 0:
|
|
590
|
+
return r;
|
|
591
|
+
case E_MISSING:
|
|
592
|
+
return null;
|
|
593
|
+
case E_OUTSIDE:
|
|
594
|
+
throw policyError(`${path} resolves outside the environment's roots`);
|
|
595
|
+
case E_NOT_FILE:
|
|
596
|
+
throw policyError(`${path} is not a regular file`);
|
|
597
|
+
case E_DANGLING:
|
|
598
|
+
throw policyError(`${path} is a dangling symbolic link`);
|
|
599
|
+
default:
|
|
600
|
+
this.noteFailure(r.stderr.toString("utf8"));
|
|
601
|
+
throw new DeviceOpError("error", `file operation on ${path} failed: ${r.stderr.toString("utf8").trim().slice(0, 300)}`);
|
|
602
|
+
}
|
|
603
|
+
}
|
|
604
|
+
async readFile(path, maxBytes) {
|
|
605
|
+
const p = this.containerPath(path);
|
|
606
|
+
if (this.inSkills(p))
|
|
607
|
+
return this.hostFiles.read(this.skillsHostPath(p), maxBytes);
|
|
608
|
+
const r = await this.fileOp(READ_SCRIPT, p, String(maxBytes + 1));
|
|
609
|
+
if (r === null)
|
|
610
|
+
return null;
|
|
611
|
+
return {
|
|
612
|
+
data: r.stdout.subarray(0, maxBytes),
|
|
613
|
+
truncated: r.stdout.length > maxBytes,
|
|
614
|
+
};
|
|
615
|
+
}
|
|
616
|
+
async writeFile(path, data) {
|
|
617
|
+
const p = this.containerPath(path);
|
|
618
|
+
if (this.inSkills(p))
|
|
619
|
+
return this.hostFiles.write(this.skillsHostPath(p), data);
|
|
620
|
+
await this.fileOp(WRITE_SCRIPT, p, "", data);
|
|
621
|
+
}
|
|
622
|
+
async stat(path) {
|
|
623
|
+
const p = this.containerPath(path);
|
|
624
|
+
if (this.inSkills(p))
|
|
625
|
+
return this.hostFiles.stat(this.skillsHostPath(p));
|
|
626
|
+
const r = await this.fileOp(STAT_SCRIPT, p, "");
|
|
627
|
+
if (r === null)
|
|
628
|
+
return null;
|
|
629
|
+
const [size, kind] = r.stdout.toString("utf8").split(" ");
|
|
630
|
+
return { size: Number(size), isDir: kind === "d" };
|
|
631
|
+
}
|
|
632
|
+
/** Kills the container processes of one marker (exact) or marker prefix. */
|
|
633
|
+
async killScript(marker, prefix) {
|
|
634
|
+
try {
|
|
635
|
+
await docker(["exec", this.name, "/bin/sh", "-c", KILL_SCRIPT, "capybara-kill", marker, prefix], { timeoutMs: 15_000 });
|
|
636
|
+
}
|
|
637
|
+
catch {
|
|
638
|
+
// No docker, or no container: nothing of ours runs.
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
killMarker(marker) {
|
|
642
|
+
return this.killScript(marker, "");
|
|
643
|
+
}
|
|
644
|
+
async killTagged(tags) {
|
|
645
|
+
const want = new Set(tags);
|
|
646
|
+
for (const r of this.running)
|
|
647
|
+
if (want.has(r.tag))
|
|
648
|
+
r.killed = true;
|
|
649
|
+
await Promise.all(tags.map((t) => this.killMarker(this.markerOf(t))));
|
|
650
|
+
}
|
|
651
|
+
async killAll() {
|
|
652
|
+
for (const r of this.running)
|
|
653
|
+
r.killed = true;
|
|
654
|
+
await this.killLeftovers();
|
|
655
|
+
}
|
|
656
|
+
/** Kills every process carrying this environment's marker (also a previous run's). */
|
|
657
|
+
async killLeftovers() {
|
|
658
|
+
await this.killScript("", `${this.dirKey}.`);
|
|
659
|
+
}
|
|
660
|
+
/** Kills every running command; the container stays for the next start. */
|
|
661
|
+
async dispose() {
|
|
662
|
+
await this.killAll();
|
|
663
|
+
}
|
|
664
|
+
}
|
|
665
|
+
/** The Docker executor: checks the daemon and kills what a previous run left running. */
|
|
666
|
+
export async function createDockerExecutor(opts) {
|
|
667
|
+
const available = await dockerAvailability();
|
|
668
|
+
if (!available.ok)
|
|
669
|
+
throw new Error(available.reason);
|
|
670
|
+
const executor = new DockerExecutor(opts);
|
|
671
|
+
await executor.killLeftovers();
|
|
672
|
+
return executor;
|
|
673
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The file-operation helper the OS executor runs **inside the sandbox** (`node -e`), so a
|
|
3
|
+
* kernel-side read or write in the workspace or tmp root never touches the host file system with
|
|
4
|
+
* the program's own privileges: a parent directory swapped for a symlink mid-operation reaches
|
|
5
|
+
* only what any sandboxed command could reach anyway.
|
|
6
|
+
*
|
|
7
|
+
* argv: `<op> <path> <maxBytes> <root>...` with op `read` | `stat` | `write` (data on stdin).
|
|
8
|
+
* stdout: one JSON object, `{ "r": <result> }` or `{ "e": "policy" | "error", "m": <message> }`.
|
|
9
|
+
* read → `null` | `{ b64, truncated }`; stat → `null` | `{ size, isDir }`; write → `null`.
|
|
10
|
+
* Non-regular files (FIFOs, sockets, devices) are refused without blocking (`O_NONBLOCK`).
|
|
11
|
+
*/
|
|
12
|
+
export declare const FS_HELPER_SCRIPT = "\n(() => {\n const fs = require(\"fs\");\n const path = require(\"path\");\n const C = fs.constants;\n const [op, p, maxS, ...roots] = process.argv.slice(1);\n const out = (o) => process.stdout.write(JSON.stringify(o));\n const realRoots = roots.map((r) => { try { return fs.realpathSync(r); } catch { return r; } });\n const under = (r) => realRoots.some((x) => r === x || r.startsWith(x + \"/\"));\n const missing = (e) => e && (e.code === \"ENOENT\" || e.code === \"ENOTDIR\");\n const real = (q) => { try { return fs.realpathSync(q); } catch (e) { if (missing(e)) return null; throw e; } };\n const outside = (r) => out({ e: \"policy\", m: p + \" resolves to \" + r + \", outside the environment's roots\" });\n try {\n if (op === \"read\" || op === \"stat\") {\n const r = real(p);\n if (r === null) return out({ r: null });\n if (!under(r)) return outside(r);\n const fd = fs.openSync(r, C.O_RDONLY | C.O_NONBLOCK | C.O_NOFOLLOW);\n try {\n const st = fs.fstatSync(fd);\n if (op === \"stat\") return out({ r: { size: st.size, isDir: st.isDirectory() } });\n if (st.isDirectory()) return out({ r: null });\n if (!st.isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n const max = Number(maxS);\n const want = Math.min(st.size, max);\n const buf = Buffer.alloc(want);\n let off = 0;\n while (off < want) {\n const n = fs.readSync(fd, buf, off, want - off, off);\n if (n === 0) break;\n off += n;\n }\n return out({ r: { b64: buf.subarray(0, off).toString(\"base64\"), truncated: st.size > max } });\n } finally {\n fs.closeSync(fd);\n }\n }\n if (op === \"write\") {\n const data = fs.readFileSync(0);\n const parent = path.dirname(p);\n let anc = parent;\n while (real(anc) === null && anc !== path.dirname(anc)) anc = path.dirname(anc);\n const ra = real(anc);\n if (ra === null || !under(ra)) return outside(ra);\n fs.mkdirSync(parent, { recursive: true });\n const rp = real(parent);\n if (rp === null) return out({ e: \"error\", m: \"cannot create \" + parent });\n if (!under(rp)) return outside(rp);\n let file = path.join(rp, path.basename(p));\n let st = null;\n try { st = fs.lstatSync(file); } catch (e) { if (!missing(e)) throw e; }\n if (st && st.isSymbolicLink()) {\n const r = real(file);\n if (r === null) return out({ e: \"policy\", m: p + \" is a dangling symbolic link\" });\n if (!under(r)) return outside(r);\n file = r;\n }\n const fd = fs.openSync(file, C.O_WRONLY | C.O_CREAT | C.O_NONBLOCK | C.O_NOFOLLOW, 0o644);\n try {\n if (!fs.fstatSync(fd).isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n fs.ftruncateSync(fd, 0);\n let off = 0;\n while (off < data.length) off += fs.writeSync(fd, data, off, data.length - off, off);\n } finally {\n fs.closeSync(fd);\n }\n return out({ r: null });\n }\n out({ e: \"error\", m: \"unknown helper op \" + op });\n } catch (e) {\n out({ e: \"error\", m: String((e && e.message) || e) });\n }\n})();\n";
|