# aquasecurity/trivy-db architecture

> Architecture diagram of the GitHub repository aquasecurity/trivy-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aquasecurity/trivy-db
- Repository: https://github.com/aquasecurity/trivy-db

## Overview

##### Project Type and Purpose
- This is a Go-based CLI tool *and* library (“trivy-db”) for building and manipulating a vulnerability database (SQLite).
- The CLI (`cmd/trivy-db/main.go`) drives the build process; the library packages (under `pkg/`) encapsulate fetching vulnerability data from various upstream sources, database construction, and utility functions.

##### High-Level Components
a. CLI Entry Point
- Component: `trivy-db` binary (built from `cmd/trivy-db`)
- Responsibilities: parse commands (`build`, etc.), kick off data fetch, invoke DB build/compact/compress routines.
b. Core Library
- `pkg/app.go` / `pkg/build.go`: orchestration logic
- `pkg/db`: abstraction over SQLite operations (create tables, insert advisories/vulns)
- `pkg/vulnsrc`: a family of fetcher modules (e.g., `pkg/vulnsrc/nvd`, `pkg/vulnsrc/redhat-oval`, etc.)
- Each implements a common interface to download and parse vendor-specific advisory feeds
- `pkg/vulndb`: staging/load test fixtures and DB migrations
- `pkg/metadata`: manage metadata.json (version, update interval)
- `pkg/utils`: helper routines (file I/O, progress bars, string/int utilities)
- `pkg/log`: centralized logging interface
c. External Services
- Upstream vulnerability data sources (NVD API, GitHub Advisory, Linux distro OVAL or JSON feeds)
- Container registry (GitHub Container Registry) for distribution
d. CI/CD Pipeline
- GitHub Actions workflows under `.github/workflows/cron.yml`: schedule builds every 6 h
- Makefile scripts orchestrate fetch→build→compact→compress steps
- ORAS CLI pushes artifacts (db.tar.gz) to GHCR

##### Interactions and Data Flow
1. **Scheduler (GitHub Actions Cron)** → triggers → 2. **Makefile**
2. **Makefile** → invokes → CLI binary (`trivy-db build`)
3. **CLI** → calls → `pkg/app` → enumerates all `pkg/vulnsrc/*` modules
4. **Each Fetcher Module** → fetch data from an **External Source** → parse into unified vulnerability structs
5. Aggregated data → passed to **pkg/db** → writes to a local SQLite database file (`trivy.db`) and metadata file
6. **pkg/db-compact** (Makefile) → optimize/compact the SQLite file
7. **pkg/db-compress** (Makefile) → gzip/tar the final DB artifact
8. **ORAS CLI** → pushes the compressed DB to **GHCR**
9. **Clients (e.g., Trivy scanner)** → pull the DB via ORAS or Trivy CLI

##### Architectural Patterns and Design Principles
- **Modular Fetchers**: each vendor or feed parser (`pkg/vulnsrc/*`) implements a shared interface for consistency.
- **Separation of Concerns**:
- Fetching/parsing (vulnsrc)
- DB operations (pkg/db)
- Metadata management (pkg/metadata)
- CLI orchestration (pkg/app)
- **Dependency Injection / Interfaces**: low-coupling between fetch modules and DB writer (e.g., inject parsed records into the builder).

##### Critical Details to Capture
- The many independent `pkg/vulnsrc` fetchers feeding into a single DB builder.
- The SQLite database as the core product of the build.
- The periodic CI/CD workflow that automates fetch→build→publish.
- How client tools (Trivy) consume the published DB artifact.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD Pipeline"
        GHAction["GitHub Actions\ncron.yml"]:::cicd
        Make["Makefile"]:::cicd
        ORAS["ORAS CLI"]:::cicd
    end
    GHCR["GHCR (Container Registry)"]:::external
    Client["Client Consumers\n(Trivy scanner, etc.)"]:::external

    subgraph "CLI Entry Point"
        CLI["trivy-db CLI\n(cmd/trivy-db/main.go)"]:::cmd
    end

    subgraph "Core Library (pkg/*)"
        App["App Orchestration\n(pkg/app.go)"]:::app
        Build["Build Orchestration\n(pkg/build.go)"]:::build
        subgraph "Modules"
            Fetchers["Fetcher Modules\n(pkg/vulnsrc/*)"]:::fetch
            DB["DB Module\n(pkg/db/)"]:::db
            Meta["Metadata\n(pkg/metadata/metadata.go)"]:::metadata
            Log["Logging\n(pkg/log/log.go)"]:::log
            Utils["Utilities\n(pkg/utils/)"]:::utils
            Types["Types Definitions\n(pkg/types/types.go)"]:::types
            Vulndb["VulnDB Staging & Testing\n(pkg/vulndb/db.go)"]:::vulndb
        end
    end

    subgraph "External Data Sources"
        NVD["NVD API"]:::external
        GHAdv["GitHub Advisory"]:::external
        OVAL["Linux Distro OVAL/JSON"]:::external
    end

    %% CI/CD flow
    GHAction -->|"schedule build"| Make
    Make -->|"invoke CLI"| CLI
    Make -->|"compact DB"| DB
    Make -->|"compress DB"| DB
    Make -->|"push artifact"| ORAS
    ORAS -->|"artifact"| GHCR
    GHCR -->|"pull DB"| Client

    %% CLI and library flow
    CLI -->|"calls"| App
    App -->|"orchestrates"| Build
    Build -->|"enumerates"| Fetchers
    Build -->|"loads fixtures/migrations"| Vulndb
    Build -->|"injects records"| DB

    %% Data fetch flow
    Fetchers -->|"- - Download JSON"| NVD
    Fetchers -->|"- - Download JSON"| GHAdv
    Fetchers -->|"- - Download JSON"| OVAL
    Fetchers -->|"- - Parse → Vuln Records"| DB

    %% Support module usage
    App -->|"uses"| Meta
    App -->|"uses"| Log
    App -->|"uses"| Utils
    Build -->|"uses"| Types

    classDef cmd fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef app fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef build fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef fetch fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef db fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef metadata fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef log fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef utils fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef types fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef vulndb fill:#ccdefc,stroke:#333,stroke-width:1px
    classDef cicd fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px

    click CLI "https://github.com/aquasecurity/trivy-db/blob/main/cmd/trivy-db/main.go"
    click App "https://github.com/aquasecurity/trivy-db/blob/main/pkg/app.go"
    click Build "https://github.com/aquasecurity/trivy-db/blob/main/pkg/build.go"
    click DB "https://github.com/aquasecurity/trivy-db/tree/main/pkg/db/"
    click Meta "https://github.com/aquasecurity/trivy-db/blob/main/pkg/metadata/metadata.go"
    click Log "https://github.com/aquasecurity/trivy-db/blob/main/pkg/log/log.go"
    click Utils "https://github.com/aquasecurity/trivy-db/tree/main/pkg/utils/"
    click Types "https://github.com/aquasecurity/trivy-db/blob/main/pkg/types/types.go"
    click Vulndb "https://github.com/aquasecurity/trivy-db/blob/main/pkg/vulndb/db.go"
    click Fetchers "https://github.com/aquasecurity/trivy-db/blob/main/pkg/vulnsrc/vulnsrc.go"
    click GHAction "https://github.com/aquasecurity/trivy-db/blob/main/.github/workflows/cron.yml"
    click Make "https://github.com/aquasecurity/trivy-db/tree/main/Makefile"
```
