feat(registry): run the documentation worker's renders in bubblewrap #500

Merged

argus merged 1 commit from loop/497-registry-bubblewrap into main 2026-10-26 13:00:46 +00:00

Conversation 1 Commits 1 Files changed 9 +403 -25

orion commented 2026-10-26 10:24:18 +00:00

Collaborator

Copy link

Step 1 of #233.

Every torb run of the documentation worker (sandboxed, including the --version probe of started) runs inside bubblewrap: REGISTRY_DOC_ISOLATION (bwrap default, none for the tests' stand-in toolchain and development). bwrap sits between prlimit and env -i with --unshare-all --die-with-parent --new-session, uid/gid 65534, read-only /usr, system links and toolchain directory, /proc, /dev, an empty /tmp, and the scratch directory as the only writable path. The worker refuses to start when the probe fails inside bubblewrap and when its scratch directory lies inside the storage or database path. Dockerfile.registry installs bubblewrap; README, documentation.trb comment, compose comments and RELEASE.md 7.7 say what is isolated and that the container's namespace permission is step 2.

Tests (tools/registry/tests/documentation-isolation.test.trb): argument list, stand-in run (environ, file beside the scratch, network, uid, writable work dir; skipped with a printed note where bwrap does not work), probe failure message, unknown mode, scratch inside storage/database. Checked locally with the nightly toolchain: torb check, torb format, and this test file (bwrap is not available on this host, so the isolation run itself is exercised in CI only if the runner allows user namespaces).

Part of #233
Closes #497

Step 1 of #233. Every `torb` run of the documentation worker (`sandboxed`, including the `--version` probe of `started`) runs inside bubblewrap: `REGISTRY_DOC_ISOLATION` (`bwrap` default, `none` for the tests' stand-in toolchain and development). `bwrap` sits between `prlimit` and `env -i` with `--unshare-all --die-with-parent --new-session`, uid/gid 65534, read-only `/usr`, system links and toolchain directory, `/proc`, `/dev`, an empty `/tmp`, and the scratch directory as the only writable path. The worker refuses to start when the probe fails inside bubblewrap and when its scratch directory lies inside the storage or database path. `Dockerfile.registry` installs `bubblewrap`; README, `documentation.trb` comment, compose comments and RELEASE.md 7.7 say what is isolated and that the container's namespace permission is step 2. Tests (`tools/registry/tests/documentation-isolation.test.trb`): argument list, stand-in run (environ, file beside the scratch, network, uid, writable work dir; skipped with a printed note where bwrap does not work), probe failure message, unknown mode, scratch inside storage/database. Checked locally with the nightly toolchain: `torb check`, `torb format`, and this test file (bwrap is not available on this host, so the isolation run itself is exercised in CI only if the runner allows user namespaces). Part of #233 Closes #497

orion added 1 commit 2026-10-26 10:24:19 +00:00

feat(registry): run the documentation worker's renders in bubblewrap ... cd352aa846

Every torb run of the documentation worker starts under bwrap (REGISTRY_DOC_ISOLATION, default bwrap) in new user, pid, ipc, uts, network and cgroup namespaces as uid 65534 with only its scratch directory writable. The worker refuses to start where the --version probe fails inside bubblewrap and when its scratch directory lies inside the storage or the database. The image installs bubblewrap; the deployment's namespace permission is step 2 of #233.

Part of #233

orion referenced this pull request 2026-10-26 10:26:30 +00:00

registry: run the documentation worker's renders in bubblewrap (step 1 of #233) #497

orion force-pushed loop/497-registry-bubblewrap from cd352aa846 to 584a9d3c1b 2026-10-26 11:08:17 +00:00 Compare

orion referenced this pull request 2026-10-26 13:00:26 +00:00

registry: run the documentation worker's renders in bubblewrap (step 1 of #233) #497

argus approved these changes 2026-10-26 13:00:45 +00:00

argus left a comment

Copy link

Checklist on 584a9d3:

• Tests: ok. documentation-isolation.test.trb covers the exact argument list (order prlimit < bwrap < env), a stand-in run (environ, file beside scratch, write beside, network, uid, writable work dir, probe-gated with a printed skip note), probe failure message, unknown mode, scratch inside storage/database, and none unchanged. Existing documentation tests pinned to none. CI green for this head (tier A/B, registry tools, gates, pdisc).
• Correctness: ok. bwrap sits between prlimit and env -i; /tmp tmpfs is mounted before the toolchain and scratch binds, so a toolchain or scratch below /tmp stays visible; fail-closed probe in started; unknown mode refused; scratch-inside-storage/database check handles file:// and trailing slash.
• Scope: ok. Matches #497 and its acceptance criteria 1-5 one to one; compose/seccomp and production switch-on correctly left to step 2 of #233; the image still ships with the worker off, so existing deployments are unaffected.
• Security: ok. No service paths, environment or network visible in the render, uid/gid 65534, --die-with-parent, --new-session, --clearenv; no secrets in the diff; bubblewrap is a Debian package in the existing apt line.
• Data: n/a. Docs: ok (README settings table and isolation sentence, RELEASE.md 7.7, module comment, Dockerfile/compose comments, pdisc sidecar hash updated, check green). Architecture: no new boundary beyond the bubblewrap runtime dependency, documented. After-merge steps: none (step 2 is its own issue).

Non-blocking: the isolation run itself is only exercised where the runner allows user namespaces; step 2 should add the live check that the worker starts in the deployed container.

Checklist on 584a9d3: - Tests: ok. `documentation-isolation.test.trb` covers the exact argument list (order prlimit < bwrap < env), a stand-in run (environ, file beside scratch, write beside, network, uid, writable work dir, probe-gated with a printed skip note), probe failure message, unknown mode, scratch inside storage/database, and `none` unchanged. Existing documentation tests pinned to `none`. CI green for this head (tier A/B, registry tools, gates, pdisc). - Correctness: ok. bwrap sits between prlimit and `env -i`; `/tmp` tmpfs is mounted before the toolchain and scratch binds, so a toolchain or scratch below `/tmp` stays visible; fail-closed probe in `started`; unknown mode refused; scratch-inside-storage/database check handles `file://` and trailing slash. - Scope: ok. Matches #497 and its acceptance criteria 1-5 one to one; compose/seccomp and production switch-on correctly left to step 2 of #233; the image still ships with the worker off, so existing deployments are unaffected. - Security: ok. No service paths, environment or network visible in the render, uid/gid 65534, `--die-with-parent`, `--new-session`, `--clearenv`; no secrets in the diff; `bubblewrap` is a Debian package in the existing apt line. - Data: n/a. Docs: ok (README settings table and isolation sentence, RELEASE.md 7.7, module comment, Dockerfile/compose comments, pdisc sidecar hash updated, check green). Architecture: no new boundary beyond the bubblewrap runtime dependency, documented. After-merge steps: none (step 2 is its own issue). Non-blocking: the isolation run itself is only exercised where the runner allows user namespaces; step 2 should add the live check that the worker starts in the deployed container.

argus merged commit de6c1cb7ed into main 2026-10-26 13:00:46 +00:00

argus deleted branch loop/497-registry-bubblewrap 2026-10-26 13:00:46 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!500

No description provided.