Image Freshness

Image Freshness

Trove can tell whether a running image is behind the current digest for its tag.

This is a read-only background check. It never pulls images, pushes images, or changes workloads.

How it works

Agents report:

• image reference
• running image digest, where available

The server stores image references used by services.

The freshness loop periodically:

1. finds images due for a check
2. resolves the latest registry manifest digest
3. stores the result in image_checks
4. compares service running digests against cached latest digests at read/alert time

Defaults

Setting	Default
scan interval	5m
successful result TTL	6h
normal error backoff	30m
rate-limit backoff	2h
batch size	50 images
concurrency	4 registry lookups

Configuration

Variable	Default	Purpose
TROVE_FRESHNESS_ENABLED	true	Set false or 0 to disable freshness checks.
TROVE_FRESHNESS_INTERVAL	5m	How often to scan for due images.
TROVE_FRESHNESS_TTL	6h	How long a successful digest result is considered fresh.
TROVE_REGISTRY_AUTHS	empty	JSON registry credentials by host.

Example credentials:

{
  "ghcr.io": {
    "username": "techdox",
    "password": "github_pat_xxx"
  },
  "docker.io": {
    "username": "docker-user",
    "password": "docker-token"
  }
}

Registry protocol

The registry client uses the Docker Registry HTTP API v2.

It tries HEAD first because that is cheaper and avoids unnecessary pull budget on registries that support it.

If needed, it falls back to GET.

It supports standard bearer-token challenge flow and basic auth.

Docker Hub defaults

Image parsing applies Docker Hub defaults:

• nginx:latest becomes registry registry-1.docker.io, repo library/nginx, tag latest
• missing tag defaults to latest
• pinned digest suffixes are removed for tag lookup

SSRF guard

Image references and registry auth challenges are attacker-influenced if an agent token is compromised.

The registry client protects freshness checks with a dial-layer guard. It blocks connections to:

• loopback
• link-local unicast
• link-local multicast
• unspecified addresses
• multicast

It deliberately does not block RFC1918 private ranges, because self-hosted registries on LANs are a real Trove use case.

That is a trade-off: private registries work, but a compromised agent token may be able to make the server attempt registry-style requests to other LAN hosts.

Alert behaviour

Freshness alerts fire when a running image falls behind its registry tag.

Freshness unknown is treated carefully. Transient registry errors should not erase an existing known-bad state or incorrectly suppress a later resolved notice.

See Alerts-and-Digest for alert state details.