Vulnerability database guide

Learning objective

By the end of this guide you will know which vdb (vulnerability database) image variant to choose for your scanning scenario, how to download it with the depscan-vdb command, and how the scan path automatically selects the right variant when you use --severity.

Published image matrix

All images live at ghcr.io/appthreat/<name>:v6.7.x and are refreshed every 12 hours. The tag v6.7.x is a floating tag; override it with the VDB_IMAGE_TAG environment variable to point at a pinned release.

App and OS scope

The main matrix has three dimensions plus a compression choice:

• Scope: App Only (application vulnerabilities) vs App+OS (adds Linux distro vulnerabilities).
• Time: 2y (2024+), default (2020+), 10y (2016+).
• Tier: standard vs extended (extended populates metadata tables for severity, text, alias, reference, symbol, source, and date search).
• Compression: vdbxz (tar.xz, smaller download) or vdbzst (zstd, faster to decompress).

Scope	Time	Standard	Extended	Approx uncompressed
App	2y	vdbxz-app-2y	vdbxz-app-2y-extended	2.05 GiB
App	default	vdbxz-app	vdbxz-app-extended	2.96 GiB
App	10y	vdbxz-app-10y	vdbxz-app-10y-extended	3.52 GiB
App+OS	default	vdbxz	vdbxz-extended	42.36 GiB
App+OS	10y	vdbxz-10y	vdbxz-10y-extended	47.55 GiB

App+OS has no 2y image. Swap vdbxz for vdbzst in any name to switch compression.

Distro-only images

Standalone distro databases (2020+, no time or extended variants) for targeted container and OS scans:

Distro	Image name	Approx uncompressed
alpine	vdbxz-alpine	0.21 GiB
debian	vdbxz-debian	0.32 GiB
redhat	vdbxz-redhat	0.56 GiB
alma	vdbxz-alma	0.02 GiB
rocky	vdbxz-rocky	0.17 GiB
ubuntu	vdbxz-ubuntu	31.78 GiB

Each distro image is published in both vdbxz and vdbzst compression.

When to pick each variant

• App-only default (vdbxz-app): the right choice for most application dependency scans. It is roughly 3 GiB and covers 2020 onward.
• App-only 2y (vdbxz-app-2y): the smallest useful database for scanning modern projects where only recent CVEs matter.
• Extended (vdbxz-app-extended or vdbxz-extended): needed when you use --severity, full-text search, alias search, or any metadata-dependent feature. The scan path selects this automatically when --severity is set.
• App+OS default (vdbxz): for container and OS-package scans. This is the zero-flag default but is multi-GB; for source-only scans an app-only image is much faster to download.
• Distro-only (vdbxz-<distro>): for targeted scans of a single Linux distribution. These are much smaller than the full App+OS image.
• 10y (vdbxz-app-10y, vdbxz-10y): for legacy audits that need CVE data going back to 2016.

Using the depscan-vdb command

The depscan-vdb command is the first-class way to select, download, and inspect any published variant.

Download

# Default: App+OS standard, xz compression
depscan-vdb download

# Smaller app-only database for source scans
depscan-vdb download --scope app

# App-only extended (for severity and metadata search)
depscan-vdb download --scope app --extended

# 10y legacy audit database
depscan-vdb download --time 10y

# Ubuntu-only database for targeted container scans
depscan-vdb download --distro ubuntu

# Zstd compression for faster decompression
depscan-vdb download --scope app --compression zst

# Verbatim override (bypasses the resolver)
depscan-vdb download --image ghcr.io/appthreat/vdbxz-app-2y:v6.7.x

The command prints the resolved image reference and approximate uncompressed size before downloading.

Inspect the local database

depscan-vdb info

This prints the VDB_HOME directory, the last-pulled image variant, creation timestamp, freshness status, and whether extended metadata tables are populated.

Print VDB_HOME

depscan-vdb path

Convenience for scripting and CI pipelines.

How the scan path selects a database

The depscan scan command resolves its vdb image automatically using this precedence:

1. If VDB_DATABASE_URL is set, use that image verbatim (no automatic selection).
2. If --vdb-image is passed (or vdb_image is set in the config file), use it verbatim.
3. Otherwise, build the image from the --vdb-* selection options (--vdb-scope, --vdb-time, --vdb-extended, --vdb-compression, --vdb-distro). Unset options fall back to their defaults (App+OS, default time window, standard, xz), and USE_VDB_10Y=true still maps to the 10y window when --vdb-time is unset.

Persisting the database choice in the config file

The --vdb-* options are ordinary scan arguments, so they can be persisted in the depscan config file ($PWD/.config/depscan.toml by default) instead of being retyped on every run. Command line values always override the config file. Use flat keys, not a nested table:

# .config/depscan.toml
vdb_scope = "app"
vdb_time = "10y"
vdb_extended = true
vdb_compression = "zst"

With this file present, depscan --src . downloads ghcr.io/appthreat/vdbzst-app-10y-extended:v6.7.x without any extra flags. To pin a specific image instead, set vdb_image = "ghcr.io/appthreat/vdbxz-app:v6.7.x".

Auto-extended for --severity

When --severity is set and VDB_DATABASE_URL is not pinned, the scan automatically upgrades to the -extended variant and sets VDB_INCLUDE_METADATA=true. This makes the severity threshold push down into the vdb search layer for faster filtering.

If VDB_DATABASE_URL points at a non-extended image, depscan does not override it. The severity floor is still applied to the final VDR via the depscan-side vuln_meets_severity filter.

Variant tracking and re-download

depscan writes a marker file (.depscan-vdb-image) under VDB_HOME after each download. This records which image variant was pulled. When you switch variants (for example, from standard to extended, or from app-only to App+OS), depscan detects the mismatch and forces a re-download even if the existing database is still within the freshness window. This closes a gap where vdb metadata records the creation timestamp but not the source variant.

Summary

• Use depscan-vdb download to select and download any vdb variant.
• The scan path auto-selects the extended image when --severity is set.
• A variant switch forces a re-download via the marker file.
• For source-only scans, prefer an app-only image to avoid the multi-GB App+OS download.