From 1cc2bacd132c82cae850a909bc64f823b126ae30 Mon Sep 17 00:00:00 2001 From: nscuro Date: Mon, 24 Aug 2026 15:00:41 +0200 Subject: [PATCH] Add upgrade note about full OSV re-mirroring for v5.0.5 Also corrects a few inaccuracies about when the first mirroring happens. Signed-off-by: nscuro --- docs/concepts/about-vulnerability-data-sources.md | 5 +++-- .../configuring-vulnerability-sources.md | 5 +++-- docs/guides/upgrading/v5.0.5.md | 10 ++++++++++ docs/reference/configuration/task-scheduler.md | 6 +++--- docs/reference/datasources/index.md | 3 ++- 5 files changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/concepts/about-vulnerability-data-sources.md b/docs/concepts/about-vulnerability-data-sources.md index fdeaa93b..31c53f79 100644 --- a/docs/concepts/about-vulnerability-data-sources.md +++ b/docs/concepts/about-vulnerability-data-sources.md @@ -38,8 +38,9 @@ The three feeds overlap heavily for open source ecosystems. Most operators do no ## How Dependency-Track uses the data -Mirroring is a background task. On a configurable schedule and at instance startup, Dependency-Track downloads new and -changed records from each enabled source and writes them into its own database. +Mirroring is a background task. On a configurable schedule, Dependency-Track downloads new and changed records from +each enabled source and writes them into its own database. A first run also happens shortly after the task is scheduled +initially, so a new deployment starts mirroring without waiting for the schedule. Vulnerability analysis is a separate process. When you upload a Bill of Materials or trigger analysis, the [internal analyzer](../reference/analyzers.md#internal) matches the project's components against the mirrored data already stored diff --git a/docs/guides/administration/configuring-vulnerability-sources.md b/docs/guides/administration/configuring-vulnerability-sources.md index b38e5415..4ce9e914 100644 --- a/docs/guides/administration/configuring-vulnerability-sources.md +++ b/docs/guides/administration/configuring-vulnerability-sources.md @@ -98,8 +98,9 @@ what each mirror is doing. ## Scheduling mirror runs -Each source has its own cron property. Mirrors also run on instance startup. To change the schedule, set the -corresponding property: +Each source has its own cron property. A mirror also runs once shortly after Dependency-Track schedules it for the +first time, which happens on a new deployment or when an upgrade introduces the task. Later restarts do not trigger it. +To change the schedule, set the corresponding property: - NVD: [`dt.task.nvd-vuln-data-source-mirror.cron`](../../reference/configuration/properties.md#dttasknvd-vuln-data-source-mirrorcron) - GitHub advisories: diff --git a/docs/guides/upgrading/v5.0.5.md b/docs/guides/upgrading/v5.0.5.md index c3441e9b..17896d2d 100644 --- a/docs/guides/upgrading/v5.0.5.md +++ b/docs/guides/upgrading/v5.0.5.md @@ -10,3 +10,13 @@ | --- | --- | | `subject.policyViolation.policyCondition` | `subject.policyViolation.condition` | | `subject.violationAnalysis` | `subject.analysis` | + +* **The upgrade forces a full OSV mirror**. Dependency-Track converted some OSV version ranges incorrectly, + which matched components against vulnerabilities that do not affect them. The upgrade purges the watermarks + that the OSV vulnerability data source uses to track incremental progress. Existing OSV data stays in place, + but the next mirror run processes the full OSV data set instead of only recent changes, + and overwrites the affected records. Expect that run to take longer than usual. + + Corrected data is not available until the OSV mirror runs, which happens daily at 03:00 UTC by default. + To get the corrected data sooner, use **Mirror now** as described in + [Triggering an initial mirror](../administration/configuring-vulnerability-sources.md#triggering-an-initial-mirror). diff --git a/docs/reference/configuration/task-scheduler.md b/docs/reference/configuration/task-scheduler.md index f50cbc5f..c714ff51 100644 --- a/docs/reference/configuration/task-scheduler.md +++ b/docs/reference/configuration/task-scheduler.md @@ -44,8 +44,8 @@ dt.task.nvd-vuln-data-source-mirror.cron=30 3 * * * ## Scheduled tasks The scheduler ships with the following recurring tasks. Tasks marked with -[^1] also run once shortly after startup, with a random delay of up to one -minute. +[^1] also run once shortly after the scheduler registers them for the first +time, with a random delay of up to one minute. | Task | Property | Default cron | Purpose | |-----------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------| @@ -69,4 +69,4 @@ minute. | Scheduled notification dispatch | [`dt.task.scheduled-notification-dispatch.cron`](properties.md#dttaskscheduled-notification-dispatchcron) | `* * * * *` | Polls for due scheduled notification rules and dispatches them. | | Telemetry submission[^1] | [`dt.task.telemetry-submission.cron`](properties.md#dttasktelemetry-submissioncron) | `0 */1 * * *` | Submits anonymous usage data. See [Telemetry](telemetry.md). | -[^1]: Triggered once on startup with a random delay of up to one minute, then on the configured schedule. +[^1]: Triggered once when the scheduler first registers the task, with a random delay of up to one minute, then on the configured schedule. Registration happens on a new deployment, or when an upgrade introduces the task. Later restarts do not trigger another run. diff --git a/docs/reference/datasources/index.md b/docs/reference/datasources/index.md index 2c051d16..426d7f29 100644 --- a/docs/reference/datasources/index.md +++ b/docs/reference/datasources/index.md @@ -11,7 +11,8 @@ sources](../../concepts/about-vulnerability-data-sources.md). For the procedure ## Mirrored sources Dependency-Track can mirror three public sources into its local database. Mirroring runs on a configurable schedule -(daily by default) and on instance startup. Progress and errors are written to the API server logs. +(daily by default), and once shortly after Dependency-Track schedules the task for the first time. Progress and errors +are written to the API server logs. | Source | Identifier prefix | Matches on | |:-------|:------------------|:-----------|