Database lifecycle

Purpose

Grype's vulnerability database is a moving target — feeds change daily, schemas occasionally bump, and users need a way to inspect, refresh, import, and delete the local copy. The grype db family of subcommands plus the in-process curator handle all of that.

Subcommands

Subcommand	File	Effect
grype db check	cmd/grype/cli/commands/db_check.go	Compares local schema/build to the remote listing. Exits 100 (grypeerr.ErrDBUpgradeAvailable) if a newer version is available.
grype db delete	db_delete.go	Removes the local DB cache.
grype db diff <a> <b>	db_diff.go	Diffs two DB archives — used during release validation.
grype db import <archive>	db_import.go	Installs a DB from a local file (air-gapped use case).
grype db list	db_list.go	Lists DB candidates from the listing, sorted newest-first.
grype db providers	db_providers.go	Shows the data providers (NVD, distro feeds, GitHub, ...) backing the current DB.
grype db search	db_search.go	Top-level search command (delegates to package/vuln subcommands).
grype db search package	db_search.go (packagesCommand)	Look up affected packages by name.
grype db search vuln	db_search_vuln.go	Look up a vulnerability ID (CVE or vendor advisory) directly.
grype db status	db_status.go	Prints local DB location, schema version, and validity.
grype db update	db_update.go	Forces a refresh of the local DB.

In-process auto-update

During every scan, grype/load_vulnerability_db.go::LoadVulnerabilityDB calls the curator's Update() if --db-auto-update is enabled (default true). The curator:

1. Hits the listing URL (default https://grype.anchore.io/databases/v6/listing.json).
2. Compares the latest entry's checksum to the local cache.
3. Downloads the new archive if needed, verifies it, and atomically swaps it into place.

If the network call fails, the scan continues with the existing cache and a warning. If RequireUpdateCheck is set (the default), the failure is escalated to a hard error.

Cache layout

Default cache path: ~/.cache/grype/db/<schema>/. Inside it:

• vulnerability.db — the SQLite file.
• metadata.json — listing metadata.
• provider.json — data provenance.

db status prints all three. db delete removes them.

Schema awareness

The CLI is bound to a specific ModelVersion (currently 6 — see grype/db/v6/db.go::ModelVersion). The listing carries archives for multiple model versions; the client picks the highest one ≤ the supported version.

If the only available archives are higher than the supported version, db check returns ErrDBUpgradeAvailable with exit code 100, prompting the user to upgrade the binary.

Listing format

The listing is a JSON document at the configured URL. Each entry includes:

• url — the archive URL.
• built — RFC3339 build timestamp.
• schemaVersion — the model version (e.g. 6).
• checksum — SHA256 of the archive.

The distribution client (grype/db/v6/distribution/) parses this and exposes it as []Listing.

Air-gapped scenarios

For environments without internet access:

1. Download the archive on a connected machine.
2. Transfer it.
3. Run grype db import path/to/archive.tar.zst.
4. Run scans with --no-db-auto-update.

db import validates the archive against the supported schema and atomically installs it.

Key source files

File	Purpose
cmd/grype/cli/commands/db_*.go	The db subcommand family.
grype/load_vulnerability_db.go	Convenience wrapper used by the scan path.
grype/db/v6/installation/	Curator (status, update, import, delete).
grype/db/v6/distribution/	CDN client (listing, archive download, verification).

Entry points for modification

• Add a new db subcommand — create a file in cmd/grype/cli/commands/, define the cobra command, and register it in commands.DB(app).
• Change listing parsing — grype/db/v6/distribution/. Listing format is shared with grype-db.
• Change cache layout — grype/db/v6/installation/. Be aware of upgrade paths from previous layouts.