diff --git a/docs/superpowers/plans/2026-07-13-plan-b-container-hardening.md b/docs/superpowers/plans/2026-07-13-plan-b-container-hardening.md index a8d51323..e6855f44 100644 --- a/docs/superpowers/plans/2026-07-13-plan-b-container-hardening.md +++ b/docs/superpowers/plans/2026-07-13-plan-b-container-hardening.md @@ -40,12 +40,21 @@ Create `docker-entrypoint.sh` at the repo root: ```sh #!/bin/sh # Runs as root: make the (bind-mounted, host-owned) data dir writable by the -# non-root runtime user, then drop privileges via gosu and exec the CMD. This -# is what lets the container run as uid 1000 while still owning ./data on hosts -# where the bind mount was created by a different uid. Idempotent. +# non-root `node` user, then drop privileges via gosu and exec the CMD. This +# lets the container run as uid 1000 while still owning ./data on hosts where +# the bind mount was created by a different uid. +# +# - Idempotent AND cheap: only chown entries not already node-owned, so after +# the first boot this is near-instant. A plain `chown -R` over a large +# uploads/ tree on slow Pi/SD storage would delay startup on EVERY restart. +# - Non-fatal: on a bind mount that rejects chown (some CIFS/NFS backings), +# warn and continue rather than crash-looping under `restart: unless-stopped` +# (the old root container booted fine on such mounts). set -e mkdir -p /app/data/uploads -chown -R node:node /app/data +chown node:node /app/data /app/data/uploads 2>/dev/null || true +find /app/data ! -user node -exec chown node:node {} + 2>/dev/null || \ + echo "docker-entrypoint: warning: could not chown /app/data; continuing (ensure it is writable by uid 1000)" exec gosu node "$@" ``` @@ -93,13 +102,19 @@ ENTRYPOINT ["docker-entrypoint.sh"] CMD ["node", "--import", "tsx/esm", "src/index.ts"] ``` -- [ ] **Step 4: Build the image (amd64) and confirm it builds without the toolchain** +- [ ] **Step 4: Build BOTH arches and confirm neither needs the toolchain** -Run (requires Docker daemon): +The runtime stage runs its own `pnpm install --prod` (Dockerfile:61), so better-sqlite3 is installed **per arch** — and the arm64 install runs under QEMU at publish time, the one path that can hard-fail a release. Verify both arches locally before committing. + +Run amd64 (loaded, for the boot test in Step 5): ```bash docker buildx build --platform linux/amd64 --load -t backspace:hardening-test --build-arg BACKSPACE_COMMIT=test . ``` -Expected: build succeeds. **Watch the `pnpm install --prod` output for better-sqlite3:** it should download a prebuilt binary (a `prebuild-install` line), NOT run `node-gyp`/compilation. If it tries to compile and fails (no toolchain), STOP — apply the fallback (re-add the toolchain to the runtime apt-get line, OR copy `packages/server/node_modules/better-sqlite3` from the builder stage) and report which you used and why. +Run arm64 (QEMU; no `--load` since a foreign-arch image can't load into the daemon — building it still exercises the arm64 `pnpm install --prod`): +```bash +docker buildx build --platform linux/arm64 --build-arg BACKSPACE_COMMIT=test -t backspace:arm64-test . +``` +Expected: BOTH builds succeed. **Watch the `pnpm install --prod` output for better-sqlite3 on each arch:** it should download a prebuilt binary (a `prebuild-install` line), NOT run `node-gyp`/compilation. If EITHER arch tries to compile and fails (no toolchain), STOP — apply the fallback (re-add the toolchain to the runtime apt-get line, OR build better-sqlite3 in the builder stage and `COPY --from=builder` its compiled module) and report which arch failed, which fallback you used, and why. Do not proceed on a one-arch pass. - [ ] **Step 5: Boot the container and verify non-root + data volume + DB** @@ -109,17 +124,24 @@ mkdir -p /tmp/bkspace-data docker run -d --name bkspace-htest -e JWT_SECRET=testsecret_at_least_32_chars_long_xx -p 3999:3000 -v /tmp/bkspace-data:/app/data backspace:hardening-test sleep 12 echo "--- health ---"; curl -fsS http://localhost:3999/api/health && echo " OK" -echo "--- process runs as node (uid 1000), not root ---"; docker exec bkspace-htest sh -c 'id' -echo "--- data dir written + owned by node ---"; docker exec bkspace-htest sh -c 'ls -ld /app/data /app/data/uploads && ls -la /app/data' +# IMPORTANT: check PID 1 (the actual server), NOT `docker exec ... id`. `docker exec` +# spawns a NEW process as the image's configured USER (root, since there is no USER +# line), so `exec ... id` prints uid=0 even when the gosu drop worked. /proc/1/status +# is the real server process's identity. +echo "--- server (PID 1) runs as node/uid 1000, not root ---"; docker exec bkspace-htest sh -c "grep '^Uid:' /proc/1/status" +echo "--- data dir written + owned by node ---"; docker exec bkspace-htest sh -c 'ls -ld /app/data /app/data/uploads' echo "--- better-sqlite3 loaded (DB file exists) ---"; docker exec bkspace-htest sh -c 'ls -la /app/data/*.db 2>/dev/null || echo NO_DB' +echo "--- sharp (native, toolchain-sensitive) loads ---"; docker exec bkspace-htest node -e "require('sharp'); console.log('sharp OK')" +echo "--- boot logs clean (no EACCES / permission errors from running non-root) ---"; docker logs bkspace-htest 2>&1 | grep -iE 'EACCES|permission denied|EPERM' && echo "PERMISSION ERRORS FOUND" || echo "logs clean" ``` -Expected: `/api/health` returns ok; `id` shows `uid=1000(node)`; `/app/data` + `/app/data/uploads` exist and are `node`-owned; a `.db` file was created (proves better-sqlite3 loaded and wrote). If the app booted but `id` shows uid=0, the gosu drop failed — fix before proceeding. +Expected: `/api/health` returns ok; `Uid:` line shows `1000 1000 1000 1000` (server runs non-root); `/app/data` + `/app/data/uploads` exist and are `node`-owned; a `.db` file was created (better-sqlite3 loaded and wrote); `sharp OK` prints (the OTHER native module survived the toolchain drop); logs show no permission errors. If any fails, fix before proceeding. - [ ] **Step 6: Tear down the test container** Run: ```bash docker rm -f bkspace-htest; rm -rf /tmp/bkspace-data +docker rmi backspace:hardening-test backspace:arm64-test 2>/dev/null || true ``` - [ ] **Step 7: Commit** @@ -232,7 +254,7 @@ docker buildx build --platform linux/amd64 --load -t backspace:scan --build-arg trivy image --severity HIGH,CRITICAL --ignore-unfixed backspace:scan | tail -25 docker rmi backspace:scan ``` -Expected: the image builds + loads, and Trivy scans it and prints a summary (findings are fine — the scan is report-only; we just need it to RUN). The multi-arch push + SBOM/provenance path cannot be exercised without publishing; note in the report that it is verified by review + a maintainer `workflow_dispatch` run. +Expected: the image builds + loads, and Trivy scans it and prints a summary (findings are fine — the scan is report-only; we just need it to RUN). Note accurately in the report: only the **amd64** image is Trivy-scanned; the published **arm64** image ships unscanned (acceptable for this plan). The multi-arch push + SBOM/provenance path cannot be exercised without publishing — it is verified by review + a maintainer `workflow_dispatch` run; the amd64 layers are gha-cache reused on the push, but the **arm64 layers build cold** there (so the push is not "free"). - [ ] **Step 5: Commit** @@ -253,26 +275,56 @@ git commit -m "ci(docker): scan the amd64 image before publish; attach SBOM + pr - Consumes: the changes from Tasks 1-2. - Produces: an upgrade/migration note + an updated pipeline reference. No code symbols. -- [ ] **Step 1: Add a container-hardening + migration note to deployment.md** +- [ ] **Step 1: Add a container-hardening + migration note to deployment.md AND correct now-false ownership statements** -Read `docs/systems/deployment.md` first to match its structure, then add a subsection (place it near the Docker/image content). Use this content: +Read `docs/systems/deployment.md` first to match its structure. Then: + +(a) Add a subsection (place it near the Docker/image content) with this content: ```markdown ### Container hardening (non-root) The runtime image runs as the unprivileged `node` user (uid 1000), not root. On container start, `docker-entrypoint.sh` runs as root only long enough to `chown` -the `./data` bind mount to `node`, then drops privileges via `gosu` and execs the +the `./data` bind mount to `node` (only entries not already node-owned, so it is +near-instant after the first boot), then drops privileges via `gosu` and execs the server. The build toolchain (`python3`/`make`/`g++`) is not installed in the -runtime stage — `better-sqlite3` loads from its prebuilt binary — which shrinks -the runtime attack surface. `ffmpeg` remains (a real runtime dependency). +runtime stage — `better-sqlite3` and `sharp` load from prebuilt binaries — which +shrinks the runtime attack surface. `ffmpeg` remains (a real runtime dependency). + +The published image carries an SBOM and SLSA provenance attestation, and the +amd64 image is scanned by Trivy before publish (report-only). Note: only the +amd64 image is scanned; the arm64 image is published unscanned. + +**Minimum Docker version:** the attestation-bearing multi-arch image requires a +reasonably modern Docker to `pull` cleanly (Docker Engine 24+ recommended). +Very old daemons (≤ 20.10) may mishandle the `unknown/unknown` attestation +manifests. New installs via `install.sh` (get.docker.com) are fine. **Upgrade note for existing self-hosters:** on the first start of the hardened image, the contents of your host `./data` directory are chowned to uid 1000. This is expected and idempotent. If you previously accessed `./data` on the host as a -different user, adjust host-side access accordingly. +different user, adjust host-side access accordingly. `./restore.sh` continues to +work — it swaps files inside a throwaway root container, and root can rewrite the +now uid-1000-owned files. ``` +(b) Correct the two statements that this change makes false (the data dir is no +longer root-owned): +- The seed-admin line (around `deployment.md:170`): change + `writes it to `data/seed-admin-rotated.txt` (mode `0600`, root-owned via the bind-mount)` + → `... (mode `0600`, owned by the container's runtime user uid 1000 via the bind-mount)`. +- The Restore intro (around `deployment.md:252`): change + `Because `data/` (including `backspace.db` and `data/backups/`) is **container-owned (root)** via the bind-mount` + → `... is **container-owned (uid 1000)** via the bind-mount`. (The throwaway + root `alpine` container still performs the swap — root can rewrite uid-1000 + files — so the mechanism description after it stays correct.) + +**Maintainer release-gate (record it, do not action it here):** before the first +`v*` tag that ships this image, do a real `docker compose pull && docker compose +up -d` on both an amd64 host and the arm64 Pi to confirm the attestation-bearing +image pulls on the actual deployment Docker versions. + - [ ] **Step 2: Reflect the image scan in security-scanning.md** In `docs/systems/security-scanning.md`, update the supply-chain line about SBOM/provenance (currently "**will be** attached ... not yet live") to reflect that image scanning + SBOM + provenance now exist in `docker-publish.yml` (report-only image scan; SBOM + provenance attached at push). Add `docker-publish.yml` to the workflow table with trigger "tag push / manual" and result "image scan (report-only) + SBOM + provenance". @@ -299,4 +351,5 @@ git commit -m "docs(docker): document non-root runtime, data-volume migration, a - **Spec coverage (WS2):** non-root USER via gosu (Task 1) ✓; slim runtime / drop toolchain with prebuilt-binary verification + fallback (Task 1) ✓; keep ffmpeg + tsx (Task 1 / constraints) ✓; bind-mount chown migration (Task 1 entrypoint + Task 3 doc) ✓; restructure to single-arch load → scan → multi-arch push (Task 2) ✓; SBOM + provenance (Task 2) ✓; image scan report-only, flips in Plan E (Task 2 + constraints) ✓. - **Deferred by design:** flipping the image scan to blocking → Plan E. Desktop, web/CSP/CORS → Plans C/D. - **Risk-managed:** the toolchain removal is verified by a real build that must show better-sqlite3 using a prebuilt binary; a fallback is defined if it compiles. The non-root switch is verified by asserting `uid=1000` at runtime and a successful `./data` write + DB creation. Multi-arch push + SBOM/provenance is review-plus-workflow_dispatch verified (cannot be exercised without publishing). -- **Enforcement stays OFF** — image scan is `continue-on-error` + `exit-code`-unset; no gate added here. +- **Enforcement stays OFF** — image scan is `continue-on-error` + `severity`-limited to HIGH/CRITICAL for the report; no build-failing gate added here. +- **Adversarial pre-execution review folded in:** the non-root verification now checks `/proc/1/status` (not `docker exec … id`, which spawns a new root process and would false-fail); BOTH arches are built to verify the toolchain drop (arm64 is the release-hard-fail path); the entrypoint chown is idempotent-cheap + non-fatal (Pi/CIFS safety); a `sharp` native-load smoke check + EACCES log scan were added; now-false `deployment.md` ownership statements are corrected; and an SBOM/provenance min-Docker floor + a maintainer pull-test release-gate are documented (attestation-bearing images can trip very old Docker on the `pull` path).