aquasecurity/trivy

Database

Active contributors: knqyf263, DmitriyLewen, afdesk

Purpose

Trivy ships pre-built read-only databases that are downloaded at runtime: the Trivy DB (vulnerability data) and the Trivy Java DB (Java archive → Maven coordinate mapping). Both databases are produced by separate repositories (trivy-db and trivy-java-db) and distributed as OCI images.

pkg/db/ and pkg/javadb/ contain the runtime client code: download, version check, open, query.

Directory layout

pkg/
├── db/
│   ├── db.go              # download, version check, open
│   ├── db_test.go
│   └── testdata/
└── javadb/
    └── javadb.go          # Java DB client

The DB content (vulnerability records, Maven indexes) is not in this repo. The schema and producer code live in the trivy-db and trivy-java-db repos. This repo holds only the client.

Key abstractions

Symbol	File	Purpose
`db.Init`	`pkg/db/db.go`	Initialize DB at the configured cache directory.
`db.Update`	`pkg/db/db.go`	Download or refresh the DB.
`db.Close`	`pkg/db/db.go`	Release bbolt locks.
`pkg/oci.Artifact`	`pkg/oci/artifact.go`	The OCI download primitive used by both DBs and the policy bundle.
`javadb.Client`	`pkg/javadb/javadb.go`	Java DB client used by the JAR analyzer.
`vulnerability.Client`	`pkg/vulnerability/vulnerability.go`	High-level read API used by detectors.

Lifecycle

sequenceDiagram
    participant CLI
    participant DB as pkg/db
    participant OCI as ghcr.io/aquasecurity/trivy-db
    participant Cache as ~/.cache/trivy/db

    CLI->>DB: Init(cacheDir, opts)
    DB->>Cache: open metadata.json
    alt outdated or missing
        DB->>OCI: pull trivy-db:2 manifest
        DB->>OCI: download db.tar.gz layer
        DB->>Cache: write trivy.db
    else fresh
        DB->>Cache: open trivy.db
    end
    CLI->>DB: query (via vulnerability.Client)
    DB-->>CLI: vulnerability records
    CLI->>DB: Close()

metadata.json records the DB version, last update time, and download URL. Trivy refreshes the DB at most once per --db-refresh-interval (default several hours). The --skip-db-update flag suppresses the version check entirely.

Versioning

The DB has a schema version baked into the OCI tag:

ghcr.io/aquasecurity/trivy-db:2 — current schema.
ghcr.io/aquasecurity/trivy-db:1 — historical.

When the schema bumps, Trivy releases a new client that targets the new tag; old clients keep working against the old tag until it is retired. This is how Trivy avoids forcing every user to upgrade in lockstep with every DB schema change.

Java DB

The Java DB is a separate, much smaller database that maps SHA-1 hashes of Java archives (JARs) to Maven coordinates. It exists because not every JAR carries a usable manifest, and Maven coordinate matching is required to resolve vulnerabilities. The client in pkg/javadb/ follows the same OCI download pattern as the main DB.

Trivy Checks (policy bundle)

Although not strictly a "database", the Trivy Checks Rego bundle is downloaded the same way: as an OCI artifact. The client lives in pkg/policy/policy.go. The bundle contains per-provider Rego policies for the IaC scanner. Source: trivy-checks.

Configuration

Flag	Purpose
`--db-repository`	Override the OCI image.
`--java-db-repository`	Override the Java DB image.
`--skip-db-update`	Don't even check for updates.
`--skip-java-db-update`	Same for Java DB.
`--download-db-only`	Refresh the DB and exit.
`--download-java-db-only`	Same for Java DB.
`--db-refresh-interval`	Minimum time between version checks.
`--no-progress`	Suppress the progress bar during downloads.

Offline operation

For air-gapped use:

trivy --download-db-only
# copy ~/.cache/trivy to the air-gapped host
trivy --skip-db-update image my-image

This pattern works for the policy bundle too, with --skip-policy-update.

Integration points

Scan service — every detector queries the DB through pkg/vulnerability/.
Cache — DB sits inside the same cache directory but is managed separately.
Server — the server typically owns the DB so clients don't have to.

Entry points for modification

Add a new vulnerability source — coordinate with the trivy-db repo, then update detectors in pkg/detector/.
Change DB download path — pkg/db/db.go and pkg/oci/artifact.go. Be careful with backward compatibility.
Add a new database — create a new client package mirroring pkg/javadb/, then wire it into the analyzers that need it.

Key source files

File	Purpose
`pkg/db/db.go`	DB lifecycle.
`pkg/javadb/javadb.go`	Java DB client.
`pkg/oci/artifact.go`	OCI download primitive.
`pkg/policy/policy.go`	Trivy Checks bundle download.
`pkg/vulnerability/vulnerability.go`	Read-side query API.