Exposure and network boundaries
In the supported topology, Edge is the only Clearplane container with host port mappings. Public HTTP reaches Edge on TCP port 80. Public HTTPS uses TCP port 443 for HTTP/1.1 and HTTP/2 and UDP port 443 for HTTP/3; Core, UI, and ContainerProxy publish no host ports.
This remains true only while the deployment keeps those boundaries intact. Publishing an application or control-plane port separately creates another public path that Clearplane cannot protect.
Network wiring
| Network | Members | Purpose |
|---|---|---|
clearplane-internal |
Edge, Core, UI, ContainerProxy | Private control-plane communication over exact-identity mTLS on HTTPS 8443. The bridge is marked internal. |
clearplane-services |
Edge and proxied application containers | Edge-to-application traffic. Core, UI, and ContainerProxy are not members. |
clearplane-egress |
Core | Outbound control-plane traffic, including metrics and WAF event export, without attaching Core to application containers. |
Joining clearplane-services does not publish a host port. To keep Edge as the only public request path, application containers join this network and do not publish their application ports to the host.
Client address trust
Edge accepts a client address header only from a direct peer in clearplane.edge.trusted-proxies. With the default clearplane.edge.client-ip-headers=X-Forwarded-For, it walks the chain from right to left through trusted hops. Trusted proxies can be canonical IPv4 or IPv6 addresses or CIDR ranges; /0 is forbidden. An empty trusted-proxy list trusts nobody.
For Cloudflare Tunnel, choose CF-Connecting-IP and trust the dedicated Docker subnet used by the local cloudflared container. The configuration example shows the Edge labels. Do not trust Cloudflare's shared public ranges for X-Forwarded-For: another customer's Worker can supply that header. Cloudflare documents that cross-zone Worker requests use the fixed CF-Connecting-IP address 2a06:98c0:3600::103; same-zone Workers can influence the value through x-real-ip, so your own Workers remain part of the trust boundary. See Cloudflare's header reference.
clearplane.edge.client-ip-headers is an explicit priority list. Edge uses the first non-empty configured header; only missing or whitespace-only values allow a later header to be tried. A selected header other than X-Forwarded-For must contain exactly one IPv4 or IPv6 address. Malformed or repeated single-address values retain the peer address and log a warning without falling through. When no configured header has a value, Edge retains the peer address; custom header lists also log a warning.
Every header in the list must be trustworthy from every trusted proxy. For example, X-Real-IP X-Forwarded-For permits either header to identify a client, in that order. Do not add X-Forwarded-For as a fallback if any trusted proxy passes through client-controlled values. With only CF-Connecting-IP configured, Edge never consults X-Forwarded-For. An untrusted peer cannot change its address, and all its configured client IP headers are removed before the request reaches an upstream.
IP filters, access control, auto-ban, request rate limits, analytics and request logs use the resolved address. When enabled, clearplane.proxy.request-headers.forward-x-forwarded-for and forward-x-real-ip replace incoming forwarding values with that address. The resulting rightmost X-Forwarded-For entry is the resolved client, including for upstreams using ForwardLimit = 1.
Connection limits run before HTTP headers exist. Trusted proxies remain exempt from the per-address connection limit; the total connection limit still applies. Missing client headers can therefore group request policies and reporting under the proxy peer address. Investigate those warnings before relying on client-specific bans or limits.
Trust only a network dedicated to the tunnel hop. Do not trust a shared application network or the Docker bridge gateway through which public traffic can arrive: every trusted peer can assert a client address. If all public traffic must pass through Cloudflare, restrict direct public access to Edge separately; trusting the tunnel does not close an exposed port.
Management exposure
Management access also enters through Edge. When enabled, ordinary protected routes expose the browser UI and management API on the selected public host:
/routes to UI overclearplane-internal./api/{**catch-all}routes to Core unchanged./api/ws/*uses the same API route for browser event connections./api/metricsserves Prometheus metrics to a session withMetrics.Reador a scrape token./internal/*is never reachable through Edge. Core accepts/internal/*only from Edge's own control-plane connection, so Edge answers any proxied request to Core whose path, after strip-prefix and rewrite, falls under/internalwith 404, and discovery rejects a Core route whose path, strip-prefix or rewrite labels can reach/internal. The shipped/api/{**catch-all}path keeps the Core route valid; an unlabelled Core container would default to/{**catch-all}and is rejected.
Discovery reserves forwarding hosts claimed by verified Core or UI routes for those management services. Unrelated discovered proxy and redirect routes cannot claim the same host space, including overlapping wildcard hosts or more-specific paths. Core and UI can continue sharing their management host. Enabling or moving management onto a host already owned by an unrelated present route is rejected until that conflicting ownership is removed.
The UI and API therefore use the same public ingress and route controls as other services without exposing their containers directly.
Browser and API clients use the HttpOnly, SameSite=Strict session cookie issued by the external sign-in endpoint. API clients keep that cookie in a cookie jar and send the fixed CSRF header on unsafe requests; the sign-in response contains session status and expiry, not a bearer token.
A sign-in session expires 24 hours after it is created; activity and dashboard refreshes do not extend it. Closing the browser can also end the browser session.
An accepted authenticator code cannot be reused during its acceptance window, even after a different valid code succeeds. Replacing or resetting the authenticator key clears the previous key's replay history.
Password and multi-factor authentication changes invalidate older sessions. If sign-in or replacement-session creation overlaps another account security change, the request can be rejected; sign in again using the current credentials.
Management route defaults
Core and UI use ordinary clearplane.proxy.* labels and the same policy pipeline as application routes. The shipped routes and their configuration resources appear in the System resource group.
The shipped Compose file gives both containers one YAML anchor, x-clearplane-management-labels, whose labels create each route's own access control, rate limit (600 requests per minute), automatic ban, request headers and response headers policies, a Detection WAF policy with the Management profile, and branded 403/502/503/504 error pages; caching is off. Access control defaults to Block and allows no address until you set clearplane.proxy.access-control.allowed-addresses on both containers to your administrator address or a narrow VPN CIDR. If the allowlist admits a private range broader than a /24, discovery warns that it can cover Docker's default address pools. To change another management policy, override its label on both containers.
When an enabled management route accepts every address, the Dashboard and Proxy routes show Management routes have no address restriction and name the affected routes. A route's own policies replace global ones, so the warning clears only when a policy that applies to that route defaults to Block; a removed assignment, a disabled policy, or an allow-by-default policy leaves the route unrestricted.
For a route mistake, inspect Proxy routes, Upstream clusters, Certificates, their policies, and discovery diagnostics. Edit Docker labels for label-owned resources and use the UI/API for API-owned resources. Management routes follow the ordinary ownership rules; there is no separate management-route reset command. Setup and account recovery are covered by Installation and CLI.
Outbound exports
Core can send optional WAF metrics over OTLP and WAF events to syslog over TLS, signed HTTPS webhooks and OTLP logs. Every new connection checks the resolved address against the global restricted destination classes and always refuses the control-plane network. Redirects and system proxy routing are disabled. Export credentials are encrypted at rest; list responses never expose them.
Configure destinations with ObservabilityExports.Manage in System โ Settings โ Observability. See Export metrics and WAF events for token handling, formats, filters and retention limits.
Preserve the boundary
Apply the hardening checklist to keep these boundaries intact. See Architecture for the full runtime topology.