Telemetry and Policy Flow

Purpose #

Map what travels Manager → Agent (policy) and Agent → Manager (telemetry) without promising lossless, exactly-once, or immutable compliance-grade audit.

Concept #

The Manager is the control plane you host. Agents are node runtimes. Operators never program eBPF maps by hand as the supported path; they change objects on the Manager and Agents synchronize.

agents.auto_register is false in the example. Production comments say it must remain false. Admission is pre-register / create, then Agent register with a one-time bootstrap token.

Data/control flow #

Policy (Manager → Agent) #

1. Administrator authenticates to /api/v1 (JWT) or the console (HttpOnly session cookie).
2. Objects stored in PostgreSQL include firewall rules, CIDR rules, DNS rules, blocked IPs, GeoIP rules, detection settings, and per-agent policy.
3. Agents pull/sync using Agent JWT:
   • POST /api/v1/agents/sync
   • capability-scoped /api/v1/agents/:id/sync/...
   • /api/v1/agent-rules/:agent_id
   • /api/v1/agent-policy/:agent_id
   • /api/v1/agent-blocked-ips
   • /api/v1/agent-geoip-rules
4. Virtualization Agents load maps into XDP/TC programs (firewall.o, firewall_egress.o).
5. Hosting Agents cannot receive rules (HTTP 409). Observation configuration is local YAML plus operator ACLs, not firewall rule assignment.

UID/GID rules (/api/v1/rules/uid-gid) exist but are not a production-complete contract.

Telemetry (Agent → Manager) #

1. Agents buffer events locally (example spool bounds in Agent logging config) and upload (POST /api/v1/security-logs and /batch, Agent capability).
2. Hosting Agents additionally expose category-safe hosting events for admins (GET /api/v1/agents/:id/hosting/events). Heartbeats carry observation_only and Hosting status.
3. Virtualization Agents can POST VM data (POST /api/v1/virtualization/vm-data).
4. Administrators read /api/v1/security-logs, /api/v1/security/logs, dashboard logs, and WebSocket /api/v1/dashboard/ws (console hub, not a public stream product).
5. Optional Prometheus /metrics on the Manager is admin-gated when enabled.

Public copy may say events are collected centrally. It must not promise lossless delivery.

Boundaries #

• Agent-facing enroll/sync URLs are operator-internal, not browser cookies.
• Hosting event APIs omit raw payload and customer IPs.
• Security logs include log_type, source_ip, action, severity (and related packet fields) for non-Hosting families; Hosting network events reject unrestricted packet fields.
• Cluster manager_urls failover on the Agent is not a public HA product.
• In-product updater campaigns are not the supported production upgrade path.

Edition differences #

Common misconceptions #

• “Every Agent gets every rule.” Assignment is per Agent; Hosting rejects rules.
• “WebSocket is a SIEM tap.” It is a console update hub.
• “Heartbeat 200 means collectors can read /var/log/nginx.” Hosting still needs ACLs.
• “Approval in AI Preview deployed the rule.” Approval records review intent only.

Related operational docs #

• Event model
• Policy model
• Agent/Manager trust
• Signals and events
• Agent enrollment
• Hosting telemetry