@capybara-hq/device 0.1.0-rc.18 → 0.1.0-rc.19
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 +65 -33
- package/dist/api.d.ts +3 -3
- package/dist/args.d.ts +8 -3
- package/dist/args.js +27 -14
- package/dist/cli.js +1 -1
- package/dist/client.js +1 -1
- package/dist/commands/ceiling.d.ts +3 -2
- package/dist/commands/ceiling.js +39 -21
- package/dist/commands/login.d.ts +15 -11
- package/dist/commands/login.js +46 -33
- package/dist/commands/policy.js +16 -10
- package/dist/commands/start.d.ts +11 -3
- package/dist/commands/start.js +25 -9
- package/dist/commands/status.js +10 -6
- package/dist/exec/docker-operations.d.ts +14 -2
- package/dist/exec/docker-operations.js +32 -5
- package/dist/exec/linux-agent.d.ts +13 -3
- package/dist/exec/linux-agent.js +450 -43
- package/dist/exec/linux-operation-backend.d.ts +27 -6
- package/dist/exec/linux-operation-backend.js +30 -9
- package/dist/exec/linux-operation-worker.d.ts +51 -3
- package/dist/exec/linux-operation-worker.js +55 -3
- package/dist/exec/linux-runtime.d.ts +3 -2
- package/dist/exec/linux-runtime.js +4 -2
- package/dist/exec/mac-operation-backend.d.ts +7 -2
- package/dist/exec/mac-operation-backend.js +18 -10
- package/dist/exec/mac-write-policy.d.ts +2 -0
- package/dist/exec/mac-write-policy.js +1 -1
- package/dist/exec/operation-types.d.ts +35 -5
- package/dist/exec/operation-types.js +73 -23
- package/dist/exec/operation-worker.d.ts +80 -1
- package/dist/exec/operation-worker.js +197 -14
- package/dist/exec/protected-targets.d.ts +16 -0
- package/dist/exec/protected-targets.js +53 -0
- package/dist/exec/shared.d.ts +7 -3
- package/dist/exec/shared.js +7 -5
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/owner-report.d.ts +1 -1
- package/dist/owner-report.js +5 -4
- package/dist/policy-store.d.ts +2 -1
- package/dist/policy-store.js +2 -1
- package/dist/policy.d.ts +23 -14
- package/dist/policy.js +28 -21
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +30 -5
- package/dist/server-ops.js +105 -85
- package/dist/staged-connect.d.ts +1 -1
- package/dist/staged-connect.js +1 -1
- package/dist/staged-device.d.ts +1 -1
- package/dist/staged-device.js +7 -5
- package/dist/staged-session.d.ts +1 -1
- package/dist/state.d.ts +41 -21
- package/dist/state.js +102 -45
- package/package.json +2 -2
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type LinuxFaultInjection } from "./linux-operation-worker.js";
|
|
1
2
|
import { type LinuxAgentTransport, type LinuxProbe } from "./linux-runtime.js";
|
|
2
3
|
import { type MacBackendDependencies, type MacOperationBackend, type MacOperationBackendOptions } from "./mac-operation-backend.js";
|
|
3
4
|
import { type LocalOperationGrant } from "./operation-types.js";
|
|
@@ -8,8 +9,8 @@ export type LocalOperationBackend = MacOperationBackend;
|
|
|
8
9
|
export interface LinuxBackendDependencies {
|
|
9
10
|
/** How agents start: on this host (default) or in the device's local container. */
|
|
10
11
|
transport?: LinuxAgentTransport;
|
|
11
|
-
/** The environment a command starts from; see {@link
|
|
12
|
-
baseEnv?: (
|
|
12
|
+
/** The environment a command starts from; see {@link hostCommandEnv}. */
|
|
13
|
+
baseEnv?: (escalated: boolean) => Record<string, string>;
|
|
13
14
|
/** Where restricted commands find version managers (default: this process's home and env). */
|
|
14
15
|
toolHome?: {
|
|
15
16
|
home: string;
|
|
@@ -31,11 +32,30 @@ export interface LinuxBackendDependencies {
|
|
|
31
32
|
* addresses, as a conformance fixture's local endpoints need. Production never sets it.
|
|
32
33
|
*/
|
|
33
34
|
allowPrivateProxyTargets?: boolean;
|
|
35
|
+
/** Test seam (trusted construction only): see the worker's `fakeIpDnsTest`. */
|
|
36
|
+
fakeIpDnsTest?: {
|
|
37
|
+
endpoints: string[];
|
|
38
|
+
caPem: string;
|
|
39
|
+
};
|
|
40
|
+
/** Test seam (trusted construction only): see the worker's `faultInjection`. */
|
|
41
|
+
faultInjection?: LinuxFaultInjection;
|
|
34
42
|
/** Called with a reap failure of a lost supervisor's session (default: ignored). */
|
|
35
43
|
onReapError?: (error: unknown) => void;
|
|
36
44
|
}
|
|
37
|
-
/**
|
|
38
|
-
|
|
45
|
+
/**
|
|
46
|
+
* A host command's starting environment (approval-only profiles design, "Fixed denies and the
|
|
47
|
+
* minimal environment"): every sandboxed command, whatever its profile, starts from a fixed set
|
|
48
|
+
* (the worker adds HOME, TMPDIR, the tool homes, the proxy and the call's own variables). An
|
|
49
|
+
* escalated call runs as the owner: this process's environment without the device's own
|
|
50
|
+
* variables (every `CAPYBARA_*`; the device credential lives in its state directory, never in
|
|
51
|
+
* the environment).
|
|
52
|
+
*/
|
|
53
|
+
export declare function hostCommandEnv(escalated: boolean): Record<string, string>;
|
|
54
|
+
/**
|
|
55
|
+
* A host device's files lock (see the worker's `filesLock`): in its state directory, which every
|
|
56
|
+
* restricted grant is denied (`restrictedDeniedReadRoots`) and the launcher refuses inside a root.
|
|
57
|
+
*/
|
|
58
|
+
export declare function hostFilesLock(stateDir: string): string;
|
|
39
59
|
/**
|
|
40
60
|
* Landlock only grants: it cannot hide an owner-denied path (a secret directory, the device's
|
|
41
61
|
* state) inside a granted root, so such an exec grant is refused rather than widened. Native work
|
|
@@ -46,8 +66,9 @@ export declare function checkLinuxRestrictedGrant(grant: LocalOperationGrant, ki
|
|
|
46
66
|
/**
|
|
47
67
|
* The Linux local operation backend (permission activation W2-S): the same functions as the macOS
|
|
48
68
|
* backend on the SDK's restricted Linux runtime. Restricted exec runs through the launcher on
|
|
49
|
-
* pinned root descriptors (Landlock, the seccomp broker), with network none
|
|
50
|
-
* by an operation-owned proxy
|
|
69
|
+
* pinned root descriptors (Landlock, the seccomp broker), with network none, an allowlist or the
|
|
70
|
+
* open public network served by an operation-owned proxy (a loopback listener the command opens is
|
|
71
|
+
* reachable from outside the sandbox only); native work uses the SDK helper on the same kind of pinned
|
|
51
72
|
* descriptors; Full access runs as the OS user without restricted filters. Background work,
|
|
52
73
|
* retained output and exact cancellation share the macOS supervisor. Restricted support is what
|
|
53
74
|
* the launcher's probe reports (an unsupported kernel, ABI or architecture fails closed while Full
|
|
@@ -1,18 +1,33 @@
|
|
|
1
1
|
import { homedir } from "node:os";
|
|
2
|
+
import { join } from "node:path";
|
|
2
3
|
import { SandboxScopeDeniedError } from "@capybara-hq/plugin-sdk";
|
|
3
|
-
import { DEVICE_PROCESS_TOKEN, linuxOperationWorker } from "./linux-operation-worker.js";
|
|
4
|
+
import { DEVICE_PROCESS_TOKEN, linuxOperationWorker, } from "./linux-operation-worker.js";
|
|
4
5
|
import { hostLinuxTransport, probeLinuxRuntime, reapLinuxSession, } from "./linux-runtime.js";
|
|
5
6
|
import { createLocalOperationBackend, createMacOperationBackend, } from "./mac-operation-backend.js";
|
|
6
7
|
import { within } from "./operation-types.js";
|
|
7
|
-
/**
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
8
|
+
/**
|
|
9
|
+
* A host command's starting environment (approval-only profiles design, "Fixed denies and the
|
|
10
|
+
* minimal environment"): every sandboxed command, whatever its profile, starts from a fixed set
|
|
11
|
+
* (the worker adds HOME, TMPDIR, the tool homes, the proxy and the call's own variables). An
|
|
12
|
+
* escalated call runs as the owner: this process's environment without the device's own
|
|
13
|
+
* variables (every `CAPYBARA_*`; the device credential lives in its state directory, never in
|
|
14
|
+
* the environment).
|
|
15
|
+
*/
|
|
16
|
+
export function hostCommandEnv(escalated) {
|
|
17
|
+
if (escalated)
|
|
18
|
+
return Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined && !e[0].startsWith("CAPYBARA_")));
|
|
11
19
|
return {
|
|
12
20
|
PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
|
|
13
21
|
LANG: process.env.LANG ?? "C.UTF-8",
|
|
14
22
|
};
|
|
15
23
|
}
|
|
24
|
+
/**
|
|
25
|
+
* A host device's files lock (see the worker's `filesLock`): in its state directory, which every
|
|
26
|
+
* restricted grant is denied (`restrictedDeniedReadRoots`) and the launcher refuses inside a root.
|
|
27
|
+
*/
|
|
28
|
+
export function hostFilesLock(stateDir) {
|
|
29
|
+
return join(stateDir, "operation-files.lock");
|
|
30
|
+
}
|
|
16
31
|
/**
|
|
17
32
|
* Landlock only grants: it cannot hide an owner-denied path (a secret directory, the device's
|
|
18
33
|
* state) inside a granted root, so such an exec grant is refused rather than widened. Native work
|
|
@@ -30,8 +45,9 @@ export function checkLinuxRestrictedGrant(grant, kind) {
|
|
|
30
45
|
/**
|
|
31
46
|
* The Linux local operation backend (permission activation W2-S): the same functions as the macOS
|
|
32
47
|
* backend on the SDK's restricted Linux runtime. Restricted exec runs through the launcher on
|
|
33
|
-
* pinned root descriptors (Landlock, the seccomp broker), with network none
|
|
34
|
-
* by an operation-owned proxy
|
|
48
|
+
* pinned root descriptors (Landlock, the seccomp broker), with network none, an allowlist or the
|
|
49
|
+
* open public network served by an operation-owned proxy (a loopback listener the command opens is
|
|
50
|
+
* reachable from outside the sandbox only); native work uses the SDK helper on the same kind of pinned
|
|
35
51
|
* descriptors; Full access runs as the OS user without restricted filters. Background work,
|
|
36
52
|
* retained output and exact cancellation share the macOS supervisor. Restricted support is what
|
|
37
53
|
* the launcher's probe reports (an unsupported kernel, ABI or architecture fails closed while Full
|
|
@@ -50,9 +66,12 @@ export async function createLinuxOperationBackend(options, dependencies = {}) {
|
|
|
50
66
|
const startWorker = dependencies.startWorker ??
|
|
51
67
|
linuxOperationWorker({
|
|
52
68
|
transport,
|
|
53
|
-
|
|
69
|
+
filesLock: hostFilesLock(options.stateDir),
|
|
70
|
+
baseEnv: dependencies.baseEnv ?? hostCommandEnv,
|
|
54
71
|
toolHome: dependencies.toolHome ?? { home: homedir(), env: process.env },
|
|
55
72
|
...(dependencies.allowPrivateProxyTargets ? { allowPrivateProxyTargets: true } : {}),
|
|
73
|
+
...(dependencies.fakeIpDnsTest ? { fakeIpDnsTest: dependencies.fakeIpDnsTest } : {}),
|
|
74
|
+
...(dependencies.faultInjection ? { faultInjection: dependencies.faultInjection } : {}),
|
|
56
75
|
...(dependencies.acquireRuntime ? { acquireRuntime: dependencies.acquireRuntime } : {}),
|
|
57
76
|
});
|
|
58
77
|
return createLocalOperationBackend(options, {
|
|
@@ -61,7 +80,9 @@ export async function createLinuxOperationBackend(options, dependencies = {}) {
|
|
|
61
80
|
}, {
|
|
62
81
|
restricted: unavailableReason === undefined,
|
|
63
82
|
...(unavailableReason ? { unavailableReason } : {}),
|
|
64
|
-
|
|
83
|
+
// the operation's forwarder enforces the open public network on the resolved address
|
|
84
|
+
openPublic: true,
|
|
85
|
+
outsideSandbox: probe.agentAvailable !== false,
|
|
65
86
|
background: probe.agentAvailable !== false,
|
|
66
87
|
pending: unavailableReason ?? "Restricted Linux execution is unavailable",
|
|
67
88
|
startWorker,
|
|
@@ -5,10 +5,20 @@ export declare const DEVICE_PROCESS_TOKEN: `${string}-${string}-${string}-${stri
|
|
|
5
5
|
export interface LinuxWorkerOptions {
|
|
6
6
|
transport: LinuxAgentTransport;
|
|
7
7
|
/**
|
|
8
|
-
* The
|
|
9
|
-
*
|
|
8
|
+
* The device's files lock, as the agent sees it: one file per device, outside every sandbox
|
|
9
|
+
* (on a host, in the device's state directory, which restricted work is denied; in the device's
|
|
10
|
+
* container, on its private /dev/shm, which no Landlock rule grants). Every restricted
|
|
11
|
+
* operation's broker, and the agent's own restricted native writes, hold it shared from a
|
|
12
|
+
* write's check to its effect; the broker holds it exclusively for a directory move into a
|
|
13
|
+
* guarded place, so no operation's move can slip between another operation's check and write.
|
|
10
14
|
*/
|
|
11
|
-
|
|
15
|
+
filesLock: string;
|
|
16
|
+
/**
|
|
17
|
+
* The environment a command starts from: an escalated call (outside the sandbox) gets the OS
|
|
18
|
+
* user's own environment without the device's own variables (on the host, this process's minus
|
|
19
|
+
* every `CAPYBARA_*`; in the container, the image's), a sandboxed one only a fixed outer set.
|
|
20
|
+
*/
|
|
21
|
+
baseEnv(escalated: boolean): Record<string, string>;
|
|
12
22
|
/**
|
|
13
23
|
* The OS user's real home and the device process's own environment: a restricted command gets
|
|
14
24
|
* their version manager variables and reads those directories ({@link restrictedToolHomes}).
|
|
@@ -32,7 +42,45 @@ export interface LinuxWorkerOptions {
|
|
|
32
42
|
* addresses, as a conformance fixture's local endpoints need.
|
|
33
43
|
*/
|
|
34
44
|
allowPrivateProxyTargets?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Test seam (trusted construction only): the encrypted DNS a fake-IP answer is re-resolved
|
|
47
|
+
* through (a fixture's DoH endpoint and the certificate it presents) instead of the SDK's
|
|
48
|
+
* `SANDBOX_FAKE_IP_DNS` endpoints, which a test network cannot reach.
|
|
49
|
+
*/
|
|
50
|
+
fakeIpDnsTest?: {
|
|
51
|
+
endpoints: string[];
|
|
52
|
+
caPem: string;
|
|
53
|
+
};
|
|
54
|
+
/**
|
|
55
|
+
* Extra addresses the forwarder closes besides its own host's: a local-Docker device's agents
|
|
56
|
+
* run in a container, whose own addresses are not the host's, so the host's interface addresses
|
|
57
|
+
* (a public one included) are closed explicitly. Read at each operation start.
|
|
58
|
+
*/
|
|
59
|
+
closedAddresses?: () => string[];
|
|
60
|
+
/**
|
|
61
|
+
* Test seam (trusted construction only): faults the launcher injects, so a test can drive a
|
|
62
|
+
* path no real kernel produces on demand (`stagedMove: "fail"`: a guarded directory move whose
|
|
63
|
+
* final rename and move back both fail, which quarantines it and ends the operation;
|
|
64
|
+
* `pauseBeforeMkdir`: a mkdir of that name pauses between its check and its effect).
|
|
65
|
+
*/
|
|
66
|
+
faultInjection?: LinuxFaultInjection;
|
|
35
67
|
}
|
|
68
|
+
/** The launcher's test-only faults; see {@link LinuxWorkerOptions.faultInjection}. */
|
|
69
|
+
export interface LinuxFaultInjection {
|
|
70
|
+
stagedMove?: "fail";
|
|
71
|
+
pauseBeforeMkdir?: string;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The anchored write denies of the protected home locations: each
|
|
75
|
+
* {@link SANDBOX_MANDATORY_WRITE_DENIES} entry under `home` reached through a symbolic link, and
|
|
76
|
+
* each {@link SANDBOX_HOME_WRITE_DENIES} entry (`~/bin`) always, with the target of its link,
|
|
77
|
+
* resolved with the workers' shared {@link protectedChain}: every link on the chain (also with its
|
|
78
|
+
* parent in on-disk form) and each final target. They go to the launcher as absolute denies,
|
|
79
|
+
* resolved once at operation start; the write policy then refuses moving an ancestor of one away,
|
|
80
|
+
* so no hop can be swapped within the operation. A link changed outside the sandbox is seen by the
|
|
81
|
+
* next operation; a dangling link is followed to the location it names.
|
|
82
|
+
*/
|
|
83
|
+
export declare function protectedWriteTargets(home: string): string[];
|
|
36
84
|
/**
|
|
37
85
|
* Starts Linux operations through the trusted agent (on the host or in the device's container),
|
|
38
86
|
* with the same handle semantics as the macOS worker: `ready` once the exact owned identity is
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
|
-
import {
|
|
2
|
+
import { basename, dirname, join } from "node:path";
|
|
3
|
+
import { SANDBOX_HOME_WRITE_DENIES, SANDBOX_MANDATORY_WRITE_DENIES, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
|
|
3
4
|
import { agentLine, reapLinuxSession, } from "./linux-runtime.js";
|
|
4
5
|
import { createCancellationAttempt, } from "./operation-worker.js";
|
|
6
|
+
import { onDisk, protectedChain } from "./protected-targets.js";
|
|
5
7
|
import { acquireSealedRuntime } from "./runtime-source.js";
|
|
6
8
|
import { ENV_NAME_RE, OutputCap, restrictedToolHomes, shellQuote } from "./shared.js";
|
|
7
9
|
/** This device process: a later one reaps sessions recorded under another token. */
|
|
@@ -10,6 +12,37 @@ export const DEVICE_PROCESS_TOKEN = randomUUID();
|
|
|
10
12
|
const FRAME = 65536;
|
|
11
13
|
/** How long an agent may take to end what it owns after a cancel before it is killed. */
|
|
12
14
|
const CANCEL_SETTLE_MS = 15_000;
|
|
15
|
+
/**
|
|
16
|
+
* The anchored write denies of the protected home locations: each
|
|
17
|
+
* {@link SANDBOX_MANDATORY_WRITE_DENIES} entry under `home` reached through a symbolic link, and
|
|
18
|
+
* each {@link SANDBOX_HOME_WRITE_DENIES} entry (`~/bin`) always, with the target of its link,
|
|
19
|
+
* resolved with the workers' shared {@link protectedChain}: every link on the chain (also with its
|
|
20
|
+
* parent in on-disk form) and each final target. They go to the launcher as absolute denies,
|
|
21
|
+
* resolved once at operation start; the write policy then refuses moving an ancestor of one away,
|
|
22
|
+
* so no hop can be swapped within the operation. A link changed outside the sandbox is seen by the
|
|
23
|
+
* next operation; a dangling link is followed to the location it names.
|
|
24
|
+
*/
|
|
25
|
+
export function protectedWriteTargets(home) {
|
|
26
|
+
const out = new Set();
|
|
27
|
+
const add = (location, always) => {
|
|
28
|
+
const chain = protectedChain(location);
|
|
29
|
+
if (always)
|
|
30
|
+
out.add(location);
|
|
31
|
+
if (!always && !chain.links.length)
|
|
32
|
+
return;
|
|
33
|
+
out.add(chain.target);
|
|
34
|
+
for (const link of chain.links) {
|
|
35
|
+
out.add(link);
|
|
36
|
+
out.add(join(onDisk(dirname(link)), basename(link)));
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
for (const entry of SANDBOX_MANDATORY_WRITE_DENIES)
|
|
40
|
+
add(join(home, ...entry), false);
|
|
41
|
+
// the home-anchored entries (`~/bin`) exist nowhere else in the policy: always denied here
|
|
42
|
+
for (const entry of SANDBOX_HOME_WRITE_DENIES)
|
|
43
|
+
add(join(home, ...entry), true);
|
|
44
|
+
return [...out];
|
|
45
|
+
}
|
|
13
46
|
function refusal(event) {
|
|
14
47
|
const message = String(event.message ?? "The operation agent refused the operation");
|
|
15
48
|
switch (event.code) {
|
|
@@ -62,6 +95,10 @@ export function linuxOperationWorker(options) {
|
|
|
62
95
|
const toolHomes = request.kind === "exec" && !request.grant.full && options.toolHome
|
|
63
96
|
? restrictedToolHomes(options.toolHome.home, options.toolHome.env, request.grant.deniedReadRoots)
|
|
64
97
|
: undefined;
|
|
98
|
+
// only on the host: a command in the device's container has the image's home
|
|
99
|
+
const writeDenies = !request.grant.full && options.toolHome
|
|
100
|
+
? protectedWriteTargets(options.toolHome.home)
|
|
101
|
+
: [];
|
|
65
102
|
const roots = request.grant.full
|
|
66
103
|
? {}
|
|
67
104
|
: {
|
|
@@ -69,6 +106,7 @@ export function linuxOperationWorker(options) {
|
|
|
69
106
|
...new Set([...request.grant.readRoots, ...(toolHomes?.readRoots ?? [])]),
|
|
70
107
|
],
|
|
71
108
|
writeRoots: [...request.grant.writeRoots],
|
|
109
|
+
...(writeDenies.length ? { writeDenies } : {}),
|
|
72
110
|
};
|
|
73
111
|
let body;
|
|
74
112
|
let cap;
|
|
@@ -78,6 +116,8 @@ export function linuxOperationWorker(options) {
|
|
|
78
116
|
full: request.grant.full,
|
|
79
117
|
...roots,
|
|
80
118
|
...(request.grant.full ? {} : { denied: [...request.grant.deniedReadRoots] }),
|
|
119
|
+
...(options.faultInjection ? { faultInjection: options.faultInjection } : {}),
|
|
120
|
+
filesLock: options.filesLock,
|
|
81
121
|
native: request.native,
|
|
82
122
|
};
|
|
83
123
|
}
|
|
@@ -99,14 +139,24 @@ export function linuxOperationWorker(options) {
|
|
|
99
139
|
op: "exec",
|
|
100
140
|
full: request.grant.full,
|
|
101
141
|
...roots,
|
|
142
|
+
// the escalated call's own network; the open public network through the forwarder
|
|
143
|
+
// (the closed address classes refused); or exactly the granted hosts
|
|
102
144
|
network: {
|
|
103
|
-
kind: request.grant.full
|
|
104
|
-
|
|
145
|
+
kind: request.grant.full
|
|
146
|
+
? "environment"
|
|
147
|
+
: request.grant.openNetwork
|
|
148
|
+
? "open"
|
|
149
|
+
: "allowlist",
|
|
150
|
+
hosts: request.grant.openNetwork ? [] : [...request.grant.hosts],
|
|
105
151
|
},
|
|
106
152
|
// single read-only files (a global version pin); the agent grants each exactly
|
|
107
153
|
...(toolHomes?.readFiles.length ? { readFiles: toolHomes.readFiles } : {}),
|
|
108
154
|
// background output is one merged stream; its stderr is the launcher's diagnostics
|
|
109
155
|
...(options.allowPrivateProxyTargets ? { allowPrivate: true } : {}),
|
|
156
|
+
...(options.fakeIpDnsTest ? { dohTest: options.fakeIpDnsTest } : {}),
|
|
157
|
+
...(options.closedAddresses ? { closedAddresses: options.closedAddresses() } : {}),
|
|
158
|
+
...(options.faultInjection ? { faultInjection: options.faultInjection } : {}),
|
|
159
|
+
filesLock: options.filesLock,
|
|
110
160
|
command: request.managedOutput
|
|
111
161
|
? `exec /bin/bash -c ${shellQuote(args.command)} 2>&1`
|
|
112
162
|
: args.command,
|
|
@@ -241,6 +291,8 @@ export function linuxOperationWorker(options) {
|
|
|
241
291
|
}
|
|
242
292
|
return response?.result ?? null;
|
|
243
293
|
}
|
|
294
|
+
if (typeof result.fatal === "string")
|
|
295
|
+
throw new Error(`The restricted launcher ended the operation: ${result.fatal}`);
|
|
244
296
|
if (result.supervisorLost === true && !cancelled)
|
|
245
297
|
throw new Error("The restricted launcher was lost; its owned session was ended");
|
|
246
298
|
const timedOut = result.timedOut === true;
|
|
@@ -75,6 +75,7 @@ export declare function reapLinuxSession(transport: LinuxAgentTransport, session
|
|
|
75
75
|
* A functional self-check of restricted execution on `root` (an existing directory the device
|
|
76
76
|
* user owns): a restricted command must list it and create and remove a file in it. Landlock
|
|
77
77
|
* rules attach to inodes, and some file systems (Docker Desktop's file sharing, for one) do not
|
|
78
|
-
* keep them, which would deny every restricted operation there.
|
|
78
|
+
* keep them, which would deny every restricted operation there. `filesLock` is the device's files
|
|
79
|
+
* lock, which every restricted launch takes. Returns why it failed, or null.
|
|
79
80
|
*/
|
|
80
|
-
export declare function checkRestrictedRoot(transport: LinuxAgentTransport, root: string, env: Record<string, string
|
|
81
|
+
export declare function checkRestrictedRoot(transport: LinuxAgentTransport, root: string, env: Record<string, string>, filesLock: string): Promise<string | null>;
|
|
@@ -155,9 +155,10 @@ export async function reapLinuxSession(transport, session, options = {}) {
|
|
|
155
155
|
* A functional self-check of restricted execution on `root` (an existing directory the device
|
|
156
156
|
* user owns): a restricted command must list it and create and remove a file in it. Landlock
|
|
157
157
|
* rules attach to inodes, and some file systems (Docker Desktop's file sharing, for one) do not
|
|
158
|
-
* keep them, which would deny every restricted operation there.
|
|
158
|
+
* keep them, which would deny every restricted operation there. `filesLock` is the device's files
|
|
159
|
+
* lock, which every restricted launch takes. Returns why it failed, or null.
|
|
159
160
|
*/
|
|
160
|
-
export async function checkRestrictedRoot(transport, root, env) {
|
|
161
|
+
export async function checkRestrictedRoot(transport, root, env, filesLock) {
|
|
161
162
|
const name = `.capybara-restricted-check-${randomUUID()}`;
|
|
162
163
|
try {
|
|
163
164
|
const event = await agentRequest(transport, {
|
|
@@ -170,6 +171,7 @@ export async function checkRestrictedRoot(transport, root, env) {
|
|
|
170
171
|
cwd: root,
|
|
171
172
|
env,
|
|
172
173
|
timeoutMs: 20_000,
|
|
174
|
+
filesLock,
|
|
173
175
|
}, "exit", 60_000, true);
|
|
174
176
|
return event.exitCode === 0
|
|
175
177
|
? null
|
|
@@ -83,8 +83,13 @@ export interface LocalBackendHost {
|
|
|
83
83
|
restricted: boolean;
|
|
84
84
|
/** Why restricted operations are unavailable, when they are. */
|
|
85
85
|
unavailableReason?: string;
|
|
86
|
-
/**
|
|
87
|
-
|
|
86
|
+
/**
|
|
87
|
+
* Restricted operations enforce the open public network (the closed address classes refused on
|
|
88
|
+
* the resolved address); reported only while restricted operations run.
|
|
89
|
+
*/
|
|
90
|
+
openPublic?: boolean;
|
|
91
|
+
/** Escalated calls (outside the sandbox) and background work run on this platform. */
|
|
92
|
+
outsideSandbox: boolean;
|
|
88
93
|
background: boolean;
|
|
89
94
|
/** The message a refused restricted operation carries. */
|
|
90
95
|
pending: string;
|
|
@@ -3,7 +3,7 @@ import { resolve } from "node:path";
|
|
|
3
3
|
import { parseSandboxBrowseScope, parseSandboxOperationScope, parseSandboxPreparationScope, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
|
|
4
4
|
import { implicitWritePaths } from "../policy.js";
|
|
5
5
|
import { MacOperationSupervisor, } from "./operation-supervisor.js";
|
|
6
|
-
import { checkRoots, digest, freezeAuthority, intersectOperation, within, } from "./operation-types.js";
|
|
6
|
+
import { checkRoots, digest, freezeAuthority, grantStillHolds, intersectOperation, within, } from "./operation-types.js";
|
|
7
7
|
import { timed } from "./transfer-timing.js";
|
|
8
8
|
const PENDING = "Restricted macOS per-instance validation and coordinated policy/background activation are pending";
|
|
9
9
|
export async function createMacOperationBackend(options, dependencies = {}) {
|
|
@@ -21,8 +21,10 @@ export async function createMacOperationBackend(options, dependencies = {}) {
|
|
|
21
21
|
: "Restricted Linux/local-Docker validation remains pending"),
|
|
22
22
|
}
|
|
23
23
|
: {}),
|
|
24
|
-
|
|
24
|
+
outsideSandbox: platform === "darwin",
|
|
25
25
|
background: platform === "darwin",
|
|
26
|
+
// the macOS worker's proxy decides the open network on the resolved address (operation-worker)
|
|
27
|
+
openPublic: platform === "darwin",
|
|
26
28
|
pending: (!restricted && dependencies.unavailableReason) || PENDING,
|
|
27
29
|
...(dependencies.startWorker ? { startWorker: dependencies.startWorker } : {}),
|
|
28
30
|
...(restricted && dependencies.restrictedProof ? { proof: dependencies.restrictedProof } : {}),
|
|
@@ -307,14 +309,24 @@ export async function createLocalOperationBackend(options, dependencies, host) {
|
|
|
307
309
|
signal.throwIfAborted();
|
|
308
310
|
// a transiently failed proof is retried before it is reported (rate-limited, bounded)
|
|
309
311
|
await host.proof?.refresh();
|
|
310
|
-
|
|
312
|
+
// the owner policy is still read (and checked) here; its outside-sandbox switch is consent,
|
|
313
|
+
// reported in the owner report, never runtime support
|
|
314
|
+
await read();
|
|
311
315
|
const restricted = restrictedNow();
|
|
316
|
+
// an operation boundary: the sandbox network (the open public internet decided on the
|
|
317
|
+
// resolved address, or the allowlist with per-operation hosts) only with restricted support
|
|
312
318
|
return {
|
|
313
|
-
version:
|
|
319
|
+
version: 2,
|
|
320
|
+
boundary: "operation",
|
|
314
321
|
restricted: restricted
|
|
315
322
|
? { filesystem: true, network: true, native: true, concurrentScopes: true }
|
|
316
323
|
: null,
|
|
317
|
-
|
|
324
|
+
network: {
|
|
325
|
+
openPublic: restricted && host.openPublic === true,
|
|
326
|
+
allowlist: restricted,
|
|
327
|
+
perOperationHosts: restricted,
|
|
328
|
+
},
|
|
329
|
+
outsideSandbox: host.outsideSandbox,
|
|
318
330
|
background: host.background,
|
|
319
331
|
...(!restricted
|
|
320
332
|
? { unavailableReason: host.proof?.failure() ?? host.unavailableReason ?? host.pending }
|
|
@@ -374,11 +386,7 @@ export async function createLocalOperationBackend(options, dependencies, host) {
|
|
|
374
386
|
const next = "profile" in record.scope
|
|
375
387
|
? intersectOperation(record.scope, ceiling, record.authority, record.kind === "native")
|
|
376
388
|
: auxiliaryGrant(record.scope, ceiling);
|
|
377
|
-
return record.grant
|
|
378
|
-
? next.full
|
|
379
|
-
: record.grant.hosts.every((h) => next.hosts.includes(h)) &&
|
|
380
|
-
record.grant.deniedReadRoots.every((r) => next.deniedReadRoots.includes(r)) &&
|
|
381
|
-
next.deniedReadRoots.every((r) => record.grant.deniedReadRoots.includes(r));
|
|
389
|
+
return grantStillHolds(record.grant, next);
|
|
382
390
|
}
|
|
383
391
|
catch {
|
|
384
392
|
return false;
|
|
@@ -4,6 +4,8 @@ export interface MacWriteRegexRule {
|
|
|
4
4
|
operations: ("file-write*" | "file-write-unlink" | "file-write-create")[];
|
|
5
5
|
regex: string;
|
|
6
6
|
}
|
|
7
|
+
/** A literal name as a regex, every letter matched in either case (APFS is case-insensitive). */
|
|
8
|
+
export declare function ci(name: string): string;
|
|
7
9
|
/**
|
|
8
10
|
* The shared SDK write policy as ordered SBPL regex rules for one write root (or, with "", any
|
|
9
11
|
* path), appended after every other write rule; Seatbelt is last-match-wins, so a later rule
|
|
@@ -3,7 +3,7 @@ import { basename, dirname, join } from "node:path";
|
|
|
3
3
|
import { SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_MANDATORY_WRITE_DENIES, } from "@capybara-hq/plugin-sdk";
|
|
4
4
|
const META = /[\\^$.|?*+()[\]{}]/g;
|
|
5
5
|
/** A literal name as a regex, every letter matched in either case (APFS is case-insensitive). */
|
|
6
|
-
function ci(name) {
|
|
6
|
+
export function ci(name) {
|
|
7
7
|
let out = "";
|
|
8
8
|
for (const ch of name) {
|
|
9
9
|
const lower = ch.toLowerCase();
|
|
@@ -1,16 +1,23 @@
|
|
|
1
|
-
import { type DeviceExecGrants, type SandboxLimits, type SandboxOperationScope, type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
1
|
+
import { type DeviceExecGrants, type DeviceNetworkMode, type SandboxLimits, type SandboxOperationScope, type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
/**
|
|
3
|
+
* The owner ceiling as this program enforces it: the fields of the protocol's
|
|
4
|
+
* `DeviceOwnerCeiling` (the device sandbox for every profile) plus the local facts the
|
|
5
|
+
* intersection needs (roots, denied read roots, preparation roots).
|
|
6
|
+
*/
|
|
2
7
|
export interface DeviceOwnerCeiling {
|
|
3
8
|
readonly revision: string;
|
|
4
|
-
|
|
9
|
+
/** Whether a call may be granted escalation outside the sandbox (device + environment). */
|
|
10
|
+
readonly outsideSandbox: boolean;
|
|
11
|
+
/** The sandbox network: the open public internet or the {@link allowedDomains} allowlist. */
|
|
12
|
+
readonly network: DeviceNetworkMode;
|
|
13
|
+
readonly allowedDomains: readonly string[];
|
|
5
14
|
readonly roots: Readonly<SandboxRoots>;
|
|
6
15
|
readonly restrictedProjectReach: "workspace" | "os-user";
|
|
7
|
-
readonly restrictedAllowedDomains: readonly string[];
|
|
8
16
|
readonly restrictedDeniedReadRoots: readonly string[];
|
|
9
17
|
readonly preparation: Readonly<{
|
|
10
18
|
skillsRoot: string;
|
|
11
19
|
attachmentsBase: string;
|
|
12
20
|
}>;
|
|
13
|
-
readonly fullNetwork: "environment";
|
|
14
21
|
}
|
|
15
22
|
export interface LocalExecAuthority {
|
|
16
23
|
readonly operationId: string;
|
|
@@ -18,7 +25,14 @@ export interface LocalExecAuthority {
|
|
|
18
25
|
readonly grants?: DeviceExecGrants;
|
|
19
26
|
}
|
|
20
27
|
export interface LocalOperationGrant {
|
|
28
|
+
/** Only an escalated call (device + environment): it runs outside the sandbox. */
|
|
21
29
|
readonly full: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* A sandboxed command may reach the open public internet (the address classes the design closes
|
|
32
|
+
* stay closed). Absent or false: exactly {@link hosts}, so a grant that does not say otherwise
|
|
33
|
+
* fails closed. Never set on a {@link full} grant, which has the escalated call's own network.
|
|
34
|
+
*/
|
|
35
|
+
readonly openNetwork?: boolean;
|
|
22
36
|
readonly readRoots: readonly string[];
|
|
23
37
|
readonly writeRoots: readonly string[];
|
|
24
38
|
readonly hosts: readonly string[];
|
|
@@ -36,7 +50,7 @@ export declare function readStrictOwnerCeiling(input: {
|
|
|
36
50
|
}): Promise<DeviceOwnerCeiling>;
|
|
37
51
|
/**
|
|
38
52
|
* {@link readStrictOwnerCeiling}, synchronously (the owner report issues it under the policy lock).
|
|
39
|
-
* Only a version-
|
|
53
|
+
* Only a version-3 policy file is authority: an old format is refused until it is converted.
|
|
40
54
|
*/
|
|
41
55
|
export declare function readStrictOwnerCeilingSync(input: {
|
|
42
56
|
stateDir: string;
|
|
@@ -52,4 +66,20 @@ export declare function readStrictOwnerCeilingSync(input: {
|
|
|
52
66
|
export declare function withCanonicalForms(paths: readonly string[]): string[];
|
|
53
67
|
export declare function checkRoots(read: readonly string[], write: readonly string[], ceiling: DeviceOwnerCeiling, preparation?: boolean): void;
|
|
54
68
|
export declare function freezeAuthority(a: LocalExecAuthority): LocalExecAuthority;
|
|
69
|
+
/** The refusal of an escalated call the owner ceiling does not allow. */
|
|
70
|
+
export declare const OUTSIDE_SANDBOX_REFUSAL: string;
|
|
71
|
+
/**
|
|
72
|
+
* One operation's scope intersected with the owner ceiling now (approval-only profiles design).
|
|
73
|
+
* Every profile's ordinary call is sandboxed: scoped roots, the owner's denied read roots and the
|
|
74
|
+
* sandbox network. Only an escalated call (`filesystem: device` with `network: environment`) runs
|
|
75
|
+
* outside the sandbox, and only while the owner ceiling allows `outsideSandbox`. The profile in the
|
|
76
|
+
* scope is audit only: it never widens anything here.
|
|
77
|
+
*/
|
|
55
78
|
export declare function intersectOperation(scope: SandboxOperationScope, ceiling: DeviceOwnerCeiling, authority?: LocalExecAuthority, native?: boolean): LocalOperationGrant;
|
|
79
|
+
/**
|
|
80
|
+
* Whether a live operation's grant still holds against the grant the fresh owner ceiling gives the
|
|
81
|
+
* same scope (owner reconcile): a full grant only while the next one is full; a sandboxed grant
|
|
82
|
+
* only while every host, the open network if it had one, and exactly the same denied read roots
|
|
83
|
+
* remain. Anything narrower revokes the operation.
|
|
84
|
+
*/
|
|
85
|
+
export declare function grantStillHolds(grant: LocalOperationGrant, next: LocalOperationGrant): boolean;
|