|
| 1 | +# About vulnerability data sources |
| 2 | + |
| 3 | +A vulnerability data source is an upstream feed of known security defects that Dependency-Track uses to find |
| 4 | +vulnerabilities in your components. No single feed covers every ecosystem, identifier scheme, or disclosure path, so |
| 5 | +Dependency-Track integrates with several. You pick which ones to enable based on what you ship and where the relevant |
| 6 | +advisories are published. None of them are required, and enabling all of them is rarely the right answer. |
| 7 | + |
| 8 | +This page explains what each source contributes, how the data reaches your findings, and the trade-offs you accept when |
| 9 | +you enable a source or turn one off. For the procedure to enable sources, see [Configuring vulnerability |
| 10 | +sources](../guides/administration/configuring-vulnerability-sources.md). |
| 11 | + |
| 12 | +## Mirrored sources |
| 13 | + |
| 14 | +Dependency-Track can mirror three public data sources into its own database: |
| 15 | + |
| 16 | +- **[National Vulnerability Database (NVD)](https://nvd.nist.gov/)** is the canonical CVE feed maintained by NIST. It |
| 17 | + contains over 200,000 CVE records spanning the early nineties to the present and describes affected products as |
| 18 | + Common Platform Enumeration (CPE) names. NVD is the broadest source for non-package software (operating systems, |
| 19 | + firmware, network equipment), but its CPE-based product model is a poor fit for open source packages. |
| 20 | +- **[GitHub advisories](https://github.com/advisories)** is GitHub's curated advisory database (GHSA). It covers open |
| 21 | + source packages on npm, Maven, PyPI, NuGet, Go, RubyGems, and others. Advisories use Package URL (PURL) keys, often |
| 22 | + appear before the corresponding NVD entry, and frequently carry more ecosystem-specific detail than the NVD record. |
| 23 | +- **[OSV](https://osv.dev/)** is Google's open source vulnerability database. It aggregates advisories from GitHub, |
| 24 | + PyPA, RustSec, the Go team, distribution security teams, and others into one PURL-keyed dataset, and it covers |
| 25 | + ecosystems and distributions that NVD and GHSA do not (for example crates.io, Hex, Pub, Alpine, and Debian). |
| 26 | + |
| 27 | +### Picking sources |
| 28 | + |
| 29 | +The three feeds overlap heavily for open source ecosystems. Most operators do not need all three: |
| 30 | + |
| 31 | +- **GHSA and OSV cover much of the same ground.** OSV ingests GitHub advisories and adds advisories from other curators |
| 32 | + (PyPA, RustSec, Go, distribution security teams). OSV also lets you mirror per ecosystem, which is finer-grained |
| 33 | + control than GHSA offers. If you want one source for open source packages, prefer OSV. |
| 34 | +- **GHSA** is useful on its own if you stay close to the GitHub ecosystem or want the data exactly as GitHub publishes |
| 35 | + it, without the aggregation layer that OSV adds. |
| 36 | +- **NVD** is the only mirrored source that meaningfully covers non-package software identified by CPE. Enable it when |
| 37 | + your BOMs include such components, or when you specifically need CVE coverage independent of curator-specific feeds. |
| 38 | + |
| 39 | +## How Dependency-Track uses the data |
| 40 | + |
| 41 | +Mirroring is a background task. On a configurable schedule and at instance startup, Dependency-Track downloads new and |
| 42 | +changed records from each enabled source and writes them into its own database. |
| 43 | + |
| 44 | +Vulnerability analysis is a separate process. When you upload a Bill of Materials or trigger analysis, the [internal |
| 45 | +analyzer](../reference/analyzers.md#internal) matches the project's components against the mirrored data already stored |
| 46 | +locally. The internal analyzer makes no outbound calls during analysis, which makes findings reproducible and keeps |
| 47 | +analysis fast. |
| 48 | + |
| 49 | +For the full analysis workflow, see [Vulnerability analysis](architecture/design/vulnerability-analysis.md). |
| 50 | + |
| 51 | +### Turning a source off |
| 52 | + |
| 53 | +Disabling a source stops further mirroring from that source, but Dependency-Track does not delete the records it has |
| 54 | +already written. Vulnerabilities mirrored before the source was turned off remain in the database, and the internal |
| 55 | +analyzer keeps matching components against them on subsequent analysis runs. Findings already raised from that source |
| 56 | +are not retroactively removed either. |
| 57 | + |
| 58 | +The practical consequence is that turning a source off is reversible without re-downloading, but it does not clean up |
| 59 | +after itself. If you intend to drop a source entirely and have its findings disappear, expect to clear the data |
| 60 | +manually. Dependency-Track does not yet provide a built-in workflow for this. |
| 61 | + |
| 62 | +## How component matching works |
| 63 | + |
| 64 | +Each advisory in a mirrored source names the products it affects, using either a CPE or a PURL, and specifies the |
| 65 | +affected versions. The internal analyzer matches a component to an advisory by identifier scheme first and version |
| 66 | +second. |
| 67 | + |
| 68 | +| Source | Identifier in records | What components need | |
| 69 | +|:-------|:----------------------|:---------------------| |
| 70 | +| NVD | CPE | A valid CPE on the component | |
| 71 | +| GitHub advisories | PURL | A valid PURL on the component | |
| 72 | +| OSV | PURL | A valid PURL on the component | |
| 73 | + |
| 74 | +A component with neither a CPE nor a PURL is not evaluated. |
| 75 | + |
| 76 | +### CPE matching |
| 77 | + |
| 78 | +CPE matching follows the [NIST CPE name matching |
| 79 | +specification](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7696.pdf): the analyzer compares all eleven CPE |
| 80 | +attributes (`part`, `vendor`, `product`, `version`, `update`, `edition`, `language`, `sw_edition`, `target_sw`, |
| 81 | +`target_hw`, `other`) and rejects the match if any attribute is disjoint. |
| 82 | + |
| 83 | +Two adjustments reduce false positives compared to a literal reading of the spec: |
| 84 | + |
| 85 | +- A SUBSET vendor combined with a SUPERSET product (or the reverse) is rejected, because these combinations otherwise |
| 86 | + produce noisy matches across unrelated products (see [issue |
| 87 | + #3178](https://github.com/DependencyTrack/dependency-track/issues/3178)). |
| 88 | +- Component versions of `*` (ANY) and `-` (NA) are handled per the spec, not run through range comparison. |
| 89 | + |
| 90 | +When the advisory specifies a version range, the analyzer evaluates it using the |
| 91 | +[vers](https://www.packageurl.org/docs/vers/introduction) range specification, with a versioning scheme inferred from |
| 92 | +the component's PURL when present and the `generic` scheme otherwise. |
| 93 | + |
| 94 | +### PURL matching |
| 95 | + |
| 96 | +PURL matching requires the advisory's PURL `type`, `namespace`, and `name` to match the component's exactly. For |
| 97 | +OS-package PURLs (`deb`, `rpm`), if both sides carry a `distro` qualifier they must agree, with semantic equivalences |
| 98 | +honored (for example, `debian-13` matches `trixie`). |
| 99 | + |
| 100 | +Version comparison uses [vers](https://www.packageurl.org/docs/vers/introduction) with the versioning scheme derived |
| 101 | +from the PURL type. If the strict scheme fails to parse a version, the analyzer falls back to the `generic` scheme to |
| 102 | +avoid false negatives. For `deb` and `rpm` PURLs, an `epoch` qualifier is folded into the version as `epoch:version` |
| 103 | +before comparison when the version does not already encode one. |
| 104 | + |
| 105 | +### Practical consequence |
| 106 | + |
| 107 | +Most modern BOM generators emit PURLs but not CPEs. As a result, components from package ecosystems (npm, Maven, PyPI, |
| 108 | +and so on) match GHSA and OSV well but produce few or no findings from NVD data, even when CVE records exist for those |
| 109 | +packages. This is the most common reason operators see fewer NVD findings than expected. |
| 110 | + |
| 111 | +If you need NVD coverage for ecosystem packages, your BOM generator must also produce CPEs for those components. |
| 112 | +Otherwise, rely on GHSA or OSV for open source coverage and on NVD primarily for non-package software identified by CPE. |
| 113 | +The OWASP SBOM Forum's [recommendations to improve the |
| 114 | +NVD](https://owasp.org/blog/2022/09/13/sbom-forum-recommends-improvements-to-nvd) document this CPE-vs-PURL mismatch and |
| 115 | +the industry effort to close it. |
| 116 | + |
| 117 | +## Aliases across sources |
| 118 | + |
| 119 | +A single vulnerability often has different identifiers in different sources. Log4Shell, for example, is `CVE-2021-44228` |
| 120 | +in NVD and `GHSA-jfh8-c2jp-5v3q` in GHSA. |
| 121 | + |
| 122 | +Dependency-Track records aliases when sources publish explicit links between identifiers and surfaces them in the UI. |
| 123 | +Aliases do not de-duplicate findings: if two enabled sources both report Log4Shell for the same component, you see two |
| 124 | +findings, one per source, with the alias relationship visible on each. |
| 125 | + |
| 126 | +## Mirrored sources vs. external analyzers |
| 127 | + |
| 128 | +The mirrored sources are not the only way Dependency-Track gets vulnerability data. It also ships analyzers that call |
| 129 | +external services at analysis time: |
| 130 | + |
| 131 | +- **OSS Index** (Sonatype) |
| 132 | +- **Snyk** |
| 133 | +- **Trivy** (against a Trivy server you operate) |
| 134 | +- **VulnDB** (Flashpoint, commercial) |
| 135 | + |
| 136 | +These analyzers send component identifiers to a third party on every analysis run, return findings inline, and store |
| 137 | +nothing locally beyond the result. They complement the mirrored sources but introduce an outbound dependency and, in |
| 138 | +some cases, a commercial contract. See [Vulnerability analyzers](../reference/analyzers.md) for the full list and their |
| 139 | +requirements. |
| 140 | + |
| 141 | +## Vulnerabilities you define yourself |
| 142 | + |
| 143 | +The [private vulnerability repository](../reference/datasources/private-vulnerability-repository.md) holds |
| 144 | +vulnerabilities you define yourself. Use it for vulnerabilities in internal code or for pre-disclosure tracking. |
| 145 | +Findings from private vulnerabilities behave the same as findings from public sources. |
0 commit comments