feat(egress): contained-mode egress-jail topology + tinyproxy sidecar (PR 2/3)

[jraicr]

Part of #149 · v0.4.0 · dual-mode-containment Phase 2 (egress jail) · PR 2/3 (stacked-to-dev)

PR 1/3 (#154, on dev) shipped the enabling machinery (sidecar image, baseline allowlist, per-session filter generation) with docker-compose.contain.yml deliberately unchanged. This PR flips the contained-mode network topology so that machinery is actually consumed: the agent loses its direct external route and egresses only through a deny-by-default tinyproxy sidecar (Architecture A — zero new Linux capabilities).

dev stays runnable after this merge: PR 1/3 already provides the effective filter file, the drydock-egress image build, and the DRYDOCK_SIDECAR_NAME export, so contained drydock run brings up the topology end-to-end. dood mode is untouched.

Topology (the flip)

• docker-compose.contain.yml rewritten in place (no new overlay — the "exactly one of dood/contain" gate and its render test stay intact):
  • drydock_internal — fixed-name internal: true bridge (no gateway/NAT; external DNS SERVFAILs). The agent is solely attached here.
  • drydock_egress — fixed-name standard NAT bridge; the sidecar's external leg.
  • Both networks carry an explicit name: so all sessions share one pair (drydock tears down with docker rm -f, never compose down / network rm, so un-named networks would leak and exhaust Docker's ~31-bridge pool).
• Agent (drydock service): HTTPS_PROXY/HTTP_PROXY/NO_PROXY (sidecar by name + loopback + metadata link-local), depends_on: drydock-egress: { condition: service_healthy } (fail-closed — the agent will not start before the proxy is healthy), and telemetry off by default (DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, all user-overridable) to collapse the required allowlist.
• Sidecar (drydock-egress service): per-session container_name=${DRYDOCK_SIDECAR_NAME} (mirrors the agent's disc-parameterized name), image: drydock-egress:latest, dual-homed to both bridges, cap_drop: [ALL] with no cap_add, no-new-privileges, read_only rootfs with tmpfs: [/run, /tmp] (the PidFile lives in /tmp), a /dev/tcp port-8888 healthcheck, and the per-session effective filter RO-mounted at /etc/tinyproxy/filter.

Lifecycle, build, reporting

Area	Change
ensure_image	Requires drydock-egress:latest only when the project resolves to contained mode. dood must not require/build it — a dood-only offline host with the agent image present would otherwise be blocked by the sidecar's apt build failing without network.
collision-retry	The discriminator collision regex is widened to (-shell|-egress)? so a disc whose sidecar still lingers after a run --rm reap-gap is not reused. The gc/seed liveness regexes are deliberately not widened (a live sidecar must not protect an orphaned dir).
gc reap	gc_orphan_session_dirs reaps an orphaned -egress sidecar in the orphan branch (the run --rm paths remove only the oneoff agent and exec away).
teardown	_run_claude_lifecycle and cmd_stop tear down the agent and its sidecar. cmd_stop guards the sidecar rm separately so a dood / already-reaped session never fails the stop.
banner / doctor	The creation banner and drydock doctor now describe the egress allowlist (with a live domain count) and the contain pin note is updated; a new doctor EGRESS section reports the baseline + user allowlists + sidecar image. Honest wording — the allowlist is named without over-claiming.

Residual gaps (named, not hidden)

L4 only (payload not inspected); ECH / domain-fronting; IP-literal CONNECT denied by deny-by-default; a compromised sidecar means open egress; a tool ignoring HTTPS_PROXY loses egress (breakage, not bypass); concurrent contained sessions share the one internal bridge and can reach a peer's sidecar (single-user trust bound). These are enumerated in full in the doctrine flip (PR 3/3).

Invariants

• INV-8 touched-but-preserved: zero new Linux capabilities anywhere. The sidecar runs cap_drop: [ALL] with zero cap_add; the agent's cap_add is the unchanged Phase 1 hardening set. A render test scoped to the sidecar service block asserts the absence of cap_add (non-vacuous — cap_add is present on the agent in that same render).
• dood unaffected: dood render contains docker.sock + network_mode: host and none of internal: true, the sidecar, HTTPS_PROXY, the filter mount, or the telemetry-off defaults (negative render tests guard this).

Tests (strict TDD)

• 1137/1137 green via scripts/test.sh; shellcheck + shfmt -d clean.
• The first failing test inverts the Phase 1 internal: true absent guard; the two drydock_net render tests are replaced (not left dangling). New coverage: R9.2–R9.13 render assertions, dood negatives, sidecar read_only/tmpfs (A5) scoped to the service block, -egress collision retry, gc sidecar reap (+ a live-agent-still-protects negative), ensure_image contained-builds / dood-skips, two-name teardown (lifecycle + stop), and banner/doctor egress reporting.

Review

Fresh adversarial review (empirical — compose renders, mutation testing of the new assertions, A6 regex replay, teardown exit-code semantics, set -euo pipefail safety, healthcheck validated against the real debian:12-slim) plus an independent spec/design verification: 0 blockers. Two test-sensitivity findings (the A5 read_only/tmpfs assertions could pass vacuously) were fixed before this PR by scoping them to the sidecar block and confirming they fail against a mutated overlay.

Size

~690 lines changed — the majority are tests; production code is ~185 lines (compose ~90, lib/ ~95). Labeled size:l.

Next

• PR 3/3 — doctrine + docs flip: INV-9 rewrite (drop the "does NOT filter egress" clause; name all residual gaps), docs/security.md, README.md, docs/architecture.md, docs/troubleshooting.md (egress-allowlist how-to), docs/ROADMAP.md → Done, CHANGELOG.md (v0.4.0).
• Release gates (v0.4.0): empirical baseline CONNECT capture + a runtime double-gate smoke (reach an allowlisted domain through the proxy and block a non-allowlisted one, IP-literal CONNECT denied) on bare Linux.

Part of #149 — the umbrella issue stays open until Phase 2 plus the v0.4.0 release.