Skip to content

Upgrading to v5.1.0

The database migration runs longer than usual

This release rebuilds the global portfolio metrics view and back-fills two new tables, one for package metadata resolution state, one for per-project analysis timestamps. The view rebuild takes an exclusive lock, so portfolio metrics queries block until it completes. Its duration scales with the number of daily project metrics snapshots inside the retention window; the back-fills scale with the number of distinct PURLs and active projects.

The back-fills write only to the new tables, so no full-stop window is needed. Raise the startup probe budget before you start, and do not interrupt the API server while the migration runs.

  • The portfolio analysis no longer runs at a fixed time. Earlier versions started the analysis of the entire portfolio once a day, which created an analysis run for every project within minutes, and delayed analyses that BOM uploads triggered in the meantime. Each project now carries the time of its last analysis attempt. The task runs continuously and picks up projects whose last analysis attempt is longer ago than dt.task.portfolio-analysis.max-analysis-age-ms, 24 hours by default. It keeps at most dt.task.portfolio-analysis.max-in-flight-analyses of its own analyses running at a time, 50 by default. The limit applies to the task alone. BOM uploads and API calls start analyses regardless of it, and every analysis updates that timestamp no matter what started it. A project that gets analysed often never becomes due for scheduled analysis.

    Warning

    The API server refuses to start when your configuration still contains dt.task.portfolio-analysis.cron. Remove the property, and set the two replacements to match the throughput your deployment can sustain.

  • Database queries now time out. The API server aborts any single database query that runs longer than 60 seconds. In earlier versions, queries ran unbounded, so a stuck or runaway query could occupy a connection indefinitely and exhaust the connection pool. API requests that hit the timeout fail with HTTP status 504.

    Work that may legitimately exceed the timeout is exempt, notably database migrations and portfolio-wide metrics refreshes.

    Raise the limit with dt.datasource.query-timeout-ms if your deployment reports timeouts for operations that used to succeed. Setting it to 0 disables query timeouts entirely. Repeated timeouts point at a deeper problem, such as slow I/O, lagging autovacuum, or inefficient query plans. Report an issue if you have to increase the value permanently.

  • New X-Total-Count-Type response header. REST API v1 gains support for communicating bounded total counts via the new X-Total-Count-Type response header. It must be accessible by the frontend, so users who overwrite the default dt.cors.allowed-headers property must add the header there manually. Bounded total counts are a performance optimization technique for operating on large datasets. In this version, only the /api/v1/finding, /api/v1/finding/grouped, and /api/v1/finding/project/{uuid} endpoints support it.

  • Dependency-Track mirrors KEV catalogs by default. A new task downloads the CISA and ENISA Known Exploited Vulnerabilities catalogs daily at 02:00 UTC. Dependency-Track turns on both data sources out of the box. Deployments with restricted egress must allow the feed hosts, or turn off the data sources they cannot reach. Change the schedule with dt.task.kev-mirror.cron.

  • lastSeen of affected version attributions now mirrors firstSeen. REST API v1 vulnerability responses expose the field as affectedComponents[].affectedVersionAttributions[].lastSeen. The API server no longer updates it, because doing so caused large volumes of UPDATE queries during mirroring. Treat the field as deprecated. Version 5.2 removes it, along with its database column.

  • CycloneDX VEX exports reference the affected components. Earlier versions set every vulnerabilities[].affects[].ref in a VEX export to the project (metadata.component), which lost the information about which component an analysis applied to. Exports now reference the affected components, and carry those components under components[], so the references resolve within the document.

    This changes what happens when you re-import a VEX that Dependency-Track exported. Earlier versions applied each analysis to every component the vulnerability affected. An analysis now reaches only the component it belongs to.

    Note

    VEX documents whose affects[].ref names metadata.component, or uses a BOM-Link, still apply their analysis to every affected component in the project. Use that form when one decision covers the whole project.