@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.29
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/LICENSE +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +822 -2
- package/dist/ablation.d.ts +2 -0
- package/dist/ablation.js +3 -0
- package/dist/ablation.js.map +1 -0
- package/dist/completion/check.d.ts +64 -0
- package/dist/completion/check.js +152 -0
- package/dist/completion/check.js.map +1 -0
- package/dist/completion/checks.d.ts +45 -0
- package/dist/completion/checks.js +173 -0
- package/dist/completion/checks.js.map +1 -0
- package/dist/completion/flags.d.ts +25 -0
- package/dist/completion/flags.js +87 -0
- package/dist/completion/flags.js.map +1 -0
- package/dist/completion/index.d.ts +8 -0
- package/dist/completion/index.js +9 -0
- package/dist/completion/index.js.map +1 -0
- package/dist/completion/snapshot.d.ts +33 -0
- package/dist/completion/snapshot.js +83 -0
- package/dist/completion/snapshot.js.map +1 -0
- package/dist/context/cap.d.ts +32 -0
- package/dist/context/cap.js +50 -0
- package/dist/context/cap.js.map +1 -0
- package/dist/context/estimate.d.ts +18 -0
- package/dist/context/estimate.js +20 -0
- package/dist/context/estimate.js.map +1 -0
- package/dist/context/file-spill.d.ts +15 -0
- package/dist/context/file-spill.js +40 -0
- package/dist/context/file-spill.js.map +1 -0
- package/dist/context/index.d.ts +10 -0
- package/dist/context/index.js +10 -0
- package/dist/context/index.js.map +1 -0
- package/dist/context/mask.d.ts +27 -0
- package/dist/context/mask.js +71 -0
- package/dist/context/mask.js.map +1 -0
- package/dist/context/mid-turn.d.ts +40 -0
- package/dist/context/mid-turn.js +82 -0
- package/dist/context/mid-turn.js.map +1 -0
- package/dist/context/policy.d.ts +9 -0
- package/dist/context/policy.js +140 -0
- package/dist/context/policy.js.map +1 -0
- package/dist/context/spill-ledger.d.ts +25 -0
- package/dist/context/spill-ledger.js +54 -0
- package/dist/context/spill-ledger.js.map +1 -0
- package/dist/context/spill.d.ts +10 -0
- package/dist/context/spill.js +18 -0
- package/dist/context/spill.js.map +1 -0
- package/dist/context/summarize.d.ts +53 -0
- package/dist/context/summarize.js +204 -0
- package/dist/context/summarize.js.map +1 -0
- package/dist/context/summary-template.d.ts +29 -0
- package/dist/context/summary-template.js +69 -0
- package/dist/context/summary-template.js.map +1 -0
- package/dist/context/types.d.ts +150 -0
- package/dist/context/types.js +2 -0
- package/dist/context/types.js.map +1 -0
- package/dist/context/write-cap.d.ts +19 -0
- package/dist/context/write-cap.js +41 -0
- package/dist/context/write-cap.js.map +1 -0
- package/dist/create-harness.d.ts +7 -0
- package/dist/create-harness.js +21 -0
- package/dist/create-harness.js.map +1 -0
- package/dist/credentials/addresses.d.ts +14 -0
- package/dist/credentials/addresses.js +144 -0
- package/dist/credentials/addresses.js.map +1 -0
- package/dist/credentials/allowlist.d.ts +54 -0
- package/dist/credentials/allowlist.js +134 -0
- package/dist/credentials/allowlist.js.map +1 -0
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +82 -0
- package/dist/credentials/egress-proxy.js +650 -0
- package/dist/credentials/egress-proxy.js.map +1 -0
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +13 -0
- package/dist/credentials/index.js +14 -0
- package/dist/credentials/index.js.map +1 -0
- package/dist/credentials/scrub.d.ts +23 -0
- package/dist/credentials/scrub.js +115 -0
- package/dist/credentials/scrub.js.map +1 -0
- package/dist/errors.d.ts +60 -0
- package/dist/errors.js +67 -0
- package/dist/errors.js.map +1 -0
- package/dist/extensions/compose.d.ts +27 -0
- package/dist/extensions/compose.js +83 -0
- package/dist/extensions/compose.js.map +1 -0
- package/dist/extensions/context-files-node.d.ts +28 -0
- package/dist/extensions/context-files-node.js +74 -0
- package/dist/extensions/context-files-node.js.map +1 -0
- package/dist/extensions/context-files.d.ts +68 -0
- package/dist/extensions/context-files.js +214 -0
- package/dist/extensions/context-files.js.map +1 -0
- package/dist/extensions/digest.d.ts +6 -0
- package/dist/extensions/digest.js +68 -0
- package/dist/extensions/digest.js.map +1 -0
- package/dist/extensions/index.d.ts +10 -0
- package/dist/extensions/index.js +10 -0
- package/dist/extensions/index.js.map +1 -0
- package/dist/extensions/load.d.ts +42 -0
- package/dist/extensions/load.js +211 -0
- package/dist/extensions/load.js.map +1 -0
- package/dist/extensions/lock.d.ts +8 -0
- package/dist/extensions/lock.js +95 -0
- package/dist/extensions/lock.js.map +1 -0
- package/dist/extensions/node.d.ts +10 -0
- package/dist/extensions/node.js +11 -0
- package/dist/extensions/node.js.map +1 -0
- package/dist/extensions/project-dirs.d.ts +24 -0
- package/dist/extensions/project-dirs.js +97 -0
- package/dist/extensions/project-dirs.js.map +1 -0
- package/dist/extensions/skills-node.d.ts +34 -0
- package/dist/extensions/skills-node.js +123 -0
- package/dist/extensions/skills-node.js.map +1 -0
- package/dist/extensions/skills.d.ts +51 -0
- package/dist/extensions/skills.js +175 -0
- package/dist/extensions/skills.js.map +1 -0
- package/dist/extensions/trust-file.d.ts +3 -0
- package/dist/extensions/trust-file.js +62 -0
- package/dist/extensions/trust-file.js.map +1 -0
- package/dist/extensions/trust-store-node.d.ts +10 -0
- package/dist/extensions/trust-store-node.js +33 -0
- package/dist/extensions/trust-store-node.js.map +1 -0
- package/dist/extensions/types.d.ts +42 -0
- package/dist/extensions/types.js +2 -0
- package/dist/extensions/types.js.map +1 -0
- package/dist/harness.d.ts +156 -0
- package/dist/harness.js +2 -0
- package/dist/harness.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/connection.d.ts +22 -0
- package/dist/mcp/connection.js +267 -0
- package/dist/mcp/connection.js.map +1 -0
- package/dist/mcp/content.d.ts +27 -0
- package/dist/mcp/content.js +177 -0
- package/dist/mcp/content.js.map +1 -0
- package/dist/mcp/errors.d.ts +19 -0
- package/dist/mcp/errors.js +21 -0
- package/dist/mcp/errors.js.map +1 -0
- package/dist/mcp/index.d.ts +10 -0
- package/dist/mcp/index.js +10 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/mcp/manager.d.ts +7 -0
- package/dist/mcp/manager.js +173 -0
- package/dist/mcp/manager.js.map +1 -0
- package/dist/mcp/record.d.ts +7 -0
- package/dist/mcp/record.js +20 -0
- package/dist/mcp/record.js.map +1 -0
- package/dist/mcp/stdio.d.ts +39 -0
- package/dist/mcp/stdio.js +382 -0
- package/dist/mcp/stdio.js.map +1 -0
- package/dist/mcp/types.d.ts +172 -0
- package/dist/mcp/types.js +2 -0
- package/dist/mcp/types.js.map +1 -0
- package/dist/memory/index.d.ts +2 -0
- package/dist/memory/index.js +3 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/permissions/default-rules.d.ts +7 -0
- package/dist/permissions/default-rules.js +42 -0
- package/dist/permissions/default-rules.js.map +1 -0
- package/dist/permissions/errors.d.ts +11 -0
- package/dist/permissions/errors.js +14 -0
- package/dist/permissions/errors.js.map +1 -0
- package/dist/permissions/index.d.ts +9 -0
- package/dist/permissions/index.js +9 -0
- package/dist/permissions/index.js.map +1 -0
- package/dist/permissions/match.d.ts +33 -0
- package/dist/permissions/match.js +287 -0
- package/dist/permissions/match.js.map +1 -0
- package/dist/permissions/pipeline.d.ts +9 -0
- package/dist/permissions/pipeline.js +235 -0
- package/dist/permissions/pipeline.js.map +1 -0
- package/dist/permissions/rules.d.ts +22 -0
- package/dist/permissions/rules.js +74 -0
- package/dist/permissions/rules.js.map +1 -0
- package/dist/permissions/shadow.d.ts +5 -0
- package/dist/permissions/shadow.js +22 -0
- package/dist/permissions/shadow.js.map +1 -0
- package/dist/permissions/types.d.ts +104 -0
- package/dist/permissions/types.js +2 -0
- package/dist/permissions/types.js.map +1 -0
- package/dist/sandbox/base.d.ts +45 -0
- package/dist/sandbox/base.js +74 -0
- package/dist/sandbox/base.js.map +1 -0
- package/dist/sandbox/docker/index.d.ts +41 -0
- package/dist/sandbox/docker/index.js +497 -0
- package/dist/sandbox/docker/index.js.map +1 -0
- package/dist/sandbox/errors.d.ts +44 -0
- package/dist/sandbox/errors.js +57 -0
- package/dist/sandbox/errors.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +65 -0
- package/dist/sandbox/host-files.js +258 -0
- package/dist/sandbox/host-files.js.map +1 -0
- package/dist/sandbox/index.d.ts +10 -0
- package/dist/sandbox/index.js +10 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sandbox/none.d.ts +17 -0
- package/dist/sandbox/none.js +108 -0
- package/dist/sandbox/none.js.map +1 -0
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.d.ts +61 -0
- package/dist/sandbox/process.js +253 -0
- package/dist/sandbox/process.js.map +1 -0
- package/dist/sandbox/spawn-env.d.ts +20 -0
- package/dist/sandbox/spawn-env.js +128 -0
- package/dist/sandbox/spawn-env.js.map +1 -0
- package/dist/sandbox/srt/index.d.ts +38 -0
- package/dist/sandbox/srt/index.js +283 -0
- package/dist/sandbox/srt/index.js.map +1 -0
- package/dist/sandbox/srt/settings.d.ts +60 -0
- package/dist/sandbox/srt/settings.js +84 -0
- package/dist/sandbox/srt/settings.js.map +1 -0
- package/dist/sandbox/types.d.ts +125 -0
- package/dist/sandbox/types.js +6 -0
- package/dist/sandbox/types.js.map +1 -0
- package/dist/server/answers.d.ts +16 -0
- package/dist/server/answers.js +43 -0
- package/dist/server/answers.js.map +1 -0
- package/dist/server/connection.d.ts +99 -0
- package/dist/server/connection.js +309 -0
- package/dist/server/connection.js.map +1 -0
- package/dist/server/dispatcher.d.ts +86 -0
- package/dist/server/dispatcher.js +800 -0
- package/dist/server/dispatcher.js.map +1 -0
- package/dist/server/index.d.ts +13 -0
- package/dist/server/index.js +12 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/local-transport.d.ts +44 -0
- package/dist/server/local-transport.js +103 -0
- package/dist/server/local-transport.js.map +1 -0
- package/dist/server/outbox.d.ts +31 -0
- package/dist/server/outbox.js +130 -0
- package/dist/server/outbox.js.map +1 -0
- package/dist/server/params.d.ts +25 -0
- package/dist/server/params.js +112 -0
- package/dist/server/params.js.map +1 -0
- package/dist/server/protocol.schema.json +2448 -0
- package/dist/server/rpc-session.d.ts +43 -0
- package/dist/server/rpc-session.js +167 -0
- package/dist/server/rpc-session.js.map +1 -0
- package/dist/server/stdio-streams.d.ts +67 -0
- package/dist/server/stdio-streams.js +218 -0
- package/dist/server/stdio-streams.js.map +1 -0
- package/dist/server/stdio.d.ts +59 -0
- package/dist/server/stdio.js +189 -0
- package/dist/server/stdio.js.map +1 -0
- package/dist/server/websocket.d.ts +106 -0
- package/dist/server/websocket.js +327 -0
- package/dist/server/websocket.js.map +1 -0
- package/dist/session/approvals.d.ts +81 -0
- package/dist/session/approvals.js +217 -0
- package/dist/session/approvals.js.map +1 -0
- package/dist/session/code-call-log.d.ts +42 -0
- package/dist/session/code-call-log.js +63 -0
- package/dist/session/code-call-log.js.map +1 -0
- package/dist/session/code-call-result.d.ts +19 -0
- package/dist/session/code-call-result.js +95 -0
- package/dist/session/code-call-result.js.map +1 -0
- package/dist/session/code-call.d.ts +49 -0
- package/dist/session/code-call.js +345 -0
- package/dist/session/code-call.js.map +1 -0
- package/dist/session/effect-scope.d.ts +11 -0
- package/dist/session/effect-scope.js +10 -0
- package/dist/session/effect-scope.js.map +1 -0
- package/dist/session/errors.d.ts +19 -0
- package/dist/session/errors.js +27 -0
- package/dist/session/errors.js.map +1 -0
- package/dist/session/file-index.d.ts +8 -0
- package/dist/session/file-index.js +70 -0
- package/dist/session/file-index.js.map +1 -0
- package/dist/session/file-key-store.d.ts +16 -0
- package/dist/session/file-key-store.js +169 -0
- package/dist/session/file-key-store.js.map +1 -0
- package/dist/session/file-lock.d.ts +52 -0
- package/dist/session/file-lock.js +324 -0
- package/dist/session/file-lock.js.map +1 -0
- package/dist/session/index.d.ts +22 -0
- package/dist/session/index.js +20 -0
- package/dist/session/index.js.map +1 -0
- package/dist/session/jsonl-store.d.ts +37 -0
- package/dist/session/jsonl-store.js +386 -0
- package/dist/session/jsonl-store.js.map +1 -0
- package/dist/session/jsonl.d.ts +9 -0
- package/dist/session/jsonl.js +10 -0
- package/dist/session/jsonl.js.map +1 -0
- package/dist/session/lock.d.ts +19 -0
- package/dist/session/lock.js +2 -0
- package/dist/session/lock.js.map +1 -0
- package/dist/session/memory-store.d.ts +12 -0
- package/dist/session/memory-store.js +60 -0
- package/dist/session/memory-store.js.map +1 -0
- package/dist/session/migrate.d.ts +41 -0
- package/dist/session/migrate.js +86 -0
- package/dist/session/migrate.js.map +1 -0
- package/dist/session/pointer.d.ts +15 -0
- package/dist/session/pointer.js +22 -0
- package/dist/session/pointer.js.map +1 -0
- package/dist/session/rebuild.d.ts +53 -0
- package/dist/session/rebuild.js +230 -0
- package/dist/session/rebuild.js.map +1 -0
- package/dist/session/resume.d.ts +26 -0
- package/dist/session/resume.js +128 -0
- package/dist/session/resume.js.map +1 -0
- package/dist/session/retention.d.ts +97 -0
- package/dist/session/retention.js +702 -0
- package/dist/session/retention.js.map +1 -0
- package/dist/session/runner.d.ts +156 -0
- package/dist/session/runner.js +656 -0
- package/dist/session/runner.js.map +1 -0
- package/dist/session/scheduler.d.ts +47 -0
- package/dist/session/scheduler.js +85 -0
- package/dist/session/scheduler.js.map +1 -0
- package/dist/session/secret-key-store.d.ts +47 -0
- package/dist/session/secret-key-store.js +79 -0
- package/dist/session/secret-key-store.js.map +1 -0
- package/dist/session/session.d.ts +106 -0
- package/dist/session/session.js +353 -0
- package/dist/session/session.js.map +1 -0
- package/dist/session/sticky.d.ts +48 -0
- package/dist/session/sticky.js +232 -0
- package/dist/session/sticky.js.map +1 -0
- package/dist/session/store.d.ts +108 -0
- package/dist/session/store.js +163 -0
- package/dist/session/store.js.map +1 -0
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +3 -0
- package/dist/telemetry/index.js.map +1 -0
- package/dist/testing/fake-sandbox.d.ts +52 -0
- package/dist/testing/fake-sandbox.js +370 -0
- package/dist/testing/fake-sandbox.js.map +1 -0
- package/dist/testing/index.d.ts +10 -0
- package/dist/testing/index.js +11 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/key-store-conformance.d.ts +22 -0
- package/dist/testing/key-store-conformance.js +97 -0
- package/dist/testing/key-store-conformance.js.map +1 -0
- package/dist/testing/run-cases.d.ts +21 -0
- package/dist/testing/run-cases.js +20 -0
- package/dist/testing/run-cases.js.map +1 -0
- package/dist/testing/sandbox-conformance.d.ts +64 -0
- package/dist/testing/sandbox-conformance.js +468 -0
- package/dist/testing/sandbox-conformance.js.map +1 -0
- package/dist/testing/scheduler-conformance.d.ts +32 -0
- package/dist/testing/scheduler-conformance.js +72 -0
- package/dist/testing/scheduler-conformance.js.map +1 -0
- package/dist/testing/store-conformance.d.ts +21 -0
- package/dist/testing/store-conformance.js +320 -0
- package/dist/testing/store-conformance.js.map +1 -0
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/errors.d.ts +13 -0
- package/dist/tools/errors.js +17 -0
- package/dist/tools/errors.js.map +1 -0
- package/dist/tools/index.d.ts +12 -0
- package/dist/tools/index.js +11 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/registry.d.ts +3 -0
- package/dist/tools/registry.js +234 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/tool-search.d.ts +30 -0
- package/dist/tools/tool-search.js +118 -0
- package/dist/tools/tool-search.js.map +1 -0
- package/dist/tools/types.d.ts +106 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/llms.txt +469 -0
- package/package.json +118 -3
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the Node-only backends that mount a workspace share: the checks before a command runs, the file calls, and a
|
|
3
|
+
* `dispose()` that every caller waits on. A backend extends it and adds how it starts a command and what it cleans up.
|
|
4
|
+
*/
|
|
5
|
+
import { HarnessError } from "../errors.js";
|
|
6
|
+
import { workingDirectory } from "./host-files.js";
|
|
7
|
+
import { APPLY_STOPS, confirmPolicy } from "./policy.js";
|
|
8
|
+
import { checkCommand, checkOptions } from "./process.js";
|
|
9
|
+
/** A sandbox that checks a command the same way, reads and writes files in the host, and disposes once. */
|
|
10
|
+
export class BackendSandbox {
|
|
11
|
+
disposed = false;
|
|
12
|
+
disposing;
|
|
13
|
+
applied = [];
|
|
14
|
+
base;
|
|
15
|
+
constructor(base) {
|
|
16
|
+
this.base = base;
|
|
17
|
+
}
|
|
18
|
+
/** Throws `sandbox_disposed` once `dispose()` has been called. */
|
|
19
|
+
live() {
|
|
20
|
+
if (this.disposed)
|
|
21
|
+
throw new HarnessError("sandbox_disposed", "the sandbox was disposed");
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Checks a command and its options, and finds its working directory. It returns the real working directory to run in,
|
|
25
|
+
* or the result that settles the call without running anything: a denial for a directory outside the workspace, and
|
|
26
|
+
* exit code 127 for a first word with `=`, which `env` would read as an assignment, as `none` answers a program it
|
|
27
|
+
* can't find.
|
|
28
|
+
*/
|
|
29
|
+
async prepare(command, options) {
|
|
30
|
+
this.live();
|
|
31
|
+
checkCommand(command);
|
|
32
|
+
checkOptions(options);
|
|
33
|
+
options.signal.throwIfAborted();
|
|
34
|
+
const located = await workingDirectory(this.base.modules, this.base.root, options);
|
|
35
|
+
if ("denied" in located)
|
|
36
|
+
return located;
|
|
37
|
+
// The sandbox or the signal may have changed while the folder was checked.
|
|
38
|
+
this.live();
|
|
39
|
+
options.signal.throwIfAborted();
|
|
40
|
+
if (command[0]?.includes("=")) {
|
|
41
|
+
return { exitCode: 127, stdout: "", stderr: `command not found: ${command[0]}\n` };
|
|
42
|
+
}
|
|
43
|
+
return located;
|
|
44
|
+
}
|
|
45
|
+
/** The stops the applied policy delivers, set by `confirm()` when the sandbox is provisioned. */
|
|
46
|
+
get stops() {
|
|
47
|
+
return this.applied;
|
|
48
|
+
}
|
|
49
|
+
/** Reads the policy back and checks it against `requested`, or disposes the sandbox and throws on a difference. */
|
|
50
|
+
async confirm(client, requested) {
|
|
51
|
+
this.applied = await confirmPolicy(client, this, requested);
|
|
52
|
+
}
|
|
53
|
+
/** Sets the stops a resumed sandbox's confirmed policy delivers, for `resumeSandbox()`. */
|
|
54
|
+
[APPLY_STOPS](stops) {
|
|
55
|
+
this.applied = stops;
|
|
56
|
+
}
|
|
57
|
+
async readFile(path) {
|
|
58
|
+
this.live();
|
|
59
|
+
return this.base.files.readFile(path);
|
|
60
|
+
}
|
|
61
|
+
async writeFile(path, data) {
|
|
62
|
+
this.live();
|
|
63
|
+
return this.base.files.writeFile(path, data);
|
|
64
|
+
}
|
|
65
|
+
/** Stops what is running and cleans up. Every call gets the first call's promise, so a second caller waits too. */
|
|
66
|
+
dispose() {
|
|
67
|
+
if (this.disposing === undefined) {
|
|
68
|
+
this.disposed = true;
|
|
69
|
+
this.disposing = this.shutDown();
|
|
70
|
+
}
|
|
71
|
+
return this.disposing;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=base.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/sandbox/base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAkB,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAoB,MAAM,cAAc,CAAC;AAW5E,2GAA2G;AAC3G,MAAM,OAAgB,cAAc;IAC1B,QAAQ,GAAG,KAAK,CAAC;IACjB,SAAS,CAA4B;IACrC,OAAO,GAA2B,EAAE,CAAC;IAC5B,IAAI,CAAc;IAEnC,YAAsB,IAAiB;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,kEAAkE;IACxD,IAAI;QACZ,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAC;IAC5F,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,OAAO,CACrB,OAA0B,EAC1B,OAAoB;QAEpB,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,YAAY,CAAC,OAAO,CAAC,CAAC;QACtB,YAAY,CAAC,OAAO,CAAC,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnF,IAAI,QAAQ,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;QACxC,2EAA2E;QAC3E,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,sBAAsB,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrF,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAOD,iGAAiG;IACjG,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,mHAAmH;IACnH,KAAK,CAAC,OAAO,CAAC,MAAqB,EAAE,SAAwB;QAC3D,IAAI,CAAC,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED,2FAA2F;IAC3F,CAAC,WAAW,CAAC,CAAC,KAA6B;QACzC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAgB;QAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,mHAAmH;IACnH,OAAO;QACL,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CAIF","sourcesContent":["/**\n * What the Node-only backends that mount a workspace share: the checks before a command runs, the file calls, and a\n * `dispose()` that every caller waits on. A backend extends it and adds how it starts a command and what it cleans up.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { type HostFiles, workingDirectory } from \"./host-files.js\";\nimport { APPLY_STOPS, confirmPolicy } from \"./policy.js\";\nimport { checkCommand, checkOptions, type NodeModules } from \"./process.js\";\nimport type { ExecOptions, ExecResult, Sandbox, SandboxClient, SandboxPolicy, SandboxStop } from \"./types.js\";\n\n/** The state a backend's sandbox is built on. */\nexport interface BackendBase {\n readonly modules: NodeModules;\n /** The workspace's real root. */\n readonly root: string;\n readonly files: HostFiles;\n}\n\n/** A sandbox that checks a command the same way, reads and writes files in the host, and disposes once. */\nexport abstract class BackendSandbox implements Sandbox {\n private disposed = false;\n private disposing: Promise<void> | undefined;\n private applied: readonly SandboxStop[] = [];\n private readonly base: BackendBase;\n\n protected constructor(base: BackendBase) {\n this.base = base;\n }\n\n /** Throws `sandbox_disposed` once `dispose()` has been called. */\n protected live(): void {\n if (this.disposed) throw new HarnessError(\"sandbox_disposed\", \"the sandbox was disposed\");\n }\n\n /**\n * Checks a command and its options, and finds its working directory. It returns the real working directory to run in,\n * or the result that settles the call without running anything: a denial for a directory outside the workspace, and\n * exit code 127 for a first word with `=`, which `env` would read as an assignment, as `none` answers a program it\n * can't find.\n */\n protected async prepare(\n command: readonly string[],\n options: ExecOptions,\n ): Promise<{ readonly cwd: string } | ExecResult> {\n this.live();\n checkCommand(command);\n checkOptions(options);\n options.signal.throwIfAborted();\n const located = await workingDirectory(this.base.modules, this.base.root, options);\n if (\"denied\" in located) return located;\n // The sandbox or the signal may have changed while the folder was checked.\n this.live();\n options.signal.throwIfAborted();\n if (command[0]?.includes(\"=\")) {\n return { exitCode: 127, stdout: \"\", stderr: `command not found: ${command[0]}\\n` };\n }\n return located;\n }\n\n abstract exec(command: readonly string[], options: ExecOptions): Promise<ExecResult>;\n\n /** Reads back the policy this sandbox applies, from what the backend wrote or will pass to each command. */\n abstract readBack(): Promise<SandboxPolicy>;\n\n /** The stops the applied policy delivers, set by `confirm()` when the sandbox is provisioned. */\n get stops(): readonly SandboxStop[] {\n return this.applied;\n }\n\n /** Reads the policy back and checks it against `requested`, or disposes the sandbox and throws on a difference. */\n async confirm(client: SandboxClient, requested: SandboxPolicy): Promise<void> {\n this.applied = await confirmPolicy(client, this, requested);\n }\n\n /** Sets the stops a resumed sandbox's confirmed policy delivers, for `resumeSandbox()`. */\n [APPLY_STOPS](stops: readonly SandboxStop[]): void {\n this.applied = stops;\n }\n\n async readFile(path: string): Promise<Uint8Array> {\n this.live();\n return this.base.files.readFile(path);\n }\n\n async writeFile(path: string, data: Uint8Array): Promise<void> {\n this.live();\n return this.base.files.writeFile(path, data);\n }\n\n /** Stops what is running and cleans up. Every call gets the first call's promise, so a second caller waits too. */\n dispose(): Promise<void> {\n if (this.disposing === undefined) {\n this.disposed = true;\n this.disposing = this.shutDown();\n }\n return this.disposing;\n }\n\n /** Ends the commands still running and removes what the sandbox made. It runs once. */\n protected abstract shutDown(): Promise<void>;\n}\n"]}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { SandboxClient } from "../types.js";
|
|
2
|
+
/** The options of `dockerSandbox()`. */
|
|
3
|
+
export interface DockerSandboxOptions {
|
|
4
|
+
/** The image to run, which must already be on the Docker host: `provision()` never pulls. Pin it by digest. */
|
|
5
|
+
readonly image: string;
|
|
6
|
+
/** CPUs a command may use. Defaults to 1. */
|
|
7
|
+
readonly cpus?: number;
|
|
8
|
+
/** Megabytes of memory a command may use, with no swap. Defaults to 1024. */
|
|
9
|
+
readonly memoryMb?: number;
|
|
10
|
+
/** Processes a command may start. Defaults to 256. */
|
|
11
|
+
readonly pidsLimit?: number;
|
|
12
|
+
/** The `docker` executable. Without it the backend finds `docker` on the absolute folders of the host's `PATH`. */
|
|
13
|
+
readonly binary?: string;
|
|
14
|
+
/** The Docker daemon's address. Without it the backend passes the host's `DOCKER_HOST` when it is set. */
|
|
15
|
+
readonly dockerHost?: string;
|
|
16
|
+
/** The user and group a command runs as, as `uid:gid`. Defaults to this process's, so its files stay yours. */
|
|
17
|
+
readonly user?: string;
|
|
18
|
+
/** Folders to read besides the policy's roots, mounted read-only. */
|
|
19
|
+
readonly extraReadRoots?: readonly string[];
|
|
20
|
+
/** Folders that stay read-only inside a write root, such as the session's own log folder. */
|
|
21
|
+
readonly denyWrite?: readonly string[];
|
|
22
|
+
/**
|
|
23
|
+
* A Unix socket on the host that a command may use to reach the hosts its policy allows, mounted at
|
|
24
|
+
* `DOCKER_PROXY_SOCKET_PATH`. The proxy on it enforces the allowlist, so start `startEgressProxy()` there with the
|
|
25
|
+
* policy's hosts, such as from `compileEgressPolicy()`; the read-back trusts it to.
|
|
26
|
+
*/
|
|
27
|
+
readonly proxySocket?: string;
|
|
28
|
+
}
|
|
29
|
+
/** Where a command finds the proxy socket, when the caller mounts one. */
|
|
30
|
+
export declare const DOCKER_PROXY_SOCKET_PATH = "/run/harness/proxy.sock";
|
|
31
|
+
/**
|
|
32
|
+
* Builds the Docker backend. `provision()` checks the platform, the `docker` client, the daemon and that the image is on
|
|
33
|
+
* the host, so a host that can't run the container throws `SandboxUnavailableError` and runs nothing. The `docker`
|
|
34
|
+
* client runs with a clean environment: a `PATH`, a private empty `HOME` and `DOCKER_HOST` when one is set, and never
|
|
35
|
+
* the parent's environment. The policy's roots, `extraReadRoots`, `denyWrite` and `proxySocket` must be absolute, and
|
|
36
|
+
* the workspace must lie inside a root. A command whose first word contains `=` resolves with exit code 127, as under
|
|
37
|
+
* `none`. Before it returns, `provision()` reads back the policy its mounts and flags apply and throws
|
|
38
|
+
* `SandboxPolicyMismatchError` on a difference. Without `proxySocket` the container reaches no host, so a policy whose
|
|
39
|
+
* `network.allow` names one is refused. The backend lists no capability: it can't resume, snapshot or pause.
|
|
40
|
+
*/
|
|
41
|
+
export declare function dockerSandbox(options: DockerSandboxOptions): SandboxClient;
|
|
@@ -0,0 +1,497 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/harness/sandbox/docker`: the container-tier backend. Each command runs in its own locked-down
|
|
3
|
+
* container: all capabilities dropped, a read-only root file system, no network, no new privileges, and limits on
|
|
4
|
+
* processes, CPUs and memory. Only the policy's write roots are writable, and only the policy's roots are mounted. It
|
|
5
|
+
* claims `mistakes` and `exfiltration`, never a `hostile_process`: the kernel is shared with the host. Only Linux and a
|
|
6
|
+
* rootful daemon are tested. A backend that can't start throws `SandboxUnavailableError` and runs nothing. It is
|
|
7
|
+
* Node-only.
|
|
8
|
+
*
|
|
9
|
+
* The container has no network, so a command reaches a host only through a proxy socket the caller mounts. The file calls
|
|
10
|
+
* run in the host on the mounted folders, checked by their real path.
|
|
11
|
+
*/
|
|
12
|
+
import { HarnessError } from "../../errors.js";
|
|
13
|
+
import { BackendSandbox } from "../base.js";
|
|
14
|
+
import { SandboxUnavailableError } from "../errors.js";
|
|
15
|
+
import { absolutePath, checkPaths, existing, findOnPath, HostFiles, inside, isProtectedPath, PROTECTED_TOP_LEVEL, realOrSelf, spellings, workspaceRoot, } from "../host-files.js";
|
|
16
|
+
import { nodeModules, ProcessRunner } from "../process.js";
|
|
17
|
+
/** Where a command finds the proxy socket, when the caller mounts one. */
|
|
18
|
+
export const DOCKER_PROXY_SOCKET_PATH = "/run/harness/proxy.sock";
|
|
19
|
+
const DEFAULTS = { cpus: 1, memoryMb: 1024, pidsLimit: 256 };
|
|
20
|
+
const DAEMON_TIMEOUT_MS = 20_000;
|
|
21
|
+
// The longest one call that kills or removes a container may take.
|
|
22
|
+
const CALL_TIMEOUT_MS = 5000;
|
|
23
|
+
// Creating a container copies the image on some storage drivers, which can take a while.
|
|
24
|
+
const CREATE_TIMEOUT_MS = 120_000;
|
|
25
|
+
// How long a stopped `docker run` client has to leave on its own, which lets it cancel a container that isn't started yet.
|
|
26
|
+
const GRACE_MS = 3000;
|
|
27
|
+
const KILL_ATTEMPTS = 5;
|
|
28
|
+
const KILL_RETRY_MS = 100;
|
|
29
|
+
const SWEEP_QUIET_PASSES = 2;
|
|
30
|
+
// The longest the sweep at the end waits for the last container to go.
|
|
31
|
+
const SWEEP_MAX_MS = 20_000;
|
|
32
|
+
const SWEEP_PAUSE_MS = 200;
|
|
33
|
+
// A variable name that `env` can set, which is every name a process can be given.
|
|
34
|
+
const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
35
|
+
// A path in a `--mount` value can't hold a comma or a quote, which that syntax reads as separators.
|
|
36
|
+
const MOUNTABLE = /^[^,"\n\r]+$/;
|
|
37
|
+
const mountFlags = (mount) => [
|
|
38
|
+
"--mount",
|
|
39
|
+
`type=bind,src=${mount.from},dst=${mount.to}${mount.readOnly ? ",readonly" : ""}`,
|
|
40
|
+
];
|
|
41
|
+
class DockerSandbox extends BackendSandbox {
|
|
42
|
+
started = 0;
|
|
43
|
+
// Whether a creation was left to finish in the background, which a sweep at the end has to catch.
|
|
44
|
+
abandoned = false;
|
|
45
|
+
// The containers being created, which `dispose()` waits for before it sweeps.
|
|
46
|
+
pending = new Set();
|
|
47
|
+
runner;
|
|
48
|
+
// Runs the calls that manage containers, which `dispose()` must not cut short: a `create` that is stopped half way
|
|
49
|
+
// leaves a container behind.
|
|
50
|
+
manager;
|
|
51
|
+
state;
|
|
52
|
+
constructor(state) {
|
|
53
|
+
super(state);
|
|
54
|
+
this.state = state;
|
|
55
|
+
this.runner = new ProcessRunner(state.modules);
|
|
56
|
+
this.manager = new ProcessRunner(state.modules);
|
|
57
|
+
}
|
|
58
|
+
/** Runs the `docker` client with `args` and waits for it, for the calls that manage containers. */
|
|
59
|
+
async client(args, timeoutMs) {
|
|
60
|
+
return this.manager.run({
|
|
61
|
+
program: this.state.docker,
|
|
62
|
+
args,
|
|
63
|
+
cwd: this.state.root,
|
|
64
|
+
env: this.state.clientEnv,
|
|
65
|
+
missingProgram: "reject",
|
|
66
|
+
}, { env: {}, signal: new AbortController().signal, timeoutMs });
|
|
67
|
+
}
|
|
68
|
+
/** The `docker run` arguments for one command in a container called `name`. */
|
|
69
|
+
runArguments(name, cwd, command, env) {
|
|
70
|
+
const assignments = [];
|
|
71
|
+
for (const [variable, value] of Object.entries(env)) {
|
|
72
|
+
if (!VARIABLE_NAME.test(variable)) {
|
|
73
|
+
throw new HarnessError("invalid_sandbox_options", `${JSON.stringify(variable)} is not a variable name`);
|
|
74
|
+
}
|
|
75
|
+
assignments.push(`${variable}=${value}`);
|
|
76
|
+
}
|
|
77
|
+
const { state } = this;
|
|
78
|
+
// `env -i` clears the image's own variables, so the command holds exactly the ones it was given.
|
|
79
|
+
return [
|
|
80
|
+
"create",
|
|
81
|
+
"--rm",
|
|
82
|
+
"--name",
|
|
83
|
+
name,
|
|
84
|
+
"--label",
|
|
85
|
+
state.label,
|
|
86
|
+
...state.flags,
|
|
87
|
+
...state.mounts.flatMap(mountFlags),
|
|
88
|
+
"--workdir",
|
|
89
|
+
cwd,
|
|
90
|
+
"--entrypoint",
|
|
91
|
+
"env",
|
|
92
|
+
state.image,
|
|
93
|
+
"-i",
|
|
94
|
+
// Ends `env`'s options, so a first word that starts with `-` is a program name.
|
|
95
|
+
"--",
|
|
96
|
+
...assignments,
|
|
97
|
+
...command,
|
|
98
|
+
];
|
|
99
|
+
}
|
|
100
|
+
/** Removes the container if it exists, which is all a container that never started needs. */
|
|
101
|
+
async removeContainer(name) {
|
|
102
|
+
await this.client(["rm", "--force", name], CALL_TIMEOUT_MS).catch(() => undefined);
|
|
103
|
+
}
|
|
104
|
+
/** Kills the container, trying again while the daemon is still creating it, and removes what is left. */
|
|
105
|
+
async killContainer(name) {
|
|
106
|
+
for (let attempt = 0; attempt < KILL_ATTEMPTS; attempt += 1) {
|
|
107
|
+
const result = await this.client(["kill", name], CALL_TIMEOUT_MS).catch(() => undefined);
|
|
108
|
+
if (result?.exitCode === 0)
|
|
109
|
+
break;
|
|
110
|
+
await new Promise((resolve) => setTimeout(resolve, KILL_RETRY_MS));
|
|
111
|
+
}
|
|
112
|
+
await this.removeContainer(name);
|
|
113
|
+
}
|
|
114
|
+
async exec(command, options) {
|
|
115
|
+
const prepared = await this.prepare(command, options);
|
|
116
|
+
if (!("cwd" in prepared))
|
|
117
|
+
return prepared;
|
|
118
|
+
const located = prepared;
|
|
119
|
+
const { root } = this.state;
|
|
120
|
+
this.started += 1;
|
|
121
|
+
const name = `${this.state.label.split("=")[1]}-${this.started}`;
|
|
122
|
+
const started = Date.now();
|
|
123
|
+
// The container is created first and started after, so a stop never leaves a client half way through creating one.
|
|
124
|
+
const created = this.client(this.runArguments(name, located.cwd, command, options.env), CREATE_TIMEOUT_MS);
|
|
125
|
+
this.track(created);
|
|
126
|
+
const made = await this.untilStopped(name, created, options);
|
|
127
|
+
if ("expired" in made)
|
|
128
|
+
return made.expired;
|
|
129
|
+
if (made.exitCode !== 0) {
|
|
130
|
+
await this.removeContainer(name);
|
|
131
|
+
return { exitCode: made.exitCode, stdout: "", stderr: made.stderr };
|
|
132
|
+
}
|
|
133
|
+
try {
|
|
134
|
+
this.live();
|
|
135
|
+
options.signal.throwIfAborted();
|
|
136
|
+
}
|
|
137
|
+
catch (error) {
|
|
138
|
+
await this.killContainer(name);
|
|
139
|
+
throw error;
|
|
140
|
+
}
|
|
141
|
+
const remaining = options.timeoutMs === undefined ? {} : { timeoutMs: Math.max(1, options.timeoutMs - (Date.now() - started)) };
|
|
142
|
+
const { stdoutBytes: _bytes, ...result } = await this.runner.run({
|
|
143
|
+
program: this.state.docker,
|
|
144
|
+
args: ["start", "--attach", name],
|
|
145
|
+
cwd: root,
|
|
146
|
+
env: this.state.clientEnv,
|
|
147
|
+
missingProgram: "reject",
|
|
148
|
+
onStop: () => this.killContainer(name),
|
|
149
|
+
graceMs: GRACE_MS,
|
|
150
|
+
}, { ...options, ...remaining });
|
|
151
|
+
return result;
|
|
152
|
+
}
|
|
153
|
+
/** Keeps `work` in the set that `dispose()` waits for, until it settles. */
|
|
154
|
+
track(work) {
|
|
155
|
+
const tracked = work.then(() => undefined, () => undefined);
|
|
156
|
+
this.pending.add(tracked);
|
|
157
|
+
void tracked.then(() => this.pending.delete(tracked));
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Waits for a container to be created, but settles the call when the caller's signal aborts or its timeout passes. The
|
|
161
|
+
* creation can't be cut short without leaving a container behind, so it carries on in the background, and the container
|
|
162
|
+
* is removed when it ends.
|
|
163
|
+
*/
|
|
164
|
+
untilStopped(name, created, options) {
|
|
165
|
+
return new Promise((resolve, reject) => {
|
|
166
|
+
let settled = false;
|
|
167
|
+
let timer;
|
|
168
|
+
const finish = (settle, discard) => {
|
|
169
|
+
if (settled)
|
|
170
|
+
return;
|
|
171
|
+
settled = true;
|
|
172
|
+
clearTimeout(timer);
|
|
173
|
+
options.signal.removeEventListener("abort", onAbort);
|
|
174
|
+
if (discard) {
|
|
175
|
+
this.abandoned = true;
|
|
176
|
+
this.track(created.then(() => this.killContainer(name)));
|
|
177
|
+
}
|
|
178
|
+
settle();
|
|
179
|
+
};
|
|
180
|
+
const onAbort = () => finish(() => reject(options.signal.reason), true);
|
|
181
|
+
options.signal.addEventListener("abort", onAbort, { once: true });
|
|
182
|
+
if (options.timeoutMs !== undefined) {
|
|
183
|
+
const note = `timed out after ${options.timeoutMs} ms\n`;
|
|
184
|
+
timer = setTimeout(() => finish(() => resolve({ expired: { exitCode: 124, stdout: "", stderr: note, timedOut: true } }), true), options.timeoutMs);
|
|
185
|
+
}
|
|
186
|
+
created.then((result) => finish(() => resolve(result), false), (error) => finish(() => reject(error), false));
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Removes every container of this sandbox until none is left. A client stopped while the daemon was creating its
|
|
191
|
+
* container can leave one behind, and a removal can take a while on a slow storage driver, so it waits for the last to go.
|
|
192
|
+
* With no creation left in the background, an empty first pass ends it.
|
|
193
|
+
*/
|
|
194
|
+
async sweep() {
|
|
195
|
+
const deadline = Date.now() + SWEEP_MAX_MS;
|
|
196
|
+
let quiet = 0;
|
|
197
|
+
for (;;) {
|
|
198
|
+
const left = await this.client(["ps", "--all", "--quiet", "--filter", `label=${this.state.label}`], DAEMON_TIMEOUT_MS)
|
|
199
|
+
.then((result) => result.stdout.split("\n").filter((id) => id !== ""))
|
|
200
|
+
.catch(() => []);
|
|
201
|
+
quiet = left.length === 0 ? quiet + 1 : 0;
|
|
202
|
+
if (left.length > 0)
|
|
203
|
+
await this.client(["rm", "--force", ...left], DAEMON_TIMEOUT_MS).catch(() => undefined);
|
|
204
|
+
if ((left.length === 0 && (!this.abandoned || quiet >= SWEEP_QUIET_PASSES)) || Date.now() > deadline)
|
|
205
|
+
return;
|
|
206
|
+
await new Promise((resolve) => setTimeout(resolve, SWEEP_PAUSE_MS));
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* The policy the mounts and flags apply, which are what every command's container is created with. The network is
|
|
211
|
+
* closed unless the caller mounted a proxy socket, and then the proxy on it enforces the requested allowlist. A
|
|
212
|
+
* read-only mount the request doesn't explain reads back as a read root it didn't ask for.
|
|
213
|
+
*
|
|
214
|
+
* One narrowing is not caught: a write root that the caller's `denyWrite` names exactly is mounted read-only but still
|
|
215
|
+
* reads back as a write root, because the read-back takes the caller's own `denyWrite` as part of the request. So
|
|
216
|
+
* `provision()` accepts it, and nothing in that root is writable inside the container.
|
|
217
|
+
*/
|
|
218
|
+
async readBack() {
|
|
219
|
+
this.live();
|
|
220
|
+
const { mounts, names, flags } = this.state;
|
|
221
|
+
const own = mounts.filter((mount) => mount.to !== DOCKER_PROXY_SOCKET_PATH);
|
|
222
|
+
// A write root that the caller's own denyWrite made read-only is still the root the request asked for.
|
|
223
|
+
const granted = (mount) => !mount.readOnly || (names.implicit.has(mount.from) && names.write.has(mount.from));
|
|
224
|
+
const writable = own.filter(granted).map((mount) => mount.from);
|
|
225
|
+
const inWritable = (path) => writable.some((root) => inside(this.state.modules, root, path));
|
|
226
|
+
const readable = (real) => names.missing.has(real) || inWritable(real) || own.some((m) => m.from === real);
|
|
227
|
+
const unexplained = own
|
|
228
|
+
.filter((mount) => mount.readOnly && !names.readReal.includes(mount.from))
|
|
229
|
+
.map((mount) => mount.from)
|
|
230
|
+
.filter((from) => !names.implicit.has(from) && !inWritable(from));
|
|
231
|
+
const closed = flags.join(" ").includes("--network none");
|
|
232
|
+
const proxied = mounts.length !== own.length;
|
|
233
|
+
return {
|
|
234
|
+
readRoots: [
|
|
235
|
+
...names.requested.readRoots.filter((_, index) => readable(names.readReal[index] ?? "")),
|
|
236
|
+
...unexplained,
|
|
237
|
+
],
|
|
238
|
+
writeRoots: writable.flatMap((path) => names.write.get(path) ?? [path]),
|
|
239
|
+
network: !closed
|
|
240
|
+
? { allow: ["*"], deny: [] }
|
|
241
|
+
: proxied
|
|
242
|
+
? names.requested.network
|
|
243
|
+
: { allow: [], deny: names.requested.network.deny },
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
async shutDown() {
|
|
247
|
+
await this.runner.stopAll();
|
|
248
|
+
await Promise.allSettled([...this.pending]);
|
|
249
|
+
await this.sweep();
|
|
250
|
+
await this.state.modules.fs.rm(this.state.folder, { recursive: true, force: true });
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
/** Throws unless `image` is a name `docker run` takes as an image and not as an option. */
|
|
254
|
+
function checkOptionValues(options) {
|
|
255
|
+
const { image, cpus, memoryMb, pidsLimit, user } = options;
|
|
256
|
+
if (typeof image !== "string" || image === "" || /\s/.test(image) || image.startsWith("-")) {
|
|
257
|
+
throw new HarnessError("invalid_sandbox_options", "dockerSandbox needs an image name, such as one pinned by digest");
|
|
258
|
+
}
|
|
259
|
+
const bad = (what) => new HarnessError("invalid_sandbox_options", `${what} is not usable`);
|
|
260
|
+
if (cpus !== undefined && !(Number.isFinite(cpus) && cpus > 0))
|
|
261
|
+
throw bad("cpus");
|
|
262
|
+
if (memoryMb !== undefined && !(Number.isInteger(memoryMb) && memoryMb >= 6))
|
|
263
|
+
throw bad("memoryMb");
|
|
264
|
+
if (pidsLimit !== undefined && !(Number.isInteger(pidsLimit) && pidsLimit >= 1))
|
|
265
|
+
throw bad("pidsLimit");
|
|
266
|
+
if (user !== undefined && !/^[0-9]+(:[0-9]+)?$/.test(user))
|
|
267
|
+
throw bad("user");
|
|
268
|
+
}
|
|
269
|
+
/** The sockets a Docker client may use: the default ones, and the one `dockerHost` names when it is a Unix socket. */
|
|
270
|
+
function daemonSockets(dockerHost) {
|
|
271
|
+
const named = dockerHost?.startsWith("unix://") ? [dockerHost.slice("unix://".length)] : [];
|
|
272
|
+
return ["/var/run/docker.sock", "/run/docker.sock", ...named];
|
|
273
|
+
}
|
|
274
|
+
/** Throws unless every source is mountable, and none is `/` or holds a Docker daemon socket, which would hand over the host. */
|
|
275
|
+
async function checkSources(modules, sources, dockerHost) {
|
|
276
|
+
for (const from of sources) {
|
|
277
|
+
if (!MOUNTABLE.test(from)) {
|
|
278
|
+
throw new HarnessError("invalid_sandbox_options", `a mounted folder can't have a comma or quote: ${from}`);
|
|
279
|
+
}
|
|
280
|
+
if (from === "/")
|
|
281
|
+
throw new HarnessError("invalid_sandbox_options", "a mounted folder can't resolve to /");
|
|
282
|
+
}
|
|
283
|
+
for (const socket of daemonSockets(dockerHost)) {
|
|
284
|
+
const real = await modules.fs.realpath(socket).catch(() => undefined);
|
|
285
|
+
if (real !== undefined && sources.some((from) => inside(modules, from, real))) {
|
|
286
|
+
throw new HarnessError("invalid_sandbox_options", `a mounted folder would hold the Docker socket ${socket}`);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
/** One mount for each destination, read-only when any of the mounts for it is. */
|
|
291
|
+
function onePerDestination(mounts) {
|
|
292
|
+
const byDestination = new Map();
|
|
293
|
+
for (const mount of mounts) {
|
|
294
|
+
const earlier = byDestination.get(mount.to);
|
|
295
|
+
byDestination.set(mount.to, earlier === undefined ? mount : { ...mount, readOnly: earlier.readOnly || mount.readOnly });
|
|
296
|
+
}
|
|
297
|
+
return [...byDestination.values()];
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* The real mounts for a policy: write roots writable, read roots and extras read-only, and read-only again on top the
|
|
301
|
+
* `denyWrite` folders inside a write root (made after the checks, so a later write can't find them writable) and the
|
|
302
|
+
* protected files that exist. A `denyWrite` path outside every write root is not mounted: nothing there is writable.
|
|
303
|
+
*/
|
|
304
|
+
async function planMounts(modules, policy, options) {
|
|
305
|
+
const real = (paths) => Promise.all(paths.map((path) => realOrSelf(modules, path)));
|
|
306
|
+
const [readRoots, writeRoots, extra, denyWrite] = await Promise.all([
|
|
307
|
+
real(policy.readRoots),
|
|
308
|
+
real(policy.writeRoots),
|
|
309
|
+
real(options.extraReadRoots ?? []),
|
|
310
|
+
real(options.denyWrite ?? []),
|
|
311
|
+
]);
|
|
312
|
+
for (const root of writeRoots) {
|
|
313
|
+
if (!(await modules.fs.stat(root).catch(() => undefined))?.isDirectory()) {
|
|
314
|
+
throw new HarnessError("invalid_sandbox_options", `a write root must be an existing folder: ${root}`);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
const underWrite = (path) => writeRoots.some((root) => inside(modules, root, path));
|
|
318
|
+
const denied = denyWrite.filter(underWrite);
|
|
319
|
+
const protectedPaths = writeRoots.flatMap((root) => PROTECTED_TOP_LEVEL.map((name) => modules.path.join(root, name)));
|
|
320
|
+
const readOnlyRoots = [...readRoots, ...extra].filter((path) => !underWrite(path));
|
|
321
|
+
// One look at which read roots exist feeds both the mounts and the names, so a folder made in between can't make them
|
|
322
|
+
// disagree.
|
|
323
|
+
const present = await existing(modules, readOnlyRoots);
|
|
324
|
+
const base = [
|
|
325
|
+
...writeRoots.map((from) => ({ from, to: from, readOnly: false })),
|
|
326
|
+
...present.map((from) => ({ from, to: from, readOnly: true })),
|
|
327
|
+
];
|
|
328
|
+
const protectedPresent = await existing(modules, protectedPaths);
|
|
329
|
+
const guarded = [...denied, ...protectedPresent].map((from) => ({ from, to: from, readOnly: true }));
|
|
330
|
+
const names = {
|
|
331
|
+
requested: policy,
|
|
332
|
+
readReal: readRoots,
|
|
333
|
+
write: spellings(writeRoots, policy.writeRoots),
|
|
334
|
+
missing: new Set(readOnlyRoots.filter((path) => !present.includes(path))),
|
|
335
|
+
implicit: new Set([...extra, ...denied, ...protectedPresent]),
|
|
336
|
+
};
|
|
337
|
+
return {
|
|
338
|
+
base: onePerDestination(base),
|
|
339
|
+
mounts: onePerDestination([...base, ...guarded]),
|
|
340
|
+
roots: { read: readRoots, write: writeRoots, denyWrite: denied },
|
|
341
|
+
names,
|
|
342
|
+
};
|
|
343
|
+
}
|
|
344
|
+
/** The `docker run` flags that lock a container down, and limit what it may use. */
|
|
345
|
+
function lockdownFlags(options, user) {
|
|
346
|
+
const memory = `${options.memoryMb ?? DEFAULTS.memoryMb}m`;
|
|
347
|
+
return [
|
|
348
|
+
"--pull",
|
|
349
|
+
"never",
|
|
350
|
+
"--network",
|
|
351
|
+
"none",
|
|
352
|
+
"--read-only",
|
|
353
|
+
"--cap-drop",
|
|
354
|
+
"ALL",
|
|
355
|
+
"--security-opt",
|
|
356
|
+
"no-new-privileges",
|
|
357
|
+
"--ipc",
|
|
358
|
+
"none",
|
|
359
|
+
"--pids-limit",
|
|
360
|
+
String(options.pidsLimit ?? DEFAULTS.pidsLimit),
|
|
361
|
+
"--cpus",
|
|
362
|
+
String(options.cpus ?? DEFAULTS.cpus),
|
|
363
|
+
"--memory",
|
|
364
|
+
memory,
|
|
365
|
+
"--memory-swap",
|
|
366
|
+
memory,
|
|
367
|
+
"--user",
|
|
368
|
+
user,
|
|
369
|
+
// The only writable place that isn't a mounted write root: memory-backed, so it is gone with the container.
|
|
370
|
+
"--tmpfs",
|
|
371
|
+
"/tmp:rw,nosuid,size=64m",
|
|
372
|
+
];
|
|
373
|
+
}
|
|
374
|
+
/** The `docker` executable, or a `SandboxUnavailableError` when there is none. */
|
|
375
|
+
async function dockerProgram(modules, options, hostPath) {
|
|
376
|
+
if (options.binary !== undefined) {
|
|
377
|
+
const program = modules.path.resolve(options.binary);
|
|
378
|
+
await modules.fs.access(program, modules.fs.constants.X_OK).catch((error) => {
|
|
379
|
+
throw new SandboxUnavailableError("docker", `${options.binary} is not an executable file`, { cause: error });
|
|
380
|
+
});
|
|
381
|
+
return program;
|
|
382
|
+
}
|
|
383
|
+
const found = await findOnPath(modules, hostPath, "docker");
|
|
384
|
+
if (found === undefined)
|
|
385
|
+
throw new SandboxUnavailableError("docker", "docker is not on the PATH");
|
|
386
|
+
return found;
|
|
387
|
+
}
|
|
388
|
+
/** The first line of what a client printed, for the message of a failure. */
|
|
389
|
+
const firstLine = (text) => text.trim().split("\n")[0] ?? "no output";
|
|
390
|
+
/**
|
|
391
|
+
* Builds the Docker backend. `provision()` checks the platform, the `docker` client, the daemon and that the image is on
|
|
392
|
+
* the host, so a host that can't run the container throws `SandboxUnavailableError` and runs nothing. The `docker`
|
|
393
|
+
* client runs with a clean environment: a `PATH`, a private empty `HOME` and `DOCKER_HOST` when one is set, and never
|
|
394
|
+
* the parent's environment. The policy's roots, `extraReadRoots`, `denyWrite` and `proxySocket` must be absolute, and
|
|
395
|
+
* the workspace must lie inside a root. A command whose first word contains `=` resolves with exit code 127, as under
|
|
396
|
+
* `none`. Before it returns, `provision()` reads back the policy its mounts and flags apply and throws
|
|
397
|
+
* `SandboxPolicyMismatchError` on a difference. Without `proxySocket` the container reaches no host, so a policy whose
|
|
398
|
+
* `network.allow` names one is refused. The backend lists no capability: it can't resume, snapshot or pause.
|
|
399
|
+
*/
|
|
400
|
+
export function dockerSandbox(options) {
|
|
401
|
+
checkOptionValues(options);
|
|
402
|
+
const client = {
|
|
403
|
+
tier: "container",
|
|
404
|
+
stops: ["mistakes", "exfiltration"],
|
|
405
|
+
async provision(manifest, policy) {
|
|
406
|
+
const modules = nodeModules("docker");
|
|
407
|
+
if (process.platform !== "linux") {
|
|
408
|
+
throw new SandboxUnavailableError("docker", `only Linux is supported, because it is the only platform this backend is tested on, and this is ${process.platform}`);
|
|
409
|
+
}
|
|
410
|
+
const hostPath = absolutePath(modules, process.env.PATH);
|
|
411
|
+
const docker = await dockerProgram(modules, options, hostPath);
|
|
412
|
+
const root = await workspaceRoot(modules, manifest.root);
|
|
413
|
+
checkPaths(modules, [...policy.readRoots, ...policy.writeRoots], "a sandbox root");
|
|
414
|
+
checkPaths(modules, options.extraReadRoots ?? [], "an extra read root");
|
|
415
|
+
checkPaths(modules, options.denyWrite ?? [], "a denyWrite folder");
|
|
416
|
+
const folder = await modules.fs.mkdtemp(modules.path.join(modules.os.tmpdir(), "harness-docker-"));
|
|
417
|
+
try {
|
|
418
|
+
return await startSandbox({ modules, docker, hostPath, root, folder, manifest, policy, options, client });
|
|
419
|
+
}
|
|
420
|
+
catch (error) {
|
|
421
|
+
await modules.fs.rm(folder, { recursive: true, force: true });
|
|
422
|
+
throw error;
|
|
423
|
+
}
|
|
424
|
+
},
|
|
425
|
+
};
|
|
426
|
+
return client;
|
|
427
|
+
}
|
|
428
|
+
async function startSandbox(input) {
|
|
429
|
+
const { modules, options } = input;
|
|
430
|
+
await modules.fs.chmod(input.folder, 0o700);
|
|
431
|
+
const home = modules.path.join(input.folder, "home");
|
|
432
|
+
await modules.fs.mkdir(home, { mode: 0o700 });
|
|
433
|
+
const dockerHost = options.dockerHost ?? process.env.DOCKER_HOST;
|
|
434
|
+
const clientEnv = {
|
|
435
|
+
PATH: input.hostPath,
|
|
436
|
+
HOME: home,
|
|
437
|
+
...(dockerHost === undefined ? {} : { DOCKER_HOST: dockerHost }),
|
|
438
|
+
};
|
|
439
|
+
const plan = await planMounts(modules, input.policy, options);
|
|
440
|
+
await checkSources(modules, plan.mounts.map((mount) => mount.from), dockerHost);
|
|
441
|
+
if (!plan.base.some((mount) => inside(modules, mount.from, input.root))) {
|
|
442
|
+
throw new HarnessError("invalid_sandbox_options", "the workspace root must lie inside a read or write root");
|
|
443
|
+
}
|
|
444
|
+
const mounts = [...plan.mounts];
|
|
445
|
+
if (options.proxySocket !== undefined) {
|
|
446
|
+
checkPaths(modules, [options.proxySocket], "the proxy socket");
|
|
447
|
+
const stats = await modules.fs.stat(options.proxySocket).catch(() => undefined);
|
|
448
|
+
if (!stats?.isSocket())
|
|
449
|
+
throw new HarnessError("invalid_sandbox_options", "proxySocket must be a Unix socket");
|
|
450
|
+
const from = await modules.fs.realpath(options.proxySocket);
|
|
451
|
+
await checkSources(modules, [from], dockerHost);
|
|
452
|
+
mounts.push({ from, to: DOCKER_PROXY_SOCKET_PATH, readOnly: false });
|
|
453
|
+
}
|
|
454
|
+
const user = options.user ?? `${process.getuid?.() ?? 0}:${process.getgid?.() ?? 0}`;
|
|
455
|
+
const sandbox = new DockerSandbox({
|
|
456
|
+
modules,
|
|
457
|
+
docker: input.docker,
|
|
458
|
+
image: options.image,
|
|
459
|
+
root: input.root,
|
|
460
|
+
files: new HostFiles(modules, input.root, plan.roots, isProtectedPath),
|
|
461
|
+
mounts,
|
|
462
|
+
flags: lockdownFlags(options, user),
|
|
463
|
+
clientEnv,
|
|
464
|
+
folder: input.folder,
|
|
465
|
+
label: `harness.sandbox=harness-${modules.path.basename(input.folder).slice("harness-docker-".length)}`,
|
|
466
|
+
names: plan.names,
|
|
467
|
+
});
|
|
468
|
+
await probe(sandbox, options.image);
|
|
469
|
+
await sandbox.confirm(input.client, input.policy);
|
|
470
|
+
for (const folder of plan.roots.denyWrite)
|
|
471
|
+
await modules.fs.mkdir(folder, { recursive: true });
|
|
472
|
+
const encoder = new TextEncoder();
|
|
473
|
+
for (const [path, data] of Object.entries(input.manifest.files ?? {})) {
|
|
474
|
+
await sandbox.writeFile(path, typeof data === "string" ? encoder.encode(data) : data);
|
|
475
|
+
}
|
|
476
|
+
return sandbox;
|
|
477
|
+
}
|
|
478
|
+
/** Asks the daemon for its version and for the image, and throws `SandboxUnavailableError` when either fails. */
|
|
479
|
+
async function probe(sandbox, image) {
|
|
480
|
+
const unavailable = (reason, cause) => new SandboxUnavailableError("docker", reason, { cause });
|
|
481
|
+
const version = await sandbox
|
|
482
|
+
.client(["version", "--format", "{{.Server.Version}}"], DAEMON_TIMEOUT_MS)
|
|
483
|
+
.catch((error) => {
|
|
484
|
+
throw unavailable("the docker client could not be started", error);
|
|
485
|
+
});
|
|
486
|
+
if (version.exitCode !== 0)
|
|
487
|
+
throw unavailable(`the daemon did not answer: ${firstLine(version.stderr)}`);
|
|
488
|
+
const found = await sandbox
|
|
489
|
+
.client(["image", "inspect", "--format", "{{.Id}}", image], DAEMON_TIMEOUT_MS)
|
|
490
|
+
.catch((error) => {
|
|
491
|
+
throw unavailable("the docker client could not be started", error);
|
|
492
|
+
});
|
|
493
|
+
if (found.exitCode !== 0) {
|
|
494
|
+
throw unavailable(`the image ${image} is not on the Docker host, and provision never pulls: pull it first`);
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
//# sourceMappingURL=index.js.map
|