@capybara-hq/device 0.1.0-rc.3 → 0.1.0-rc.5
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 +13 -0
- package/dist/client.js +72 -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 +190 -15
- package/dist/exec/shared.d.ts +44 -0
- package/dist/exec/shared.js +210 -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/network.js
ADDED
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
import { isIP } from "node:net";
|
|
2
|
+
import { validateAllowHost } from "@capybara-hq/plugin-sdk";
|
|
3
|
+
import { covers, deviceHosts, deviceTier, provisionalTier } from "./policy.js";
|
|
4
|
+
/** At most this many blocked hosts are reported per command. */
|
|
5
|
+
export const MAX_BLOCKED_HOSTS = 20;
|
|
6
|
+
// The proxy's line in @anthropic-ai/sandbox-runtime 0.0.81 (`recordOutboundDeny`):
|
|
7
|
+
// `deny network-outbound <host>:<port> (<reason>)`. Pinned by test/network.test.ts.
|
|
8
|
+
const OUTBOUND_DENY = /^deny network-outbound (\S+) \((.*)\)$/;
|
|
9
|
+
/**
|
|
10
|
+
* Parses one sandbox-runtime 0.0.81 violation line `deny network-outbound <host>:<port> (<reason>)`;
|
|
11
|
+
* undefined for other lines. IPv6 hosts arrive bracketed and are returned without the brackets.
|
|
12
|
+
*/
|
|
13
|
+
export function parseNetworkViolation(line) {
|
|
14
|
+
const m = OUTBOUND_DENY.exec(line.trim());
|
|
15
|
+
if (m === null)
|
|
16
|
+
return undefined;
|
|
17
|
+
const target = m[1];
|
|
18
|
+
const reason = m[2];
|
|
19
|
+
let host;
|
|
20
|
+
let portText;
|
|
21
|
+
const bracketed = /^\[([^\]]+)\]:(\d+)$/.exec(target);
|
|
22
|
+
if (bracketed !== null) {
|
|
23
|
+
host = bracketed[1];
|
|
24
|
+
portText = bracketed[2];
|
|
25
|
+
}
|
|
26
|
+
else {
|
|
27
|
+
// The SOCKS path writes IPv6 unbracketed: the port follows the last colon.
|
|
28
|
+
const at = target.lastIndexOf(":");
|
|
29
|
+
if (at <= 0)
|
|
30
|
+
return undefined;
|
|
31
|
+
host = target.slice(0, at);
|
|
32
|
+
portText = target.slice(at + 1);
|
|
33
|
+
if (host.includes(":") && isIP(host) !== 6)
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
|
36
|
+
if (!/^\d+$/.test(portText))
|
|
37
|
+
return undefined;
|
|
38
|
+
const port = Number(portText);
|
|
39
|
+
if (port > 65535)
|
|
40
|
+
return undefined;
|
|
41
|
+
return { host: normalizeHost(host), port, reason };
|
|
42
|
+
}
|
|
43
|
+
/** Lowercase, without the trailing dot of a fully qualified name. */
|
|
44
|
+
function normalizeHost(host) {
|
|
45
|
+
const h = host.toLowerCase();
|
|
46
|
+
return h.endsWith(".") ? h.slice(0, -1) : h;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Whether `host` is a public DNS name a command may reach when nothing narrows it (device and org
|
|
50
|
+
* both open): never an IP literal, a single-label or internal name, or a wildcard.
|
|
51
|
+
*/
|
|
52
|
+
export function isPublicName(host) {
|
|
53
|
+
const h = normalizeHost(host);
|
|
54
|
+
return !h.startsWith("*") && validateAllowHost(h).length === 0;
|
|
55
|
+
}
|
|
56
|
+
function admittedBy(list, host) {
|
|
57
|
+
return list.some((p) => covers(p.toLowerCase(), host));
|
|
58
|
+
}
|
|
59
|
+
/** IP literals, single-label and internal names: the runtime's guard refuses them for good. */
|
|
60
|
+
function isAddress(host, reason) {
|
|
61
|
+
return reason.startsWith("resolved to ") || validateAllowHost(host).length > 0;
|
|
62
|
+
}
|
|
63
|
+
function orgAllows(host, limits) {
|
|
64
|
+
if (limits.egress === "none")
|
|
65
|
+
return false;
|
|
66
|
+
if (limits.egress === "open")
|
|
67
|
+
return true;
|
|
68
|
+
return admittedBy(limits.allowHosts, host);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Whether the device's own tier admits `host` (spec §4.2): `open` admits every host, `dev` its
|
|
72
|
+
* `allowedDomains` and the dev hosts, `strict` its `allowedDomains`. Without limits (nothing run
|
|
73
|
+
* yet) the owner's choice, else `dev`, stands with no dev hosts known.
|
|
74
|
+
*/
|
|
75
|
+
function deviceAllows(host, policy, limits) {
|
|
76
|
+
const tier = limits === undefined ? provisionalTier(policy) : deviceTier(policy, limits);
|
|
77
|
+
const list = deviceHosts(policy, tier, limits?.devHosts ?? []);
|
|
78
|
+
return list === undefined || admittedBy(list, host);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The layer that refused `host`: `address` (an IP literal, a name `validateAllowHost` refuses, or
|
|
82
|
+
* a resolved-address reason), `org` (not in the org's effective egress, or egress none; also when
|
|
83
|
+
* the device lacks it too), `device` (the org allows it, the local policy does not), else `unknown`.
|
|
84
|
+
*/
|
|
85
|
+
export function classifyHost(host, reason, limits, policy) {
|
|
86
|
+
const h = normalizeHost(host);
|
|
87
|
+
if (isAddress(h, reason))
|
|
88
|
+
return "address";
|
|
89
|
+
if (!orgAllows(h, limits))
|
|
90
|
+
return "org";
|
|
91
|
+
if (!deviceAllows(h, policy, limits))
|
|
92
|
+
return "device";
|
|
93
|
+
return "unknown";
|
|
94
|
+
}
|
|
95
|
+
/** The refused hosts in `lines`, deduped by host (first port kept), at most {@link MAX_BLOCKED_HOSTS}. */
|
|
96
|
+
export function blockedHosts(lines, limits, policy) {
|
|
97
|
+
const out = new Map();
|
|
98
|
+
for (const line of lines) {
|
|
99
|
+
if (out.size >= MAX_BLOCKED_HOSTS)
|
|
100
|
+
break;
|
|
101
|
+
const v = parseNetworkViolation(line);
|
|
102
|
+
if (v === undefined || out.has(v.host))
|
|
103
|
+
continue;
|
|
104
|
+
out.set(v.host, {
|
|
105
|
+
host: v.host,
|
|
106
|
+
port: v.port,
|
|
107
|
+
layer: classifyHost(v.host, v.reason, limits, policy),
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
return [...out.values()];
|
|
111
|
+
}
|
|
112
|
+
function target(b) {
|
|
113
|
+
return b.host.includes(":") ? `[${b.host}]:${b.port}` : `${b.host}:${b.port}`;
|
|
114
|
+
}
|
|
115
|
+
function explain(b) {
|
|
116
|
+
switch (b.layer) {
|
|
117
|
+
case "device":
|
|
118
|
+
return ("not in this device's allowed domains. Only the device owner can allow it " +
|
|
119
|
+
`(capybara-device policy add allowedDomains ${b.host}, or the device page).`);
|
|
120
|
+
case "org":
|
|
121
|
+
return "not in the organization's network allowlist. Only an organization admin can add it.";
|
|
122
|
+
case "address":
|
|
123
|
+
return "a private or local address; commands can never reach it.";
|
|
124
|
+
case "unknown":
|
|
125
|
+
return "refused by the sandbox's network proxy.";
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/** The stderr trailer of spec §9.2 (English, model-visible); "" for an empty list. */
|
|
129
|
+
export function networkTrailer(blocked) {
|
|
130
|
+
if (blocked.length === 0)
|
|
131
|
+
return "";
|
|
132
|
+
return [
|
|
133
|
+
"[capybara-device] Network access was blocked:",
|
|
134
|
+
...blocked.slice(0, MAX_BLOCKED_HOSTS).map((b) => `- ${target(b)}: ${explain(b)}`),
|
|
135
|
+
].join("\n");
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The reason the sandbox's ask callback answers (spec §9.1). The callback has no command id, so
|
|
139
|
+
* `limits` are the last ones seen (a device belongs to one org); without any, the org layer is
|
|
140
|
+
* not judged.
|
|
141
|
+
*/
|
|
142
|
+
export function denyReason(host, limits, policy) {
|
|
143
|
+
const h = normalizeHost(host);
|
|
144
|
+
let layer;
|
|
145
|
+
if (limits !== undefined)
|
|
146
|
+
layer = classifyHost(h, "", limits, policy);
|
|
147
|
+
else if (isAddress(h, ""))
|
|
148
|
+
layer = "address";
|
|
149
|
+
else
|
|
150
|
+
layer = deviceAllows(h, policy, undefined) ? "unknown" : "device";
|
|
151
|
+
switch (layer) {
|
|
152
|
+
case "device":
|
|
153
|
+
return `capybara: ${host} is not in this device's allowed domains`;
|
|
154
|
+
case "org":
|
|
155
|
+
return `capybara: ${host} is not in the organization's network allowlist`;
|
|
156
|
+
case "address":
|
|
157
|
+
return `capybara: ${host} is a private or local address`;
|
|
158
|
+
case "unknown":
|
|
159
|
+
return `capybara: ${host} is not allowed by the network policy`;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { type Policy } from "./state.js";
|
|
2
|
+
/**
|
|
3
|
+
* The device's local policy as the running program sees it. Commands read {@link current} at
|
|
4
|
+
* each exec, so a change applies at the next command without a restart, whether this program
|
|
5
|
+
* wrote it ({@link update}) or someone ran `capybara-device policy` meanwhile. Each new version
|
|
6
|
+
* is a new object, so a reader can tell a reload by identity (the OS executor reruns its
|
|
7
|
+
* localhost proxy guard then).
|
|
8
|
+
*/
|
|
9
|
+
export declare class PolicyStore {
|
|
10
|
+
private readonly dir;
|
|
11
|
+
private policy;
|
|
12
|
+
private version;
|
|
13
|
+
/** The broken version last reported, so each one is reported once. */
|
|
14
|
+
private reportedBad;
|
|
15
|
+
private readonly file;
|
|
16
|
+
private readonly err;
|
|
17
|
+
/**
|
|
18
|
+
* policy.json had the legacy `network: "open"` when the store was made (start prints a notice;
|
|
19
|
+
* the key is dropped at the next write).
|
|
20
|
+
*/
|
|
21
|
+
readonly legacyNetworkOpen: boolean;
|
|
22
|
+
constructor(dir: string, opts?: {
|
|
23
|
+
err?: (line: string) => void;
|
|
24
|
+
initial?: Policy;
|
|
25
|
+
});
|
|
26
|
+
/**
|
|
27
|
+
* The policy now: re-reads policy.json when it changed (or appeared, or vanished: defaults).
|
|
28
|
+
* An invalid file keeps the last good policy, never a looser one, with the sandbox turned back
|
|
29
|
+
* on (a broken file never keeps commands running unsandboxed), and is reported once per version.
|
|
30
|
+
*/
|
|
31
|
+
current(): Policy;
|
|
32
|
+
/**
|
|
33
|
+
* Read-modify-write under policy.json.lock: reads the file (throws on an invalid one rather
|
|
34
|
+
* than overwrite it), writes the change atomically keeping unknown keys, and swaps the
|
|
35
|
+
* in-memory policy. Returns the new policy.
|
|
36
|
+
*/
|
|
37
|
+
update(change: (p: Policy) => Policy): Policy;
|
|
38
|
+
}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import { statSync } from "node:fs";
|
|
2
|
+
import { policyPath, readPolicyFile, withPolicyLock, writePolicy } from "./state.js";
|
|
3
|
+
/** What identifies one version of policy.json: absent, or its inode, size and mtime. */
|
|
4
|
+
function versionOf(file) {
|
|
5
|
+
try {
|
|
6
|
+
const st = statSync(file);
|
|
7
|
+
// An atomic write (rename) changes the inode; an in-place edit changes size or mtime.
|
|
8
|
+
return `${st.ino}:${st.size}:${st.mtimeMs}`;
|
|
9
|
+
}
|
|
10
|
+
catch {
|
|
11
|
+
return "absent";
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* The device's local policy as the running program sees it. Commands read {@link current} at
|
|
16
|
+
* each exec, so a change applies at the next command without a restart, whether this program
|
|
17
|
+
* wrote it ({@link update}) or someone ran `capybara-device policy` meanwhile. Each new version
|
|
18
|
+
* is a new object, so a reader can tell a reload by identity (the OS executor reruns its
|
|
19
|
+
* localhost proxy guard then).
|
|
20
|
+
*/
|
|
21
|
+
export class PolicyStore {
|
|
22
|
+
dir;
|
|
23
|
+
policy;
|
|
24
|
+
version;
|
|
25
|
+
/** The broken version last reported, so each one is reported once. */
|
|
26
|
+
reportedBad;
|
|
27
|
+
file;
|
|
28
|
+
err;
|
|
29
|
+
/**
|
|
30
|
+
* policy.json had the legacy `network: "open"` when the store was made (start prints a notice;
|
|
31
|
+
* the key is dropped at the next write).
|
|
32
|
+
*/
|
|
33
|
+
legacyNetworkOpen;
|
|
34
|
+
constructor(dir, opts = {}) {
|
|
35
|
+
this.dir = dir;
|
|
36
|
+
this.file = policyPath(dir);
|
|
37
|
+
this.err = opts.err ?? (() => { });
|
|
38
|
+
this.version = versionOf(this.file);
|
|
39
|
+
// Without an initial policy, an unreadable file throws here: the program does not start.
|
|
40
|
+
if (opts.initial !== undefined) {
|
|
41
|
+
this.policy = opts.initial;
|
|
42
|
+
this.legacyNetworkOpen = false;
|
|
43
|
+
}
|
|
44
|
+
else {
|
|
45
|
+
const read = readPolicyFile(dir);
|
|
46
|
+
this.policy = read.policy;
|
|
47
|
+
this.legacyNetworkOpen = read.legacyNetworkOpen;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* The policy now: re-reads policy.json when it changed (or appeared, or vanished: defaults).
|
|
52
|
+
* An invalid file keeps the last good policy, never a looser one, with the sandbox turned back
|
|
53
|
+
* on (a broken file never keeps commands running unsandboxed), and is reported once per version.
|
|
54
|
+
*/
|
|
55
|
+
current() {
|
|
56
|
+
const version = versionOf(this.file);
|
|
57
|
+
if (version === this.version)
|
|
58
|
+
return this.policy;
|
|
59
|
+
try {
|
|
60
|
+
this.policy = readPolicyFile(this.dir).policy;
|
|
61
|
+
// Advanced only on a good read: a broken version is retried until it is fixed.
|
|
62
|
+
this.version = version;
|
|
63
|
+
this.reportedBad = undefined;
|
|
64
|
+
}
|
|
65
|
+
catch (e) {
|
|
66
|
+
// A new object only when it narrows: readers tell a reload by identity.
|
|
67
|
+
if (this.policy.isolation === "none")
|
|
68
|
+
this.policy = { ...this.policy, isolation: "sandbox" };
|
|
69
|
+
if (this.reportedBad !== version) {
|
|
70
|
+
this.reportedBad = version;
|
|
71
|
+
this.err(`${e.message}; keeping the last valid policy with the sandbox on until the ` +
|
|
72
|
+
"file is fixed");
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
return this.policy;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Read-modify-write under policy.json.lock: reads the file (throws on an invalid one rather
|
|
79
|
+
* than overwrite it), writes the change atomically keeping unknown keys, and swaps the
|
|
80
|
+
* in-memory policy. Returns the new policy.
|
|
81
|
+
*/
|
|
82
|
+
update(change) {
|
|
83
|
+
return withPolicyLock(this.dir, () => {
|
|
84
|
+
const { policy, extra } = readPolicyFile(this.dir);
|
|
85
|
+
const next = change(policy);
|
|
86
|
+
writePolicy(this.dir, next, extra);
|
|
87
|
+
this.policy = next;
|
|
88
|
+
this.version = versionOf(this.file);
|
|
89
|
+
return next;
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
}
|
package/dist/policy.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
|
|
2
2
|
import type { Policy } from "./state.js";
|
|
3
3
|
/**
|
|
4
4
|
* Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
@@ -14,11 +14,76 @@ export declare function deniedSecretPaths(home?: string): string[];
|
|
|
14
14
|
* convenience directories). They lie outside the device directory, so they are denied.
|
|
15
15
|
*/
|
|
16
16
|
export declare function implicitWritePaths(home?: string): string[];
|
|
17
|
+
/** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
|
|
18
|
+
export declare function covers(pattern: string, host: string): boolean;
|
|
17
19
|
/**
|
|
18
|
-
* The
|
|
19
|
-
*
|
|
20
|
+
* The entry {@link effectiveEgress} returns when a command may reach any public host (the device
|
|
21
|
+
* is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
|
|
22
|
+
* per-command list, so the OS executor never registers it: its ask callback allows instead.
|
|
20
23
|
*/
|
|
21
|
-
export declare
|
|
24
|
+
export declare const ANY_HOST = "*";
|
|
25
|
+
/** The tier fields of an exec's limits: the org's ceiling and its default. */
|
|
26
|
+
export type TierLimits = Pick<SandboxLimits, "tier" | "defaultTier">;
|
|
27
|
+
/**
|
|
28
|
+
* The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
|
|
29
|
+
* when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
|
|
30
|
+
* kernel sends in `limits.tier`.
|
|
31
|
+
*/
|
|
32
|
+
export declare function deviceTier(policy: Pick<Policy, "tier">, limits: TierLimits): SandboxTier;
|
|
33
|
+
/**
|
|
34
|
+
* The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
|
|
35
|
+
* default of every org unless changed. Used for the sandbox's first configuration only; the next
|
|
36
|
+
* command applies its own limits.
|
|
37
|
+
*/
|
|
38
|
+
export declare function provisionalTier(policy: Pick<Policy, "tier">): SandboxTier;
|
|
39
|
+
/** What a tier really gives on this machine (the device page and `policy show`). */
|
|
40
|
+
export interface TierFacts {
|
|
41
|
+
effectiveTier: SandboxTier;
|
|
42
|
+
/** Whether sandboxed commands may listen on and reach localhost. */
|
|
43
|
+
localhost: "on" | "off-proxy-detected" | "off";
|
|
44
|
+
/** Unix sockets: within the device's directories, every socket with the host's masked, none. */
|
|
45
|
+
unixSockets: "roots" | "all-masked" | "off";
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
|
|
49
|
+
* yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
|
|
50
|
+
* describe the sandboxed tier).
|
|
51
|
+
*
|
|
52
|
+
* - Docker mode: the container has its own loopback and sockets in every tier.
|
|
53
|
+
* - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
|
|
54
|
+
* reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
|
|
55
|
+
* - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
|
|
56
|
+
* directories and localhost unless a local forwarding proxy was detected and the owner did not
|
|
57
|
+
* set `localhost: allow`.
|
|
58
|
+
*/
|
|
59
|
+
export declare function tierFacts(policy: Policy, limits: TierLimits | undefined, opts: {
|
|
60
|
+
platform?: NodeJS.Platform;
|
|
61
|
+
proxyDetected: boolean;
|
|
62
|
+
mode: "os" | "docker";
|
|
63
|
+
}): TierFacts;
|
|
64
|
+
type Limits = Pick<SandboxLimits, "egress" | "allowHosts">;
|
|
65
|
+
/**
|
|
66
|
+
* The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
|
|
67
|
+
* only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
|
|
68
|
+
* only those the org's egress admits (any host when it is `open`, none when it is `none`).
|
|
69
|
+
*/
|
|
70
|
+
export declare function grantedHosts(policy: Pick<Policy, "remoteGrants">, limits: Limits, grants: Pick<DeviceExecGrants, "hosts"> | undefined): string[];
|
|
71
|
+
/** The limits {@link effectiveEgress} reads: the ceiling's network and tiers, and the dev hosts. */
|
|
72
|
+
export type EgressLimits = Pick<SandboxLimits, "egress" | "allowHosts" | "tier" | "defaultTier" | "devHosts">;
|
|
73
|
+
/**
|
|
74
|
+
* The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
|
|
75
|
+
* the dev hosts in `dev`. Undefined for `open`: the device admits every host.
|
|
76
|
+
*/
|
|
77
|
+
export declare function deviceHosts(policy: Pick<Policy, "allowedDomains">, tier: SandboxTier, devHosts: readonly string[]): string[] | undefined;
|
|
78
|
+
/**
|
|
79
|
+
* The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
|
|
80
|
+
* hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
|
|
81
|
+
* - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
|
|
82
|
+
* - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
|
|
83
|
+
* - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
|
|
84
|
+
* plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
|
|
85
|
+
*/
|
|
86
|
+
export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains" | "tier" | "remoteGrants">, limits: EgressLimits, grants?: Pick<DeviceExecGrants, "hosts">): string[];
|
|
22
87
|
/** The sandbox-runtime configuration of one device. */
|
|
23
88
|
export interface SrtConfig {
|
|
24
89
|
filesystem: {
|
|
@@ -29,14 +94,40 @@ export interface SrtConfig {
|
|
|
29
94
|
network: {
|
|
30
95
|
allowedDomains: string[];
|
|
31
96
|
deniedDomains: string[];
|
|
97
|
+
/** macOS: bind and accept on local ports, connect to any port on localhost. */
|
|
98
|
+
allowLocalBinding: boolean;
|
|
99
|
+
/** macOS only: the paths under which unix sockets may be bound and connected to. */
|
|
100
|
+
allowUnixSockets?: string[];
|
|
32
101
|
};
|
|
33
102
|
}
|
|
34
|
-
/**
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
*/
|
|
39
|
-
export declare function srtConfig(_policy: Policy, roots: SandboxRoots, egress: string[], opts?: {
|
|
103
|
+
/** What {@link srtConfig} needs besides the policy and the roots. */
|
|
104
|
+
export interface SrtConfigOptions {
|
|
105
|
+
/** The tier the commands run at (default `strict`). */
|
|
106
|
+
tier?: SandboxTier;
|
|
107
|
+
/** The home whose secret paths are denied (default: the user's home). */
|
|
40
108
|
home?: string;
|
|
109
|
+
/** More paths commands may not read (this program's state directory). */
|
|
41
110
|
denyRead?: string[];
|
|
42
|
-
|
|
111
|
+
platform?: NodeJS.Platform;
|
|
112
|
+
/** The proxy guard found a local forwarding proxy (macOS `dev` / `open` then skip localhost). */
|
|
113
|
+
proxyDetected?: boolean;
|
|
114
|
+
/** macOS: the short socket directory (`TMPDIR` in `dev` / `open`). */
|
|
115
|
+
socketDir?: string;
|
|
116
|
+
/** The device's package caches (`<dir>/cache`), writable in `dev` / `open`. */
|
|
117
|
+
cacheDir?: string;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
|
|
121
|
+
* roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
|
|
122
|
+
* `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
|
|
123
|
+
* `egress`.
|
|
124
|
+
*
|
|
125
|
+
* `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
|
|
126
|
+
* package caches and (macOS) the short socket directory; on macOS they may listen on and reach
|
|
127
|
+
* localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
|
|
128
|
+
* and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
|
|
129
|
+
* sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
|
|
130
|
+
* sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
|
|
131
|
+
*/
|
|
132
|
+
export declare function srtConfig(policy: Policy, roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
|
|
133
|
+
export {};
|
package/dist/policy.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { homedir } from "node:os";
|
|
2
2
|
import { join } from "node:path";
|
|
3
|
+
import { minTier, validateAllowHost, } from "@capybara-hq/plugin-sdk";
|
|
3
4
|
/**
|
|
4
5
|
* Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
5
6
|
* credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
|
|
@@ -51,47 +52,181 @@ export function implicitWritePaths(home = homedir()) {
|
|
|
51
52
|
];
|
|
52
53
|
}
|
|
53
54
|
/** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
|
|
54
|
-
function covers(pattern, host) {
|
|
55
|
+
export function covers(pattern, host) {
|
|
55
56
|
if (pattern === host)
|
|
56
57
|
return true;
|
|
57
58
|
// `*.x.com` admits `a.x.com` and `*.a.x.com`, never the apex `x.com`.
|
|
58
59
|
return pattern.startsWith("*.") && host.endsWith(pattern.slice(1));
|
|
59
60
|
}
|
|
60
61
|
/**
|
|
61
|
-
* The
|
|
62
|
-
*
|
|
62
|
+
* The entry {@link effectiveEgress} returns when a command may reach any public host (the device
|
|
63
|
+
* is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
|
|
64
|
+
* per-command list, so the OS executor never registers it: its ask callback allows instead.
|
|
63
65
|
*/
|
|
64
|
-
export
|
|
65
|
-
|
|
66
|
+
export const ANY_HOST = "*";
|
|
67
|
+
/**
|
|
68
|
+
* The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
|
|
69
|
+
* when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
|
|
70
|
+
* kernel sends in `limits.tier`.
|
|
71
|
+
*/
|
|
72
|
+
export function deviceTier(policy, limits) {
|
|
73
|
+
return minTier(policy.tier ?? limits.defaultTier ?? "strict", limits.tier);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
|
|
77
|
+
* default of every org unless changed. Used for the sandbox's first configuration only; the next
|
|
78
|
+
* command applies its own limits.
|
|
79
|
+
*/
|
|
80
|
+
export function provisionalTier(policy) {
|
|
81
|
+
return policy.tier ?? "dev";
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
|
|
85
|
+
* yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
|
|
86
|
+
* describe the sandboxed tier).
|
|
87
|
+
*
|
|
88
|
+
* - Docker mode: the container has its own loopback and sockets in every tier.
|
|
89
|
+
* - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
|
|
90
|
+
* reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
|
|
91
|
+
* - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
|
|
92
|
+
* directories and localhost unless a local forwarding proxy was detected and the owner did not
|
|
93
|
+
* set `localhost: allow`.
|
|
94
|
+
*/
|
|
95
|
+
export function tierFacts(policy, limits, opts) {
|
|
96
|
+
const effectiveTier = limits === undefined ? provisionalTier(policy) : deviceTier(policy, limits);
|
|
97
|
+
if (opts.mode === "docker")
|
|
98
|
+
return { effectiveTier, localhost: "on", unixSockets: "all-masked" };
|
|
99
|
+
const platform = opts.platform ?? process.platform;
|
|
100
|
+
if (platform !== "darwin")
|
|
101
|
+
return { effectiveTier, localhost: "on", unixSockets: "off" };
|
|
102
|
+
if (effectiveTier === "strict")
|
|
103
|
+
return { effectiveTier, localhost: "off", unixSockets: "off" };
|
|
104
|
+
return {
|
|
105
|
+
effectiveTier,
|
|
106
|
+
localhost: localBinding(policy, opts.proxyDetected) ? "on" : "off-proxy-detected",
|
|
107
|
+
unixSockets: "roots",
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/** macOS `dev` / `open`: local binding, unless a local proxy was found and not overridden. */
|
|
111
|
+
function localBinding(policy, proxyDetected) {
|
|
112
|
+
return policy.localhost === "allow" || !proxyDetected;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
|
|
116
|
+
* only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
|
|
117
|
+
* only those the org's egress admits (any host when it is `open`, none when it is `none`).
|
|
118
|
+
*/
|
|
119
|
+
export function grantedHosts(policy, limits, grants) {
|
|
120
|
+
if (grants === undefined || policy.remoteGrants !== "owner")
|
|
121
|
+
return [];
|
|
66
122
|
if (limits.egress === "none")
|
|
67
123
|
return [];
|
|
68
|
-
if (limits.egress === "open")
|
|
69
|
-
return [...new Set(local)];
|
|
70
124
|
const out = new Set();
|
|
71
|
-
for (const raw of
|
|
125
|
+
for (const raw of grants.hosts) {
|
|
126
|
+
if (typeof raw !== "string")
|
|
127
|
+
continue;
|
|
72
128
|
const host = raw.toLowerCase();
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
else if (covers(host, p))
|
|
78
|
-
out.add(p);
|
|
129
|
+
if (host.startsWith("*.") || validateAllowHost(host).length > 0)
|
|
130
|
+
continue;
|
|
131
|
+
if (limits.egress === "open" || limits.allowHosts.some((p) => covers(p.toLowerCase(), host))) {
|
|
132
|
+
out.add(host);
|
|
79
133
|
}
|
|
80
134
|
}
|
|
81
135
|
return [...out];
|
|
82
136
|
}
|
|
83
137
|
/**
|
|
84
|
-
* The
|
|
85
|
-
*
|
|
86
|
-
* unreadable, and network limited to `egress`.
|
|
138
|
+
* The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
|
|
139
|
+
* the dev hosts in `dev`. Undefined for `open`: the device admits every host.
|
|
87
140
|
*/
|
|
88
|
-
export function
|
|
141
|
+
export function deviceHosts(policy, tier, devHosts) {
|
|
142
|
+
if (tier === "open")
|
|
143
|
+
return undefined;
|
|
144
|
+
const local = policy.allowedDomains.map((d) => d.toLowerCase());
|
|
145
|
+
if (tier === "dev")
|
|
146
|
+
for (const d of devHosts)
|
|
147
|
+
local.push(d.toLowerCase());
|
|
148
|
+
return [...new Set(local)];
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
|
|
152
|
+
* hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
|
|
153
|
+
* - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
|
|
154
|
+
* - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
|
|
155
|
+
* - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
|
|
156
|
+
* plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
|
|
157
|
+
*/
|
|
158
|
+
export function effectiveEgress(policy, limits, grants) {
|
|
159
|
+
if (limits.egress === "none")
|
|
160
|
+
return [];
|
|
161
|
+
const local = deviceHosts(policy, deviceTier(policy, limits), limits.devHosts ?? []);
|
|
162
|
+
if (local === undefined) {
|
|
163
|
+
if (limits.egress === "open")
|
|
164
|
+
return [ANY_HOST];
|
|
165
|
+
return [...new Set(limits.allowHosts.map((h) => h.toLowerCase()))];
|
|
166
|
+
}
|
|
167
|
+
const out = new Set();
|
|
168
|
+
if (limits.egress === "open") {
|
|
169
|
+
for (const d of local)
|
|
170
|
+
out.add(d);
|
|
171
|
+
}
|
|
172
|
+
else {
|
|
173
|
+
for (const raw of limits.allowHosts) {
|
|
174
|
+
const host = raw.toLowerCase();
|
|
175
|
+
for (const p of local) {
|
|
176
|
+
// The intersection of two entries is the narrower one, if either contains the other.
|
|
177
|
+
if (covers(p, host))
|
|
178
|
+
out.add(host);
|
|
179
|
+
else if (covers(host, p))
|
|
180
|
+
out.add(p);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
for (const h of grantedHosts(policy, limits, grants))
|
|
185
|
+
out.add(h);
|
|
186
|
+
return [...out];
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
|
|
190
|
+
* roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
|
|
191
|
+
* `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
|
|
192
|
+
* `egress`.
|
|
193
|
+
*
|
|
194
|
+
* `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
|
|
195
|
+
* package caches and (macOS) the short socket directory; on macOS they may listen on and reach
|
|
196
|
+
* localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
|
|
197
|
+
* and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
|
|
198
|
+
* sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
|
|
199
|
+
* sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
|
|
200
|
+
*/
|
|
201
|
+
export function srtConfig(policy, roots, egress, opts = {}) {
|
|
202
|
+
const platform = opts.platform ?? process.platform;
|
|
203
|
+
const tier = opts.tier ?? "strict";
|
|
204
|
+
const darwin = platform === "darwin";
|
|
205
|
+
const dev = tier !== "strict";
|
|
206
|
+
const socketDir = darwin && dev ? opts.socketDir : undefined;
|
|
89
207
|
return {
|
|
90
208
|
filesystem: {
|
|
91
209
|
denyRead: [...deniedSecretPaths(opts.home), ...(opts.denyRead ?? [])],
|
|
92
|
-
allowWrite: [
|
|
210
|
+
allowWrite: [
|
|
211
|
+
roots.workspace,
|
|
212
|
+
roots.tmp,
|
|
213
|
+
...(socketDir !== undefined ? [socketDir] : []),
|
|
214
|
+
...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
|
|
215
|
+
],
|
|
93
216
|
denyWrite: [roots.skills, ...implicitWritePaths()],
|
|
94
217
|
},
|
|
95
|
-
network: {
|
|
218
|
+
network: {
|
|
219
|
+
allowedDomains: [...egress],
|
|
220
|
+
deniedDomains: [],
|
|
221
|
+
allowLocalBinding: darwin && dev && localBinding(policy, opts.proxyDetected === true),
|
|
222
|
+
...(darwin &&
|
|
223
|
+
dev && {
|
|
224
|
+
allowUnixSockets: [
|
|
225
|
+
roots.tmp,
|
|
226
|
+
roots.workspace,
|
|
227
|
+
...(socketDir !== undefined ? [socketDir] : []),
|
|
228
|
+
],
|
|
229
|
+
}),
|
|
230
|
+
},
|
|
96
231
|
};
|
|
97
232
|
}
|