fleet-manager: checkpoint 2 — gRPC agent plane (bidi mTLS stream)

The steady-state host<->manager transport, resolving the design's OPEN FORK to bespoke gRPC (not OTLP+Wazuh). One long-lived, host-dialed, mTLS bidi stream: health/metrics up, desired-state/commands down — no polling, real-time control, still no inbound host port. - proto/fleet_agent.proto: FleetAgent.Session(stream AgentUp) -> stream ManagerDown. AgentUp = Hello | HealthSnapshot | CommandResult; ManagerDown = DesiredState | Command(reboot/drain/resync). int64 unix times (no well-known-type dep). Generated stubs committed (CI needs no protoc). - agent.go: gRPC server with mTLS verified by the FLEET CA (the host's reused TPM identity cert — distinct from the admin plane's admin CA). Identity is the peer cert SERIAL, taken from the verified cert = inventory key, never self-asserted; an unenrolled serial is refused (enrolment gates the stream). Per-conn send channel decouples admin pushes from stream.Send. Stream registry (serial->conn) with reconnect eviction. On connect + on change, desired-state is pushed live; inventory stays authoritative so offline hosts reconcile on reconnect. Metrics go through a MetricsSink seam (no-op now; InfluxDB in ckpt 4). - main.go: agent plane starts only when its cert/key/CA are set; admin can run standalone. Lifecycle PUT now live-pushes and reports pushed_live. Full mTLS integration test (in-process fleet CA + host client cert): initial desired-state on connect, Hello+snapshot -> inventory + online presence, live desired-state push, and unenrolled-serial rejection. go build/test/vet/gofmt clean. Deps (server-side only): google.golang.org/grpc + protobuf.
2026-07-04 03:40:55 +00:00
parent 0572d21c07
commit 80cbb833cc
11 changed files with 1700 additions and 13 deletions
@@ -0,0 +1,96 @@
+syntax = "proto3";
+
+// The steady-state contract between the on-host fleet agent and the
+// fleet-manager. ONE long-lived, host-dialed, mTLS bidi stream (health/metrics
+// up, desired-state down) — the design's resolved transport fork (bespoke gRPC,
+// not OTLP+Wazuh). See docs/fleet-management-design.md + tpm-enrolment-design.md.
+//
+// Identity is the mTLS peer cert (the host's reused TPM identity cert, fleet CA);
+// the manager derives the cert serial (= inventory key) from it, so AgentUp
+// messages carry NO self-asserted identity — a host can only ever be itself.
+package fleet.agent.v1;
+
+option go_package = "fleet-manager/proto;fleetpb";
+
+service FleetAgent {
+  // Session: the single bidirectional stream. The host opens it (dials out, no
+  // inbound host port); the manager pushes desired-state/commands back over the
+  // same connection. Closing/keepalive-timeout = the host's offline signal.
+  rpc Session(stream AgentUp) returns (stream ManagerDown);
+}
+
+// ---- host -> manager ------------------------------------------------------
+
+message AgentUp {
+  oneof msg {
+    Hello hello = 1;              // first frame after connect
+    HealthSnapshot snapshot = 2;  // periodic telemetry (also written to InfluxDB)
+    CommandResult result = 3;     // outcome of a ManagerDown.Command
+  }
+}
+
+// Hello — what the host is running, sent once on connect so the manager can
+// reconcile version drift immediately.
+message Hello {
+  string image_version = 1;
+  string rootfs_digest = 2;
+  string kernel = 3;
+  string kiosk_url = 4;
+  string starship_name = 5;  // advisory; manager already knows it from inventory
+}
+
+// HealthSnapshot — one telemetry sample. Cached as the latest value in inventory
+// AND written as a time-series point to InfluxDB (tagged with the authenticated
+// cert serial / hostnqn).
+message HealthSnapshot {
+  int64  at_unix         = 1;  // sample time, unix seconds (0 = manager stamps now)
+  double load_avg        = 2;
+  double cpu_pct         = 3;
+  double temp_c          = 4;
+  double mem_used_pct    = 5;
+  double tmpfs_used_pct  = 6;  // overlay RAM pressure
+  string nvme_root       = 7;  // ok|degraded|down
+  string auth            = 8;  // 802.1x/macsec: up|down
+  string selinux         = 9;  // enforcing|permissive
+  string chrony          = 10; // synced|unsynced
+  bool   kiosk_active    = 11;
+  string session_uptime  = 12;
+  int32  chromium_crashes = 13;
+  string display         = 14;
+}
+
+message CommandResult {
+  string command_id = 1;
+  bool   ok         = 2;
+  string detail     = 3;
+}
+
+// ---- manager -> host ------------------------------------------------------
+
+message ManagerDown {
+  oneof msg {
+    DesiredState desired = 1;  // full desired-state: sent on connect + on change
+    Command      command = 2;  // imperative action
+  }
+}
+
+// DesiredState — server-authoritative target the agent reconciles toward.
+message DesiredState {
+  string target_version = 1;
+  string kiosk_url      = 2;
+  int64  reboot_at_unix = 3;  // 0 = no scheduled reboot
+  bool   drain          = 4;
+}
+
+// Command — an imperative action pushed live (admin clicked a button in the SPA).
+message Command {
+  string command_id = 1;
+  Kind   kind       = 2;
+
+  enum Kind {
+    KIND_UNSPECIFIED = 0;
+    REBOOT           = 1;  // reboot now (into desired target_version)
+    DRAIN            = 2;  // stop taking work / prepare for maintenance
+    RESYNC           = 3;  // re-fetch + re-apply desired-state now
+  }
+}