Container runtime isolation

The container-runtime socket is a host-level security boundary. A process with unrestricted access to it can usually control containers and reach sensitive host resources. Clearplane therefore does not mount the socket into Edge, Core, or UI.

The ContainerProxy boundary

ContainerProxy is the only Clearplane container that receives the runtime socket. It exposes read-only container-runtime operations for connectivity checks, container listings, and events, plus bounded resource telemetry and self-restart operations. Core reaches those internal operations over clearplane-internal using the exact Core client identity; the health endpoint accepts only ContainerProxy's own identity.

ContainerProxy does not decide what labels mean or write Clearplane configuration. Core validates labels, resolves ownership, rejects ambiguous discovery candidates, and reconciles accepted resources. Edge receives only the resulting configuration revision. An invalid label candidate is reported without replacing the previous valid discovered resource graph. A transient runtime or ContainerProxy failure also leaves the last valid graph in place.

This split means a compromise of the public Edge or management Core process does not directly provide the Docker socket. It also keeps container-runtime-specific code out of the routing and management components.

Socket permissions

Set CLEARPLANE_CONTAINER_PROXY_SOCKET_PATH for a nondefault local Unix socket. No host group-ID setting is needed. Clearplane does not change socket ownership, permissions, user-namespace mappings, or SELinux policy. A read-only socket bind does not make Docker's API read-only; ContainerProxy's allowlisted API supplies that boundary.

The health check calls Docker's /_ping; blocked socket access fails health validation. If you explicitly configure a non-root container user, supply its socket access yourself, for example with a matching group_add. A rootless Docker daemon reduces the impact of a compromised runtime boundary.

What the boundary does not promise

ContainerProxy remains a high-trust component because it holds the socket. Its narrow API, read-only filesystem, dropped capabilities, and private network reduce exposure but cannot turn a compromised Docker host or daemon into a trusted environment.

Operators still own host patching, Docker daemon access, volume permissions, and administrator access. Do not expose ContainerProxy or the runtime socket outside clearplane-internal.