cve-db

Russian version: README.ru.md

cve-db builds a local SQLite database with CVE data for offline lookups and batch processing.

The database combines three sources:

• NVD for CVE metadata, CVSS, CPE, vendor, and product
• EPSS for exploitation probability
• CISA KEV for known exploited vulnerabilities

The published OCI image is based on scratch and contains one file:

/opt/db/cve.db

This is useful when you need:

• one offline SQLite file for Python tools, shell scripts, CI, and containers
• a small OCI artifact that can be copied into another image
• a reproducible daily snapshot with build provenance

Quick start

Install dependencies:

pip install -r requirements.txt

Build the database for the first time:

export NIST_API=your_api_key
python -m cve_db.sync init --db-path ./dist/cve.db

Update an existing database:

python -m cve_db.sync update --db-path ./dist/cve.db

Show status:

python -m cve_db.sync status --db-path ./dist/cve.db

How to get an NVD API key

1. Open the request form: https://nvd.nist.gov/developers/request-an-api-key
2. Fill in Organization Name, Email Address, and Organization Type.
3. Scroll to the end of the Terms of Use and confirm agreement.
4. Submit the form.
5. Open the email from NVD and follow the activation link.
6. Export the key before running sync:

export NIST_API=your_api_key

General NVD developer documentation: https://nvd.nist.gov/developers/start-here

Python usage

from cve_db import db_nist_check, db_epss_check

nvd = db_nist_check("CVE-2021-44228", db_path="/opt/db/cve.db")
epss = db_epss_check("CVE-2021-44228", db_path="/opt/db/cve.db")

print(nvd["cvss_baseScore"])
print(nvd["cvss_severity"])
print(nvd["cisa_kev"])
print(epss["epss"])

SQL usage

sqlite3 /opt/db/cve.db \
  "SELECT cve_id, priority, cvss_base_score, epss
   FROM cve_priority
   WHERE priority IN ('Priority 1+', 'Priority 1')
   ORDER BY epss DESC
   LIMIT 20;"

OCI usage

Copy the DB into another image:

FROM ghcr.io/drybalka-s/cve-db:v1 AS cve-db

FROM your-app:latest
COPY --from=cve-db /opt/db/cve.db /opt/db/cve.db

Use v1 in runtime workloads. Use dated tags for pinning and rollback.

Release model

The OCI image uses two tags:

• v1 as the moving compatibility tag
• v1-YYYY-MM-DD as the immutable daily snapshot tag

The release workflow:

1. Pulls the current v1 image if it exists.
2. Extracts /opt/db/cve.db.
3. Runs update, or init on the first release.
4. Builds a new scratch image.
5. Pushes v1 and v1-YYYY-MM-DD.
6. Publishes a provenance attestation.
7. Deletes old dated tags older than 14 days.

Workflow files:

• publish-oci.yml
• reusable-publish-oci.yml

Required repository secrets:

• NIST_API for faster NVD sync
• GHCR_CLEANUP_TOKEN for deleting old GHCR package versions

Provenance verification

Verify the moving tag:

gh attestation verify oci://ghcr.io/drybalka-s/cve-db:v1 -R drybalka-s/cve-db

Verify a dated snapshot:

gh attestation verify oci://ghcr.io/drybalka-s/cve-db:v1-2026-04-27 -R drybalka-s/cve-db

Verify by digest:

gh attestation verify \
  oci://ghcr.io/drybalka-s/cve-db@sha256:IMAGE_DIGEST \
  -R drybalka-s/cve-db

Priority model

The cve_priority view calculates priority from CVSS, EPSS, and KEV status.

• Priority 1+: in CISA KEV or CVSS v4 vector contains /E:A/
• Priority 1: CVSS >= 6.0 and EPSS >= 0.5
• Priority 2: CVSS >= 6.0 and EPSS < 0.5
• Priority 3: CVSS < 6.0 and EPSS >= 0.5
• Priority 4: CVSS < 6.0 and EPSS < 0.5

Sources

• NVD
• NVD API Key Request
• NVD Developers Start Here
• EPSS
• CISA KEV Catalog