vulnerability-db

name	vulnerability-db
description	Use when working with a practical skill guide for AI agents that need to use or extend `vdb`.
metadata	{"author":"AppThreat"}

SKILL.md

A practical skill guide for AI agents that need to use or extend vdb.

Skill: choose the right VDB database

Use the database variant that matches the user's scan scope:

Need	Recommended variant
Modern application dependencies only	app-only 2-year or app-only default
Standard dependency scanning	app-only default
Legacy application audit	app-only 10-year
Container or Linux OS package scanning	app+OS default
Legacy container/VM audit	app+OS 10-year
Metadata/text/alias/reference/symbol search	matching *-extended variant

Prefer organization-controlled mirrors or internally produced artifacts when available. Use AppThreat-hosted defaults for bootstrap, local testing, or when no internal URL is provided.

Normal v6.7+ databases keep extended metadata tables empty to minimize index size. Choose a *-extended database when the task needs search_full_text(), search_by_alias(), search_by_reference(), search_by_package_name(), search_by_symbol(), or filters that depend on metadata such as source, severity, dates, and malware flags.

Skill: download before searching

A pre-built SQLite database must exist before normal search operations.

CLI quick start:

vdb --download-image

Extended app-only database for metadata search APIs:

export VDB_APP_ONLY_DATABASE_URL=ghcr.io/appthreat/vdbxz-app-extended:v6.7.x
vdb --download-image

Full app+OS database:

vdb --download-full-image

Extended app+OS database for container/OS scans plus metadata searches:

export VDB_DATABASE_URL=ghcr.io/appthreat/vdbxz-extended:v6.7.x
vdb --download-full-image

Python usage:

import os
from vdb.lib import config, db6, search
from vdb.lib.orasclient import download_image

DB_URL = os.getenv("VDB_APP_ONLY_DATABASE_URL", config.VDB_APP_ONLY_DATABASE_URL)

if db6.needs_update(days=1, default_status=True):
    download_image(DB_URL, config.DATA_DIR)

results = search.search_by_any("pkg:pypi/requests@2.31.0", with_data=True)

Skill: query structured results

Do not expect the CLI to emit stable JSON. For structured output, use the Python API.

import json
from vdb.lib import search

output = []
for item in search.search_by_any("pkg:npm/lodash@4.17.20", with_data=True):
    row = {
        "cve_id": item["cve_id"],
        "package": item["name"],
        "purl_prefix": item["purl_prefix"],
        "vers": item["vers"],
        "fix_version": item.get("fix_version"),
        "severity": item.get("severity"),
    }
    if item.get("source_data"):
        row["cve_data"] = item["source_data"].model_dump(mode="json")
    output.append(row)

print(json.dumps(output, indent=2))

Skill: perform bulk searches

Use batched APIs for large SBOM or package lists.

from vdb.lib import search

packages = [
    {"purl": "pkg:pypi/requests@2.31.0"},
    {"purl": "pkg:npm/react@18.2.0"},
    {"url": "https://github.com/pallets/flask"},
]

for batch in search.search_packages_batched(packages, batch_size=100, with_data=False):
    for item in batch:
        print(item["locator"], item["result_count"], item.get("max_severity"))

Skill: build a local database safely

Use app-only builds unless OS package scanning is required.

export VDB_HOME=/tmp/vdb-home
export VDB_CACHE=/tmp/vdb-cache
export VDB_TEMP_DIR=/tmp/vdb-home/tmp
export NVD_START_YEAR=2024
export GITHUB_PAGE_COUNT=1
export OSV_EXCLUDE_MALWARE=true
mkdir -p "$VDB_HOME" "$VDB_CACHE" "$VDB_TEMP_DIR"

vdb --cache

For app+OS builds:

vdb --cache-os

For extended builds that populate metadata search tables, add --include-metadata or set VDB_INCLUDE_METADATA=true:

vdb --cache --include-metadata
vdb --cache-os --include-metadata

Cache builds print minimal progress. Use --quiet or VDB_QUIET=true to suppress logo, logs, and progress output. Tune progress cadence with VDB_PROGRESS_INTERVAL.

To restrict OS data, use VDB_IGNORE_* or VDB_INCLUDE_* flags from vdb/lib/config.py.

Example:

export VDB_IGNORE_DEBIAN=true
export VDB_IGNORE_ALPINE=true
export VDB_IGNORE_UBUNTU=true
vdb --cache-os

Skill: reproduce cache bugs without large downloads

AquaSource reads $VDB_CACHE/vuln-list.zip if it exists. Agents can create a small zip with representative paths and monkeypatch config.CACHE_DIR in tests.

This avoids cloning or downloading the full vuln-list repository.

Skill: reason about VDB 6.7 storage

VDB 6.7+ stores source CVE blobs once in cve_source_data and stores package locator rows in cve_data. The index database stores package/version rows in cve_index. Extended metadata is normalized into compact package-level rows in cve_metadata and long one-per-CVE text in cve_metadata_text.

Default databases leave cve_metadata and cve_metadata_text empty; matching *-extended variants populate them. Metadata-specific searches fail safe with no metadata matches when those tables are empty. Databases are built from scratch by the release workflows; schema migrations and legacy inline cve_data.source_data write paths are intentionally not required.

When changing storage:

• Optimize for clean, reproducible database builds.
• Keep source-data hashes stable.
• Add tests for row counts and source-data retrieval.
• Use file-backed harnesses when validating final SQLite size.

Skill: add a new source converter

1. Convert upstream data into Vulnerability and VulnerabilityDetail objects.
2. Reuse CVESource.store() for persistence.
3. Add small fixtures under test/data/.
4. Add conversion tests and, when relevant, search tests.
5. Ensure aliases, references, severity, dates, package type, version ranges, and purl prefixes are populated consistently.

Skill: investigate false positives or false negatives

Trace in this order:

1. Source converter (osv.py, aqua.py, gha.py, nvd.py).
2. VulnerabilityDetail fields: mii, mie, mai, mae, fixed_location, package_type.
3. to_purl_vers() in utils.py.
4. CVESource.store5() purl prefix and index row creation.
5. Search function and utils.vers_compare() behavior.

Add a regression test at the lowest layer that demonstrates the bug.

Skill: direct SQLite inspection

The .vdb6 files are SQLite databases.

sqlite3 "$VDB_HOME/data.index.vdb6" ".schema cve_index"
sqlite3 "$VDB_HOME/data.index.vdb6" "SELECT count(*) FROM cve_metadata;"
sqlite3 "$VDB_HOME/data.index.vdb6" "SELECT count(*) FROM cve_metadata_text;"
sqlite3 "$VDB_HOME/data.index.vdb6" "SELECT count(*) FROM cve_index;"
sqlite3 "$VDB_HOME/data.vdb6" "SELECT count(*) FROM cve_data;"
sqlite3 "$VDB_HOME/data.vdb6" "SELECT count(*) FROM cve_source_data;"

For VDB 6.7+, a healthy normalized build should have many cve_data rows and fewer cve_source_data rows when vulnerabilities affect multiple packages. In a normal non-extended database, cve_metadata and cve_metadata_text should have zero rows; in an extended database they should be populated.

---

Source: AppThreat/vulnerability-db — distributed by TomeVault.