Skip to main content

Agent Enrollment Runtime Lite

OneProtect now has the Phase 1 runtime-lite path for agent identity bootstrap. Tenant admins can issue bounded enrollment tokens, revoke them, and agents can exchange a token plus CSR for a tenant-scoped agent identity and placeholder certificate record. The exchange also returns a platform-issued runtime-lite service-account token for identity-bound heartbeat until enforced mTLS replaces that compatibility path.

User Value​

  • Gives RMM, discovery, SSH, macOS, Intune, and command work a real identity foundation instead of a fixture-only assumption.
  • Keeps enrollment tokens as bootstrap secrets: returned once, stored hashed, and never returned by list/status APIs.
  • Emits audit and event evidence for token issue, token revoke, failed enrollment, and successful enrollment.

Implemented Runtime​

  • GET /api/v1/agent-enrollment/tokens
  • POST /api/v1/agent-enrollment/tokens
  • POST /api/v1/agent-enrollment/tokens/{enrollment_token_id}/revoke
  • POST /api/v1/agent-enrollment/exchange
  • GET /api/v1/agents
  • GET /api/v1/agents/{agent_id}
  • POST /api/v1/agents/{agent_id}/telemetry/heartbeat

Storage is tenant-scoped through agent_enrollment_tokens, agent_identities, agent_device_certificates, and agent_revocations with Postgres RLS plus SQLite parity for local tests.

The heartbeat endpoint is identity-bound rather than a generic ingest shortcut. It accepts only service-account callers mapped to an existing tenant agent_identities row in enrolled or active status. Runtime-lite agents use the service_account_token returned by enrollment exchange; the token is signed by the platform runtime secret, scoped to agent_heartbeat, and bound to the enrolled tenant, agent, collector, and asset. Revoked, stale, unknown, wrong-tenant, actor-mismatched, or collector-mismatched calls fail closed and are audited.

Validation​

  • Token lifecycle, revocation, expiry, exhaustion, and replay behavior are covered by tests/test_agent_enrollment_runtime.py.
  • Runtime heartbeat bearer signing, TTL bounds, tamper rejection, and missing secret fail-closed behavior are covered by tests/test_agent_runtime_auth.py.
  • Identity-bound heartbeat with the platform-issued runtime token is covered by tests/test_agent_telemetry_runtime.py.
  • Event schemas validate for agent.enrollment_token.issued, agent.enrollment_token.revoked, agent.enrollment.failed, and agent.enrolled.
  • Enrollment token secrets, runtime bearer tokens, CSR bodies, hardware fingerprints, and certificate PEM values are not stored in audit records or returned through metadata APIs. Runtime token issue audit stores only token metadata and a SHA-256 hash.

Non-Scope​

This does not implement a certificate authority, enforced mTLS authentication, collector runtime, active/passive discovery, command execution, or deployment. AWS dev Helm must provide ONEPROTECT_AGENT_RUNTIME_TOKEN_SECRET through the existing runtime secret before enrollment exchange can issue heartbeat tokens.