feat(docker): migrate socket proxy to wollomatic, pin allowlist to GET /images/json - #89

Closes #63. Completes the half of M23/SC-7 that was deliberately deferred out of the 2026-07-13 supply-chain batch.

Summary

The docker-env sidecar — the only container in the stack that mounts /var/run/docker.sock — moves from tecnativa/docker-socket-proxy:v0.4.2 (HAProxy on Alpine, USER root, coarse env-var toggles) to wollomatic/socket-proxy:1.12.3 (from-scratch Go binary, USER 65534, per-method regex allowlisting), pinned by digest.

The point of the migration is the allowlist. Scrye makes exactly one request of this proxy — GET /images/json (backend/app/core/docker_proxy.py; list_images() is the only caller, and the core/egress.py guard in front of it is DNS-only). The old config permitted far more than that, because tecnativa's rules are prefix matches:

The whole allowlist is now one flag: -allowGET=(/v1\.[0-9]{1,2})?/images/json. Upstream anchors patterns itself (regexp.Compile("^"+regex+"$")) and matches against the URL path only, and answers 405 for any method with no -allow* entry — so omitting the other five method flags is what makes the proxy read-only, replacing POST=0.

Hardening deltas

• /run tmpfs retired. INF-5 existed only because HAProxy needed a writable pid/stats path under read_only: true. A static Go binary needs none, so the sidecar is now read-only with no writable path at all.
• Runs as uid 65534 in a from-scratch image (no shell, no libc, no package manager) instead of root on haproxy:alpine.
• Healthcheck moved off the proxied API (wget …/info) onto the bundled /healthcheck binary and its separate 127.0.0.1:55555 listener — which is why /info no longer has to be exposed just to have a liveness probe.
• Added -watchdoginterval=3600 -stoponwatchdog so a socket broken by a Docker engine update is recovered by restart: unless-stopped.
• Memory cap 128M → 64M. cap_drop: ALL, no-new-privileges, digest pin, no host port, capped logging, CPU limit unchanged.

⚠️ One operational difference

tecnativa ran as root in-container and could read the socket regardless of ownership. wollomatic ships USER 65534:65534, and /var/run/docker.sock is root:docker mode 0660 — so the container's GID must be the host's docker group. The service is now user: "65534:${DOCKER_GID:-999}" and operators enabling docker-env must set:

export DOCKER_GID="$(stat -c '%g' /var/run/docker.sock)"

The 999 default is a Debian/Ubuntu convention, not a guarantee; a wrong GID surfaces as a socket permission error at proxy start. This is a deployment prerequisite only — no application behavior, API contract, schema, or client code changed, and SCRYE_DOCKER_PROXY_URL / port 2375 are unchanged.

Verification

No Docker daemon was reachable in the environment where this was prepared, and Docker Hub's blob CDN (production.cloudfront.docker.com) is egress-blocked, so the published image could not be pulled or booted. The request-handling path was therefore exercised directly instead: upstream's handlehttprequest.go and bindmount.go at tag 1.12.3 were compiled verbatim (the module is stdlib-only) against a minimal internal/config carrying upstream's AllowList types and compileRegexp unmodified, put in front of a stub Docker API on a real unix socket, and configured with the -allowGET pattern read out of docker-compose.yml. Against that harness:

• the real docker_proxy.list_images() enumerated images successfully (untagged dropped as expected);
• all 11 previously-permitted sensitive paths returned 403;
• HEAD/POST/PUT/DELETE/PATCH returned 405;
• the /v1.NN form and a query string were accepted;
• the stub socket's access log confirmed only the 4 allowed requests ever reached it, while all 16 blocked ones stopped at the proxy.

docker compose --profile docker-env config renders the service with the regex and DOCKER_GID interpolation intact. The egress guard's loopback refusal was also confirmed intact along the way.

Still to do on a Docker-capable host: one docker compose --profile docker-env up to confirm the published image boots under the full hardened option set and that DOCKER_GID is right for that host.

Tests

backend/tests/test_compose_hardening.py gains seven regression tests that keep the allowlist tied to the client rather than to a hardcoded string: the -allowGET pattern is compiled the way upstream compiles it and checked against the path list_images() is observed to request, checked to reject every previously-allowed sensitive path, and checked for method flags, source restriction, digest pin, unprivileged uid, and the absence of a re-introduced writable /run. Each was verified to fail against a deliberately widened Compose config before being committed.

Full backend suite (561 passed, 3 skipped), ruff, black, ESLint, Prettier, and the frontend Vitest suite (54 passed) are green locally.

Docs

README § Optional sidecars, § Configuration (the DOCKER_GID note), and § Security model updated; CHANGELOG.md Unreleased entry with the action-required note; docs/reviews/STATUS.md moves M23/SC-7 from § Deferred to § Resolved.

See docs/ARCHIVE.md § Deviations (2026-07-24) for the full before/after allowlist mapping.