aquasecurity/trivy

Cache

Active contributors: knqyf263, simar7, DmitriyLewen

Purpose

pkg/cache/ stores the output of file analysis (BlobInfo) and artifact-level metadata (ArtifactInfo) keyed by content digest, so that re-scanning the same image, layer, or filesystem only re-analyzes content that has changed. The cache is also the wire-format used between trivy client and trivy server: a remote cache means the server only needs to receive blobs the client computed.

Directory layout

pkg/cache/
├── cache.go      # Cache interface
├── client.go     # Concrete client (selects a backend)
├── fs.go         # Filesystem backend (default)
├── memory.go     # In-process backend (tests, ephemeral scans)
├── nop.go        # Disabled cache
├── redis.go      # Redis backend (multi-replica deployments)
├── remote.go     # Remote backend (Twirp; used by trivy client)
├── dir.go        # Default cache directory resolution
└── key.go        # Content-addressed key derivation

Key abstractions

Symbol	File	Purpose
`Cache`	`pkg/cache/cache.go`	The interface. Reads/writes `ArtifactInfo` and `BlobInfo` records.
`NewClient`	`pkg/cache/client.go`	Selects a backend based on the `--cache-backend` flag.
`FSCache`	`pkg/cache/fs.go`	Filesystem-backed bbolt store. The default for local scans.
`MemoryCache`	`pkg/cache/memory.go`	In-process map.
`RedisCache`	`pkg/cache/redis.go`	Redis-backed cache for multi-replica servers.
`RemoteCache`	`pkg/cache/remote.go`	Twirp-RPC cache; used by `trivy client`.
`NopCache`	`pkg/cache/nop.go`	No-op; useful when the user passes `--no-cache`.
`Key.CalcKey`	`pkg/cache/key.go`	Computes the content-addressed key from analyzer types and file content.

What is cached

graph LR
    Walker[fanal walker] -->|BlobInfo per layer/snapshot| Cache
    Artifact[artifact handler] -->|ArtifactInfo per scan| Cache
    Cache -->|GetBlob blobID| Applier
    Cache -->|GetArtifact artifactID| Applier

BlobInfo — analysis result for one layer or one filesystem snapshot. Contains OS family, packages, applications, secrets, licenses, configuration findings, etc. Keyed by sha256(<analyzer versions> + <layer digest>).
ArtifactInfo — top-level artifact metadata (image config, repo URL, etc.). Keyed by artifact-specific identifier.

The key derivation in key.go includes the version of every analyzer that participated, so bumping an analyzer's Version() automatically invalidates stale blobs.

Backend selection

graph TD
    Flag[--cache-backend] -->|fs default| FS[FSCache<br/>~/.cache/trivy]
    Flag -->|memory| Mem[MemoryCache]
    Flag -->|redis://...| Redis[RedisCache]
    Flag -->|remote| Remote[RemoteCache<br/>Twirp client]
    Flag -->|--no-cache / nop| Nop[NopCache]

pkg/cache/client.go parses the flag and returns a Cache instance. The filesystem backend uses bbolt buckets under ~/.cache/trivy/fanal/ and ~/.cache/trivy/policy/. The path is overridable with --cache-dir.

Filesystem layout

~/.cache/trivy/
├── db/                   # Trivy DB (bbolt)
├── fanal/                # FSCache (bbolt)
│   ├── fanal.db
│   └── ...
├── java-db/              # Java DB
├── policy/               # Trivy Checks bundle
└── vex-repo/             # VEX repositories

trivy clean (pkg/commands/clean/) wipes any subset of these directories.

Redis backend

The Redis backend writes the same data structures as the filesystem backend but serialized to JSON. It is most useful for trivy server deployments with multiple replicas — every replica reads from the same Redis instance, so a blob uploaded by one client is visible to a scan handled by another replica.

Configure with --cache-backend redis://<host>:<port> (and --redis-tls/--redis-ca/--redis-cert/--redis-key for TLS).

Remote backend

Used by trivy client. The remote cache is a Twirp client that proxies PutArtifact/PutBlob/GetArtifact/GetBlob to the server (rpc/cache/service.proto). Because keys are content digests, the client checks MissingBlobs first and only ships the blobs the server doesn't already have.

Integration points

fanal — the producer of cached blobs.
Scan service — consumes blobs via the applier.
RPC system — defines the Cache Twirp service.
Server — typically uses redis:// or filesystem.

Entry points for modification

Add a backend — implement Cache in a new file under pkg/cache/, then wire it up in client.go.
Change cache key derivation — pkg/cache/key.go. Be careful: changing the schema must bump the cache version.
Add a stored field — extend BlobInfo or ArtifactInfo in pkg/fanal/types/, then update the relevant analyzer and the applier.

Key source files

File	Purpose
`pkg/cache/cache.go`	`Cache` interface.
`pkg/cache/client.go`	Backend factory.
`pkg/cache/fs.go`	Bbolt-backed filesystem cache.
`pkg/cache/memory.go`	In-memory cache.
`pkg/cache/redis.go`	Redis cache.
`pkg/cache/remote.go`	Twirp-backed remote cache.
`pkg/cache/key.go`	Content-addressed key derivation.
`pkg/cache/dir.go`	Default cache directory resolution.