Endpoint Agent Go Binary

The OneProtect endpoint agent is a standalone Go binary that runs on tenant Windows, macOS, and Linux endpoints. Its implementation lives in a separate top-level repository (oneconnect-agent); this repository owns the platform contracts the agent consumes.

What It Is

The endpoint agent:

• enrols once through POST /api/v1/agent-enrollment/exchange,
• stores local agent identity, certificate, and key material with mode 0600,
• collects basic inventory and host telemetry,
• posts identity-bound heartbeat telemetry to the platform via POST /api/v1/agents/{agent_id}/telemetry/heartbeat,
• stops cleanly when the platform rejects the identity as unknown, revoked, or stale.

It is not a remote shell, SSH broker, patch manager, software deployer, EDR, process monitor, or log forwarder.

Where The Implementation Lives

Concern	Repository
Go agent binary, build, tests, packaging, release pipeline	oneconnect-agent
OpenAPI / AsyncAPI / JSON Schema contracts the agent calls	oneconnect (this repo)
Platform enrollment + telemetry runtime (Python)	oneconnect (this repo)
ADR-0019 boundary decision and ADR-0009 enrollment contract	oneconnect (this repo)

Repository: git@gitlab-oneconnect-agent:medhamsh/oneconnect-agent.git.

Why Two Repositories

Endpoint software ships to thousands of tenant machines through MSI / PKG / DEB / RPM packaging and signed-release pipelines that are independent of the platform's container images and Helm chart. Splitting the agent keeps:

• a tighter dependency policy on the agent side (gopkg.in/yaml.v3 plus golang.org/x/sys only),
• a smaller contributor surface for security researchers and external contributors,
• and independent release cadences for platform vs. endpoint software.

ADR-0019 originally placed the agent under a top-level agent/ directory in this monorepo. After OP-053R staging, the architect chose to spin the implementation out so cross-repo concerns are explicit rather than implicit.

Runtime Shape (Summary)

The full runtime documentation lives in oneconnect-agent/README.md. Phase 1 lifecycle in summary:

• Install: YAML config at /etc/oneprotect/agent.yaml (Linux/macOS) or C:\ProgramData\OneProtect\agent.yaml (Windows).
• Enroll: one-shot CSR + nonce exchange; identity persisted at mode 0600; enrollment token cleared after success.
• Run: periodic heartbeat (default 60s); exponential backoff with jitter on transient errors; fail-closed exit on 401/403.
• Shutdown: clean exit on SIGINT/SIGTERM.

Telemetry Contract

The agent emits AgentHeartbeatTelemetryRequest per specs/openapi.yaml in this repo (flat shape with additionalProperties: true). New fields ride on additionalProperties. Required Phase 1 facts come from ADR-0019:

• hostname, OS family + version, uptime
• CPU count + usage percentage
• memory total + used
• disk total + used per mount
• network interfaces with IP and MAC addresses
• running process count

Security Rules

These constraints govern the agent runtime in oneconnect-agent and are mirrored here for platform-side contributors who design or change the contracts the agent consumes:

• Store private keys with owner-only permissions (0600).
• Delete enrollment tokens after successful enrollment.
• Never log tokens, certificate PEM, private keys, bearer credentials, CSR bodies, hardware fingerprints, agent nonces, or sensitive host details.
• Generate a fresh random nonce for every enrollment attempt.
• Prefer machine ID or serial-number style fingerprints over MAC-only fingerprints.
• Treat source IP, MAC, and hostname as telemetry, not tenant identity.

Non-Scope

Remote shell, SSH broker, patch manager, software deployer, EDR, real-time process monitor, and log forwarder remain separate scoped features. Adding any of those to the agent module requires a successor ADR.

What This Repo Should Not Contain

Pull requests that add agent/ directories or Go source files to oneconnect should be redirected to the oneconnect-agent repository. The boundary is enforced by social process, not by code today.