Suvra

Nodes

Enforcement Nodes are the distributed policy checkpoints that sit close to your agents. The Nodes dashboard (/dashboard/nodes) shows every registered node, its policy cache state, and its connection health.

Requires nodes.read to view; policies.write to push a bundle.

Nodes table

ColumnDescription
Node IDStable identifier issued at bootstrap (code format)
HostnameNode hostname reported on registration
Suvra VersionBinary version the node is running
RegionRegion label from the node manifest
HealthBadge derived from last-seen + heartbeat state
StatusNode lifecycle status
Last SeenUTC timestamp of most recent heartbeat
AgentsComma-separated agent_ids bound to the node, or -
ActionsPer-row Push Policy Update button

A top-of-page Push Policy to All Nodes button broadcasts a refresh to every registered node.

Bootstrap flow

Nodes join the control plane by presenting SUVRA_NODE_BOOTSTRAP_TOKEN. In return they receive:

  • X-Suvra-Node-ID — their stable identifier
  • X-Suvra-Node-Token — authentication for node endpoints

After bootstrap the node registers and begins heartbeating to POST /control/nodes/{node_id}/heartbeat. The per-node token is persisted at SUVRA_NODE_CREDENTIAL_PATH.

Push policy

Push Policy Update posts to /dashboard/nodes/{node_id}/push-policy (or /dashboard/nodes/push-policy-all for the broadcast button) and:

  1. Updates the node's desired_policy_bundle_id / desired_policy_bundle_version
  2. The node pulls the new signed bundle from GET /control/policy/bundle/active on its next heartbeat
  3. It verifies the Ed25519 signature and activates the bundle atomically

If the push can't be delivered, the node keeps serving its last cached bundle until TTL expiry, then fails closed.

Audit spool

Every node maintains a local SQLite spool (data/node-audit-spool.db by default, overridable via SUVRA_NODE_AUDIT_SPOOL_PATH). Enforcement never blocks on central audit — decisions write to the local spool first, then flush to POST /control/audit/ingest in best-effort batches.

Node health

The Health badge reflects a mix of:

  • Time since last heartbeat
  • Status field on the node record
  • Any error the control plane captured during the last bundle exchange

Nodes also expose their own endpoints:

  • GET /health — liveness
  • GET /metrics — Prometheus counters (heartbeat stats, approval broker counts, policy-bundle fetch activity, mode labels)

RBAC

  • View: nodes.read (Viewer+)
  • Push bundle: policies.write (Policy Admin, Admin)

Related