Security Model

Security Model

Trove is designed as an observation layer, not a control plane.

The safest way to run it is to keep that boundary intact.

Main security properties

• Agents push to the server. The server does not call agents.
• Agents use read-only platform credentials.
• The network write endpoint requires an agent bearer token.
• Agent tokens are stored as SHA-256 hashes.
• Registry freshness checks are read-only.
• The dashboard/read APIs are read-only and can be protected with OIDC.

Authentication boundary

Authenticated:

POST /api/v1/report

Authenticated when OIDC is configured, otherwise open by default:

GET /api/v1/services
GET /api/v1/agents
GET /api/v1/events
GET /api/v1/me
GET /metrics
GET /

Always unauthenticated:

GET /healthz
GET /oauth2/login       # registered when OIDC is enabled
GET /oauth2/callback    # registered when OIDC is enabled
POST /oauth2/logout     # registered when OIDC is enabled

Do not expose the dashboard directly to the public internet unless you enable native OIDC or put authentication in front of it. See Authentication.

OIDC logout clears Trove's local trove_session cookie and redirects through the provider's end_session_endpoint when available. That prevents the browser from being silently signed back in by an existing upstream SSO session.

Agent tokens

Tokens are generated with high entropy and prefixed with:

trove_

The server stores only SHA-256 token hashes.

A token grants the ability to submit reports as that agent. It does not grant access to Docker, Kubernetes, Proxmox, or host control through the Trove server because no such control endpoint exists.

Still, treat tokens as secrets. A compromised token can poison catalog data for that agent.

Platform credentials

Use the narrowest read-only credential possible.

Docker:

• Docker socket access is sensitive even when mounted read-only.
• The agent code should only use GET-style Docker API paths.

Kubernetes:

• use read-only RBAC
• avoid create/update/patch/delete/exec/attach permissions

Proxmox:

• use dedicated trove@pve user
• assign PVEAuditor
• create token with --privsep 0 so it actually inherits the read-only rights

Local:

• query systemd state only
• do not grant management rights the agent does not need

Registry SSRF guard

Freshness checks make outbound requests based on image references and registry challenges.

The registry client blocks network classes that should not be legitimate registries:

• loopback
• link-local
• unspecified
• multicast

It allows RFC1918 private ranges because self-hosted LAN registries are a supported use case.

That means private registry support is preserved, but server-side network placement still matters.

Recommended deployment posture

Run Trove with:

• private network binding or firewall rules
• native OIDC or reverse proxy authentication if exposed beyond LAN/VPN
• separate agent token per host/cluster
• read-only platform credentials
• regular database backups
• registry credentials scoped to pull/read only

What a compromised agent token can do

A compromised Trove token can:

• submit fake reports for that agent
• change what Trove believes about that agent's services
• trigger misleading events/alerts
• introduce image references that the freshness checker later attempts to resolve

It cannot, through Trove itself:

• restart workloads
• deploy workloads
• run shell commands
• read arbitrary files from agents
• call agent hosts from the server

What a compromised dashboard viewer can see

If someone can access the dashboard/API, they can see inventory data:

• service names
• hostnames
• image names
• ports
• labels
• agent names
• recent events

Treat that as sensitive infrastructure metadata.