Skip to content

Commit db49340

Browse files
Ph4t3Ph4t3
authored
Merge pull request #97 from l3montree-dev/chore/vulndb-update
Adds first verion of vulndb update schedule
2 parents 34012c7 + 1533e75 commit db49340

1 file changed

Lines changed: 98 additions & 8 deletions

File tree

‎src/pages/reference/vulnerability-database/update-schedule.mdx‎

Lines changed: 98 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,102 @@
1-
import Image from 'next/image'
1+
---
2+
title: Update Schedule
3+
description: How DevGuard's vulnerability database is built, signed, distributed, and kept up to date
4+
---
5+
26
import { Callout } from 'nextra/components'
3-
import {
4-
Tooltip,
5-
TooltipTrigger,
6-
TooltipContent,
7-
} from '@/components/ui/tooltip'
8-
import PageContentComingSoon from '@/components/PageContentComingSoon'
97

108
# Update Schedule
119

12-
<PageContentComingSoon />
10+
DevGuard maintains its own aggregated vulnerability database that is rebuilt every **6 hours** from upstream sources, cryptographically signed, and distributed as an OCI artifact. DevGuard instances pull these incremental updates automatically.
11+
12+
## Build Schedule
13+
14+
The vulnerability database is built by a [GitHub Actions workflow](https://github.com/l3montree-dev/devguard/actions/workflows/vulndb.yaml) that runs on a fixed schedule:
15+
16+
| Property | Value |
17+
|---|---|
18+
| **Schedule** | Every 6 hours (`0 */6 * * *`) |
19+
| **Trigger** | Cron schedule + manual dispatch |
20+
| **Pipeline** | [`vulndb.yaml`](https://github.com/l3montree-dev/devguard/blob/main/.github/workflows/vulndb.yaml) |
21+
| **Artifact registry** | [`ghcr.io/l3montree-dev/devguard/vulndb/v1`](https://github.com/l3montree-dev/devguard/pkgs/container/devguard%2Fvulndb%2Fv1) |
22+
23+
## Data Sources Synced
24+
25+
Each build synchronizes the following upstream sources into a single PostgreSQL database:
26+
27+
| Source | Description |
28+
|---|---|
29+
| **OSV** | Open Source Vulnerabilities — covers npm, PyPI, Go, Maven, Cargo, NuGet, RubyGems, and [many more ecosystems](https://osv.dev/list) |
30+
| **EPSS** | Exploit Prediction Scoring System — probability that a CVE will be exploited in the wild |
31+
| **CISA KEV** | Known Exploited Vulnerabilities catalog |
32+
| **CWE** | Common Weakness Enumeration taxonomy |
33+
| **ExploitDB** | Public exploit database |
34+
| **GitHub PoC** | Proof-of-concept exploits published on GitHub |
35+
| **Debian Security Tracker (DSA)** | Debian-specific security advisories and affected package mappings |
36+
| **Malicious Packages** | Known malicious packages across ecosystems |
37+
38+
<Callout type="info">
39+
For details on each data source and how they are used, see [Data Sources](/reference/vulnerability-database/data-sources).
40+
</Callout>
41+
42+
## Build Pipeline
43+
44+
The workflow executes the following steps in sequence:
45+
46+
1. **Import** — Pull the latest published database state from the OCI registry using `devguard-cli vulndb import`, restoring the previous build as a baseline.
47+
2. **Sync** — Fetch fresh data from all upstream sources using `devguard-cli vulndb sync`. This updates CVEs, affected components, exploit data, EPSS scores, CISA KEV status, CWE mappings, and malicious package entries.
48+
3. **Export** — Compute the differential between the previous and current database states using `devguard-cli vulndb export`. The result is a set of CSV files containing only inserts, updates, and deletes.
49+
4. **Package** — Bundle the differential CSV files into a `vulndb.zip` archive.
50+
5. **Sign** — Sign the archive using [Cosign](https://docs.sigstore.dev/cosign/overview/) with a private key. The signature is stored as `vulndb.zip.sig`.
51+
6. **Publish** — Push both the archive and its signature to the GitHub Container Registry as OCI artifacts using [ORAS](https://oras.land/). Each artifact is tagged with a Unix timestamp (e.g., `1708185600`).
52+
53+
<Callout type="info">
54+
Full database snapshots can also be generated via manual workflow dispatch by setting `run_generate_snapshot` to `true`. Snapshots contain the complete database state rather than just a differential and are used as a baseline for new instances.
55+
</Callout>
56+
57+
## Distribution Format
58+
59+
The database is distributed as OCI artifacts via the GitHub Container Registry:
60+
61+
```
62+
ghcr.io/l3montree-dev/devguard/vulndb/v1:<timestamp> # differential update
63+
ghcr.io/l3montree-dev/devguard/vulndb/v1:<timestamp>.sig # cosign signature
64+
ghcr.io/l3montree-dev/devguard/vulndb/v1:<timestamp>-snapshot # full snapshot (periodic)
65+
ghcr.io/l3montree-dev/devguard/vulndb/v1:<timestamp>-snapshot.sig
66+
```
67+
68+
Each archive contains CSV files with the changes since the last build:
69+
70+
| File | Contents |
71+
|---|---|
72+
| `cves_insert.csv` / `cves_update.csv` / `cves_delete.csv` | New, modified, or removed CVE entries |
73+
| `affected_components_*.csv` | Affected component mappings |
74+
| `cve_affected_component_*.csv` | CVE-to-component join records |
75+
| `cwes_*.csv` | CWE taxonomy updates |
76+
| `exploits_*.csv` | Exploit data changes |
77+
| `malicious_packages_*.csv` | Malicious package entries |
78+
| `malicious_affected_components_*.csv` | Malicious package component mappings |
79+
| `cve_relationships_*.csv` | CVE relationship updates |
80+
81+
## How DevGuard Instances Consume Updates
82+
83+
DevGuard server instances automatically pull and apply database updates:
84+
85+
1. On startup (and periodically thereafter), the server's **VulnDB daemon** calls `ImportFromDiff`.
86+
2. The daemon connects to `ghcr.io/l3montree-dev/devguard/vulndb/v1` and lists all available tags.
87+
3. It identifies tags newer than the last imported version (tracked in the `vulndb.lastIncrementalImport` config key).
88+
4. For each new tag, it downloads the OCI artifact, **verifies the Cosign signature** against the bundled `cosign.pub` public key, unzips the archive, and applies the differential CSV files to the local database.
89+
5. Snapshot tags are handled separately — if a snapshot is encountered, the full database state is loaded before applying subsequent differentials.
90+
91+
<Callout type="warning">
92+
To disable automatic updates (e.g., in air-gapped environments), set the environment variable `DISABLE_VULNDB_UPDATE=true`. See [Database Maintenance](/how-to-guides/administration/database-maintenance) for more details.
93+
</Callout>
94+
95+
## Signature Verification
96+
97+
Every database artifact is signed and verified before being applied:
98+
99+
- **Signing**: The build pipeline signs `vulndb.zip` using Cosign with an ECDSA private key. The signature is base64-encoded and published alongside the archive.
100+
- **Verification**: On import, the DevGuard instance loads the `cosign.pub` public key, downloads the `.sig` artifact for the corresponding tag, and verifies the signature using `sigstore/sigstore`. If verification fails, the update is rejected.
101+
102+
This ensures that only database artifacts built by the official pipeline are applied, protecting against supply chain attacks on the vulnerability data itself.

0 commit comments

Comments
 (0)