Skip to main content

Customization through environment variables

The following environment variables can be used to customize the behavior.

Vulnerability database selection​

Use the depscan-vdb command to select, download, and inspect any published vdb image variant (scope, time window, extended tier, compression, distro) without hand-editing URLs. See the vulnerability database guide for the full image matrix and worked examples.

# Download the default app+OS database
depscan-vdb download

# Download a smaller app-only database
depscan-vdb download --scope app

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

# Download a distro-specific database
depscan-vdb download --distro ubuntu

# Inspect the locally cached database
depscan-vdb info

The scan command (depscan) auto-downloads the database it needs. When --severity is set and no custom image is pinned, depscan automatically selects the extended variant so severity push-down filtering fires inside the search layer.

The same selection can be set on the scan command with --vdb-scope, --vdb-time, --vdb-extended, --vdb-compression, --vdb-distro, and --vdb-image, and persisted in the depscan config file as flat keys (vdb_scope, vdb_time, vdb_extended, vdb_compression, vdb_distro, vdb_image). See the vulnerability database guide for a worked config example.

The environment variables below are advanced override knobs for automation and specialized deployments. In most cases the depscan-vdb command or the default scan behavior is sufficient.

Environment variables​

  • VDB_HOME - Directory to use for caching database. For docker-based execution, this directory should get mounted as a volume from the host.
  • VDB_DATABASE_URL - Override the vulnerability database OCI image URL verbatim. When set, depscan uses this image for the scan download without applying any automatic variant selection. Default: ghcr.io/appthreat/vdbxz:v6.7.x (app+OS).
  • USE_VDB_10Y - Set to true to use the larger 10-year vulnerability database with both app and OS vulnerabilities. Default download url: ghcr.io/appthreat/vdbxz-10y:v6.7.x. For an app-only 10 year database use ghcr.io/appthreat/vdbxz-app-10y:v6.7.x.
  • VDB_IMAGE_TAG - OCI tag for the vdb images. Default: v6.7.x. Override to point at a pinned point release or a custom tag. Applies to both depscan-vdb and the scan download path.
  • VDB_AGE_HOURS - Set the age threshold for the vulnerability database before it is re-downloaded. The default is 48 hours.
  • VDB_INCLUDE_METADATA - Set to true to use extended vulnerability metadata tables during the scan. When --severity is set without a custom VDB_DATABASE_URL pin, depscan sets this automatically and downloads the extended image. When this is unset and no severity threshold is used, the standard image is downloaded and --severity still filters the final VDR via the depscan-side severity floor.
  • DEPSCAN_TEMP_DIR - Temporary directory to use.
  • DEPSCAN_SOURCE_DIR_IMAGE - Alternative to --src argument to pass the source directory or image name.
  • DEPSCAN_REPORTS_DIR - Alternative to --reports-dir to pass the output reports directory.
  • DEPSCAN_SEVERITY - Alternative to the --severity argument. Set to low, medium, high, or critical to apply a minimum severity floor to the report. When set, depscan auto-selects the extended vdb image (unless VDB_DATABASE_URL is pinned) and pushes the filter into the search layer.
  • DEPSCAN_FAIL_ON_ERROR - Alternative to the --fail-on-error argument. Set to true or 1 to abort the scan with a non-zero exit code on unreadable reachability reports, empty slices, failed tools (blint, rusi, golem, dosai), or a failed BOM/package lookup, instead of silently degrading the results. The flag is also passed through to cdxgen's --fail-on-error.
  • OSV_EXCLUDE_MALWARE - Set to true or 1 to exclude malware (MAL-*) advisories from the results. This filter works on the default database because the is_malware signal is always populated.
  • DEPSCAN_SOURCE_IMAGE - Source image name to use for lifecycle analysis. Same as the key source_image in the configuration file.
  • DEPSCAN_BUILD_DIR - Build directory to use for lifecycle analysis. Blint sbom command will be executed with this directory. Defaults to the source directory (--src). Same as the key build_dir in the configuration file.
  • DEPSCAN_SERVER_API_KEY - API key required for all requests when the dep-scan server is configured with built-in authentication. Accepted via X-API-Key or Authorization: Bearer <key>.
  • DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND - Set to true only if you intentionally want the dep-scan server to bind to a non-local address without built-in authentication.
  • DEPSCAN_SERVER_ALLOWED_GIT_SCHEMES - Comma-separated list of allowed URL schemes for server-side URL scans. Defaults to http,https,git,git+http,git+https.
  • DEPSCAN_SERVER_ALLOW_PRIVATE_URLS - Set to true to allow the server to scan URLs that resolve to private, loopback, or link-local addresses. Leave unset for the safer default.
  • DEPSCAN_SERVER_MAX_CONTENT_LENGTH - Maximum accepted request body size in bytes for the built-in server, including uploaded BOM files. Defaults to 104857600 (100 MiB).