Skip to content

docs: enhance known vulnerabilities page #6088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
valentijnscholten wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: enhance known vulnerabilities page #6088

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e0911b8
docs: enhance known vulnerabilities page
valentijnscholten May 4, 2026
88e34f3
docs: enhance known vulnerabilities page
valentijnscholten May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 126 additions & 36 deletions docs/_docs/analysis-types/known-vulnerabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,79 +5,169 @@ chapter: 3
order: 1
---

Dependency-Track integrates with multiple sources of vulnerability intelligence to identify components with known
vulnerabilities. The platform employs several methods of vulnerability identification including:
Dependency-Track integrates with multiple sources of vulnerability intelligence to identify components with known
vulnerabilities. The platform employs several methods of vulnerability identification:

| Analyzer | Description |
|-----------|--------------------------------------------------------------------------------------------------------|
| Internal | Identifies vulnerable components from an internal directory of vulnerable software |
| OSS Index | OSS Index is a service provided by Sonatype which identifies vulnerabilities in third-party components |
| VulnDB | VulnDB is a commercial service which identifies vulnerabilities in third-party components |
| Snyk | Snyk is a commercial service which identifies vulnerabilities in third-party components |
| Analyzer | Type | Identifier | Description |
|-----------|-----------------|--------------|------------------------------------------------------------------------------------------|
| Internal | Mirror-based | CPE and PURL | Analyzes components against a local mirror of NVD, GitHub Advisories, OSV, and/or VulnDB data |
| OSS Index | External API | PURL | Sonatype's hosted vulnerability service, queried at analysis time |
| VulnDB | External API | CPE | Flashpoint's commercial vulnerability service, queried at analysis time |
| Snyk | External API | PURL | Snyk's commercial vulnerability service, queried at analysis time |
| Trivy | External server | PURL | Self-hosted Trivy server, queried at analysis time |

Each of the analyzers above can be enabled or disabled independently of one another.

> **Components must have the right identifier for an analyzer to process them.**
> A component without a CPE is silently skipped by analyzers that require CPE; a component without a PURL is
> silently skipped by analyzers that require PURL. If a component yields no findings, always verify its
> identifiers first.

### Mirror-based vs. External Analyzers

Dependency-Track uses two fundamentally different approaches to vulnerability analysis:

**Mirror-based analysis (Internal Analyzer)**

The Internal Analyzer queries a local copy of vulnerability data that Dependency-Track periodically synchronizes
from upstream sources (NVD, GitHub Advisories, OSV, VulnDB). Analysis happens entirely within Dependency-Track
without any outbound requests at analysis time. The freshness of results depends on how recently the mirrors
were last updated — by default, mirrors are refreshed daily or on instance restart.

**External analyzers (OSS Index, VulnDB, Snyk, Trivy)**

These analyzers send component identifiers to a remote service at analysis time and receive vulnerability findings
in return. Results reflect the current state of the remote service, but are subject to network availability,
rate limits, authentication requirements, and the remote service's own update schedule.
To reduce redundant requests, results are cached locally for 12 hours by default
(see [Analysis Result Cache](#analysis-result-cache)).

### Vulnerability Assignment and Persistence

Once Dependency-Track assigns a vulnerability to a component, that assignment **persists even if the upstream
source data later changes** — for example, if a CVE's affected version ranges are revised to exclude the
component's version, or if the vulnerability is retracted entirely.

This is by design: automatically removing assigned vulnerabilities could silently erase audit trails and analyst
work. Dependency-Track re-evaluates components during each analysis run and may add newly discovered
vulnerabilities, but it does not remove existing ones.

If a previously assigned vulnerability is determined to be incorrect, it must be explicitly addressed by setting
an appropriate analysis state on the finding (e.g. *False Positive* or *Not Affected*).

### Internal Analyzer

The internal analyzer relies on a dictionary of vulnerable software. This dictionary is automatically populated when
NVD, GitHub Advisories, OSV, or VulnDB mirroring is performed. The internal analyzer is applicable to all components
with valid CPEs or PURLs, including application, operating system, and hardware components, and all components with
Package URLs.
The Internal Analyzer relies on a local dictionary of vulnerable software. This dictionary is automatically
populated when NVD, GitHub Advisories, OSV, or VulnDB mirroring is performed. Which identifier is used for
matching depends on the mirrored data source:

* **CPE** — used for data from the NVD and VulnDB mirrors.
* **PURL** — used for data from the GitHub Advisories and OSV mirrors.

A component needs at least one valid identifier to be analyzed. Components with both a CPE and a PURL are
evaluated against all applicable mirrored data sources.

#### CPE Matching

Matching against data from the NVD requires components to have a valid CPE. Dependency-Track follows
the [NIST CPE name matching specification](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7696.pdf),
the [NIST CPE name matching specification](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7696.pdf),
with a few customizations.

To reduce false positives, the following additional checks are performed:

* If comparison of *vendor* yields `SUBSET`, and comparison of *product* yields `SUPERSET`, then it's a no-match
* If comparison of *vendor* yields `SUPSERSET`, and comparison of *product* yields `SUBSET`, then it's a no-match
* If comparison of *vendor* yields `SUPERSET`, and comparison of *product* yields `SUBSET`, then it's a no-match

This is to avoid component CPEs like `cpe:2.3:a:*:zstandard:1.5.2:*:*:*:*:*:*:*` from getting matched to
CVE CPEs like `cpe:2.3:a:pascom_cloud_phone_system:*:*:*:*:*:*:*:*:*`.

Dependency-Track will emit a log in `DEBUG` level whenever it discards matches due to the above.
Dependency-Track will emit a log at `DEBUG` level whenever it discards matches due to the above.

### OSS Index Analyzer

OSS Index is a service provided by Sonatype which identifies vulnerabilities in third-party components. The service
supports a wide range of package management ecosystems. Dependency-Track integrates natively with OSS Index to provide
highly accurate results. This analyzer is applicable to all components with valid Package URLs.
> **Requires:** A valid Package URL (PURL). Components without a PURL are not analyzed by OSS Index.

> Starting with Dependency-Track v4.0, OSS Index is enabled by default and does not require an account. For prior
> Dependency-Track versions, OSS Index is disabled by default and requires an account. To enable OSS Index,
> sign up for a free account and enter the account details in Dependency-Track in the 'Analyzers' settings in the
> administrative console.
OSS Index is a service provided by Sonatype which identifies vulnerabilities in third-party components. The
service supports a wide range of package management ecosystems. Dependency-Track integrates with OSS Index using
its public API — vulnerability data is not mirrored locally, but consumed on an as-identified basis.

OSS Index is a source of vulnerability intelligence that provides its own content. Refer to
[OSS Index (Datasource)]({{ site.baseurl }}{% link _docs/datasources/ossindex.md %}) for additional information.
> **Note:** Unauthenticated usage of OSS Index is no longer supported. An API token is required.
> Refer to [OSS Index (Datasource)]({{ site.baseurl }}{% link _docs/datasources/ossindex.md %}) for
> configuration details.

### VulnDB Analyzer

VulnDB is a subscription service offered by Risk Based Security. The VulnDB Analyzer is capable of analyzing all
components with CPEs against the VulnDB service. Use of this analyzer requires a valid CPE for the components being
analyzed.
> **Requires:** A valid CPE. Components without a CPE are not analyzed by the VulnDB Analyzer.

VulnDB is a subscription service offered by Flashpoint. The VulnDB Analyzer queries the VulnDB REST APIs at
analysis time to identify vulnerabilities in components. Dependency-Track does not mirror VulnDB data for this
analyzer — it is consumed on an as-identified basis.

VulnDB is a source of vulnerability intelligence that provides its own content. Refer to
[VulnDB (Datasource)]({{ site.baseurl }}{% link _docs/datasources/vulndb.md %}) for additional information.
> VulnDB data can also be ingested into the Internal Analyzer via the VulnDB mirror. Refer to
> [VulnDB (Datasource)]({{ site.baseurl }}{% link _docs/datasources/vulndb.md %}) for additional information.

### Snyk Analyzer

It is a service provided by Snyk which identifies vulnerabilities in third-party components using REST API. Snyk returns only direct vulnerabilities for a specific package version identified by Package URL (purl).
This analyzer is applicable to all components with valid Package URLs.
> **Requires:** A valid Package URL (PURL). Components without a PURL are not analyzed by Snyk.

Snyk is a commercial service that identifies vulnerabilities in third-party components using its REST API. Snyk
returns direct vulnerabilities for a specific package version identified by PURL. Vulnerability data is not
mirrored locally — it is consumed on an as-identified basis.

Snyk REST API version is updated every 6 months and can be referred at
[Snyk REST API for PURL](https://apidocs.snyk.io/?version=2022-10-06#get-/orgs/-org_id-/packages/-purl-/issues) for additional information.
Refer to [Snyk (Datasource)]({{ site.baseurl }}{% link _docs/datasources/snyk.md %}) for configuration details.

### Trivy Analyzer

Trivy analyzer relies on a server trivy instance to perform the analysis using REST API.
Trivy REST API is not publically documented so upgrading to a new version might lead to some issues.
> **Requires:** A valid Package URL (PURL). Components without a PURL are not analyzed by Trivy.

The Trivy Analyzer sends components to an external Trivy server instance for analysis using its REST API.
The Trivy integration requires a separately deployed Trivy server and is disabled by default.

> The Trivy server REST API is not publicly documented, so upgrading to a new version may introduce
> compatibility issues. Refer to [Trivy (Datasource)]({{ site.baseurl }}{% link _docs/datasources/trivy.md %})
> for deployment instructions and known limitations.

### Analysis Result Cache

Dependency-Track contains an internal limiter which prevents repeated requests to remote services when performing
vulnerability analysis. When a component's Package URL or CPE is successfully analyzed by a given analyzer,
vulnerability analysis. When a component's Package URL or CPE is successfully analyzed by a given analyzer,
the result is cached. By default, cache entries expire after 12 hours.

### Troubleshooting False Positives and False Negatives

Before reporting a false positive or false negative as a bug, work through the following steps.

#### Step 1: Identify which analyzer reported the finding

On the project's *Vulnerability Audit* page, the *Analyzer* column shows which analyzer produced each finding.
Use this to determine which upstream source to consult in the steps below, and to confirm that the expected
analyzer is actually running for the affected component.

#### Step 2: Verify the component's identifiers in Dependency-Track

Navigate to the component in question and confirm it has a valid CPE and/or PURL, as required by the
analyzer(s) you expect to produce results (see the table at the top of this page). A missing, empty, or
malformed identifier causes the analyzer to silently skip the component and is the most common cause of
unexpected results.

#### Step 3: Check the vulnerability's affected ranges in Dependency-Track

Open the vulnerability in Dependency-Track and review the affected version ranges it lists. If the component's
version does not fall within any listed range, Dependency-Track correctly does not match it — this is expected
behavior, not a bug.

#### Step 4: Compare with the upstream source

* For the **Internal Analyzer**, cross-reference the relevant upstream source directly:
[NVD](https://nvd.nist.gov), [GitHub Advisories](https://github.com/advisories), [OSV](https://osv.dev),
or VulnDB. Check whether the upstream source agrees with what Dependency-Track has stored. If there is a
discrepancy, the local mirror may be stale — trigger a manual re-sync and re-analyze before concluding
there is a bug.

* For **external analyzers** (OSS Index, VulnDB, Snyk, Trivy), query the remote service directly using the
exact same PURL or CPE the component has in Dependency-Track. If the external service also does not report
the vulnerability for that identifier, the discrepancy lies in the upstream data, not in Dependency-Track's
integration.

Only after completing these steps and confirming a genuine discrepancy between Dependency-Track and the
upstream source should an issue be reported as a bug.
Loading