Skip to main content

Agent Identity Telemetry Runtime

Status​

Implemented as a narrow RMM runtime slice. This does not implement CA runtime, enforced mTLS, osquery/Fleet/OTel bridges, scanner runtime, command execution, SSH, patching, or deployment changes.

  • Client response references: tenant-scoped enrollment and RMM telemetry are Phase 1.
  • ADR references: ADR-0009 agent enrollment/mTLS identity and ADR-0012 discovery authorization boundaries.
  • Task board references: OP-032R and OP-052.

Problem Statement​

Agent enrollment was real, but telemetry still mostly flowed through the older heartbeat helper. OneProtect needed the next safe link in the RMM chain: enrolled identity to heartbeat/inventory to asset read-model updates.

Architectural Intent​

The heartbeat endpoint is scoped to a stored agent identity. The API resolves tenant, site, collector, and asset IDs from agent_identities and rejects caller attempts to override identity boundaries.

What Was Implemented​

  • POST /api/v1/agents/{agent_id}/telemetry/heartbeat
  • Active/enrolled agent identity validation before accepting telemetry.
  • Clear 401/403 responses for unknown, revoked, stale, wrong-actor, wrong collector, and non-service-account callers.
  • Reuse of existing asset.discovered and asset.telemetry.received projection paths.
  • Agent identity last_seen_at, status, hostname, and version refresh.
  • Tests for tenant isolation, service-account enforcement, status rejection, actor mismatch, collector mismatch, projection, and duplicate idempotency.

APIs / Events / Schemas​

  • POST /api/v1/agents/{agent_id}/telemetry/heartbeat
  • Reuses existing events:
    • asset.discovered
    • asset.telemetry.received

No new event schema was required.

Security / Tenant Isolation​

  • The caller must be a service account.
  • The caller actor must match the stored agent_id or collector_id.
  • The agent identity must exist in the authenticated tenant.
  • Only enrolled and active identities can submit telemetry.
  • revoked and stale identities fail closed with explicit 403 errors.
  • Unknown tenant-scoped identities return 401 so the caller can re-enroll or stop.

Validation Steps​

.venv/bin/python -m unittest tests.test_agent_telemetry_runtime
make test-sqlite

Known Limitations​

  • Runtime-lite identity only; no CA or enforced mTLS.
  • No real agent binary.
  • No osquery/Fleet/OTel collector bridge.
  • No scanner or passive network discovery runtime.
  • No command execution.