@capybara-hq/device 0.1.0-rc.7 → 0.1.0-rc.9
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 +106 -189
- package/dist/api.d.ts +5 -0
- package/dist/args.d.ts +8 -3
- package/dist/args.js +38 -19
- package/dist/cli.d.ts +7 -5
- package/dist/cli.js +20 -31
- package/dist/client.d.ts +0 -2
- package/dist/client.js +23 -12
- package/dist/command-log.d.ts +3 -5
- package/dist/commands/login.js +55 -1
- package/dist/commands/mode.d.ts +52 -0
- package/dist/commands/mode.js +108 -0
- package/dist/commands/policy.d.ts +11 -65
- package/dist/commands/policy.js +62 -249
- package/dist/commands/service.d.ts +4 -3
- package/dist/commands/service.js +30 -2
- package/dist/commands/start.d.ts +2 -2
- package/dist/commands/start.js +14 -6
- package/dist/commands/status.js +11 -3
- package/dist/exec/docker.d.ts +22 -30
- package/dist/exec/docker.js +81 -69
- package/dist/exec/fs-helper.d.ts +13 -8
- package/dist/exec/fs-helper.js +30 -12
- package/dist/exec/host.d.ts +8 -8
- package/dist/exec/host.js +9 -9
- package/dist/exec/os.d.ts +36 -69
- package/dist/exec/os.js +65 -159
- package/dist/exec/sandbox-messages.d.ts +14 -0
- package/dist/exec/sandbox-messages.js +21 -0
- package/dist/exec/shared.d.ts +21 -36
- package/dist/exec/shared.js +30 -164
- package/dist/exec/switch.d.ts +38 -55
- package/dist/exec/switch.js +58 -108
- package/dist/exec/types.d.ts +8 -18
- package/dist/index.d.ts +1 -1
- package/dist/network.d.ts +7 -7
- package/dist/network.js +11 -18
- package/dist/policy-store.d.ts +7 -8
- package/dist/policy-store.js +11 -15
- package/dist/policy.d.ts +25 -100
- package/dist/policy.js +44 -146
- package/dist/server-ops.d.ts +15 -35
- package/dist/server-ops.js +36 -117
- package/dist/service/launchd.d.ts +11 -1
- package/dist/service/launchd.js +14 -5
- package/dist/state.d.ts +15 -16
- package/dist/state.js +38 -36
- package/package.json +2 -2
- package/dist/proxy-guard.d.ts +0 -58
- package/dist/proxy-guard.js +0 -137
package/dist/policy.d.ts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots
|
|
2
|
-
import type { Policy } from "./state.js";
|
|
1
|
+
import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
import type { Policy, SandboxMode } from "./state.js";
|
|
3
3
|
/**
|
|
4
|
-
* Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
4
|
+
* Paths no sandboxed command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
5
5
|
* credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
|
|
6
6
|
* macOS keychains, and the browser profile directories (Chrome, Firefox, Chromium, Safari, Brave,
|
|
7
|
-
* Edge, Arc). Relative to `~`.
|
|
7
|
+
* Edge, Arc). Relative to `~`. Auto mode runs as the owner and does not apply them: command review
|
|
8
|
+
* in the kernel does (spec §5.2).
|
|
8
9
|
*/
|
|
9
10
|
export declare const DENIED_SECRET_PATHS: readonly string[];
|
|
10
11
|
/** {@link DENIED_SECRET_PATHS} with `~` expanded to `home`. */
|
|
@@ -16,122 +17,46 @@ export declare function deniedSecretPaths(home?: string): string[];
|
|
|
16
17
|
export declare function implicitWritePaths(home?: string): string[];
|
|
17
18
|
/** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
|
|
18
19
|
export declare function covers(pattern: string, host: string): boolean;
|
|
20
|
+
/** The limits fields that decide the mode and the sandbox-mode network. */
|
|
21
|
+
export type ModeLimits = Pick<SandboxLimits, "mode" | "network">;
|
|
19
22
|
/**
|
|
20
|
-
* The
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
+
* The mode a command runs in (spec §4.1): the device's own choice cut to the kernel's ceiling. A
|
|
24
|
+
* sandbox-mode machine never runs auto because the organization allows it; an auto-mode machine in
|
|
25
|
+
* an organization that forbids auto runs in the sandbox (and its summary says so).
|
|
23
26
|
*/
|
|
24
|
-
export declare
|
|
25
|
-
/** The
|
|
26
|
-
export
|
|
27
|
+
export declare function effectiveMode(policy: Pick<Policy, "mode">, limits: Pick<SandboxLimits, "mode">): SandboxMode;
|
|
28
|
+
/** The granted hosts that apply to one command, within the kernel's network limits. */
|
|
29
|
+
export declare function grantedHosts(limits: Pick<SandboxLimits, "network">, grants: Pick<DeviceExecGrants, "hosts"> | undefined): string[];
|
|
27
30
|
/**
|
|
28
|
-
* The
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
+
* The domains one sandbox-mode command may reach (spec §4.1, §4.4): the intersection of the
|
|
32
|
+
* device's own `allowedDomains` and the kernel's allowlist (`limits.network`), plus the command's
|
|
33
|
+
* grants. An empty list allows nothing. Auto mode ignores both lists: the command has the machine's
|
|
34
|
+
* own network, so this returns no list there (the OS sandbox is not running).
|
|
31
35
|
*/
|
|
32
|
-
export declare function
|
|
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[];
|
|
87
|
-
/** The sandbox-runtime configuration of one device. */
|
|
36
|
+
export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains" | "mode">, limits: ModeLimits, grants?: Pick<DeviceExecGrants, "hosts">): string[];
|
|
37
|
+
/** The sandbox-runtime configuration of a sandbox-mode device. */
|
|
88
38
|
export interface SrtConfig {
|
|
89
39
|
filesystem: {
|
|
90
40
|
denyRead: string[];
|
|
91
41
|
allowWrite: string[];
|
|
92
42
|
denyWrite: string[];
|
|
93
|
-
/** Whether commands may write `.git/config` (`dev` / `open`); `.git/hooks` never. */
|
|
94
|
-
allowGitConfig: boolean;
|
|
95
43
|
};
|
|
96
44
|
network: {
|
|
97
45
|
allowedDomains: string[];
|
|
98
46
|
deniedDomains: string[];
|
|
99
|
-
/** macOS: bind and accept on local ports, connect to any port on localhost. */
|
|
100
|
-
allowLocalBinding: boolean;
|
|
101
|
-
/** macOS only: the paths under which unix sockets may be bound and connected to. */
|
|
102
|
-
allowUnixSockets?: string[];
|
|
103
47
|
};
|
|
104
48
|
}
|
|
105
|
-
/** What {@link srtConfig} needs besides the
|
|
49
|
+
/** What {@link srtConfig} needs besides the egress list. */
|
|
106
50
|
export interface SrtConfigOptions {
|
|
107
|
-
/** The tier the commands run at (default `strict`). */
|
|
108
|
-
tier?: SandboxTier;
|
|
109
51
|
/** The home whose secret paths are denied (default: the user's home). */
|
|
110
52
|
home?: string;
|
|
111
53
|
/** More paths commands may not read (this program's state directory). */
|
|
112
54
|
denyRead?: string[];
|
|
113
|
-
platform?: NodeJS.Platform;
|
|
114
|
-
/** The proxy guard found a local forwarding proxy (macOS `dev` / `open` then skip localhost). */
|
|
115
|
-
proxyDetected?: boolean;
|
|
116
|
-
/** macOS: the short socket directory (`TMPDIR` in `dev` / `open`). */
|
|
117
|
-
socketDir?: string;
|
|
118
|
-
/** The device's package caches (`<dir>/cache`), writable in `dev` / `open`. */
|
|
119
|
-
cacheDir?: string;
|
|
120
55
|
}
|
|
121
56
|
/**
|
|
122
|
-
* The sandbox-runtime configuration (spec §
|
|
123
|
-
* roots (the runtime's implicit write paths
|
|
124
|
-
* `opts.denyRead`, such as this program's own
|
|
125
|
-
* `egress`.
|
|
126
|
-
*
|
|
127
|
-
* `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
|
|
128
|
-
* package caches and (macOS) the short socket directory; on macOS they may listen on and reach
|
|
129
|
-
* localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
|
|
130
|
-
* and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
|
|
131
|
-
* sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
|
|
132
|
-
* sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
|
|
133
|
-
* `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
|
|
134
|
-
* `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
|
|
57
|
+
* The sandbox-runtime configuration of sandbox mode (spec §4.1, §4.4): today's strict profile
|
|
58
|
+
* only. Writes only under the workspace and tmp roots (the runtime's implicit write paths
|
|
59
|
+
* denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own
|
|
60
|
+
* state directory) unreadable, and network limited to `egress`. No local binding, no unix sockets.
|
|
135
61
|
*/
|
|
136
|
-
export declare function srtConfig(
|
|
137
|
-
export {};
|
|
62
|
+
export declare function srtConfig(roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
|
package/dist/policy.js
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import { homedir } from "node:os";
|
|
2
2
|
import { join } from "node:path";
|
|
3
|
-
import {
|
|
3
|
+
import { validateAllowHost, } from "@capybara-hq/plugin-sdk";
|
|
4
4
|
/**
|
|
5
|
-
* Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
5
|
+
* Paths no sandboxed command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
|
|
6
6
|
* credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
|
|
7
7
|
* macOS keychains, and the browser profile directories (Chrome, Firefox, Chromium, Safari, Brave,
|
|
8
|
-
* Edge, Arc). Relative to `~`.
|
|
8
|
+
* Edge, Arc). Relative to `~`. Auto mode runs as the owner and does not apply them: command review
|
|
9
|
+
* in the kernel does (spec §5.2).
|
|
9
10
|
*/
|
|
10
11
|
export const DENIED_SECRET_PATHS = Object.freeze([
|
|
11
12
|
"~/.ssh",
|
|
@@ -59,199 +60,96 @@ export function covers(pattern, host) {
|
|
|
59
60
|
return pattern.startsWith("*.") && host.endsWith(pattern.slice(1));
|
|
60
61
|
}
|
|
61
62
|
/**
|
|
62
|
-
* The
|
|
63
|
-
*
|
|
64
|
-
*
|
|
63
|
+
* The mode a command runs in (spec §4.1): the device's own choice cut to the kernel's ceiling. A
|
|
64
|
+
* sandbox-mode machine never runs auto because the organization allows it; an auto-mode machine in
|
|
65
|
+
* an organization that forbids auto runs in the sandbox (and its summary says so).
|
|
65
66
|
*/
|
|
66
|
-
export
|
|
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;
|
|
67
|
+
export function effectiveMode(policy, limits) {
|
|
68
|
+
return policy.mode === "sandbox" || limits.mode === "sandbox" ? "sandbox" : "auto";
|
|
113
69
|
}
|
|
114
|
-
/**
|
|
115
|
-
|
|
116
|
-
|
|
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 [];
|
|
122
|
-
if (limits.egress === "none")
|
|
70
|
+
/** The granted hosts that apply to one command, within the kernel's network limits. */
|
|
71
|
+
export function grantedHosts(limits, grants) {
|
|
72
|
+
if (grants === undefined)
|
|
123
73
|
return [];
|
|
124
74
|
const out = new Set();
|
|
125
75
|
for (const raw of grants.hosts) {
|
|
126
76
|
if (typeof raw !== "string")
|
|
127
77
|
continue;
|
|
128
78
|
const host = raw.toLowerCase();
|
|
129
|
-
|
|
79
|
+
// Only valid exact public hosts (no wildcards, addresses or internal names).
|
|
80
|
+
if (validateAllowHost(host).length > 0)
|
|
130
81
|
continue;
|
|
131
|
-
if (limits.
|
|
82
|
+
if (limits.network.kind === "open-public" ||
|
|
83
|
+
limits.network.hosts.some((p) => covers(p.toLowerCase(), host))) {
|
|
132
84
|
out.add(host);
|
|
133
85
|
}
|
|
134
86
|
}
|
|
135
87
|
return [...out];
|
|
136
88
|
}
|
|
137
89
|
/**
|
|
138
|
-
* The
|
|
139
|
-
*
|
|
140
|
-
|
|
141
|
-
|
|
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.
|
|
90
|
+
* The domains one sandbox-mode command may reach (spec §4.1, §4.4): the intersection of the
|
|
91
|
+
* device's own `allowedDomains` and the kernel's allowlist (`limits.network`), plus the command's
|
|
92
|
+
* grants. An empty list allows nothing. Auto mode ignores both lists: the command has the machine's
|
|
93
|
+
* own network, so this returns no list there (the OS sandbox is not running).
|
|
157
94
|
*/
|
|
158
95
|
export function effectiveEgress(policy, limits, grants) {
|
|
159
|
-
if (limits
|
|
96
|
+
if (effectiveMode(policy, limits) === "auto")
|
|
160
97
|
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
98
|
const out = new Set();
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
for (const
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
else if (covers(host, p))
|
|
180
|
-
out.add(p);
|
|
181
|
-
}
|
|
99
|
+
const local = policy.allowedDomains.map((d) => d.toLowerCase());
|
|
100
|
+
// `open-public` is for cloud instances only; a local sandbox-mode device is stricter and keeps
|
|
101
|
+
// its own allowlist.
|
|
102
|
+
const orgHosts = limits.network.kind === "allowlist" ? limits.network.hosts.map((h) => h.toLowerCase()) : local;
|
|
103
|
+
for (const host of orgHosts) {
|
|
104
|
+
for (const p of local) {
|
|
105
|
+
// The intersection of two entries is the narrower one, if either contains the other.
|
|
106
|
+
if (covers(p, host))
|
|
107
|
+
out.add(host);
|
|
108
|
+
else if (covers(host, p))
|
|
109
|
+
out.add(p);
|
|
182
110
|
}
|
|
183
111
|
}
|
|
184
|
-
for (const h of grantedHosts(
|
|
112
|
+
for (const h of grantedHosts(limits, grants))
|
|
185
113
|
out.add(h);
|
|
186
114
|
return [...out];
|
|
187
115
|
}
|
|
188
116
|
/** Characters the sandbox runtime reads as a glob in a path entry. */
|
|
189
117
|
const GLOB_CHARS = /[*?[\]{}]/;
|
|
190
118
|
/**
|
|
191
|
-
* Write denies for git under each writable root (spec §5.2.1): `.git/hooks`
|
|
192
|
-
*
|
|
119
|
+
* Write denies for git under each writable root (spec §5.2.1): `.git/hooks` and `.git/config`
|
|
120
|
+
* (a hook or `core.sshCommand` set by a command would run when the owner later runs git there).
|
|
193
121
|
* The runtime has the same mandatory denies, but anchored at this program's own working directory,
|
|
194
122
|
* which may not contain the roots. A root whose path reads as a glob gets none (it cannot be
|
|
195
123
|
* anchored literally); the runtime's own denies still apply when it lies under the working
|
|
196
124
|
* directory.
|
|
197
125
|
*/
|
|
198
|
-
function gitWriteDenies(writable
|
|
126
|
+
function gitWriteDenies(writable) {
|
|
199
127
|
const out = [];
|
|
200
128
|
for (const root of writable) {
|
|
201
129
|
if (GLOB_CHARS.test(root))
|
|
202
130
|
continue;
|
|
203
131
|
out.push(`${root}/.git/hooks/**`, `${root}/**/.git/hooks/**`);
|
|
204
|
-
|
|
205
|
-
out.push(`${root}/.git/config`, `${root}/**/.git/config`);
|
|
132
|
+
out.push(`${root}/.git/config`, `${root}/**/.git/config`);
|
|
206
133
|
}
|
|
207
134
|
return out;
|
|
208
135
|
}
|
|
209
136
|
/**
|
|
210
|
-
* The sandbox-runtime configuration (spec §
|
|
211
|
-
* roots (the runtime's implicit write paths
|
|
212
|
-
* `opts.denyRead`, such as this program's own
|
|
213
|
-
* `egress`.
|
|
214
|
-
*
|
|
215
|
-
* `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
|
|
216
|
-
* package caches and (macOS) the short socket directory; on macOS they may listen on and reach
|
|
217
|
-
* localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
|
|
218
|
-
* and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
|
|
219
|
-
* sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
|
|
220
|
-
* sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
|
|
221
|
-
* `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
|
|
222
|
-
* `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
|
|
137
|
+
* The sandbox-runtime configuration of sandbox mode (spec §4.1, §4.4): today's strict profile
|
|
138
|
+
* only. Writes only under the workspace and tmp roots (the runtime's implicit write paths
|
|
139
|
+
* denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own
|
|
140
|
+
* state directory) unreadable, and network limited to `egress`. No local binding, no unix sockets.
|
|
223
141
|
*/
|
|
224
|
-
export function srtConfig(
|
|
225
|
-
const
|
|
226
|
-
const tier = opts.tier ?? "strict";
|
|
227
|
-
const darwin = platform === "darwin";
|
|
228
|
-
const dev = tier !== "strict";
|
|
229
|
-
const socketDir = darwin && dev ? opts.socketDir : undefined;
|
|
230
|
-
const allowWrite = [
|
|
231
|
-
roots.workspace,
|
|
232
|
-
roots.tmp,
|
|
233
|
-
...(socketDir !== undefined ? [socketDir] : []),
|
|
234
|
-
...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
|
|
235
|
-
];
|
|
142
|
+
export function srtConfig(roots, egress, opts = {}) {
|
|
143
|
+
const allowWrite = [roots.workspace, roots.tmp];
|
|
236
144
|
return {
|
|
237
145
|
filesystem: {
|
|
238
146
|
denyRead: [...deniedSecretPaths(opts.home), ...(opts.denyRead ?? [])],
|
|
239
147
|
allowWrite,
|
|
240
|
-
denyWrite: [roots.skills, ...implicitWritePaths(), ...gitWriteDenies(allowWrite
|
|
241
|
-
allowGitConfig: dev,
|
|
148
|
+
denyWrite: [roots.skills, ...implicitWritePaths(opts.home), ...gitWriteDenies(allowWrite)],
|
|
242
149
|
},
|
|
243
150
|
network: {
|
|
244
151
|
allowedDomains: [...egress],
|
|
245
152
|
deniedDomains: [],
|
|
246
|
-
allowLocalBinding: darwin && dev && localBinding(policy, opts.proxyDetected === true),
|
|
247
|
-
...(darwin &&
|
|
248
|
-
dev && {
|
|
249
|
-
allowUnixSockets: [
|
|
250
|
-
roots.tmp,
|
|
251
|
-
roots.workspace,
|
|
252
|
-
...(socketDir !== undefined ? [socketDir] : []),
|
|
253
|
-
],
|
|
254
|
-
}),
|
|
255
153
|
},
|
|
256
154
|
};
|
|
257
155
|
}
|
package/dist/server-ops.d.ts
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
|
-
import { type DeviceLocalPolicySummary, type DeviceRes, type KernelReq } from "@capybara-hq/plugin-sdk";
|
|
1
|
+
import { type DeviceLocalPolicySummary, type DeviceRes, type KernelReq, type SandboxLimits } from "@capybara-hq/plugin-sdk";
|
|
2
2
|
import type { CommandLogEntry } from "./command-log.js";
|
|
3
|
-
import { type
|
|
4
|
-
import { type TierLimits } from "./policy.js";
|
|
3
|
+
import { type ExecMode, type Executor } from "./exec/types.js";
|
|
5
4
|
import type { PolicyStore } from "./policy-store.js";
|
|
6
5
|
import { type Policy } from "./state.js";
|
|
7
6
|
/** What this program has seen across requests (one per program run, kept over reconnects). */
|
|
8
7
|
export interface SeenState {
|
|
9
|
-
/** The
|
|
10
|
-
limits?:
|
|
8
|
+
/** The mode of the latest exec's limits (the kernel's ceiling), for the summary. */
|
|
9
|
+
limits?: Pick<SandboxLimits, "mode">;
|
|
11
10
|
}
|
|
12
11
|
/** What a request may need beyond the executor. */
|
|
13
12
|
export interface OpContext {
|
|
@@ -18,52 +17,33 @@ export interface OpContext {
|
|
|
18
17
|
policy?: PolicyStore;
|
|
19
18
|
/** Updated by every exec; read by the policy op's summary. */
|
|
20
19
|
seen?: SeenState;
|
|
21
|
-
/** The platform the summary describes (default: this process's). */
|
|
22
|
-
platform?: NodeJS.Platform;
|
|
23
20
|
}
|
|
24
|
-
/** The refusal of a `policy` op
|
|
25
|
-
export declare const
|
|
26
|
-
/** The refusal of a `policy` op raising the tier under `remoteGrants: "off"`. */
|
|
27
|
-
export declare const REMOTE_TIER_OFF_MESSAGE: string;
|
|
28
|
-
/**
|
|
29
|
-
* The refusal of a `policy` op that tries to turn the sandbox off: whatever `remoteGrants` says,
|
|
30
|
-
* only the person on the machine does that (spec §5.4).
|
|
31
|
-
*/
|
|
32
|
-
export declare const ISOLATION_REMOTE_MESSAGE: string;
|
|
33
|
-
/**
|
|
34
|
-
* The refusal of a widening `policy` op in Docker mode: the container has either no network or the
|
|
35
|
-
* whole internet, so one allowed domain would open everything.
|
|
36
|
-
*/
|
|
37
|
-
export declare const DOCKER_WIDENING_MESSAGE: string;
|
|
21
|
+
/** The refusal of a `policy` op that tries to turn auto mode on from the deployment. */
|
|
22
|
+
export declare const MODE_ON_DEVICE_MESSAGE = "The device's mode can only be changed on the machine: run `capybara-device mode auto`.";
|
|
38
23
|
/** The local-log line for a finished request; `detail` is its audit line, `run` how an exec ran. */
|
|
39
|
-
export declare function logEntryFor(req: KernelReq, res: DeviceRes, now: Date, detail?: string, run?:
|
|
24
|
+
export declare function logEntryFor(req: KernelReq, res: DeviceRes, now: Date, detail?: string, run?: ExecMode): CommandLogEntry;
|
|
40
25
|
/** What the summary describes besides the policy file. */
|
|
41
26
|
export interface SummaryFacts {
|
|
42
27
|
mode: Executor["mode"];
|
|
43
|
-
/** The latest exec's
|
|
44
|
-
limits?:
|
|
45
|
-
/** The localhost proxy guard found a local forwarding proxy (OS mode). */
|
|
46
|
-
proxyDetected?: boolean;
|
|
47
|
-
platform?: NodeJS.Platform;
|
|
28
|
+
/** The latest exec's mode ceiling; undefined before the first exec. */
|
|
29
|
+
limits?: Pick<SandboxLimits, "mode"> | undefined;
|
|
48
30
|
}
|
|
49
31
|
/**
|
|
50
|
-
* The summary the kernel keeps of a local policy (hello, `policy` op result): the
|
|
51
|
-
*
|
|
52
|
-
* isolation. Docker mode always reports `sandbox` (it ignores `isolation`).
|
|
32
|
+
* The summary the kernel keeps of a local policy (hello, `policy` op result): the effective mode
|
|
33
|
+
* (the owner's choice cut to the latest ceiling seen) and the device's sandbox-mode allowlist.
|
|
53
34
|
*/
|
|
54
35
|
export declare function policySummary(p: Policy, facts: SummaryFacts): DeviceLocalPolicySummary;
|
|
55
36
|
/** The summary facts of a request context. */
|
|
56
37
|
export declare function summaryFacts(executor: Executor, ctx: OpContext): SummaryFacts;
|
|
57
38
|
/**
|
|
58
|
-
* Runs one request and returns the answer plus its local audit line and, for an exec, its
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
* Never throws.
|
|
39
|
+
* Runs one request and returns the answer plus its local audit line and, for an exec, its mode
|
|
40
|
+
* (for the local command log). A vanished device directory answers `fs_gone` for every operation
|
|
41
|
+
* except `stop`, `policy` and `policyStatus`. Never throws.
|
|
62
42
|
*/
|
|
63
43
|
export declare function serveOp(executor: Executor, req: KernelReq, signal: AbortSignal, ctx?: OpContext): Promise<{
|
|
64
44
|
res: DeviceRes;
|
|
65
45
|
detail?: string;
|
|
66
|
-
run?:
|
|
46
|
+
run?: ExecMode;
|
|
67
47
|
}>;
|
|
68
48
|
/** {@link serveOp} without the audit line. */
|
|
69
49
|
export declare function runOp(executor: Executor, req: KernelReq, signal: AbortSignal, ctx?: OpContext): Promise<DeviceRes>;
|