How Trivy Client-Server Mode Works and When to Use It

Trivy client-server mode runs a persistent server that hosts the vulnerability database and optionally caches artifact metadata, while lightweight clients send scan targets via HTTP/Twirp RPC and receive results without downloading the ~2 GB database themselves.

Trivy client-server mode centralizes heavy resource management in a long-running server process while distributing lightweight scanning operations across multiple machines. In the aquasecurity/trivy repository, this architecture separates the vulnerability database (approximately 2 GB) and artifact caching from the scanning logic, allowing CI agents and edge devices to operate with minimal overhead. Understanding how this mode functions helps you optimize scan performance in distributed environments.

Architecture Overview

The Server Component

The Trivy server starts an HTTP listener (default localhost:8080) and registers two Twirp RPC services in pkg/rpc/server/server.go. The Scanner service performs actual vulnerability, license, and misconfiguration scans, while the Cache service stores artifact metadata to prevent redundant layer downloads. Database initialization occurs via vulnerability.NewClient inside initializeScanServer, ensuring the vulnerability database is ready before accepting requests.

The Client Component

The client operates as a thin CLI wrapper defined in pkg/rpc/client/client.go that constructs protobuf requests and transmits them to the server's /twirp endpoint. When you invoke trivy image --server http://host:port, the client builds an rpcScanner.ScanRequest and sends it to <server>/twirp/github.com/aquasecurity.trivy/rpc.scanner.Scanner/Scan. The client then converts the rpcScanner.ScanResponse back into Trivy's native types.Report for display.

Request Lifecycle in Client-Server Mode

Understanding the request flow clarifies how Trivy client-server mode minimizes client-side resource consumption.

1. Server Initialization: The server.Run function in pkg/rpc/server/listen.go creates an http.Server with a ServeMux that registers the Twirp handlers. It parses flags for listen address, authentication tokens, and cache configuration from pkg/commands/app.go.

2. Client Invocation: The CLI parses the --server flag in pkg/commands/app.go and invokes client.Service.Scan, which marshals the target (image name, file path, or repository URL) into a protobuf message.

3. Remote Execution: The server's ScanServer.Scan method receives the request, invokes the underlying local scan service, and returns a protobuf-encoded response containing vulnerability findings.

4. Result Rendering: The client deserializes the response and renders it according to the selected output format (table, JSON, SARIF, etc.).

When to Use Trivy Client-Server Mode

Multiple CI Agents: When numerous build nodes need to scan containers but you want to avoid each node downloading the ~2 GB vulnerability database. The single server holds the DB, reducing network I/O and startup time across your fleet.

Centralized Policy Enforcement: Use this mode to enforce shared ignore rules, custom database mirrors, or uniform vulnerability definitions. The server configuration propagates to all clients automatically.

High-Throughput Scanning: For large CI pipelines or CI/CD SaaS environments, the Cache service prevents repeated layer pulls for identical images, significantly accelerating subsequent scans of the same base images.

Security-Sensitive Environments: In scenarios where you cannot expose raw files to remote services, note that vulnerability scanning runs on the server while misconfiguration and secret detection execute locally on the client, keeping sensitive file contents decentralized.

Resource-Constrained Nodes: Edge devices and low-memory containers benefit from negligible client resource usage, while the server runs on more powerful infrastructure.

Configuration Examples

Start a server with authentication:

# Start server on all interfaces with token protection

trivy server --listen 0.0.0.0:8080 --token my-secret-token

Scan via client:

# Scan a container image

trivy image --server http://localhost:8080 --token my-secret-token alpine:3.10

# Scan filesystem

trivy fs --server http://localhost:8080 --severity HIGH ./my-app/

# Scan a remote repository

trivy repo https://github.com/example/project --server http://localhost:8080

Health checks:

# Check server health (no auth required)

curl -s http://localhost:8080/healthz

# Get version and DB metadata

curl -s http://localhost:8080/version | jq

Key Implementation Files

Understanding these source files clarifies how data flows through the system:

• pkg/commands/app.go: Defines the server sub-command, flag parsing for --listen and --token, and client-side --server flag handling.
• pkg/rpc/server/server.go: Implements the Scanner and Cache Twirp services, including ScanServer.Scan and cache management logic.
• pkg/rpc/server/listen.go: Constructs the HTTP server, registers Twirp handlers on the ServeMux, and manages the server lifecycle.
• pkg/rpc/client/client.go: Handles client-side RPC calls, version negotiation, and response deserialization.

Summary

• Trivy client-server mode separates the heavy vulnerability database (~2 GB) from lightweight scanning clients using HTTP/Twirp RPC.
• The server exposes two services: Scanner for vulnerability analysis and Cache for artifact metadata storage.
• Clients send minimal target information and receive full reports without downloading or storing vulnerability data locally.
• Ideal for CI/CD fleets, resource-constrained environments, and centralized policy management scenarios.

Frequently Asked Questions

Does the Trivy client download the vulnerability database in client-server mode?

No. In client-server mode, only the server downloads and maintains the vulnerability database. Clients transmit target specifications (image names, file paths) to the server and receive processed results, eliminating the ~2 GB download requirement per client.

How does the client authenticate with the Trivy server?

Authentication uses the --token flag on both sides. Start the server with --token my-secret-token, then configure clients with --token my-secret-token and --server http://host:port. The token is transmitted via HTTP headers in the Twirp requests.

What happens if the Trivy server is unavailable during a scan?

The client requires an active connection to the server to perform vulnerability scans. If the server is unreachable, the client returns a connection error and exits. For local-only operation, you must run Trivy in standalone mode without the --server flag.

Can I run secret detection and misconfiguration scans in client-server mode?

Secret detection and misconfiguration scanning execute locally on the client rather than on the server. According to the aquasecurity/trivy documentation, only vulnerability database lookups are centralized; sensitive file contents for secret scanning remain on the client machine for security reasons.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}