skip to content

In Trivy 0.74 client/server mode, what does `trivy server` do, what still runs on the client, and where does each side keep its cache?

level: seniorimportance: should knowfreq 12%

answer

  1. the database moves, the artefact stays
  2. missing layers only
  3. secrets never leave the client
  4. one BoltDB, one process
  5. Redis for several servers

basics

~20 s

The Trivy server holds and refreshes the vulnerability database and matches packages; the client still pulls the artefact, extracts packages and runs secret and misconfiguration checks. Both use --cache-dir, and several servers must share a Redis scan cache.

solid answer

~50 s

`trivy server` (listening on `localhost:4954` by default; bind `0.0.0.0` for remote clients) downloads the vulnerability database and keeps refreshing it, so clients do not keep their own copy of it. A client such as `trivy image --server http://trivy.example.internal:4954 --token ...` still pulls and unpacks the image, asks the server which layers it has not analysed, and uploads only those analysis results; vulnerability and license matching then run on the server, while misconfiguration and secret checks run on the client, so file contents never leave it. The docs list image, rootfs, filesystem and repository as supported; `config` and `k8s` are not. Each side keeps state under `--cache-dir` (the user cache directory plus `trivy`); the default `fs` scan cache is BoltDB, which one process can open at a time, and several servers behind a load balancer need a shared `redis://` cache backend.

code

bash · 7 lines
bash
# server: holds and refreshes the vulnerability DB; Redis lets replicas share layer results
trivy server --listen 0.0.0.0:4954 --token "$TRIVY_TOKEN" \
  --cache-backend redis://redis.example.internal:6379

# client: pulls the image, runs secret checks locally, sends package data
trivy image --server http://trivy.example.internal:4954 \
  --token "$TRIVY_TOKEN" registry.example.com/shop/api:1.4

go deeper

for a junior

Remember that trivy server holds the vulnerability database and clients connect with --server and an http or https URL.

for a middle

Explain the split: client analysis, server matching, secret and misconfiguration checks on the client, and the BoltDB lock behind cache-in-use errors.

for a senior

Run it in production: bind address and token, Redis for replicas, the layer cache missing failure, and per-process cache choices on busy agents.

for a principal

Weigh a shared scanning service against per-agent standalone runs: database traffic and freshness versus a central dependency every pipeline now waits on.

## Why client/server mode exists In standalone mode every Trivy run keeps its own copy of the **vulnerability database** in its cache directory and refreshes it when it is stale. Across dozens of build agents that means dozens of downloads and dozens of copies. **Client/server mode** moves the database to one long-running `trivy server`; clients send it what they found and receive the matched vulnerabilities. ## What runs where | Work | Where it runs in 0.74 | |---|---| | Pulling and unpacking the image, walking the filesystem | client | | Extracting packages from each layer | client, for layers the server has not seen | | Vulnerability matching | server | | License scanning | server | | Misconfiguration scanning | client (the checks bundle is downloaded on the client) | | Secret scanning | client; only the masked result is sent to the server | The split is deliberate: misconfiguration and secret checks need **file contents**, and shipping those to a shared server would move sensitive data across the network. The client therefore still needs registry access and disk space for the artefact; only the database moves. The supported targets are `image`, `rootfs`, `fs` and `repo`. `trivy config` and `trivy k8s` do not support client mode. ## Running it 1. Start the server: `trivy server --listen 0.0.0.0:4954 --token "$TRIVY_TOKEN"`. The default listen address is `localhost:4954`, which refuses other machines. 2. Point clients at it with a scheme: `trivy image --server http://trivy.example.internal:4954 --token "$TRIVY_TOKEN" registry.example.com/shop/api:1.4`. 3. The token travels in the `Trivy-Token` header unless `--token-header` changes the name. 4. `/healthz` and `/version` answer without authentication, which suits load-balancer probes. ## The layer handshake The server keeps a **scan cache** of per-layer analysis results. Before analysing, the client asks which of the image's layers are missing and analyses and uploads only those. That makes repeated scans of images sharing a base fast, and it explains a classic failure: with two servers behind a load balancer, one request can upload a layer to server A while the scan request lands on server B, which fails with `layer cache missing`. Several servers must share a Redis cache backend (`--cache-backend redis://host:6379`, with `--redis-tls` or `--redis-ca`, `--redis-cert` and `--redis-key` for TLS). ## The cache directory on either side `--cache-dir` is a global flag; its default is the operating system's user cache directory plus `trivy` (for example `~/.cache/trivy` on Linux). It holds: - the **scan cache** when the `fs` backend is used; - the vulnerability database and, when JARs are scanned, the Java index database; - the misconfiguration checks bundle and any VEX repositories. The `fs` backend is the default for `image`, `vm` and `repo` scans and is a **BoltDB** file that one process can hold at a time. Two concurrent scans on one cache directory, or a standalone scan beside a server using that directory, produce `cache may be in use by another process`. The remedies, in the docs' order of preference: - `--cache-backend memory` (already the default for `fs`, `rootfs` and `sbom`), at the cost of re-analysing layers each run; - Redis, for shared and concurrent access; - a separate `--cache-dir` per process, each of which then downloads its own database copy. `trivy clean --scan-cache`, `--vuln-db` or `--all` empties the cache without hunting for the directory. Where the database itself comes from, mirrors for air-gapped networks and skipping updates are separate subjects; client/server mode only decides who holds it.

  • Two image scans run in parallel on one build agent and one fails with `cache may be in use by another process`. Why, and what are the fixes?
    Both use the default `fs` scan cache, a BoltDB file that only one process can open. Use `--cache-backend memory` for one-off scans, Redis when the cache must be shared, or give each process its own `--cache-dir`, accepting that each then downloads its own copy of the database.
  • Why does Trivy run secret scanning on the client even in client/server mode?
    Secret scanning needs raw file contents. Running it on the server would mean shipping every file, sensitive ones included, across the network to a shared service, so the client scans locally and sends only the result, with the secret masked.

saying these in an interview costs you the question

  • In client/server mode the client no longer needs to pull the image.
  • The server receives every file so it can scan for secrets centrally.
  • Any number of Trivy servers can sit behind a load balancer with their default caches.
  • trivy k8s and trivy config can use --server like trivy image.
  • The vulnerability database is what causes cache lock errors.