@capybara-hq/device 0.1.0-rc.3 → 0.1.0-rc.4
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/README.md +201 -11
- package/dist/args.d.ts +4 -2
- package/dist/args.js +21 -5
- package/dist/cli.d.ts +12 -2
- package/dist/cli.js +60 -8
- package/dist/client.d.ts +8 -0
- package/dist/client.js +37 -13
- package/dist/command-log.d.ts +10 -0
- package/dist/commands/policy.d.ts +66 -3
- package/dist/commands/policy.js +347 -31
- package/dist/commands/start.d.ts +9 -3
- package/dist/commands/start.js +18 -3
- package/dist/exec/docker.d.ts +41 -5
- package/dist/exec/docker.js +73 -19
- package/dist/exec/groups.d.ts +42 -0
- package/dist/exec/groups.js +100 -0
- package/dist/exec/host.d.ts +53 -0
- package/dist/exec/host.js +183 -0
- package/dist/exec/os.d.ts +73 -5
- package/dist/exec/os.js +186 -14
- package/dist/exec/shared.d.ts +28 -0
- package/dist/exec/shared.js +154 -1
- package/dist/exec/switch.d.ts +108 -0
- package/dist/exec/switch.js +214 -0
- package/dist/exec/types.d.ts +37 -3
- package/dist/network.d.ts +45 -0
- package/dist/network.js +161 -0
- package/dist/policy-store.d.ts +38 -0
- package/dist/policy-store.js +92 -0
- package/dist/policy.d.ts +102 -11
- package/dist/policy.js +155 -20
- package/dist/proxy-guard.d.ts +58 -0
- package/dist/proxy-guard.js +137 -0
- package/dist/public-suffix.d.ts +6 -0
- package/dist/public-suffix.js +79 -0
- package/dist/server-ops.d.ts +65 -7
- package/dist/server-ops.js +289 -29
- package/dist/state.d.ts +44 -1
- package/dist/state.js +177 -9
- package/package.json +2 -2
package/dist/exec/docker.js
CHANGED
|
@@ -3,7 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
|
|
|
3
3
|
import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
|
|
4
4
|
import { join, resolve } from "node:path";
|
|
5
5
|
import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
|
|
6
|
-
import { effectiveEgress } from "../policy.js";
|
|
6
|
+
import { ANY_HOST, deviceTier, effectiveEgress, provisionalTier, tierFacts, } from "../policy.js";
|
|
7
7
|
import { EXEC_MARKER } from "./procs.js";
|
|
8
8
|
import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
|
|
9
9
|
import { DeviceOpError } from "./types.js";
|
|
@@ -26,6 +26,31 @@ const SPEC_LABEL = "capybara.device.spec";
|
|
|
26
26
|
/** A file operation in the container that takes longer than this is killed. */
|
|
27
27
|
const FILE_OP_TIMEOUT_S = 30;
|
|
28
28
|
const ROOTS = DEFAULT_SANDBOX_ROOTS;
|
|
29
|
+
/**
|
|
30
|
+
* The container's `--shm-size` for a tier (spec §5.2): `strict` keeps Docker's default (64 MiB);
|
|
31
|
+
* `dev` and `open` get a quarter of the memory ceiling up to 1 GiB (at least the default), or
|
|
32
|
+
* 1 GiB without a ceiling, so browsers have room.
|
|
33
|
+
*/
|
|
34
|
+
export function shmSize(tier, memoryMb) {
|
|
35
|
+
if (tier === "strict")
|
|
36
|
+
return undefined;
|
|
37
|
+
if (memoryMb === null)
|
|
38
|
+
return "1g";
|
|
39
|
+
return `${Math.max(64, Math.min(1024, Math.floor(memoryMb / 4)))}m`;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Whether a command gets the default bridge (spec §5.2 table). Docker mode has no domain filter,
|
|
43
|
+
* and the bridge reaches the host and the intranet, so only an explicit choice opens it: the
|
|
44
|
+
* device's own allowed domains within the ceiling (as `strict` computes them; the dev hosts do
|
|
45
|
+
* not count), or tier `open` with a ceiling that allows any host (an allowlist ceiling at `open`
|
|
46
|
+
* counts only its explicit local domains, like the lower tiers).
|
|
47
|
+
*/
|
|
48
|
+
export function bridgeNetwork(policy, limits) {
|
|
49
|
+
if (deviceTier(policy, limits) === "open" && effectiveEgress(policy, limits).includes(ANY_HOST)) {
|
|
50
|
+
return true;
|
|
51
|
+
}
|
|
52
|
+
return effectiveEgress({ ...policy, tier: "strict" }, limits).length > 0;
|
|
53
|
+
}
|
|
29
54
|
/** Container name of a device. */
|
|
30
55
|
export function containerName(deviceId) {
|
|
31
56
|
return `capybara-device-${deviceId}`;
|
|
@@ -125,8 +150,10 @@ cat > "$f" || exit ${E_FAIL}`;
|
|
|
125
150
|
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
126
151
|
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
127
152
|
* 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
|
|
129
|
-
*
|
|
153
|
+
* same real-path checks as the OS executor. Network: none unless {@link bridgeNetwork} says
|
|
154
|
+
* otherwise, then the default bridge (Docker mode has no domain allowlist). Tiers `dev` and
|
|
155
|
+
* `open` get a larger `/dev/shm` ({@link shmSize}); a change of the container's flags recreates it
|
|
156
|
+
* at the next command that finds it idle.
|
|
130
157
|
*/
|
|
131
158
|
export class DockerExecutor {
|
|
132
159
|
opts;
|
|
@@ -148,6 +175,10 @@ export class DockerExecutor {
|
|
|
148
175
|
queue = [];
|
|
149
176
|
pumping = false;
|
|
150
177
|
dirty = false;
|
|
178
|
+
/** The limits of the latest command: they decide the tier the container is made for. */
|
|
179
|
+
lastLimits;
|
|
180
|
+
/** The spec hash of the container in use (set when it is created or reused). */
|
|
181
|
+
spec;
|
|
151
182
|
constructor(opts) {
|
|
152
183
|
this.opts = opts;
|
|
153
184
|
const dir = resolve(opts.dir);
|
|
@@ -182,9 +213,20 @@ export class DockerExecutor {
|
|
|
182
213
|
{ source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
|
|
183
214
|
];
|
|
184
215
|
}
|
|
216
|
+
/** The tier commands run at now (the owner's choice, else `dev`, before any command). */
|
|
217
|
+
tier(policy = this.opts.policy()) {
|
|
218
|
+
return this.lastLimits === undefined
|
|
219
|
+
? provisionalTier(policy)
|
|
220
|
+
: deviceTier(policy, this.lastLimits);
|
|
221
|
+
}
|
|
222
|
+
/** What the tier gives in this mode (for the policy summary). */
|
|
223
|
+
tierFacts(policy = this.opts.policy()) {
|
|
224
|
+
return tierFacts(policy, this.lastLimits, { proxyDetected: false, mode: "docker" });
|
|
225
|
+
}
|
|
185
226
|
/** Every `docker run` flag of the container except its name and spec label. */
|
|
186
227
|
runArgs() {
|
|
187
|
-
const
|
|
228
|
+
const policy = this.opts.policy();
|
|
229
|
+
const shm = shmSize(this.tier(policy), policy.memoryMb);
|
|
188
230
|
return [
|
|
189
231
|
"--init",
|
|
190
232
|
"--read-only",
|
|
@@ -208,6 +250,7 @@ export class DockerExecutor {
|
|
|
208
250
|
...(policy.memoryMb !== null
|
|
209
251
|
? ["--memory", `${policy.memoryMb}m`, "--memory-swap", `${policy.memoryMb}m`]
|
|
210
252
|
: []),
|
|
253
|
+
...(shm !== undefined ? ["--shm-size", shm] : []),
|
|
211
254
|
"--entrypoint",
|
|
212
255
|
"sleep",
|
|
213
256
|
SANDBOX_IMAGE,
|
|
@@ -216,7 +259,10 @@ export class DockerExecutor {
|
|
|
216
259
|
}
|
|
217
260
|
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
218
261
|
specHash() {
|
|
219
|
-
return
|
|
262
|
+
return this.hashOf(this.runArgs());
|
|
263
|
+
}
|
|
264
|
+
hashOf(runArgs) {
|
|
265
|
+
return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
|
|
220
266
|
}
|
|
221
267
|
matches(c) {
|
|
222
268
|
return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
|
|
@@ -228,8 +274,13 @@ export class DockerExecutor {
|
|
|
228
274
|
}
|
|
229
275
|
return r;
|
|
230
276
|
}
|
|
231
|
-
/**
|
|
232
|
-
|
|
277
|
+
/**
|
|
278
|
+
* Creates the container, or reuses the existing one when it matches; call inside `serial`.
|
|
279
|
+
* A file operation (`anySpec`) reuses any container that sees the directory: it needs no
|
|
280
|
+
* particular flags, and before the first command the tier is not known yet. The next command
|
|
281
|
+
* that finds it idle recreates it if its flags differ.
|
|
282
|
+
*/
|
|
283
|
+
async ensureContainer(opts = {}) {
|
|
233
284
|
if (this.ready)
|
|
234
285
|
return;
|
|
235
286
|
if (!existsSync(this.dir)) {
|
|
@@ -242,20 +293,16 @@ export class DockerExecutor {
|
|
|
242
293
|
mkdirSync(r, { recursive: true });
|
|
243
294
|
}
|
|
244
295
|
let c = await this.inspect();
|
|
245
|
-
if (c !== null &&
|
|
296
|
+
if (c !== null &&
|
|
297
|
+
((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
|
|
246
298
|
await this.mustDocker(["rm", "-f", this.name], "removing the old container");
|
|
247
299
|
c = null;
|
|
248
300
|
}
|
|
249
301
|
if (c === null) {
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
this.name,
|
|
255
|
-
"--label",
|
|
256
|
-
`${SPEC_LABEL}=${this.specHash()}`,
|
|
257
|
-
...this.runArgs(),
|
|
258
|
-
], "creating the container");
|
|
302
|
+
const runArgs = this.runArgs();
|
|
303
|
+
const spec = this.hashOf(runArgs);
|
|
304
|
+
await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
|
|
305
|
+
this.spec = spec;
|
|
259
306
|
// Created on the default bridge (a container created with `none` cannot join it later).
|
|
260
307
|
this.netOpen = true;
|
|
261
308
|
}
|
|
@@ -263,6 +310,7 @@ export class DockerExecutor {
|
|
|
263
310
|
if (!c.State.Running)
|
|
264
311
|
await this.mustDocker(["start", this.name], "starting the container");
|
|
265
312
|
this.netOpen = "bridge" in (await this.inspectNetworks());
|
|
313
|
+
this.spec = c.Config.Labels?.[SPEC_LABEL];
|
|
266
314
|
}
|
|
267
315
|
this.ready = true;
|
|
268
316
|
}
|
|
@@ -354,6 +402,11 @@ export class DockerExecutor {
|
|
|
354
402
|
let served;
|
|
355
403
|
try {
|
|
356
404
|
served = await this.serial(async () => {
|
|
405
|
+
// The policy or the tier changed the container's flags (shm, cpu, memory): recreate
|
|
406
|
+
// it once nothing runs in it.
|
|
407
|
+
if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
|
|
408
|
+
this.ready = false;
|
|
409
|
+
}
|
|
357
410
|
await this.ensureContainer();
|
|
358
411
|
if (w.dead)
|
|
359
412
|
return true;
|
|
@@ -411,7 +464,8 @@ export class DockerExecutor {
|
|
|
411
464
|
if (!ENV_NAME_RE.test(k))
|
|
412
465
|
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
413
466
|
}
|
|
414
|
-
|
|
467
|
+
this.lastLimits = args.limits;
|
|
468
|
+
const open = bridgeNetwork(this.opts.policy(), args.limits);
|
|
415
469
|
await this.acquire(open, signal);
|
|
416
470
|
try {
|
|
417
471
|
signal.throwIfAborted();
|
|
@@ -563,7 +617,7 @@ export class DockerExecutor {
|
|
|
563
617
|
/** Runs one file script in the container; `null` for a missing file. */
|
|
564
618
|
async fileOp(script, path, arg2, input) {
|
|
565
619
|
// A file operation does not need the network; it runs on whichever state the container has.
|
|
566
|
-
await this.serial(() => this.ensureContainer());
|
|
620
|
+
await this.serial(() => this.ensureContainer({ anySpec: true }));
|
|
567
621
|
const r = await docker([
|
|
568
622
|
"exec",
|
|
569
623
|
...(input !== undefined ? ["-i"] : []),
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { ChildProcess } from "node:child_process";
|
|
2
|
+
/**
|
|
3
|
+
* The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
|
|
4
|
+
* marker variable). Executors of the same directory compute the same key, so either one finds
|
|
5
|
+
* and kills what the other started.
|
|
6
|
+
*/
|
|
7
|
+
export declare function dirKeyOf(realDir: string): string;
|
|
8
|
+
/** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
|
|
9
|
+
export declare function killGroupId(pgid: number, signal?: NodeJS.Signals | 0): boolean;
|
|
10
|
+
export declare function pidAlive(pid: number): boolean;
|
|
11
|
+
/**
|
|
12
|
+
* One command's process group. It is tracked after the command's main process exits, as long as
|
|
13
|
+
* the group has members (background children), so killTagged / killAll still reach them.
|
|
14
|
+
*/
|
|
15
|
+
export interface Group {
|
|
16
|
+
tag: string;
|
|
17
|
+
pgid: number;
|
|
18
|
+
/** The leader (the outer shell) has exited and been reaped. */
|
|
19
|
+
exited: boolean;
|
|
20
|
+
/** Called by a kill while the command runs: the result then has `exitCode: null`. */
|
|
21
|
+
onKill?: (() => void) | undefined;
|
|
22
|
+
}
|
|
23
|
+
/** The process groups of one executor's commands (each command leads its own group). */
|
|
24
|
+
export declare class GroupTracker {
|
|
25
|
+
private readonly groups;
|
|
26
|
+
private pruneTimer;
|
|
27
|
+
/** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
|
|
28
|
+
track(tag: string, child: ChildProcess): Group | undefined;
|
|
29
|
+
/** Stops tracking a group (its command failed to start). */
|
|
30
|
+
forget(g: Group): void;
|
|
31
|
+
/** Forgets finished groups with no members left (or whose id was taken by another process). */
|
|
32
|
+
prune(): void;
|
|
33
|
+
kill(g: Group): void;
|
|
34
|
+
/** Kills the groups of the given tags. */
|
|
35
|
+
killTags(tags: Iterable<string>): void;
|
|
36
|
+
killAll(): void;
|
|
37
|
+
/** Stops the prune timer (the groups stay known). */
|
|
38
|
+
dispose(): void;
|
|
39
|
+
/** The number of groups tracked (for tests). */
|
|
40
|
+
get size(): number;
|
|
41
|
+
private stopTimerWhenEmpty;
|
|
42
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
/** How often process groups of finished commands are checked for remaining members. */
|
|
3
|
+
const PRUNE_INTERVAL_MS = 5_000;
|
|
4
|
+
/**
|
|
5
|
+
* The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
|
|
6
|
+
* marker variable). Executors of the same directory compute the same key, so either one finds
|
|
7
|
+
* and kills what the other started.
|
|
8
|
+
*/
|
|
9
|
+
export function dirKeyOf(realDir) {
|
|
10
|
+
return createHash("sha256").update(realDir).digest("hex").slice(0, 16);
|
|
11
|
+
}
|
|
12
|
+
/** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
|
|
13
|
+
export function killGroupId(pgid, signal = "SIGKILL") {
|
|
14
|
+
try {
|
|
15
|
+
process.kill(-pgid, signal);
|
|
16
|
+
return true;
|
|
17
|
+
}
|
|
18
|
+
catch {
|
|
19
|
+
return false;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
export function pidAlive(pid) {
|
|
23
|
+
try {
|
|
24
|
+
process.kill(pid, 0);
|
|
25
|
+
return true;
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
return false;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/** The process groups of one executor's commands (each command leads its own group). */
|
|
32
|
+
export class GroupTracker {
|
|
33
|
+
groups = new Set();
|
|
34
|
+
pruneTimer;
|
|
35
|
+
/** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
|
|
36
|
+
track(tag, child) {
|
|
37
|
+
if (child.pid === undefined)
|
|
38
|
+
return undefined;
|
|
39
|
+
const g = { tag, pgid: child.pid, exited: false };
|
|
40
|
+
this.groups.add(g);
|
|
41
|
+
if (this.pruneTimer === undefined) {
|
|
42
|
+
this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
|
|
43
|
+
this.pruneTimer.unref();
|
|
44
|
+
}
|
|
45
|
+
return g;
|
|
46
|
+
}
|
|
47
|
+
/** Stops tracking a group (its command failed to start). */
|
|
48
|
+
forget(g) {
|
|
49
|
+
this.groups.delete(g);
|
|
50
|
+
}
|
|
51
|
+
/** Forgets finished groups with no members left (or whose id was taken by another process). */
|
|
52
|
+
prune() {
|
|
53
|
+
for (const g of this.groups) {
|
|
54
|
+
if (!g.exited)
|
|
55
|
+
continue;
|
|
56
|
+
// A reaped leader's pid can be reused only once its group is gone: a live process with
|
|
57
|
+
// that pid means the id now belongs to someone else.
|
|
58
|
+
if (pidAlive(g.pgid) || !killGroupId(g.pgid, 0))
|
|
59
|
+
this.groups.delete(g);
|
|
60
|
+
}
|
|
61
|
+
this.stopTimerWhenEmpty();
|
|
62
|
+
}
|
|
63
|
+
kill(g) {
|
|
64
|
+
if (g.exited) {
|
|
65
|
+
this.prune();
|
|
66
|
+
if (!this.groups.has(g))
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
g.onKill?.();
|
|
70
|
+
if (!killGroupId(g.pgid) && g.exited)
|
|
71
|
+
this.groups.delete(g);
|
|
72
|
+
}
|
|
73
|
+
/** Kills the groups of the given tags. */
|
|
74
|
+
killTags(tags) {
|
|
75
|
+
const want = new Set(tags);
|
|
76
|
+
for (const g of [...this.groups])
|
|
77
|
+
if (want.has(g.tag))
|
|
78
|
+
this.kill(g);
|
|
79
|
+
}
|
|
80
|
+
killAll() {
|
|
81
|
+
for (const g of [...this.groups])
|
|
82
|
+
this.kill(g);
|
|
83
|
+
}
|
|
84
|
+
/** Stops the prune timer (the groups stay known). */
|
|
85
|
+
dispose() {
|
|
86
|
+
if (this.pruneTimer !== undefined)
|
|
87
|
+
clearInterval(this.pruneTimer);
|
|
88
|
+
this.pruneTimer = undefined;
|
|
89
|
+
}
|
|
90
|
+
/** The number of groups tracked (for tests). */
|
|
91
|
+
get size() {
|
|
92
|
+
return this.groups.size;
|
|
93
|
+
}
|
|
94
|
+
stopTimerWhenEmpty() {
|
|
95
|
+
if (this.groups.size === 0 && this.pruneTimer !== undefined) {
|
|
96
|
+
clearInterval(this.pruneTimer);
|
|
97
|
+
this.pruneTimer = undefined;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { DeviceExecArgs, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
import type { ExecHooks, Executor } from "./types.js";
|
|
3
|
+
export interface HostExecutorOptions {
|
|
4
|
+
/** The device directory (from login). */
|
|
5
|
+
dir: string;
|
|
6
|
+
/** The environment commands start from (default: this program's own, `process.env`). */
|
|
7
|
+
env?: NodeJS.ProcessEnv;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
|
|
11
|
+
* user, with this program's own environment plus the request's, so commands see the real `HOME`,
|
|
12
|
+
* `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
|
|
13
|
+
* (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
|
|
14
|
+
* (see `exec/switch.ts`).
|
|
15
|
+
*
|
|
16
|
+
* What stays the same as the OS sandbox: the working directory is checked inside the device's
|
|
17
|
+
* roots, file operations are confined to the roots (direct host IO), and every command leads its
|
|
18
|
+
* own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
|
|
19
|
+
* `killAll` reach it and what it leaves running.
|
|
20
|
+
*/
|
|
21
|
+
export declare class HostExecutor implements Executor {
|
|
22
|
+
private readonly opts;
|
|
23
|
+
readonly mode: "os";
|
|
24
|
+
readonly roots: SandboxRoots;
|
|
25
|
+
private readonly dir;
|
|
26
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
|
|
27
|
+
private readonly dirKey;
|
|
28
|
+
private readonly groups;
|
|
29
|
+
private readonly guard;
|
|
30
|
+
private readonly files;
|
|
31
|
+
constructor(opts: HostExecutorOptions);
|
|
32
|
+
ensureRoot(): Promise<"ok" | "gone">;
|
|
33
|
+
/** The marker value of a tag's processes. */
|
|
34
|
+
markerOf(tag: string): string;
|
|
35
|
+
/** The command's environment: this program's, the request's, then the marker. */
|
|
36
|
+
private envFor;
|
|
37
|
+
exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
|
|
38
|
+
readFile(path: string, maxBytes: number): Promise<{
|
|
39
|
+
data: Uint8Array;
|
|
40
|
+
truncated: boolean;
|
|
41
|
+
} | null>;
|
|
42
|
+
writeFile(path: string, data: Uint8Array): Promise<void>;
|
|
43
|
+
stat(path: string): Promise<{
|
|
44
|
+
size: number;
|
|
45
|
+
isDir: boolean;
|
|
46
|
+
} | null>;
|
|
47
|
+
killTagged(tags: string[]): Promise<void>;
|
|
48
|
+
killAll(): Promise<void>;
|
|
49
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
50
|
+
killLeftovers(): Promise<void>;
|
|
51
|
+
/** Kills every running command and stops tracking. */
|
|
52
|
+
dispose(): Promise<void>;
|
|
53
|
+
}
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { existsSync, realpathSync } from "node:fs";
|
|
3
|
+
import { constants as osConstants } from "node:os";
|
|
4
|
+
import { resolve } from "node:path";
|
|
5
|
+
import { dirKeyOf, GroupTracker } from "./groups.js";
|
|
6
|
+
import { EXEC_MARKER, killMarked } from "./procs.js";
|
|
7
|
+
import { ENV_NAME_RE, HostFiles, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
|
|
8
|
+
/**
|
|
9
|
+
* Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
|
|
10
|
+
* user, with this program's own environment plus the request's, so commands see the real `HOME`,
|
|
11
|
+
* `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
|
|
12
|
+
* (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
|
|
13
|
+
* (see `exec/switch.ts`).
|
|
14
|
+
*
|
|
15
|
+
* What stays the same as the OS sandbox: the working directory is checked inside the device's
|
|
16
|
+
* roots, file operations are confined to the roots (direct host IO), and every command leads its
|
|
17
|
+
* own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
|
|
18
|
+
* `killAll` reach it and what it leaves running.
|
|
19
|
+
*/
|
|
20
|
+
export class HostExecutor {
|
|
21
|
+
opts;
|
|
22
|
+
mode = "os";
|
|
23
|
+
roots;
|
|
24
|
+
dir;
|
|
25
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
|
|
26
|
+
dirKey;
|
|
27
|
+
groups = new GroupTracker();
|
|
28
|
+
guard;
|
|
29
|
+
files;
|
|
30
|
+
constructor(opts) {
|
|
31
|
+
this.opts = opts;
|
|
32
|
+
const dir = resolve(opts.dir);
|
|
33
|
+
this.dir = existsSync(dir) ? realpathSync(dir) : dir;
|
|
34
|
+
this.roots = osRoots(this.dir);
|
|
35
|
+
this.guard = new RootGuard(this.dir, this.roots);
|
|
36
|
+
this.files = new HostFiles(this.roots);
|
|
37
|
+
this.dirKey = dirKeyOf(this.dir);
|
|
38
|
+
}
|
|
39
|
+
async ensureRoot() {
|
|
40
|
+
return this.guard.ensure();
|
|
41
|
+
}
|
|
42
|
+
/** The marker value of a tag's processes. */
|
|
43
|
+
markerOf(tag) {
|
|
44
|
+
return `${this.dirKey}.${tag}`;
|
|
45
|
+
}
|
|
46
|
+
/** The command's environment: this program's, the request's, then the marker. */
|
|
47
|
+
envFor(args) {
|
|
48
|
+
const env = {};
|
|
49
|
+
for (const [k, v] of Object.entries(this.opts.env ?? process.env)) {
|
|
50
|
+
if (v !== undefined)
|
|
51
|
+
env[k] = v;
|
|
52
|
+
}
|
|
53
|
+
for (const [k, v] of Object.entries(args.env ?? {})) {
|
|
54
|
+
if (!ENV_NAME_RE.test(k))
|
|
55
|
+
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
56
|
+
env[k] = v;
|
|
57
|
+
}
|
|
58
|
+
env[EXEC_MARKER] = this.markerOf(args.tag);
|
|
59
|
+
return env;
|
|
60
|
+
}
|
|
61
|
+
async exec(args, signal, hooks) {
|
|
62
|
+
signal.throwIfAborted();
|
|
63
|
+
const cwd = await this.files.inside(args.cwd ?? this.roots.workspace, "cwd");
|
|
64
|
+
const env = this.envFor(args);
|
|
65
|
+
// The kernel may have cancelled while the cwd was checked.
|
|
66
|
+
signal.throwIfAborted();
|
|
67
|
+
// The sandbox may have been turned back on meanwhile: judged again with no await before the
|
|
68
|
+
// spawn, so a kill of every unsandboxed command never misses this one.
|
|
69
|
+
hooks?.beforeSpawn?.();
|
|
70
|
+
// detached: the command leads its own process group, so a kill reaches its children too.
|
|
71
|
+
const child = spawn("/bin/bash", ["-c", args.command], {
|
|
72
|
+
cwd,
|
|
73
|
+
env,
|
|
74
|
+
detached: true,
|
|
75
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
76
|
+
});
|
|
77
|
+
return new Promise((resolvePromise, reject) => {
|
|
78
|
+
const cap = new OutputCap(args.maxOutputBytes);
|
|
79
|
+
let timedOut = false;
|
|
80
|
+
let killed = false;
|
|
81
|
+
let exit;
|
|
82
|
+
let settled = false;
|
|
83
|
+
let grace;
|
|
84
|
+
const group = this.groups.track(args.tag, child);
|
|
85
|
+
if (group) {
|
|
86
|
+
group.onKill = () => {
|
|
87
|
+
// A kill after a clean exit (a background child) leaves the result alone.
|
|
88
|
+
if (exit === undefined)
|
|
89
|
+
killed = true;
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
const kill = () => {
|
|
93
|
+
if (group)
|
|
94
|
+
this.groups.kill(group);
|
|
95
|
+
};
|
|
96
|
+
const timer = setTimeout(() => {
|
|
97
|
+
if (exit === undefined)
|
|
98
|
+
timedOut = true;
|
|
99
|
+
kill();
|
|
100
|
+
}, args.timeoutMs);
|
|
101
|
+
const onAbort = () => kill();
|
|
102
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
103
|
+
const cleanup = () => {
|
|
104
|
+
clearTimeout(timer);
|
|
105
|
+
if (grace)
|
|
106
|
+
clearTimeout(grace);
|
|
107
|
+
signal.removeEventListener("abort", onAbort);
|
|
108
|
+
if (group) {
|
|
109
|
+
group.exited = true;
|
|
110
|
+
group.onKill = undefined;
|
|
111
|
+
}
|
|
112
|
+
};
|
|
113
|
+
const finish = () => {
|
|
114
|
+
if (settled || exit === undefined)
|
|
115
|
+
return;
|
|
116
|
+
settled = true;
|
|
117
|
+
cleanup();
|
|
118
|
+
child.stdout?.destroy();
|
|
119
|
+
child.stderr?.destroy();
|
|
120
|
+
let exitCode = exit.code;
|
|
121
|
+
if (killed || timedOut)
|
|
122
|
+
exitCode = null;
|
|
123
|
+
else if (exitCode === null && exit.sig !== null) {
|
|
124
|
+
exitCode = 128 + (osConstants.signals[exit.sig] ?? 0);
|
|
125
|
+
}
|
|
126
|
+
resolvePromise({
|
|
127
|
+
exitCode,
|
|
128
|
+
stdout: cap.text("stdout"),
|
|
129
|
+
stderr: cap.text("stderr"),
|
|
130
|
+
truncated: cap.truncated,
|
|
131
|
+
timedOut,
|
|
132
|
+
});
|
|
133
|
+
};
|
|
134
|
+
child.stdout?.on("data", (b) => cap.push("stdout", b));
|
|
135
|
+
child.stderr?.on("data", (b) => cap.push("stderr", b));
|
|
136
|
+
child.once("error", (e) => {
|
|
137
|
+
if (settled)
|
|
138
|
+
return;
|
|
139
|
+
settled = true;
|
|
140
|
+
if (group)
|
|
141
|
+
this.groups.forget(group);
|
|
142
|
+
cleanup();
|
|
143
|
+
reject(e);
|
|
144
|
+
});
|
|
145
|
+
child.once("exit", (code, sig) => {
|
|
146
|
+
exit = { code, sig };
|
|
147
|
+
if (group)
|
|
148
|
+
group.exited = true;
|
|
149
|
+
// A background child may hold the pipes open; do not wait for it past a short grace.
|
|
150
|
+
grace = setTimeout(finish, PIPE_GRACE_MS);
|
|
151
|
+
});
|
|
152
|
+
child.once("close", () => finish());
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
async readFile(path, maxBytes) {
|
|
156
|
+
return this.files.read(path, maxBytes);
|
|
157
|
+
}
|
|
158
|
+
async writeFile(path, data) {
|
|
159
|
+
await this.files.write(path, data);
|
|
160
|
+
}
|
|
161
|
+
async stat(path) {
|
|
162
|
+
return this.files.stat(path);
|
|
163
|
+
}
|
|
164
|
+
async killTagged(tags) {
|
|
165
|
+
this.groups.killTags(tags);
|
|
166
|
+
const values = new Set(tags.map((t) => this.markerOf(t)));
|
|
167
|
+
await killMarked((v) => values.has(v));
|
|
168
|
+
}
|
|
169
|
+
async killAll() {
|
|
170
|
+
this.groups.killAll();
|
|
171
|
+
await this.killLeftovers();
|
|
172
|
+
}
|
|
173
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
174
|
+
async killLeftovers() {
|
|
175
|
+
const prefix = `${this.dirKey}.`;
|
|
176
|
+
await killMarked((v) => v.startsWith(prefix));
|
|
177
|
+
}
|
|
178
|
+
/** Kills every running command and stops tracking. */
|
|
179
|
+
async dispose() {
|
|
180
|
+
await this.killAll();
|
|
181
|
+
this.groups.dispose();
|
|
182
|
+
}
|
|
183
|
+
}
|
package/dist/exec/os.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
-
import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
|
|
2
|
-
import type { DeviceExecArgs, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
1
|
+
import { type SandboxAskCallback, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
|
|
2
|
+
import type { DeviceExecArgs, ExecResult, SandboxRoots, SandboxTier } from "@capybara-hq/plugin-sdk";
|
|
3
|
+
import { type TierFacts } from "../policy.js";
|
|
4
|
+
import { type ProxyGuardResult } from "../proxy-guard.js";
|
|
3
5
|
import type { Policy } from "../state.js";
|
|
4
6
|
import { type Executor } from "./types.js";
|
|
5
7
|
export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
|
|
@@ -13,11 +15,16 @@ export declare function sandboxAvailability(): {
|
|
|
13
15
|
export interface OsExecutorOptions {
|
|
14
16
|
/** The device directory (from login). */
|
|
15
17
|
dir: string;
|
|
16
|
-
policy
|
|
18
|
+
/** The local policy now (read at each command, so a change applies without a restart). */
|
|
19
|
+
policy: () => Policy;
|
|
17
20
|
/** The home whose secret paths are denied (default: the user's home). */
|
|
18
21
|
home?: string;
|
|
19
22
|
/** More paths commands may not read (this program's state directory). */
|
|
20
23
|
denyRead?: string[];
|
|
24
|
+
/** The localhost proxy guard (default: {@link detectLocalProxy}); injectable for tests. */
|
|
25
|
+
detectProxy?: () => Promise<ProxyGuardResult>;
|
|
26
|
+
/** Where the macOS short socket directory is made (default `/private/tmp`). */
|
|
27
|
+
socketBase?: string;
|
|
21
28
|
}
|
|
22
29
|
/**
|
|
23
30
|
* Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap):
|
|
@@ -37,10 +44,71 @@ export declare class OsExecutor implements Executor {
|
|
|
37
44
|
private pruneTimer;
|
|
38
45
|
private readonly guard;
|
|
39
46
|
private readonly files;
|
|
47
|
+
/**
|
|
48
|
+
* The limits of the latest command. The ask callback has no command id; a device belongs to one
|
|
49
|
+
* org, so these stand for the org's egress when it explains a refusal.
|
|
50
|
+
*/
|
|
51
|
+
private lastLimits;
|
|
52
|
+
/** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
|
|
53
|
+
private socketDir;
|
|
54
|
+
/** The device's package caches (`<dir>/cache`). */
|
|
55
|
+
private readonly cacheDir;
|
|
56
|
+
/** The latest proxy guard result, and the policy object it was taken for. */
|
|
57
|
+
private proxy;
|
|
58
|
+
private guardedPolicy;
|
|
59
|
+
private guardedAt;
|
|
60
|
+
/** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
|
|
61
|
+
private installed;
|
|
62
|
+
/**
|
|
63
|
+
* Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
|
|
64
|
+
* running. The ask callback allows any public name only while one runs.
|
|
65
|
+
*/
|
|
66
|
+
private readonly openCommands;
|
|
40
67
|
constructor(opts: OsExecutorOptions);
|
|
41
|
-
/**
|
|
42
|
-
|
|
68
|
+
/**
|
|
69
|
+
* The tier of work that has no limits of its own (the file helper): the device's choice cut to
|
|
70
|
+
* the latest exec's ceiling, `strict` before any exec (no ceiling known yet).
|
|
71
|
+
*/
|
|
72
|
+
tier(policy?: Policy): SandboxTier;
|
|
73
|
+
/** What the tier gives on this machine now (for the policy summary). */
|
|
74
|
+
tierFacts(policy?: Policy): TierFacts;
|
|
75
|
+
/** The latest proxy guard result. */
|
|
76
|
+
proxyGuard(): ProxyGuardResult;
|
|
77
|
+
/** The sandbox configuration for the policy at `tier` (no domains: those are per command). */
|
|
78
|
+
config(policy?: Policy, tier?: SandboxTier): SandboxRuntimeConfig;
|
|
79
|
+
/**
|
|
80
|
+
* Installs {@link config} when the policy or the tier changed it, so the change applies at the
|
|
81
|
+
* next command without a restart. The runtime reads its global configuration at each wrap.
|
|
82
|
+
*/
|
|
83
|
+
private applyConfig;
|
|
84
|
+
/** Records the configuration the sandbox was initialized with. */
|
|
85
|
+
markInstalled(config: SandboxRuntimeConfig): void;
|
|
86
|
+
/**
|
|
87
|
+
* macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
|
|
88
|
+
* command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
|
|
89
|
+
* device without one: commands then use the tmp root.
|
|
90
|
+
*/
|
|
91
|
+
prepareSocketDir(): void;
|
|
92
|
+
/**
|
|
93
|
+
* Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
|
|
94
|
+
* (the store returns a new object for each new version of policy.json), and when the last result
|
|
95
|
+
* is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
|
|
96
|
+
* fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
|
|
97
|
+
*/
|
|
98
|
+
refreshProxyGuard(policy: Policy): Promise<void>;
|
|
43
99
|
ensureRoot(): Promise<"ok" | "gone">;
|
|
100
|
+
/**
|
|
101
|
+
* The sandbox's ask callback, reached only for a host no list allows. sandbox-runtime refuses `*`
|
|
102
|
+
* in a per-command list, so a command that may reach any host (device policy `open`, its limits
|
|
103
|
+
* `open`) is allowed here: a public name is allowed while such a command runs and the policy
|
|
104
|
+
* and latest limits still say so (narrowing takes effect at once). The callback has no command
|
|
105
|
+
* id, so a concurrent command of the same device may ride along meanwhile; the file helper never
|
|
106
|
+
* opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
|
|
107
|
+
* show (spec §9.1).
|
|
108
|
+
*/
|
|
109
|
+
readonly askCallback: SandboxAskCallback;
|
|
110
|
+
/** The classified network refusals of one command (read before it unregisters). */
|
|
111
|
+
private blockedFor;
|
|
44
112
|
/** The marker value of a tag's processes. */
|
|
45
113
|
markerOf(tag: string): string;
|
|
46
114
|
/**
|