taco-vulndb

A CLI tool for building, updating, and distributing the TACO vulnerability database.

Overview

Property	Value
Language	Go
Framework	Cobra CLI
Port	8080 (when serving)
Type	CLI tool (not a long-running service)
Dependencies	taco-lib/vulndb
Repository	tacosec/taco-vulndb

Architecture

taco-vulndb is a command-line tool that manages the vulnerability database used by taco-scanner. It aggregates vulnerability data from 9 different sources, merges them with deduplication and source-priority ordering, and produces a single compressed database file.

The core database logic lives in taco-lib/vulndb -- this CLI is a thin wrapper that exposes the library's functionality as commands.

Commands

taco-vulndb update

Fetch vulnerability data from sources and update the local cache.

bashCopy# Update from all sources (incremental -- last 7 days)
taco-vulndb update

# Force full historical fetch
taco-vulndb update --full

# Update from specific sources only
taco-vulndb update --sources nvd,osv,ghsa

On first run (no existing cache), a full historical fetch is performed automatically. Subsequent runs are incremental (last 7 days).

taco-vulndb build

Build a standalone database file by fetching from NVD.

bashCopytaco-vulndb build --output ./vulndb.json
taco-vulndb build --output ./vulndb.json --days 30

taco-vulndb download

Download a pre-built database from a URL.

bashCopytaco-vulndb download --url https://example.com/vulndb.json.gz

taco-vulndb load

Import a local database file into the cache.

bashCopytaco-vulndb load --file /path/to/vulndb.json.gz

taco-vulndb export

Export the cached database as a gzip file for distribution.

bashCopytaco-vulndb export --output vulndb.json.gz

taco-vulndb serve

Start an HTTP server to host the database.

bashCopytaco-vulndb serve              # default :8080
taco-vulndb serve --addr :9090

Endpoints:

• GET /vulndb.json -- Database file (JSON)
• GET /vulndb.json.gz -- Database file (gzip-compressed)
• GET /meta.json -- Database metadata
• GET /health -- Health check

taco-vulndb push

Push the local database to an OCI registry.

bashCopytaco-vulndb push ghcr.io/tacosec/taco-vulndb:latest

taco-vulndb pull

Pull a database from an OCI registry.

bashCopytaco-vulndb pull ghcr.io/tacosec/taco-vulndb:latest

taco-vulndb status

Show the current state of the local vulnerability database.

Database path:    /home/user/.cache/taco-vulndb/vulndb.json
Last updated:     2024-01-15 10:00:00 UTC
Entry count:      245832
Status:           OK

Sources:
  nvd              180000 entries  (updated 2024-01-15 09:45)
  osv              30000 entries   (updated 2024-01-15 09:50)
  ghsa             15000 entries   (updated 2024-01-15 09:55)
  ...

Vulnerability Sources

Source	Identifier	Description
NVD	nvd	NIST National Vulnerability Database
OSV	osv	Open Source Vulnerabilities (Google)
GHSA	ghsa	GitHub Security Advisories
Alpine SecDB	alpine-secdb	Alpine Linux security database
Debian	debian	Debian Security Tracker
Ubuntu	ubuntu	Ubuntu Security Notices
Red Hat	redhat	Red Hat Security Data
ALAS	alas	Amazon Linux Security Advisories
CISA KEV	cisa-kev	CISA Known Exploited Vulnerabilities

Source Priority

When multiple sources report the same vulnerability for the same package/ecosystem, the source with higher priority wins. Priority order (highest first):

1. Alpine SecDB
2. Debian
3. Ubuntu
4. Red Hat
5. ALAS
6. GHSA
7. OSV
8. NVD
9. CISA KEV

Environment Variables

Variable	Required	Default	Description
TACO_NVD_API_KEY	No	--	NVD API key (increases rate limit)
GITHUB_TOKEN	No	--	GitHub token for GHSA (increases rate limit)