vulnerability-db

Environment variables

VDB is configured almost entirely through environment variables. Boolean toggles treat true or 1 as enabled. Path and build-scope variables are read at import time, so set VDB_HOME before importing vdb.lib.config; setting them later in a long-running process has no effect.

This page is the full reference, grouped the way vdb/lib/config.py and the ingestion modules are organized. If you change a variable in code, keep this page, the root README and the MCP server readme in sync.

Paths and local storage

Variable	Default	Used by	Description
VDB_HOME	Platform user data directory	CLI and library	Directory containing data.vdb7, data.index.vdb7 and vdb.meta.
VDB_CACHE	Platform user cache directory	vdb --cache-os, AquaSource	Cache directory. If $VDB_CACHE/vuln-list.zip exists it is used instead of downloading.
VDB_TEMP_DIR	System temp directory	SQLite setup	Directory for SQLite temporary files during large builds and VACUUM. Use a partition with room for app+OS builds.
VDB_SHARDS_DIR	$VDB_HOME/shards	Shard-mode search	Local type-shard store: one <shard>/ directory per shard, each with data.vdb7, data.index.vdb7 and a v2 vdb.meta. The connected main database participates as a shard when its own meta declares completeness: "partial".
VDB_AUTO_FETCH	unset	Shard-mode search	Opt-in on-demand shard fetch. When enabled, a shard-mode purl search needing a missing shard fetches it from the registry recorded in a local shard’s vdb.meta siblings. Off by default so scans never reach for the network implicitly.
VDB_SHARD_FANOUT	sequential	Shard-mode search	Multi-shard fan-out strategy. sequential runs the canonical per-shard search path; attach UNION-ALLs attached shard indexes for the index sweep. Both are gated by the multi-shard match-set gate.
VDB_ZSTD_BIN	unset (search PATH for zstd)	-zst artifact refresh	Explicit zstd binary for unpacking -zst artifacts on Python < 3.14 (3.14+ uses the stdlib compression.zstd module). An absolute path for bundled or air-gapped deployments, or a bare name resolved against PATH. A value that resolves to nothing leaves zst refreshes refused with both remedies named; xz always works.

Pre-built database downloads

Variable	Default	Used by	Description
VDB_APP_ONLY_DATABASE_URL	ghcr.io/appthreat/vdb7-app-only:v7.0.x-xz	vdb db refresh full --app-only, MCP auto-download	OCI image URL for the default app-only database. vdb7-app-only (a complete app-scope database), not vdb7-app (the partial group shard). Override to consume an internally published artifact.
VDB_DATABASE_URL	ghcr.io/appthreat/vdb7-full:v7.0.x-xz	vdb db refresh full, vdb db refresh full --image <oci-ref>	OCI image URL for the app+OS database. Must be a v7 artifact; a v6 image is rejected. Prefer the -xz variant: it unpacks unconditionally, while -zst needs a zstd decompressor (Python 3.14+ or a zstd binary on PATH).

Source and feed selection for builds

Variable	Default	Used by	Description
NVD_START_YEAR	2022	NVD/vuln-list conversion, distro feeds	Start year for NVD-style CVE data and the Linux distro feeds. Older years increase coverage, build time and database size. Does not apply to application ecosystem advisories, because a distro fix moves the whole release forward while a lockfile does not.
VDB_APP_ECOSYSTEM_START_YEAR	unset (no floor)	OSV application ecosystem feeds	Re-imposes a start year on the application ecosystems (npm, PyPI, Maven, Go, crates.io, NuGet, RubyGems, Hex, Packagist, Pub, CRAN, SwiftURL, Julia, GitHub Actions). A year, or nvd to follow NVD_START_YEAR. Set it only to trade coverage for a smaller artifact.
GITHUB_TOKEN	unset	GitHub advisory ingestion	Token for the GitHub GraphQL API. Never print this value in logs.
GITHUB_GRAPHQL_URL	https://api.github.com/graphql	GitHub advisory ingestion	Alternate GitHub GraphQL endpoint, for testing or enterprise proxies.
GITHUB_PAGE_COUNT	2	GitHub advisory ingestion	Number of GitHub advisory GraphQL pages to fetch during a full refresh.
NPM_PAGE_COUNT	2	npm advisory configuration	Number of npm advisory pages to fetch where npm ingestion is used.
OSV_INCLUDE_FUZZ	unset	OSV ingestion	Include the Linux, OSS-Fuzz and Android OSV feeds that are excluded by default to reduce false positives.
OSV_EXCLUDE_MALWARE	unset	OSV conversion	Exclude OSV malware advisories whose identifiers start with MAL.
VDB_OSV_STORE_BATCH_SIZE	100	OSV ingestion	Converted OSV records stored per database batch. Invalid values fall back to 100; minimum 1.
VDB_MAX_AFFECTED_PER_BLOB	32	CVE-5 blob storage	Maximum affected entries merged into one source blob per CVE; further entries spill into more blobs so blob size and per-row hydration cost stay flat as CVE fan-out grows. 0 disables merging; invalid values fall back to 32.
VDB_INCLUDE_METADATA	unset	CLI, storage, search metadata indexes	Populate extended metadata tables. Equivalent to --include-metadata.
VDB_METADATA_*	unset	vdb.meta creation	Adds custom build metadata to vdb.meta; the prefix is stripped and the key lowercased. true/1 and false/0 are stored as booleans.

OS distro filtering for builds

Variable	Default	Used by	Description
VDB_IGNORE_OS	unset	OSV source configuration	Skip the OSV operating-system feeds added by default. Use app-only workflows for the smallest app database.
VDB_IGNORE_<DISTRO>	unset	vuln-list and selected OSV distro feeds	Exclude distro-specific data. Static OSV toggles are VDB_IGNORE_ALMALINUX, VDB_IGNORE_ALPINE, VDB_IGNORE_REDHAT, VDB_IGNORE_DEBIAN, VDB_IGNORE_ROCKYLINUX, VDB_IGNORE_MAGEIA, VDB_IGNORE_ALPAQUITA, VDB_IGNORE_MINIMOS and VDB_IGNORE_AZURE_LINUX; vuln-list also supports the distro keys in LINUX_DISTRO_VULN_LIST_PATHS. SUSE and openSUSE are opt-in instead. Debian, Ubuntu, Red Hat, SUSE, openSUSE and Azure Linux data comes from the OSV feeds only.
VDB_EXCLUDE_<DISTRO>	unset	vuln-list filtering	Alias for excluding vuln-list distro paths.
VDB_INCLUDE_<DISTRO>	unset	vuln-list filtering	Force-include distro paths from LINUX_DISTRO_VULN_LIST_PATHS, such as VDB_INCLUDE_ALPINE=true. VDB_INCLUDE_SUSE=true and VDB_INCLUDE_OPENSUSE=true are separate: they enable the OSV SUSE and openSUSE feeds, the only source of SUSE family data, which are off by default. They have the heaviest errata fan-out of any feed, so they stay opt-in for local builds; the published OS databases enable both.
VDB_IGNORE_LINUX_KERNEL	true	Storage	Skip pkg:generic/linux records. The kernel feed dominates the database (around 130k rows) with commit-sha version ranges that semantic-version lookups cannot match.
VDB_INCLUDE_LINUX_KERNEL	unset	Storage	Opt back in to storing Linux kernel CVEs. Overrides VDB_IGNORE_LINUX_KERNEL.

See LINUX_DISTRO_VULN_LIST_PATHS in config.py for the full list of distro strings.

Output and SQLite tuning

Variable	Default	Used by	Description
VDB_QUIET	unset	CLI	Suppress logo, logs and cache progress output. Equivalent to --quiet.
VDB_PROGRESS_INTERVAL	10000	Source progress callbacks	Minimum records between progress messages. Invalid values fall back to 10000; minimum 1.
VDB_SQLITE_IMMUTABLE	unset	Search database connections	Open file-backed search databases with SQLite’s immutable URI option, for read-only deployments where .vdb7 files are not modified while the process runs.
VDB_SQLITE_CACHE_SIZE	-65536	SQLite setup	Value passed to PRAGMA cache_size. The default is about 64 MiB using SQLite’s negative-KiB convention.
VDB_SQLITE_JOURNAL_MODE	DELETE	SQLite setup	Value passed to PRAGMA journal_mode. Valid: DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF.
VDB_SQLITE_SYNCHRONOUS	OFF	SQLite setup	Value passed to PRAGMA synchronous. Valid: OFF, NORMAL, FULL, EXTRA, or 0 to 3.
VDB_DATA_PAGE_SIZE	32768	Builds and splits	Page size for the data database. Powers of two from 512 to 65536; invalid values warn and fall back. The 32K default ships around 27% smaller files and halves cold hydration; set 4096 to restore the previous size.
VDB_INDEX_PAGE_SIZE	unset	Builds and splits	Page size for the index database. The random-access index file shows no win past the 4096 default, so leaving this unset is the recommendation.
PYTHONIOENCODING	unset	Windows startup	If unset on Windows, VDB reconfigures standard streams to UTF-8.

MCP server

Variable	Default	Used by	Description
VDB_AGE_DAYS	2	MCP server	Days before the MCP server considers the local database stale and attempts an app-only ORAS download. Non-numeric values are passed through to the freshness check, so prefer an integer string.

Variables that do not exist

VDB_EXTENDED_DATABASE_URL, VDB_APP_ONLY_EXTENDED_DATABASE_URL and USE_VDB_10Y do not exist in v7. The artifacts those 6.x variables selected are the app-scope variants, reached with vdb db refresh full --flavor <name> or --image <oci-ref>. Do not document them as live options.

This site is open source. Improve this page.