taco-scanner

The vulnerability scanning engine. Matches components against the TacoDB vulnerability database and publishes findings.

Overview

Property	Value
Language	Go
Framework	Standard library HTTP
Port	8084 (health check)
Exposed	Internal only
Dependencies	MySQL, RabbitMQ, TacoDB file
Repository	tacosec/taco-scanner

Architecture

taco-scanner is a periodic batch processor that:

1. Loads the TacoDB vulnerability database from a compressed file on disk (/data/taco.db.gz).
2. Queries all components from MySQL.
3. Matches each component's package URL (purl) against known vulnerabilities using version range comparison.
4. Inserts new findings and resolves old ones (sets resolved_at timestamp).
5. Publishes finding events to RabbitMQ for the alerting pipeline.
6. Takes daily finding snapshots for trend tracking.

Key Packages

Package	Purpose
scanner/	Core scan cycle, component matching, SBOM diff logic, priority scan handling, image scan processing
db/	MySQL operations: findings CRUD, scan state, snapshots, component queries, finding expiration
publisher/	RabbitMQ client for publishing finding events
tacodb/	TacoDB file reader (loads compressed vulnerability database)
updater/	Background auto-updater for the TacoDB file
config/	Environment variable loading

Scan Cycle

The scanner runs on a configurable interval (default 5 minutes):

1. Load DB -- Read and decompress TacoDB from disk.
2. Fetch components -- Query all components from MySQL with their package URLs.
3. Match -- For each component, check if its purl and version match any vulnerability entry. The matcher supports ecosystem-specific version comparison.
4. Diff -- Compare new findings against existing findings to determine what is new and what has been resolved.
5. Persist -- Insert new findings, mark resolved findings, update scan state.
6. Publish -- Send finding events to RabbitMQ for taco-alert.
7. Snapshot -- Record daily finding counts by severity per project.

Priority Scan Requests

Users can request on-demand scans via the API (POST /projects/:id/sboms/:sbom_id/scan). The scanner polls the scan_requests table every 10 seconds for pending requests and processes them immediately.

Image Scan Requests

Users can request container image scans (POST /projects/:id/image-scans). If INBOUND_URL and INBOUND_TOKEN are configured, the scanner fetches SBOMs from the specified images and submits them to taco-inbound for processing.

VulnDB Auto-Updater

If VULNDB_UPDATE_INTERVAL is set (e.g., 24h), the scanner runs a background goroutine that periodically updates the TacoDB file by fetching from all vulnerability sources.

Migrations

taco-scanner owns and manages these MySQL tables:

• findings -- Vulnerability findings linked to components
• scan_state -- Scan run metadata (hash, timing, counts)
• scan_requests -- On-demand scan request queue
• image_scan_requests -- Image scan request queue
• finding_snapshots -- Daily finding count snapshots per project

It also creates prerequisite tables (sboms, components, sbom_components) if they do not exist, since it needs to read component data.

Environment Variables

Variable	Required	Default	Description
MYSQL_DSN	Yes	--	MySQL connection string
RABBITMQ_URL	Yes	--	RabbitMQ AMQP URL
TACODB_PATH	No	/data/taco.db.gz	Path to the TacoDB vulnerability database file
SCAN_INTERVAL	No	5m	Time between scan cycles
HEALTH_PORT	No	8084	Health check HTTP port
VULNDB_UPDATE_INTERVAL	No	--	Auto-update interval (e.g., 24h). Disabled if empty.
TACO_NVD_API_KEY	No	--	NVD API key for faster fetching
GITHUB_TOKEN	No	--	GitHub token for GHSA source
INBOUND_URL	No	--	taco-inbound URL for image scan submissions
INBOUND_TOKEN	No	--	Project token for image scan submissions

Health Check

GET /healthz -- Returns 200 OK with status of MySQL, RabbitMQ, and TacoDB file (including staleness check). Returns 503 if any dependency is unhealthy.