[Phase 3] Provide a safe DinD sidecar mode

[Saber5656]

Background

FR-1.4.2 defines a --dind mode for a Docker-in-Docker sidecar. Cage must never pass the host Docker socket into the sandbox; when nested container access is needed, it should use a dedicated sidecar on an isolated network.

Scope

• Start a sidecar when --dind is supplied.
• Create a dedicated Docker network.
• Set environment variables so the agent container can connect to the sidecar daemon.
• Do not mount host volumes into the sidecar.
• Clean up the sidecar and network when the session ends.

Acceptance Criteria

• Host /var/run/docker.sock is not mounted even when DinD mode is enabled.
• Sidecar container and network names include a collision-resistant session ID.
• Cleanup is idempotent.
• DinD privileged-mode requirements and risks are documented.

References

• cage-demo/docs/PRD.md FR-1.4.2
• cage-demo/docs/security/stride-threat-model.md THREAT-CE-E-01
• cage-demo/src/engine/dind.rs

Technical Audit Addendum (2026-07-06)

• Resource limits on the sidecar: the security docs list "resource limits applied" as a DinD mitigation (PRD FR-1.4.2), but the current acceptance criteria don't require it. Add: the sidecar gets memory/cpus/pids limits like any cage container, even though it runs --privileged.
• TCP endpoint decision: design docs mix tcp://dind:2375 and 2376. Decide plain-TCP-on-isolated-network (2375, no TLS) vs TLS (2376, cert bootstrap complexity) and record it — plain TCP is defensible only because the per-session network is dedicated (THREAT-CE-S-02 / THREAT-TM-T-02); if so, assert the network has no other members.
• Readiness wait: dockerd inside the sidecar takes seconds to come up; the agent's first docker call will fail without a bounded wait/retry (poll docker version via the sidecar) before handing control to the agent.
• Storage lifecycle: sidecar /var/lib/docker grows with pulled images; cleanup on session end must remove its anonymous volume too (idempotent per existing AC).