feat(daemon): remote transport with mTLS caller authentication

CHANGELOG.md

@@ -29,13 +29,22 @@ Releases are cut automatically from [Conventional Commits](https://www.conventio
   need `/var/run/docker.sock`, with per-profile isolation policy resolved
   server-side from configuration alone.
 - `pkg/brokerclient`: a drop-in `sandbox.Backend` that talks to `openbloxd`
-  over its Unix socket, satisfying the same contract the Docker backend does.
+  over a Unix socket, satisfying the same contract the Docker backend does.
 - `openbloxd`: `max_sandboxes` per profile, bounding how many sandboxes exist
   at once — the one resource dimension a profile did not otherwise cover.
   Exceeding it returns `429` with the new `at_capacity` error kind
   (`brokerapi.ErrAtCapacity`), distinct from a malformed request because the
   request is valid and may succeed once the reaper frees a slot. Unset means
   unlimited, so existing deployments are unchanged.
+- `openbloxd`: an optional `listen` block for a mutual-TLS network listener,
+  alongside (or instead of) the Unix socket — `socket` is now optional once
+  `listen` is set. Every caller presents a client certificate; only Common
+  Names on the configured allowlist are accepted, so a shared or mis-issued
+  CA cannot silently grant access. The caller's verified CN is recorded on
+  every request the daemon handles.
+- `pkg/brokerclient`: `NewRemote` and `TLSFiles`, so a caller can reach
+  `openbloxd` over the network with the same `sandbox.Backend` contract the
+  Unix-socket client satisfies.
 
 ### Changed
 

cmd/openbloxd/main.go

@@ -78,9 +78,39 @@ func run(configPath string) error {
 	}
 	defer func() { _ = backend.Close() }()
 
-	ln, err := daemon.Listen(cfg.Socket, cfg.SocketGroup)
-	if err != nil {
-		return err
+	// One handler, two listeners. There is no second route table that could
+	// drift from the first, which is what makes "policy is unreachable
+	// regardless of transport" a property of the design rather than a rule
+	// somebody has to remember.
+	var lns []net.Listener
+	if cfg.Socket != "" {
+		ln, err := daemon.Listen(cfg.Socket, cfg.SocketGroup)
+		if err != nil {
+			return err
+		}
+		lns = append(lns, ln)
+	}
+	if cfg.Listen != nil {
+		if cfg.Listen.IsWildcardHost() {
+			// Legitimate for a daemon whose network namespace is already the
+			// boundary, and a serious mistake otherwise. The difference is
+			// invisible in the config file, so say it out loud at boot.
+			slog.Warn("listen.address binds every interface; the daemon is reachable from any network this host is on",
+				slog.String("address", cfg.Listen.Address))
+		}
+		ln, err := daemon.ListenTLS(*cfg.Listen)
+		if err != nil {
+			// Nothing has been handed to a server yet, so this is the only
+			// chance to close what's already open: leaving the socket listener
+			// alive here means its fd outlives us without net's unlink-on-close
+			// ever running, so the socket file survives the process — a down
+			// daemon would then answer ECONNREFUSED instead of ENOENT.
+			for _, l := range lns {
+				_ = l.Close()
+			}
+			return err
+		}
+		lns = append(lns, ln)
 	}
 
 	srv := daemon.New(backend, cfg)
@@ -98,21 +128,34 @@ func run(configPath string) error {
 	// or a long-lived dialled stream. It closes a real Slowloris hole (a peer
 	// that trickles headers forever) on the socket that holds the Docker
 	// connection, even though that peer is local.
-	httpSrv := &http.Server{Handler: srv.Handler(), ReadHeaderTimeout: 10 * time.Second}
+	httpSrv := &http.Server{Handler: daemon.WithCaller(srv.Handler()), ReadHeaderTimeout: 10 * time.Second}
 
-	slog.Info("openbloxd listening", slog.String("socket", cfg.Socket), slog.Int("profiles", len(cfg.Profiles)))
-	return serve(ctx, httpSrv, ln)
+	socket := "off"
+	if cfg.Socket != "" {
+		socket = cfg.Socket
+	}
+	network := "off"
+	if cfg.Listen != nil {
+		network = cfg.Listen.Address
+	}
+	slog.Info("openbloxd listening",
+		slog.String("socket", socket),
+		slog.String("network", network),
+		slog.Int("profiles", len(cfg.Profiles)))
+	return serve(ctx, httpSrv, lns...)
 }
 
-// serve runs httpSrv on ln until ctx is cancelled or Serve fails on its own.
+// serve runs httpSrv on lns until ctx is cancelled or a Serve call fails on its own.
 //
 // A Serve failure with no signal must return promptly rather than wait on
 // ctx.Done(), which may never fire: Restart=on-failure in the unit only
 // triggers if the process actually exits, and a process that hangs after
 // Serve dies looks "active (running)" to systemd while accepting nothing.
-func serve(ctx context.Context, httpSrv *http.Server, ln net.Listener) error {
-	serveErr := make(chan error, 1)
-	go func() { serveErr <- httpSrv.Serve(ln) }()
+func serve(ctx context.Context, httpSrv *http.Server, lns ...net.Listener) error {
+	serveErr := make(chan error, len(lns))
+	for _, ln := range lns {
+		go func() { serveErr <- httpSrv.Serve(ln) }()
+	}
 
 	select {
 	case err := <-serveErr:
@@ -138,8 +181,14 @@ func serve(ctx context.Context, httpSrv *http.Server, ln net.Listener) error {
 		slog.Warn("openbloxd: graceful shutdown did not complete in time", slog.Any("error", err))
 	}
 
-	if err := <-serveErr; err != nil && !errors.Is(err, http.ErrServerClosed) {
-		return fmt.Errorf("serve: %w", err)
+	// Shutdown closes every listener, so each Serve returns. Drain them all:
+	// leaving one undrained would leak its goroutine, and returning on the
+	// first would hide a real failure behind another listener's ErrServerClosed.
+	var firstErr error
+	for range lns {
+		if err := <-serveErr; err != nil && !errors.Is(err, http.ErrServerClosed) && firstErr == nil {
+			firstErr = fmt.Errorf("serve: %w", err)
+		}
 	}
-	return nil
+	return firstErr
 }

deploy/openbloxd.example.yaml

@@ -9,6 +9,27 @@ socket: /run/openbloxd/openbloxd.sock
 socket_group: openbloxd
 reap_interval: 1m
 
+# A network listener, so the daemon can run on a host of its own. OPTIONAL and
+# off by default: omit this block entirely and the daemon serves only the Unix
+# socket above, which stays the recommended arrangement wherever the caller and
+# the daemon share a host.
+#
+# Nothing here has a default. A daemon that started listening on a network
+# interface because a key was omitted is the failure this block exists to
+# avoid, so every field below is required once `listen` is present.
+#listen:
+#  address: "127.0.0.1:9443"
+#  tls:
+#    cert_file: /etc/openbloxd/tls/server.crt
+#    key_file: /etc/openbloxd/tls/server.key
+#    # The CA that signs callers. It must sign NOTHING else: with certificate
+#    # verification alone, this CA is the entire access control list.
+#    client_ca_file: /etc/openbloxd/tls/clients-ca.crt
+#    # The second gate, and the reason a CA mis-issuance is survivable. Only a
+#    # certificate whose Common Name is listed here is accepted. Revoking a
+#    # caller means removing its name and restarting: there is no CRL or OCSP.
+#    allowed_client_cns: ["sandbox-caller"]
+
 profiles:
   code-exec:
     # Pin a digest. A tag can be repointed by whoever controls the registry,

docs/security.md

@@ -153,7 +153,9 @@ resolves the path fresh on every connection and picks up the new socket.
 
 **The socket group is the entire access-control list.** There is no token and no TLS —
 a Unix socket is a kernel object with no wire to intercept, and mTLS would add a CA,
-issuance and rotation for no real gain here. Two different groups do two different jobs
+issuance and rotation for no real gain here. That calculus only holds while caller and
+daemon share a host; see [Remote transport](#remote-transport) below for the network
+case, where a CA is unavoidable and buys something real. Two different groups do two different jobs
 here, and they are easy to conflate: `socket_group` in the daemon's own config file
 (`deploy/openbloxd.example.yaml`) names the group that may reach the socket — the
 daemon itself creates the socket `0660` and chowns it to that group in `Listen`
@@ -184,6 +186,109 @@ audit trail or profile-to-identity binding off of. Under user-namespace remappin
 that's the *remapped* uid — the one the kernel sees on the socket, not the uid the
 process believes it's running as inside its container.
 
+## Remote transport
+
+openbloxd serves a Unix socket by default, and that remains the recommended
+arrangement wherever the caller and the daemon share a host. The optional
+`listen` block (`internal/daemon/config.go`) adds a network listener so the
+daemon can run on a machine of its own — because gVisor contains escape, not
+contention, and sandboxes otherwise compete for CPU, memory bandwidth and disk
+IO with whatever runs beside them.
+
+A network listener requires mutual TLS. There is no unauthenticated network
+mode and there is no way to configure one: every field of `listen.tls` is
+required, and `Load` refuses to start the daemon if any is missing.
+
+### What authenticates a caller
+
+Two gates, both during the TLS handshake in `ListenTLS`
+(`internal/daemon/listener_tls.go`):
+
+1. The client certificate must chain to `listen.tls.client_ca_file`.
+2. Its Common Name must appear in `listen.tls.allowed_client_cns`.
+
+The second is not redundant. With verification alone **the CA is the entire
+access control list** — any certificate it ever signs is accepted. Use a CA
+that signs nothing else, and treat the allowlist as the thing that makes a
+mis-issuance survivable.
+
+### What this does not protect against
+
+**mTLS authenticates the process holding the key, not its intent.** A caller
+that has been compromised is a *valid* caller: it holds the certificate.
+Authentication contributes nothing to that case.
+
+That case is the one openbloxd exists for, and the credential is not what
+answers it. The guarantee is the same one the rest of this page describes: a
+compromised caller gains sandboxes bounded by a profile, never the host, and
+that bound is enforced daemon-side and unreachable from a request — see
+[Profiles are the whole policy surface](#deploying-the-policy-broker-openbloxd)
+above. Nothing about arriving over the network relaxes that. `openbloxd`
+serves both listeners from the one handler
+(`cmd/openbloxd/main.go`), and `internal/daemon/policy_test.go` asserts every
+hostile request body rejected over both transports rather than leaving that
+as a convention.
+
+**A private network is a real mitigation and a poor sole control.** Running
+the daemon on a VPN or a private subnet meaningfully reduces exposure and is
+recommended. It is not a substitute for the credential: it authenticates a
+route rather than a peer, and it fails open the moment anything else on that
+network is compromised.
+
+**Confidentiality in transit is TLS's alone.** Exec output, file reads and
+dialled streams all cross the network now, with no application-layer
+encryption beneath.
+
+### Revocation
+
+There is none beyond configuration. Go checks neither CRL nor OCSP by default,
+and openbloxd runs neither.
+
+**To revoke a caller: remove its Common Name from `allowed_client_cns` and
+restart the daemon.** `RuntimeDirectoryPreserve=yes` in the shipped unit
+(`deploy/openbloxd.service`) is what makes that restart transparent to
+clients mounting the socket directory, as described above.
+
+This is a limitation, not a design feature. It is workable for a small,
+enumerated set of callers and would not be workable at a scale where
+certificates are issued automatically — anything issuing certificates
+automatically should revoke them automatically too.
+
+### Issuing the certificates
+
+openbloxd is not a certificate authority and does not want to be. A minimal
+private CA, sufficient for one daemon and one caller (bash/zsh — `<(...)`
+process substitution is not POSIX `sh`):
+
+```bash
+# A CA that signs nothing else.
+openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 3650 \
+  -keyout ca.key -out ca.crt -subj "/CN=openbloxd-ca"
+
+# The daemon's certificate. The SAN must match the address callers dial.
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
+  -keyout server.key -out server.csr -subj "/CN=openbloxd"
+openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+  -days 825 -out server.crt \
+  -extfile <(printf "subjectAltName=IP:127.0.0.1\nextendedKeyUsage=serverAuth")
+
+# One caller. The CN is what goes in allowed_client_cns.
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
+  -keyout client.key -out client.csr -subj "/CN=sandbox-caller"
+openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+  -days 825 -out client.crt \
+  -extfile <(printf "extendedKeyUsage=clientAuth")
+```
+
+Keep `ca.key` off both machines once the certificates are issued.
+
+`server.crt`/`server.key` and `ca.crt` stay on the daemon's host, as
+`cert_file`, `key_file` and `client_ca_file`; the CN `sandbox-caller` is what
+goes in `allowed_client_cns`. `client.crt`/`client.key` are the only pair
+that leaves the daemon's host at all — they travel to the caller, which
+configures its own TLS client with them and with `ca.crt` to verify the
+server.
+
 ## Reporting a vulnerability
 
 See [SECURITY.md](https://github.com/blox-eng/openblox/blob/main/SECURITY.md). Please do

internal/daemon/caller.go

@@ -0,0 +1,60 @@
+package daemon
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+)
+
+// Transport names the way a request arrived.
+const (
+	TransportUnix = "unix"
+	TransportTLS  = "tls"
+)
+
+// Caller is who made a request.
+//
+// Nothing consumes this yet. It exists anyway because a transport that
+// discards the caller's identity has to be reopened to add per-caller quotas
+// or an audit trail, and the place to record identity is where it is still
+// available.
+//
+// Transport is carried explicitly rather than inferred from an empty Name: a
+// log line for a security boundary should say whether a request arrived
+// locally or over a network, not leave it to be deduced.
+type Caller struct {
+	Transport string
+	Name      string
+}
+
+type callerKey struct{}
+
+// WithCaller records the caller on the request context, over every transport.
+//
+// Name is empty for a Unix caller because SO_PEERCRED is unimplemented; that
+// is the local transport's identity seam and is unrelated to this one.
+func WithCaller(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		c := Caller{Transport: TransportUnix}
+		if r.TLS != nil {
+			c.Transport = TransportTLS
+			if len(r.TLS.PeerCertificates) > 0 {
+				c.Name = r.TLS.PeerCertificates[0].Subject.CommonName
+			}
+			// Logged only for network callers. The Unix socket is the
+			// high-volume local path and its behaviour is deliberately
+			// unchanged; a remote request is the one worth an audit line.
+			slog.Info("openbloxd request",
+				slog.String("caller", c.Name),
+				slog.String("method", r.Method),
+				slog.String("path", r.URL.Path))
+		}
+		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), callerKey{}, c)))
+	})
+}
+
+// CallerFrom returns the caller recorded by WithCaller.
+func CallerFrom(ctx context.Context) (Caller, bool) {
+	c, ok := ctx.Value(callerKey{}).(Caller)
+	return c, ok
+}

internal/daemon/caller_test.go

@@ -0,0 +1,58 @@
+package daemon
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestWithCallerRecordsUnixCaller(t *testing.T) {
+	var got Caller
+	var ok bool
+	h := WithCaller(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+		got, ok = CallerFrom(r.Context())
+	}))
+	h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/profiles", nil))
+
+	if !ok {
+		t.Fatal("no caller on the context")
+	}
+	if got.Transport != TransportUnix {
+		t.Errorf("Transport = %q, want %q", got.Transport, TransportUnix)
+	}
+	// SO_PEERCRED is unimplemented, so a local caller has no name yet. This
+	// asserts the current honest answer rather than a placeholder.
+	if got.Name != "" {
+		t.Errorf("Name = %q, want empty for a unix caller", got.Name)
+	}
+}
+
+func TestWithCallerRecordsCertificateCommonName(t *testing.T) {
+	var got Caller
+	h := WithCaller(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+		got, _ = CallerFrom(r.Context())
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/profiles", nil)
+	req.TLS = &tls.ConnectionState{PeerCertificates: []*x509.Certificate{
+		{Subject: pkix.Name{CommonName: "sandbox-caller"}},
+	}}
+	h.ServeHTTP(httptest.NewRecorder(), req)
+
+	if got.Transport != TransportTLS {
+		t.Errorf("Transport = %q, want %q", got.Transport, TransportTLS)
+	}
+	if got.Name != "sandbox-caller" {
+		t.Errorf("Name = %q, want sandbox-caller", got.Name)
+	}
+}
+
+func TestCallerFromReportsAbsence(t *testing.T) {
+	if _, ok := CallerFrom(context.Background()); ok {
+		t.Fatal("CallerFrom reported a caller on a bare context")
+	}
+}