@kana-ai/edgar-ext-docker 0.1.4 → 0.1.6

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 CHANGED
@@ -4,7 +4,7 @@ The Docker extension of EDGAR. Its environment `compose` starts a service's Dock
4
4
 
5
5
  ## Steps
6
6
 
7
- The engine runs the four steps around the checks of a `check` stage: `stop`, `prepare`, `start`, `health`, then the checks, then `stop` again, also after a failed step. Each step runs `docker compose` in the run's checkout, where the Compose file of the service is.
7
+ The engine runs the four steps around the checks of a `check` stage: `stop`, `prepare`, `start`, `health`, then the checks, then `stop` again, also after a failed step. Each step runs `docker compose` in the run's checkout, where the Compose file of the service is, on the machine itself and outside the run's command sandbox, so the stack starts whatever `[sandbox] kind` and `[sandbox] deny` say, while the run's agents and checks reach no Docker daemon.
8
8
 
9
9
  | Step | What it runs | Fails when |
10
10
  | --------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -13,7 +13,7 @@ The engine runs the four steps around the checks of a `check` stage: `stop`, `pr
13
13
  | `health` | `docker compose ps --all --format json` | A container is not running and healthy. A one-off job, such as a migration, may end with 0. |
14
14
  | `stop` | `docker compose down --volumes --remove-orphans --rmi local` | Docker does not answer. A stack that is not up is already stopped, so `stop` is safe to repeat. |
15
15
 
16
- Each stack is its own Compose project, `edgar-<service>-<run>`, so two runs never share a container, a network or a volume. `start` answers the stack's default network, `edgar-<service>-<run>_default`, which the rules keep internal. With `[sandbox] kind = "container"`, each check of the stage joins that network, so a check reaches a service by its name, such as `curl -f http://api:8080/health`, and reaches nothing outside the stack. A stack with no service on its default network answers no network, and its checks stay on none. One stack of a service is up at a time. A health check in the Compose file says when the service is ready, for example a `curl` of its address. `start` waits for it.
16
+ Each stack is its own Compose project, `edgar-<service>-<run>`, so two runs never share a container, a network or a volume. `start` answers the stack's default network, `edgar-<service>-<run>_default`, which the rules keep internal. With `[sandbox] kind = "container"`, each check of the stage joins that network, so a check reaches a service by its name, such as `curl -f http://api:8080/health`, and reaches nothing outside the stack. With `kind = "worktree"` the stack starts, but a check has no network to reach it. A stack with no service on its default network answers no network, and its checks stay on none. One stack of a service is up at a time. A health check in the Compose file says when the service is ready, for example a `curl` of its address. `start` waits for it.
17
17
 
18
18
  The Compose file comes from the run's checkout, and a stage can change it on its branch, so `prepare` and `start` each read the file as `docker compose config --no-env-resolution` writes it, with each `env_file` kept as its path, and refuse what gives a container more than its own share of the machine. The rules are a list of what a stack may use, so a key that is not on it, including one that Compose adds later, is refused:
19
19
 
@@ -102,14 +102,18 @@ A log can hold secrets and personal data, so the tool reads only the containers
102
102
  environment = { provider = "docker__compose" }
103
103
  ```
104
104
 
105
- 2. Approve its capabilities. The manifest declares `sandbox:read` and `sandbox:write`, no secret and no network:
105
+ 2. Approve its capabilities. The manifest declares `sandbox:read`, `sandbox:write` (for `read_logs`) and `environment:docker` (for the steps), no secret and no network:
106
106
 
107
107
  ```sh
108
108
  edgar extensions approve docker
109
109
  ```
110
110
 
111
- The environment needs a Docker daemon that the sandbox reaches. Whoever enables it gives each run that daemon. The rules above check the stack that the environment's steps start. They do not check a command of a role that reaches the same daemon, as each command does with `[sandbox] kind = "none"`, and access to a Docker daemon is the same as root on the machine that runs the daemon. So use this environment with `kind = "none"` only on a machine for development or tests. Only the services on the network `edge` can reach outside the machine.
111
+ The steps reach the Docker daemon that EDGAR itself reaches: they run as EDGAR's own process, with its `HOME`, its temporary folder and its `DOCKER_HOST`, `DOCKER_CONTEXT`, `DOCKER_CONFIG`, `DOCKER_CERT_PATH` and `DOCKER_TLS_VERIFY`, and with the service's own variables, never the sandbox's `home/`. The capability `environment:docker` lets a step run only its own stack's commands there, and EDGAR checks each one first: the `docker compose` commands of the table above on the project `edgar-<service>-<run>`, with a Compose file inside the checkout; `docker volume inspect` and the copy of a volume of `save`; and `readlink -f`, which resolves the Compose file's paths where Docker reads them. Any other command of a step goes to the run's sandbox, which the steps do not hold, so it is refused. The run's agents, checks and tools never get the daemon: with `[sandbox] kind = "worktree"` or `"container"` and a `[sandbox] deny` entry `docker`, they reach no Docker at all. With `kind = "none"` each command of a role runs on the machine and can reach the daemon itself, and access to a Docker daemon is the same as root on the machine that runs the daemon, so use `kind = "none"` only on a machine for development or tests. Only the services on the network `edge` can reach outside the machine.
112
+
113
+ The same approval lets EDGAR build the image of a check that sets `dockerfile`, such as `checks.base_image = { dockerfile = "Dockerfile.base" }`. EDGAR runs that build itself, with no push and no secret, checks the Dockerfile and its folder first, and removes the image after. See [Image checks](/docs/guides/config.md#image-checks).
114
+
115
+ The steps read the checkout as it is on the machine, so a Compose file can read a `[sandbox] secret_files` file of the checkout, which the run's commands see empty. Keep secrets out of the files a stack's Compose file reads.
112
116
 
113
117
  The steps need a Docker Compose release whose `config` has `--no-env-resolution`. With an older one, each step fails and nothing starts.
114
118
 
115
- `edgar check` refuses the project when `docker` is not on `PATH`, because the extension declares it in `executables.requires`. The sandbox must reach the Docker daemon: with `[sandbox] kind = "none"` the steps use the machine's Docker. A secret of the stack goes in the service's own environment, never in the Compose file or its `.env`.
119
+ `edgar check` refuses the project when `docker` is not on `PATH`, because the extension declares it in `executables.requires`. `read_logs` runs `docker logs` in the run's sandbox, so it still needs a sandbox that reaches the daemon, such as `kind = "none"`. A secret of the stack goes in the service's own environment, never in the Compose file or its `.env`.
@@ -1,5 +1,5 @@
1
1
  import { type Capability } from "@kana-ai/edgar-sdk";
2
- /** The steps run `docker compose` in the checkout of the run, where the service's Compose file is. */
2
+ /** The steps run `docker compose` in the checkout of the run, where the service's Compose file is, on the machine and outside the command sandbox, so a run's own commands never reach the Docker daemon. */
3
3
  export declare const access: readonly Capability[];
4
4
  /** The `compose` environment: a service's Docker Compose stack, up while the stage's checks run. */
5
5
  export declare const composeEnvironment: import("@kana-ai/edgar-sdk").Environment;
@@ -4,8 +4,8 @@ import { container, composeConfig, stepInput, stepOutput, } from "#schemas/compo
4
4
  import { readConfig } from "#schemas/config";
5
5
  import { compose, copyVolume, json, project, realPaths, rows, savedVolume, volumeExists, } from "#stack/compose";
6
6
  import { hostPaths, notUp, refusals } from "#stack/rules";
7
- /** The steps run `docker compose` in the checkout of the run, where the service's Compose file is. */
8
- export const access = ["sandbox:read", "sandbox:write"];
7
+ /** The steps run `docker compose` in the checkout of the run, where the service's Compose file is, on the machine and outside the command sandbox, so a run's own commands never reach the Docker daemon. */
8
+ export const access = ["sandbox:read", "environment:docker"];
9
9
  /** The stack of the step's service, its Compose project and the service, or the failure when the input or the `[extensions.docker]` table does not read, or the table names no stack for the service. */
10
10
  function stackOf(raw, ctx) {
11
11
  const input = stepInput.safeParse(raw);
package/dist/src/index.js CHANGED
@@ -6,14 +6,14 @@ import { config } from "#schemas/config";
6
6
  export default defineExtension({
7
7
  name: "docker",
8
8
  config,
9
- capabilities: [...access],
9
+ capabilities: [...access, "sandbox:write"],
10
10
  tools: { read_logs: readLogs },
11
11
  environments: { compose: composeEnvironment },
12
12
  executables: {
13
13
  requires: [
14
14
  {
15
15
  name: "docker",
16
- reason: "The environment compose runs docker compose, and read_logs runs docker logs, in the sandbox of the run.",
16
+ reason: "The environment compose runs docker compose on the machine, in the checkout of the run, and read_logs runs docker logs in the sandbox of the run.",
17
17
  },
18
18
  ],
19
19
  },
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "contract": 1,
3
3
  "name": "docker",
4
- "version": "0.1.4",
4
+ "version": "0.1.6",
5
5
  "config_schema": "schemas/config.json",
6
6
  "secrets": [],
7
- "capabilities": ["sandbox:read", "sandbox:write"],
7
+ "capabilities": ["sandbox:read", "environment:docker", "sandbox:write"],
8
8
  "tools": [
9
9
  {
10
10
  "name": "read_logs",
@@ -31,28 +31,28 @@
31
31
  "input_schema": "schemas/environment.compose.prepare.in.json",
32
32
  "output_schema": "schemas/environment.compose.prepare.out.json",
33
33
  "secrets": [],
34
- "capabilities": ["sandbox:read", "sandbox:write"]
34
+ "capabilities": ["sandbox:read", "environment:docker"]
35
35
  },
36
36
  "start": {
37
37
  "description": "Start the stack and wait until it is healthy",
38
38
  "input_schema": "schemas/environment.compose.start.in.json",
39
39
  "output_schema": "schemas/environment.compose.start.out.json",
40
40
  "secrets": [],
41
- "capabilities": ["sandbox:read", "sandbox:write"]
41
+ "capabilities": ["sandbox:read", "environment:docker"]
42
42
  },
43
43
  "health": {
44
44
  "description": "Check that each container of the stack is up",
45
45
  "input_schema": "schemas/environment.compose.health.in.json",
46
46
  "output_schema": "schemas/environment.compose.health.out.json",
47
47
  "secrets": [],
48
- "capabilities": ["sandbox:read", "sandbox:write"]
48
+ "capabilities": ["sandbox:read", "environment:docker"]
49
49
  },
50
50
  "stop": {
51
51
  "description": "Remove the stack's containers, networks, volumes and built images",
52
52
  "input_schema": "schemas/environment.compose.stop.in.json",
53
53
  "output_schema": "schemas/environment.compose.stop.out.json",
54
54
  "secrets": [],
55
- "capabilities": ["sandbox:read", "sandbox:write"]
55
+ "capabilities": ["sandbox:read", "environment:docker"]
56
56
  }
57
57
  }
58
58
  ],
@@ -61,7 +61,7 @@
61
61
  "requires": [
62
62
  {
63
63
  "name": "docker",
64
- "reason": "The environment compose runs docker compose, and read_logs runs docker logs, in the sandbox of the run."
64
+ "reason": "The environment compose runs docker compose on the machine, in the checkout of the run, and read_logs runs docker logs in the sandbox of the run."
65
65
  }
66
66
  ],
67
67
  "provides": []
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kana-ai/edgar-ext-docker",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "EDGAR extension for Docker: a service's Docker Compose stack as the environment that its checks run against.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -21,11 +21,11 @@
21
21
  ".": "./dist/src/index.js"
22
22
  },
23
23
  "dependencies": {
24
- "@kana-ai/edgar-sdk": "0.1.4",
24
+ "@kana-ai/edgar-sdk": "0.1.6",
25
25
  "zod": "4.6.7"
26
26
  },
27
27
  "devDependencies": {
28
- "@kana-ai/edgar-contracts": "0.1.4",
28
+ "@kana-ai/edgar-contracts": "0.1.6",
29
29
  "@types/node": "24.19.2",
30
30
  "oxfmt": "0.76.0",
31
31
  "oxlint": "1.91.0",