@capybara-hq/device 0.1.0-rc.1 → 0.1.0-rc.11
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 +205 -44
- package/dist/api.d.ts +6 -1
- package/dist/args.d.ts +14 -3
- package/dist/args.js +74 -10
- package/dist/cli.d.ts +27 -4
- package/dist/cli.js +81 -11
- package/dist/client.d.ts +19 -6
- package/dist/client.js +93 -19
- package/dist/command-log.d.ts +8 -0
- package/dist/commands/drain.d.ts +14 -1
- package/dist/commands/drain.js +31 -2
- package/dist/commands/login.d.ts +3 -0
- package/dist/commands/login.js +96 -11
- package/dist/commands/logout.d.ts +2 -0
- package/dist/commands/logout.js +1 -1
- package/dist/commands/mode.d.ts +69 -0
- package/dist/commands/mode.js +129 -0
- package/dist/commands/policy.d.ts +13 -4
- package/dist/commands/policy.js +162 -33
- package/dist/commands/service.d.ts +26 -4
- package/dist/commands/service.js +242 -19
- package/dist/commands/signal.d.ts +6 -2
- package/dist/commands/signal.js +7 -4
- package/dist/commands/start.d.ts +18 -3
- package/dist/commands/start.js +46 -7
- package/dist/commands/status.js +12 -4
- package/dist/commands/stop.d.ts +20 -2
- package/dist/commands/stop.js +26 -3
- package/dist/exec/docker.d.ts +41 -13
- package/dist/exec/docker.js +123 -57
- package/dist/exec/fs-helper.d.ts +13 -8
- package/dist/exec/fs-helper.js +31 -13
- 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 +85 -15
- package/dist/exec/os.js +208 -36
- package/dist/exec/reap.d.ts +41 -0
- package/dist/exec/reap.js +89 -0
- package/dist/exec/sandbox-messages.d.ts +14 -0
- package/dist/exec/sandbox-messages.js +21 -0
- package/dist/exec/shared.d.ts +42 -13
- package/dist/exec/shared.js +94 -16
- package/dist/exec/switch.d.ts +98 -0
- package/dist/exec/switch.js +175 -0
- package/dist/exec/types.d.ts +28 -4
- package/dist/index.d.ts +1 -1
- package/dist/network.d.ts +45 -0
- package/dist/network.js +154 -0
- package/dist/pid.d.ts +44 -3
- package/dist/pid.js +110 -7
- package/dist/policy-ops.d.ts +47 -0
- package/dist/policy-ops.js +90 -0
- package/dist/policy-store.d.ts +43 -0
- package/dist/policy-store.js +94 -0
- package/dist/policy.d.ts +36 -16
- package/dist/policy.js +77 -19
- package/dist/public-suffix.d.ts +6 -0
- package/dist/public-suffix.js +79 -0
- package/dist/server-ops.d.ts +48 -7
- package/dist/server-ops.js +287 -29
- package/dist/service/installed.d.ts +5 -0
- package/dist/service/installed.js +14 -0
- package/dist/service/launchd.d.ts +14 -1
- package/dist/service/launchd.js +25 -1
- package/dist/service/manager.d.ts +41 -0
- package/dist/service/manager.js +91 -0
- package/dist/service/systemd.d.ts +2 -0
- package/dist/service/systemd.js +8 -0
- package/dist/state.d.ts +50 -6
- package/dist/state.js +195 -16
- package/package.json +3 -3
package/dist/exec/docker.d.ts
CHANGED
|
@@ -5,13 +5,13 @@ import { type Executor } from "./types.js";
|
|
|
5
5
|
export declare const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
|
|
6
6
|
export declare const SANDBOX_IMAGE = "ghcr.io/capybara-hq/capybara-sandbox:0.1.0-rc.5";
|
|
7
7
|
/**
|
|
8
|
-
* The user commands run as. On Linux the bind-mounted
|
|
8
|
+
* The user commands run as. On Linux the bind-mounted device directory belongs to the host user,
|
|
9
9
|
* so the container runs as that uid:gid (never root: a root host user falls back to the image's user).
|
|
10
10
|
* Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
|
|
11
11
|
*/
|
|
12
12
|
export declare function containerUser(platform?: NodeJS.Platform, uid?: number | undefined, gid?: number | undefined): string;
|
|
13
|
-
/** Container name of
|
|
14
|
-
export declare function containerName(
|
|
13
|
+
/** Container name of a device. */
|
|
14
|
+
export declare function containerName(deviceId: string): string;
|
|
15
15
|
/** Whether the docker CLI can reach a daemon, and why not. */
|
|
16
16
|
export declare function dockerAvailability(): Promise<{
|
|
17
17
|
ok: true;
|
|
@@ -20,19 +20,25 @@ export declare function dockerAvailability(): Promise<{
|
|
|
20
20
|
reason: string;
|
|
21
21
|
}>;
|
|
22
22
|
export interface DockerExecutorOptions {
|
|
23
|
-
/** The
|
|
23
|
+
/** The device directory (from login). */
|
|
24
24
|
dir: string;
|
|
25
|
-
|
|
26
|
-
|
|
25
|
+
deviceId: string;
|
|
26
|
+
/**
|
|
27
|
+
* The local policy now. The network decision reads it at each command; cpu and memory apply
|
|
28
|
+
* when the container is next created (at the next command that finds it idle).
|
|
29
|
+
*/
|
|
30
|
+
policy: () => Policy;
|
|
27
31
|
}
|
|
28
32
|
/**
|
|
29
33
|
* Runs every command with `docker exec` in one long-lived container of the published sandbox
|
|
30
|
-
* image: the
|
|
34
|
+
* image: the device directory's workspace, skills (read only) and tmp are mounted at
|
|
31
35
|
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
32
36
|
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
33
37
|
* host); the skills directory, which commands cannot write, is accessed from the host with the
|
|
34
|
-
* same real-path checks as the OS executor.
|
|
35
|
-
*
|
|
38
|
+
* same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
|
|
39
|
+
* file operations reach any absolute path in the container. Sandbox mode: no network attached and
|
|
40
|
+
* file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
|
|
41
|
+
* container's flags recreates it at the next command that finds it idle.
|
|
36
42
|
*/
|
|
37
43
|
export declare class DockerExecutor implements Executor {
|
|
38
44
|
private readonly opts;
|
|
@@ -43,7 +49,7 @@ export declare class DockerExecutor implements Executor {
|
|
|
43
49
|
private readonly hostRoots;
|
|
44
50
|
private readonly guard;
|
|
45
51
|
private readonly hostFiles;
|
|
46
|
-
/** Marks every process of this
|
|
52
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>`. */
|
|
47
53
|
private readonly dirKey;
|
|
48
54
|
private readonly running;
|
|
49
55
|
private chain;
|
|
@@ -54,19 +60,38 @@ export declare class DockerExecutor implements Executor {
|
|
|
54
60
|
private readonly queue;
|
|
55
61
|
private pumping;
|
|
56
62
|
private dirty;
|
|
63
|
+
/** The limits of the latest command: the kernel's mode ceiling for file operations. */
|
|
64
|
+
private lastLimits;
|
|
65
|
+
/** When {@link lastLimits} came (file operations follow it only inside the window). */
|
|
66
|
+
private lastLimitsAt;
|
|
67
|
+
/** The spec hash of the container in use (set when it is created or reused). */
|
|
68
|
+
private spec;
|
|
57
69
|
constructor(opts: DockerExecutorOptions);
|
|
58
70
|
ensureRoot(): Promise<"ok" | "gone">;
|
|
59
71
|
markerOf(tag: string): string;
|
|
60
72
|
private serial;
|
|
61
73
|
private inspect;
|
|
62
74
|
private wanted;
|
|
75
|
+
/**
|
|
76
|
+
* The mode file operations use now. File operations carry no limits and never pass command
|
|
77
|
+
* review, so they use the sandboxed result before any exec and once the latest decision is stale
|
|
78
|
+
* (the safe default for an organization whose ceiling is sandbox), else
|
|
79
|
+
* `effectiveMode(policy, limits)`.
|
|
80
|
+
*/
|
|
81
|
+
private modeNow;
|
|
63
82
|
/** Every `docker run` flag of the container except its name and spec label. */
|
|
64
83
|
private runArgs;
|
|
65
84
|
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
66
85
|
private specHash;
|
|
86
|
+
private hashOf;
|
|
67
87
|
private matches;
|
|
68
88
|
private mustDocker;
|
|
69
|
-
/**
|
|
89
|
+
/**
|
|
90
|
+
* Creates the container, or reuses the existing one when it matches; call inside `serial`.
|
|
91
|
+
* A file operation (`anySpec`) reuses any container that sees the directory: it needs no
|
|
92
|
+
* particular flags, and before the first command the policy is not known yet. The next command
|
|
93
|
+
* that finds it idle recreates it if its flags differ.
|
|
94
|
+
*/
|
|
70
95
|
private ensureContainer;
|
|
71
96
|
/**
|
|
72
97
|
* Whether a reused container's mounts still show this directory's roots: after the directory was
|
|
@@ -89,7 +114,10 @@ export declare class DockerExecutor implements Executor {
|
|
|
89
114
|
private noteFailure;
|
|
90
115
|
exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
|
|
91
116
|
private run;
|
|
92
|
-
/**
|
|
117
|
+
/**
|
|
118
|
+
* `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
|
|
119
|
+
* is the boundary); sandbox mode refuses anything outside the mounted roots.
|
|
120
|
+
*/
|
|
93
121
|
private containerPath;
|
|
94
122
|
/** The host path of a /skills path (the skills directory is mounted read only). */
|
|
95
123
|
private skillsHostPath;
|
|
@@ -111,7 +139,7 @@ export declare class DockerExecutor implements Executor {
|
|
|
111
139
|
private killMarker;
|
|
112
140
|
killTagged(tags: string[]): Promise<void>;
|
|
113
141
|
killAll(): Promise<void>;
|
|
114
|
-
/** Kills every process carrying this
|
|
142
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
115
143
|
killLeftovers(): Promise<void>;
|
|
116
144
|
/** Kills every running command; the container stays for the next start. */
|
|
117
145
|
dispose(): Promise<void>;
|
package/dist/exec/docker.js
CHANGED
|
@@ -2,10 +2,11 @@ import { spawn } from "node:child_process";
|
|
|
2
2
|
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
|
-
import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
|
|
6
|
-
import {
|
|
5
|
+
import { DEFAULT_SANDBOX_ROOTS, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
|
|
6
|
+
import { effectiveMode } 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
|
+
import { FILE_OPS_DECISION_TTL_MS } from "./switch.js";
|
|
9
10
|
import { DeviceOpError } from "./types.js";
|
|
10
11
|
/** The version of the published sandbox images this program runs commands in. */
|
|
11
12
|
export const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
|
|
@@ -13,7 +14,7 @@ export const SANDBOX_IMAGE = `ghcr.io/capybara-hq/capybara-sandbox:${SANDBOX_IMA
|
|
|
13
14
|
/** The image's `sandbox` user. */
|
|
14
15
|
const IMAGE_USER = "1000:1000";
|
|
15
16
|
/**
|
|
16
|
-
* The user commands run as. On Linux the bind-mounted
|
|
17
|
+
* The user commands run as. On Linux the bind-mounted device directory belongs to the host user,
|
|
17
18
|
* so the container runs as that uid:gid (never root: a root host user falls back to the image's user).
|
|
18
19
|
* Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
|
|
19
20
|
*/
|
|
@@ -26,11 +27,11 @@ const SPEC_LABEL = "capybara.device.spec";
|
|
|
26
27
|
/** A file operation in the container that takes longer than this is killed. */
|
|
27
28
|
const FILE_OP_TIMEOUT_S = 30;
|
|
28
29
|
const ROOTS = DEFAULT_SANDBOX_ROOTS;
|
|
29
|
-
/** Container name of
|
|
30
|
-
export function containerName(
|
|
31
|
-
return `capybara-device-${
|
|
30
|
+
/** Container name of a device. */
|
|
31
|
+
export function containerName(deviceId) {
|
|
32
|
+
return `capybara-device-${deviceId}`;
|
|
32
33
|
}
|
|
33
|
-
/** Runs `docker <args>` to completion (not a command of the
|
|
34
|
+
/** Runs `docker <args>` to completion (not a command of the device). */
|
|
34
35
|
function docker(args, o = {}) {
|
|
35
36
|
return new Promise((resolvePromise, reject) => {
|
|
36
37
|
const child = spawn("docker", args, { stdio: [o.input ? "pipe" : "ignore", "pipe", "pipe"] });
|
|
@@ -91,42 +92,59 @@ done; done; exit 0`;
|
|
|
91
92
|
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
93
|
/** The pids limit of a container (as the cloud sandbox). */
|
|
93
94
|
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
95
|
// Exit codes of the file scripts.
|
|
96
|
+
const E_MODE = 9;
|
|
98
97
|
const E_MISSING = 10;
|
|
99
98
|
const E_OUTSIDE = 11;
|
|
100
99
|
const E_NOT_FILE = 12;
|
|
101
100
|
const E_FAIL = 13;
|
|
102
101
|
const E_DANGLING = 14;
|
|
103
|
-
|
|
104
|
-
|
|
102
|
+
/**
|
|
103
|
+
* The shared prologue of the file scripts: `$1` is the mode, `$2` the path, `$3` the extra
|
|
104
|
+
* argument. In sandbox mode `allowed` checks a real path against the mounted roots; in auto mode
|
|
105
|
+
* any absolute path in the container is allowed (the host checks its shape already).
|
|
106
|
+
*/
|
|
107
|
+
const FILE_PROLOGUE = `mode=$1; p=$2; arg=$3
|
|
108
|
+
allowed() {
|
|
109
|
+
if [ "$mode" = "auto" ]; then
|
|
110
|
+
case "$1" in /*) ;; *) return 1;; esac
|
|
111
|
+
case "/$1/" in *"/../"*) return 1;; esac
|
|
112
|
+
return 0
|
|
113
|
+
fi
|
|
114
|
+
case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac
|
|
115
|
+
return 1
|
|
116
|
+
}
|
|
117
|
+
if [ "$mode" != "auto" ] && [ "$mode" != "sandbox" ]; then exit ${E_MODE}; fi
|
|
118
|
+
`;
|
|
119
|
+
const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
|
|
120
|
+
allowed "$r" || exit ${E_OUTSIDE}
|
|
105
121
|
[ -d "$r" ] && exit ${E_MISSING}
|
|
106
122
|
[ -f "$r" ] || exit ${E_NOT_FILE}
|
|
107
|
-
head -c "$
|
|
108
|
-
const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$
|
|
109
|
-
|
|
123
|
+
head -c "$arg" -- "$r"`;
|
|
124
|
+
const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
|
|
125
|
+
allowed "$r" || exit ${E_OUTSIDE}
|
|
110
126
|
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}
|
|
127
|
+
const WRITE_SCRIPT = `${FILE_PROLOGUE}d=$(dirname -- "$p"); a=$d
|
|
112
128
|
while [ ! -e "$a" ] && [ "$a" != / ]; do a=$(dirname -- "$a"); done
|
|
113
129
|
ra=$(realpath -e -- "$a" 2>/dev/null) || exit ${E_FAIL}
|
|
114
|
-
|
|
130
|
+
allowed "$ra" || exit ${E_OUTSIDE}
|
|
115
131
|
mkdir -p -- "$d" || exit ${E_FAIL}
|
|
116
132
|
rp=$(realpath -e -- "$d" 2>/dev/null) || exit ${E_FAIL}
|
|
117
|
-
|
|
133
|
+
allowed "$rp" || exit ${E_OUTSIDE}
|
|
118
134
|
f="$rp/$(basename -- "$p")"
|
|
119
|
-
if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING};
|
|
135
|
+
if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING}; allowed "$r" || exit ${E_OUTSIDE}; f=$r; fi
|
|
120
136
|
if [ -e "$f" ] && [ ! -f "$f" ]; then exit ${E_NOT_FILE}; fi
|
|
121
137
|
cat > "$f" || exit ${E_FAIL}`;
|
|
122
138
|
/**
|
|
123
139
|
* Runs every command with `docker exec` in one long-lived container of the published sandbox
|
|
124
|
-
* image: the
|
|
140
|
+
* image: the device directory's workspace, skills (read only) and tmp are mounted at
|
|
125
141
|
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
126
142
|
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
127
143
|
* host); the skills directory, which commands cannot write, is accessed from the host with the
|
|
128
|
-
* same real-path checks as the OS executor.
|
|
129
|
-
*
|
|
144
|
+
* same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
|
|
145
|
+
* file operations reach any absolute path in the container. Sandbox mode: no network attached and
|
|
146
|
+
* file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
|
|
147
|
+
* container's flags recreates it at the next command that finds it idle.
|
|
130
148
|
*/
|
|
131
149
|
export class DockerExecutor {
|
|
132
150
|
opts;
|
|
@@ -137,7 +155,7 @@ export class DockerExecutor {
|
|
|
137
155
|
hostRoots;
|
|
138
156
|
guard;
|
|
139
157
|
hostFiles;
|
|
140
|
-
/** Marks every process of this
|
|
158
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>`. */
|
|
141
159
|
dirKey;
|
|
142
160
|
running = new Set();
|
|
143
161
|
chain = Promise.resolve();
|
|
@@ -148,14 +166,20 @@ export class DockerExecutor {
|
|
|
148
166
|
queue = [];
|
|
149
167
|
pumping = false;
|
|
150
168
|
dirty = false;
|
|
169
|
+
/** The limits of the latest command: the kernel's mode ceiling for file operations. */
|
|
170
|
+
lastLimits;
|
|
171
|
+
/** When {@link lastLimits} came (file operations follow it only inside the window). */
|
|
172
|
+
lastLimitsAt = 0;
|
|
173
|
+
/** The spec hash of the container in use (set when it is created or reused). */
|
|
174
|
+
spec;
|
|
151
175
|
constructor(opts) {
|
|
152
176
|
this.opts = opts;
|
|
153
177
|
const dir = resolve(opts.dir);
|
|
154
178
|
this.dir = existsSync(dir) ? realpathSync(dir) : dir;
|
|
155
179
|
this.hostRoots = osRoots(this.dir);
|
|
156
180
|
this.guard = new RootGuard(this.dir, this.hostRoots);
|
|
157
|
-
this.hostFiles = new HostFiles(this.hostRoots);
|
|
158
|
-
this.name = containerName(opts.
|
|
181
|
+
this.hostFiles = new HostFiles(this.hostRoots, "sandbox");
|
|
182
|
+
this.name = containerName(opts.deviceId);
|
|
159
183
|
this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
|
|
160
184
|
}
|
|
161
185
|
async ensureRoot() {
|
|
@@ -182,9 +206,22 @@ export class DockerExecutor {
|
|
|
182
206
|
{ source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
|
|
183
207
|
];
|
|
184
208
|
}
|
|
209
|
+
/**
|
|
210
|
+
* The mode file operations use now. File operations carry no limits and never pass command
|
|
211
|
+
* review, so they use the sandboxed result before any exec and once the latest decision is stale
|
|
212
|
+
* (the safe default for an organization whose ceiling is sandbox), else
|
|
213
|
+
* `effectiveMode(policy, limits)`.
|
|
214
|
+
*/
|
|
215
|
+
modeNow(policy = this.opts.policy()) {
|
|
216
|
+
if (policy.mode === "sandbox" || this.lastLimits === undefined)
|
|
217
|
+
return "sandbox";
|
|
218
|
+
if (Date.now() - this.lastLimitsAt > FILE_OPS_DECISION_TTL_MS)
|
|
219
|
+
return "sandbox";
|
|
220
|
+
return effectiveMode(policy, this.lastLimits);
|
|
221
|
+
}
|
|
185
222
|
/** Every `docker run` flag of the container except its name and spec label. */
|
|
186
223
|
runArgs() {
|
|
187
|
-
const
|
|
224
|
+
const policy = this.opts.policy();
|
|
188
225
|
return [
|
|
189
226
|
"--init",
|
|
190
227
|
"--read-only",
|
|
@@ -199,7 +236,7 @@ export class DockerExecutor {
|
|
|
199
236
|
"--workdir",
|
|
200
237
|
ROOTS.workspace,
|
|
201
238
|
"--label",
|
|
202
|
-
`capybara.device.
|
|
239
|
+
`capybara.device.id=${this.opts.deviceId}`,
|
|
203
240
|
...this.wanted().flatMap((m) => [
|
|
204
241
|
"--mount",
|
|
205
242
|
`type=bind,source=${m.source},target=${m.dest}${m.rw ? "" : ",readonly"}`,
|
|
@@ -216,7 +253,10 @@ export class DockerExecutor {
|
|
|
216
253
|
}
|
|
217
254
|
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
218
255
|
specHash() {
|
|
219
|
-
return
|
|
256
|
+
return this.hashOf(this.runArgs());
|
|
257
|
+
}
|
|
258
|
+
hashOf(runArgs) {
|
|
259
|
+
return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
|
|
220
260
|
}
|
|
221
261
|
matches(c) {
|
|
222
262
|
return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
|
|
@@ -228,34 +268,35 @@ export class DockerExecutor {
|
|
|
228
268
|
}
|
|
229
269
|
return r;
|
|
230
270
|
}
|
|
231
|
-
/**
|
|
232
|
-
|
|
271
|
+
/**
|
|
272
|
+
* Creates the container, or reuses the existing one when it matches; call inside `serial`.
|
|
273
|
+
* A file operation (`anySpec`) reuses any container that sees the directory: it needs no
|
|
274
|
+
* particular flags, and before the first command the policy is not known yet. The next command
|
|
275
|
+
* that finds it idle recreates it if its flags differ.
|
|
276
|
+
*/
|
|
277
|
+
async ensureContainer(opts = {}) {
|
|
233
278
|
if (this.ready)
|
|
234
279
|
return;
|
|
235
280
|
if (!existsSync(this.dir)) {
|
|
236
|
-
throw new DeviceOpError("error", "the
|
|
281
|
+
throw new DeviceOpError("error", "the device directory is gone");
|
|
237
282
|
}
|
|
238
283
|
for (const r of Object.values(this.hostRoots)) {
|
|
239
284
|
if (r.includes(",")) {
|
|
240
|
-
throw new DeviceOpError("error", `the
|
|
285
|
+
throw new DeviceOpError("error", `the device directory ${this.dir} contains a comma`);
|
|
241
286
|
}
|
|
242
287
|
mkdirSync(r, { recursive: true });
|
|
243
288
|
}
|
|
244
289
|
let c = await this.inspect();
|
|
245
|
-
if (c !== null &&
|
|
290
|
+
if (c !== null &&
|
|
291
|
+
((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
|
|
246
292
|
await this.mustDocker(["rm", "-f", this.name], "removing the old container");
|
|
247
293
|
c = null;
|
|
248
294
|
}
|
|
249
295
|
if (c === null) {
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
this.name,
|
|
255
|
-
"--label",
|
|
256
|
-
`${SPEC_LABEL}=${this.specHash()}`,
|
|
257
|
-
...this.runArgs(),
|
|
258
|
-
], "creating the container");
|
|
296
|
+
const runArgs = this.runArgs();
|
|
297
|
+
const spec = this.hashOf(runArgs);
|
|
298
|
+
await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
|
|
299
|
+
this.spec = spec;
|
|
259
300
|
// Created on the default bridge (a container created with `none` cannot join it later).
|
|
260
301
|
this.netOpen = true;
|
|
261
302
|
}
|
|
@@ -263,6 +304,7 @@ export class DockerExecutor {
|
|
|
263
304
|
if (!c.State.Running)
|
|
264
305
|
await this.mustDocker(["start", this.name], "starting the container");
|
|
265
306
|
this.netOpen = "bridge" in (await this.inspectNetworks());
|
|
307
|
+
this.spec = c.Config.Labels?.[SPEC_LABEL];
|
|
266
308
|
}
|
|
267
309
|
this.ready = true;
|
|
268
310
|
}
|
|
@@ -354,6 +396,11 @@ export class DockerExecutor {
|
|
|
354
396
|
let served;
|
|
355
397
|
try {
|
|
356
398
|
served = await this.serial(async () => {
|
|
399
|
+
// The policy or the mode changed the container's flags (shm, cpu, memory): recreate
|
|
400
|
+
// it once nothing runs in it.
|
|
401
|
+
if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
|
|
402
|
+
this.ready = false;
|
|
403
|
+
}
|
|
357
404
|
await this.ensureContainer();
|
|
358
405
|
if (w.dead)
|
|
359
406
|
return true;
|
|
@@ -399,7 +446,8 @@ export class DockerExecutor {
|
|
|
399
446
|
}
|
|
400
447
|
async exec(args, signal) {
|
|
401
448
|
signal.throwIfAborted();
|
|
402
|
-
const
|
|
449
|
+
const mode = effectiveMode(this.opts.policy(), args.limits);
|
|
450
|
+
const cwd = this.containerPath(args.cwd ?? ROOTS.workspace, mode);
|
|
403
451
|
const env = {
|
|
404
452
|
HOME: ROOTS.workspace,
|
|
405
453
|
TERM: "dumb",
|
|
@@ -411,7 +459,10 @@ export class DockerExecutor {
|
|
|
411
459
|
if (!ENV_NAME_RE.test(k))
|
|
412
460
|
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
413
461
|
}
|
|
414
|
-
|
|
462
|
+
this.lastLimits = args.limits;
|
|
463
|
+
this.lastLimitsAt = Date.now();
|
|
464
|
+
// Auto: the container on its default bridge. Sandbox: no network at all (spec P-D7).
|
|
465
|
+
const open = effectiveMode(this.opts.policy(), args.limits) === "auto";
|
|
415
466
|
await this.acquire(open, signal);
|
|
416
467
|
try {
|
|
417
468
|
signal.throwIfAborted();
|
|
@@ -542,14 +593,23 @@ export class DockerExecutor {
|
|
|
542
593
|
child.once("close", () => finish());
|
|
543
594
|
});
|
|
544
595
|
}
|
|
545
|
-
/**
|
|
546
|
-
|
|
596
|
+
/**
|
|
597
|
+
* `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
|
|
598
|
+
* is the boundary); sandbox mode refuses anything outside the mounted roots.
|
|
599
|
+
*/
|
|
600
|
+
containerPath(path, mode) {
|
|
601
|
+
if (mode === "auto") {
|
|
602
|
+
const errors = validateSandboxPathShape(path);
|
|
603
|
+
if (errors.length > 0)
|
|
604
|
+
throw policyError(`${path}: ${errors.join("; ")}`);
|
|
605
|
+
return resolve(path);
|
|
606
|
+
}
|
|
547
607
|
if (!path.startsWith("/"))
|
|
548
608
|
throw policyError(`${path} is not an absolute path`);
|
|
549
609
|
const p = resolve(path);
|
|
550
610
|
const roots = Object.values(ROOTS);
|
|
551
611
|
if (!roots.some((r) => isUnder(p, r))) {
|
|
552
|
-
throw policyError(`${path} is outside the
|
|
612
|
+
throw policyError(`${path} is outside the device's roots (${roots.join(", ")})`);
|
|
553
613
|
}
|
|
554
614
|
return p;
|
|
555
615
|
}
|
|
@@ -561,9 +621,9 @@ export class DockerExecutor {
|
|
|
561
621
|
return isUnder(p, ROOTS.skills);
|
|
562
622
|
}
|
|
563
623
|
/** Runs one file script in the container; `null` for a missing file. */
|
|
564
|
-
async fileOp(script, path, arg2, input) {
|
|
624
|
+
async fileOp(script, mode, path, arg2, input) {
|
|
565
625
|
// A file operation does not need the network; it runs on whichever state the container has.
|
|
566
|
-
await this.serial(() => this.ensureContainer());
|
|
626
|
+
await this.serial(() => this.ensureContainer({ anySpec: true }));
|
|
567
627
|
const r = await docker([
|
|
568
628
|
"exec",
|
|
569
629
|
...(input !== undefined ? ["-i"] : []),
|
|
@@ -576,6 +636,7 @@ export class DockerExecutor {
|
|
|
576
636
|
"-c",
|
|
577
637
|
script,
|
|
578
638
|
"capybara-file",
|
|
639
|
+
mode,
|
|
579
640
|
path,
|
|
580
641
|
arg2,
|
|
581
642
|
], {
|
|
@@ -588,10 +649,12 @@ export class DockerExecutor {
|
|
|
588
649
|
switch (r.code) {
|
|
589
650
|
case 0:
|
|
590
651
|
return r;
|
|
652
|
+
case E_MODE:
|
|
653
|
+
throw new DeviceOpError("policy", `missing or unknown mode for ${path}`);
|
|
591
654
|
case E_MISSING:
|
|
592
655
|
return null;
|
|
593
656
|
case E_OUTSIDE:
|
|
594
|
-
throw policyError(`${path} resolves outside the
|
|
657
|
+
throw policyError(`${path} resolves outside the device's roots`);
|
|
595
658
|
case E_NOT_FILE:
|
|
596
659
|
throw policyError(`${path} is not a regular file`);
|
|
597
660
|
case E_DANGLING:
|
|
@@ -602,10 +665,11 @@ export class DockerExecutor {
|
|
|
602
665
|
}
|
|
603
666
|
}
|
|
604
667
|
async readFile(path, maxBytes) {
|
|
605
|
-
const
|
|
668
|
+
const mode = this.modeNow();
|
|
669
|
+
const p = this.containerPath(path, mode);
|
|
606
670
|
if (this.inSkills(p))
|
|
607
671
|
return this.hostFiles.read(this.skillsHostPath(p), maxBytes);
|
|
608
|
-
const r = await this.fileOp(READ_SCRIPT, p, String(maxBytes + 1));
|
|
672
|
+
const r = await this.fileOp(READ_SCRIPT, mode, p, String(maxBytes + 1));
|
|
609
673
|
if (r === null)
|
|
610
674
|
return null;
|
|
611
675
|
return {
|
|
@@ -614,16 +678,18 @@ export class DockerExecutor {
|
|
|
614
678
|
};
|
|
615
679
|
}
|
|
616
680
|
async writeFile(path, data) {
|
|
617
|
-
const
|
|
681
|
+
const mode = this.modeNow();
|
|
682
|
+
const p = this.containerPath(path, mode);
|
|
618
683
|
if (this.inSkills(p))
|
|
619
684
|
return this.hostFiles.write(this.skillsHostPath(p), data);
|
|
620
|
-
await this.fileOp(WRITE_SCRIPT, p, "", data);
|
|
685
|
+
await this.fileOp(WRITE_SCRIPT, mode, p, "", data);
|
|
621
686
|
}
|
|
622
687
|
async stat(path) {
|
|
623
|
-
const
|
|
688
|
+
const mode = this.modeNow();
|
|
689
|
+
const p = this.containerPath(path, mode);
|
|
624
690
|
if (this.inSkills(p))
|
|
625
691
|
return this.hostFiles.stat(this.skillsHostPath(p));
|
|
626
|
-
const r = await this.fileOp(STAT_SCRIPT, p, "");
|
|
692
|
+
const r = await this.fileOp(STAT_SCRIPT, mode, p, "");
|
|
627
693
|
if (r === null)
|
|
628
694
|
return null;
|
|
629
695
|
const [size, kind] = r.stdout.toString("utf8").split(" ");
|
|
@@ -653,7 +719,7 @@ export class DockerExecutor {
|
|
|
653
719
|
r.killed = true;
|
|
654
720
|
await this.killLeftovers();
|
|
655
721
|
}
|
|
656
|
-
/** Kills every process carrying this
|
|
722
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
657
723
|
async killLeftovers() {
|
|
658
724
|
await this.killScript("", `${this.dirKey}.`);
|
|
659
725
|
}
|
package/dist/exec/fs-helper.d.ts
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The file-operation helper the OS executor runs **inside the sandbox** (`node -e`), so a
|
|
3
|
-
* kernel-side read or write
|
|
4
|
-
*
|
|
5
|
-
*
|
|
3
|
+
* kernel-side read or write never touches the host file system with the program's own privileges:
|
|
4
|
+
* a parent directory swapped for a symlink mid-operation reaches only what any sandboxed command
|
|
5
|
+
* could reach anyway.
|
|
6
6
|
*
|
|
7
|
-
* argv: `<op> <path> <maxBytes> <root
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
7
|
+
* argv: `<mode> <op> <path> <maxBytes> <root>...`, mode `auto` | `sandbox`, op `read` | `stat` |
|
|
8
|
+
* `write` (data on stdin). A missing or unknown mode is refused. In sandbox mode the roots are
|
|
9
|
+
* enforced; in auto mode any clean absolute path is accepted (shape checks: absolute, no `..`
|
|
10
|
+
* segments, no control characters). The `auto` branch is required by this contract but has no
|
|
11
|
+
* production caller today: the OS executor runs the helper in sandbox mode only, and auto mode
|
|
12
|
+
* reads and writes directly through `HostExecutor`. stdout: one JSON object, `{ "r": <result> }`
|
|
13
|
+
* or `{ "e": "policy" | "error", "m": <message> }`. read → `null` | `{ b64, truncated }`; stat →
|
|
14
|
+
* `null` | `{ size, isDir }`; write → `null`. Non-regular files (FIFOs, sockets, devices) are
|
|
15
|
+
* refused without blocking (`O_NONBLOCK`).
|
|
11
16
|
*/
|
|
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
|
|
17
|
+
export declare const FS_HELPER_SCRIPT = "\n(() => {\n const fs = require(\"fs\");\n const path = require(\"path\");\n const C = fs.constants;\n const [mode, 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 device's roots\" });\n // auto mode: any clean absolute path; sandbox mode: one of the roots.\n const shapeOk = () => {\n if (typeof p !== \"string\" || !path.isAbsolute(p)) return false;\n if (/[\\u0000-\\u001f\\u007f]/.test(p)) return false;\n return !p.split(\"/\").some((s) => s === \"..\");\n };\n const allowed = (r) => mode === \"auto\" ? true : under(r);\n try {\n if (mode !== \"auto\" && mode !== \"sandbox\") {\n return out({ e: \"policy\", m: \"missing or unknown mode\" });\n }\n if (mode === \"auto\" && !shapeOk()) {\n return out({ e: \"policy\", m: p + \" is not a clean absolute path\" });\n }\n if (op === \"read\" || op === \"stat\") {\n const r = real(p);\n if (r === null) return out({ r: null });\n if (!allowed(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 || !allowed(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 (!allowed(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 (!allowed(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";
|
package/dist/exec/fs-helper.js
CHANGED
|
@@ -1,31 +1,49 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The file-operation helper the OS executor runs **inside the sandbox** (`node -e`), so a
|
|
3
|
-
* kernel-side read or write
|
|
4
|
-
*
|
|
5
|
-
*
|
|
3
|
+
* kernel-side read or write never touches the host file system with the program's own privileges:
|
|
4
|
+
* a parent directory swapped for a symlink mid-operation reaches only what any sandboxed command
|
|
5
|
+
* could reach anyway.
|
|
6
6
|
*
|
|
7
|
-
* argv: `<op> <path> <maxBytes> <root
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
7
|
+
* argv: `<mode> <op> <path> <maxBytes> <root>...`, mode `auto` | `sandbox`, op `read` | `stat` |
|
|
8
|
+
* `write` (data on stdin). A missing or unknown mode is refused. In sandbox mode the roots are
|
|
9
|
+
* enforced; in auto mode any clean absolute path is accepted (shape checks: absolute, no `..`
|
|
10
|
+
* segments, no control characters). The `auto` branch is required by this contract but has no
|
|
11
|
+
* production caller today: the OS executor runs the helper in sandbox mode only, and auto mode
|
|
12
|
+
* reads and writes directly through `HostExecutor`. stdout: one JSON object, `{ "r": <result> }`
|
|
13
|
+
* or `{ "e": "policy" | "error", "m": <message> }`. read → `null` | `{ b64, truncated }`; stat →
|
|
14
|
+
* `null` | `{ size, isDir }`; write → `null`. Non-regular files (FIFOs, sockets, devices) are
|
|
15
|
+
* refused without blocking (`O_NONBLOCK`).
|
|
11
16
|
*/
|
|
12
17
|
export const FS_HELPER_SCRIPT = `
|
|
13
18
|
(() => {
|
|
14
19
|
const fs = require("fs");
|
|
15
20
|
const path = require("path");
|
|
16
21
|
const C = fs.constants;
|
|
17
|
-
const [op, p, maxS, ...roots] = process.argv.slice(1);
|
|
22
|
+
const [mode, op, p, maxS, ...roots] = process.argv.slice(1);
|
|
18
23
|
const out = (o) => process.stdout.write(JSON.stringify(o));
|
|
19
24
|
const realRoots = roots.map((r) => { try { return fs.realpathSync(r); } catch { return r; } });
|
|
20
25
|
const under = (r) => realRoots.some((x) => r === x || r.startsWith(x + "/"));
|
|
21
26
|
const missing = (e) => e && (e.code === "ENOENT" || e.code === "ENOTDIR");
|
|
22
27
|
const real = (q) => { try { return fs.realpathSync(q); } catch (e) { if (missing(e)) return null; throw e; } };
|
|
23
|
-
const outside = (r) => out({ e: "policy", m: p + " resolves to " + r + ", outside the
|
|
28
|
+
const outside = (r) => out({ e: "policy", m: p + " resolves to " + r + ", outside the device's roots" });
|
|
29
|
+
// auto mode: any clean absolute path; sandbox mode: one of the roots.
|
|
30
|
+
const shapeOk = () => {
|
|
31
|
+
if (typeof p !== "string" || !path.isAbsolute(p)) return false;
|
|
32
|
+
if (/[\\u0000-\\u001f\\u007f]/.test(p)) return false;
|
|
33
|
+
return !p.split("/").some((s) => s === "..");
|
|
34
|
+
};
|
|
35
|
+
const allowed = (r) => mode === "auto" ? true : under(r);
|
|
24
36
|
try {
|
|
37
|
+
if (mode !== "auto" && mode !== "sandbox") {
|
|
38
|
+
return out({ e: "policy", m: "missing or unknown mode" });
|
|
39
|
+
}
|
|
40
|
+
if (mode === "auto" && !shapeOk()) {
|
|
41
|
+
return out({ e: "policy", m: p + " is not a clean absolute path" });
|
|
42
|
+
}
|
|
25
43
|
if (op === "read" || op === "stat") {
|
|
26
44
|
const r = real(p);
|
|
27
45
|
if (r === null) return out({ r: null });
|
|
28
|
-
if (!
|
|
46
|
+
if (!allowed(r)) return outside(r);
|
|
29
47
|
const fd = fs.openSync(r, C.O_RDONLY | C.O_NONBLOCK | C.O_NOFOLLOW);
|
|
30
48
|
try {
|
|
31
49
|
const st = fs.fstatSync(fd);
|
|
@@ -52,18 +70,18 @@ export const FS_HELPER_SCRIPT = `
|
|
|
52
70
|
let anc = parent;
|
|
53
71
|
while (real(anc) === null && anc !== path.dirname(anc)) anc = path.dirname(anc);
|
|
54
72
|
const ra = real(anc);
|
|
55
|
-
if (ra === null || !
|
|
73
|
+
if (ra === null || !allowed(ra)) return outside(ra);
|
|
56
74
|
fs.mkdirSync(parent, { recursive: true });
|
|
57
75
|
const rp = real(parent);
|
|
58
76
|
if (rp === null) return out({ e: "error", m: "cannot create " + parent });
|
|
59
|
-
if (!
|
|
77
|
+
if (!allowed(rp)) return outside(rp);
|
|
60
78
|
let file = path.join(rp, path.basename(p));
|
|
61
79
|
let st = null;
|
|
62
80
|
try { st = fs.lstatSync(file); } catch (e) { if (!missing(e)) throw e; }
|
|
63
81
|
if (st && st.isSymbolicLink()) {
|
|
64
82
|
const r = real(file);
|
|
65
83
|
if (r === null) return out({ e: "policy", m: p + " is a dangling symbolic link" });
|
|
66
|
-
if (!
|
|
84
|
+
if (!allowed(r)) return outside(r);
|
|
67
85
|
file = r;
|
|
68
86
|
}
|
|
69
87
|
const fd = fs.openSync(file, C.O_WRONLY | C.O_CREAT | C.O_NONBLOCK | C.O_NOFOLLOW, 0o644);
|