diff --git a/docs/assets/images/guides/administration/configuring-vulnerability-sources/github.png b/docs/assets/images/guides/administration/configuring-vulnerability-sources/github.png new file mode 100644 index 0000000..99fb875 Binary files /dev/null and b/docs/assets/images/guides/administration/configuring-vulnerability-sources/github.png differ diff --git a/docs/assets/images/guides/administration/configuring-vulnerability-sources/nvd.png b/docs/assets/images/guides/administration/configuring-vulnerability-sources/nvd.png new file mode 100644 index 0000000..abda616 Binary files /dev/null and b/docs/assets/images/guides/administration/configuring-vulnerability-sources/nvd.png differ diff --git a/docs/assets/images/guides/administration/configuring-vulnerability-sources/osv.png b/docs/assets/images/guides/administration/configuring-vulnerability-sources/osv.png new file mode 100644 index 0000000..22c0543 Binary files /dev/null and b/docs/assets/images/guides/administration/configuring-vulnerability-sources/osv.png differ diff --git a/docs/concepts/.pages b/docs/concepts/.pages index 87d7cc2..b144267 100644 --- a/docs/concepts/.pages +++ b/docs/concepts/.pages @@ -2,6 +2,7 @@ title: Concepts nav: - index.md - About access control: access-control.md + - About vulnerability data sources: about-vulnerability-data-sources.md - About notifications: notifications.md - About time series metrics: time-series-metrics.md - About component policies: component-policies.md diff --git a/docs/concepts/about-vulnerability-data-sources.md b/docs/concepts/about-vulnerability-data-sources.md new file mode 100644 index 0000000..fdeaa93 --- /dev/null +++ b/docs/concepts/about-vulnerability-data-sources.md @@ -0,0 +1,145 @@ +# About vulnerability data sources + +A vulnerability data source is an upstream feed of known security defects that Dependency-Track uses to find +vulnerabilities in your components. No single feed covers every ecosystem, identifier scheme, or disclosure path, so +Dependency-Track integrates with several. You pick which ones to enable based on what you ship and where the relevant +advisories are published. None of them are required, and enabling all of them is rarely the right answer. + +This page explains what each source contributes, how the data reaches your findings, and the trade-offs you accept when +you enable a source or turn one off. For the procedure to enable sources, see [Configuring vulnerability +sources](../guides/administration/configuring-vulnerability-sources.md). + +## Mirrored sources + +Dependency-Track can mirror three public data sources into its own database: + +- **[National Vulnerability Database (NVD)](https://nvd.nist.gov/)** is the canonical CVE feed maintained by NIST. It + contains over 200,000 CVE records spanning the early nineties to the present and describes affected products as + Common Platform Enumeration (CPE) names. NVD is the broadest source for non-package software (operating systems, + firmware, network equipment), but its CPE-based product model is a poor fit for open source packages. +- **[GitHub advisories](https://github.com/advisories)** is GitHub's curated advisory database (GHSA). It covers open + source packages on npm, Maven, PyPI, NuGet, Go, RubyGems, and others. Advisories use Package URL (PURL) keys, often + appear before the corresponding NVD entry, and frequently carry more ecosystem-specific detail than the NVD record. +- **[OSV](https://osv.dev/)** is Google's open source vulnerability database. It aggregates advisories from GitHub, + PyPA, RustSec, the Go team, distribution security teams, and others into one PURL-keyed dataset, and it covers + ecosystems and distributions that NVD and GHSA do not (for example crates.io, Hex, Pub, Alpine, and Debian). + +### Picking sources + +The three feeds overlap heavily for open source ecosystems. Most operators do not need all three: + +- **GHSA and OSV cover much of the same ground.** OSV ingests GitHub advisories and adds advisories from other curators + (PyPA, RustSec, Go, distribution security teams). OSV also lets you mirror per ecosystem, which is finer-grained + control than GHSA offers. If you want one source for open source packages, prefer OSV. +- **GHSA** is useful on its own if you stay close to the GitHub ecosystem or want the data exactly as GitHub publishes + it, without the aggregation layer that OSV adds. +- **NVD** is the only mirrored source that meaningfully covers non-package software identified by CPE. Enable it when + your BOMs include such components, or when you specifically need CVE coverage independent of curator-specific feeds. + +## 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. + +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 +locally. The internal analyzer makes no outbound calls during analysis, which makes findings reproducible and keeps +analysis fast. + +For the full analysis workflow, see [Vulnerability analysis](architecture/design/vulnerability-analysis.md). + +### Turning a source off + +Disabling a source stops further mirroring from that source, but Dependency-Track does not delete the records it has +already written. Vulnerabilities mirrored before the source was turned off remain in the database, and the internal +analyzer keeps matching components against them on subsequent analysis runs. Findings already raised from that source +are not retroactively removed either. + +The practical consequence is that turning a source off is reversible without re-downloading, but it does not clean up +after itself. If you intend to drop a source entirely and have its findings disappear, expect to clear the data +manually. Dependency-Track does not yet provide a built-in workflow for this. + +## How component matching works + +Each advisory in a mirrored source names the products it affects, using either a CPE or a PURL, and specifies the +affected versions. The internal analyzer matches a component to an advisory by identifier scheme first and version +second. + +| Source | Identifier in records | What components need | +|:-------|:----------------------|:---------------------| +| NVD | CPE | A valid CPE on the component | +| GitHub advisories | PURL | A valid PURL on the component | +| OSV | PURL | A valid PURL on the component | + +A component with neither a CPE nor a PURL is not evaluated. + +### CPE matching + +CPE matching follows the [NIST CPE name matching +specification](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7696.pdf): the analyzer compares all eleven CPE +attributes (`part`, `vendor`, `product`, `version`, `update`, `edition`, `language`, `sw_edition`, `target_sw`, +`target_hw`, `other`) and rejects the match if any attribute is disjoint. + +Two adjustments reduce false positives compared to a literal reading of the spec: + +- A SUBSET vendor combined with a SUPERSET product (or the reverse) is rejected, because these combinations otherwise + produce noisy matches across unrelated products (see [issue + #3178](https://github.com/DependencyTrack/dependency-track/issues/3178)). +- Component versions of `*` (ANY) and `-` (NA) are handled per the spec, not run through range comparison. + +When the advisory specifies a version range, the analyzer evaluates it using the +[vers](https://www.packageurl.org/docs/vers/introduction) range specification, with a versioning scheme inferred from +the component's PURL when present and the `generic` scheme otherwise. + +### PURL matching + +PURL matching requires the advisory's PURL `type`, `namespace`, and `name` to match the component's exactly. For +OS-package PURLs (`deb`, `rpm`), if both sides carry a `distro` qualifier they must agree, with semantic equivalences +honored (for example, `debian-13` matches `trixie`). + +Version comparison uses [vers](https://www.packageurl.org/docs/vers/introduction) with the versioning scheme derived +from the PURL type. If the strict scheme fails to parse a version, the analyzer falls back to the `generic` scheme to +avoid false negatives. For `deb` and `rpm` PURLs, an `epoch` qualifier is folded into the version as `epoch:version` +before comparison when the version does not already encode one. + +### Practical consequence + +Most modern BOM generators emit PURLs but not CPEs. As a result, components from package ecosystems (npm, Maven, PyPI, +and so on) match GHSA and OSV well but produce few or no findings from NVD data, even when CVE records exist for those +packages. This is the most common reason operators see fewer NVD findings than expected. + +If you need NVD coverage for ecosystem packages, your BOM generator must also produce CPEs for those components. +Otherwise, rely on GHSA or OSV for open source coverage and on NVD primarily for non-package software identified by CPE. +The OWASP SBOM Forum's [recommendations to improve the +NVD](https://owasp.org/blog/2022/09/13/sbom-forum-recommends-improvements-to-nvd) document this CPE-vs-PURL mismatch and +the industry effort to close it. + +## Aliases across sources + +A single vulnerability often has different identifiers in different sources. Log4Shell, for example, is `CVE-2021-44228` +in NVD and `GHSA-jfh8-c2jp-5v3q` in GHSA. + +Dependency-Track records aliases when sources publish explicit links between identifiers and surfaces them in the UI. +Aliases do not de-duplicate findings: if two enabled sources both report Log4Shell for the same component, you see two +findings, one per source, with the alias relationship visible on each. + +## Mirrored sources vs. external analyzers + +The mirrored sources are not the only way Dependency-Track gets vulnerability data. It also ships analyzers that call +external services at analysis time: + +- **OSS Index** (Sonatype) +- **Snyk** +- **Trivy** (against a Trivy server you operate) +- **VulnDB** (Flashpoint, commercial) + +These analyzers send component identifiers to a third party on every analysis run, return findings inline, and store +nothing locally beyond the result. They complement the mirrored sources but introduce an outbound dependency and, in +some cases, a commercial contract. See [Vulnerability analyzers](../reference/analyzers.md) for the full list and their +requirements. + +## Vulnerabilities you define yourself + +The [private vulnerability repository](../reference/datasources/private-vulnerability-repository.md) holds +vulnerabilities you define yourself. Use it for vulnerabilities in internal code or for pre-disclosure tracking. +Findings from private vulnerabilities behave the same as findings from public sources. diff --git a/docs/concepts/changes-in-v5.md b/docs/concepts/changes-in-v5.md index 2edbdcd..bbe0199 100644 --- a/docs/concepts/changes-in-v5.md +++ b/docs/concepts/changes-in-v5.md @@ -168,6 +168,7 @@ remediation steps, lives in the use for them), and its file storage abstracts over backends like S3 rather than assuming a local filesystem to serve from. Dependency-Track no longer serves this endpoint. Fetch feeds directly from NIST or run a dedicated mirror. + See [Running air-gapped](../guides/administration/running-air-gapped.md) for hosting an internal NVD or OSV mirror. [CEL]: https://cel.dev/ [Protobuf]: https://protobuf.dev/ diff --git a/docs/guides/administration/.pages b/docs/guides/administration/.pages index 41720cf..93f98f5 100644 --- a/docs/guides/administration/.pages +++ b/docs/guides/administration/.pages @@ -7,6 +7,8 @@ nav: - configuring-secret-management.md - configuring-internal-ca.md - configuring-http-proxy.md + - configuring-vulnerability-sources.md + - running-air-gapped.md - configuring-observability.md - configuring-ldap.md - configuring-oidc.md diff --git a/docs/guides/administration/configuring-http-proxy.md b/docs/guides/administration/configuring-http-proxy.md index ba29ee9..ea5787b 100644 --- a/docs/guides/administration/configuring-http-proxy.md +++ b/docs/guides/administration/configuring-http-proxy.md @@ -1,9 +1,9 @@ # Configuring an HTTP proxy -The Dependency-Track API server makes outbound HTTP and HTTPS calls to mirror vulnerability data sources, fetch -package metadata from repositories, perform OIDC discovery, deliver webhooks, and reach other integrations. In -environments where outbound traffic must traverse a corporate proxy, configure the API server to route those calls -through it. +The Dependency-Track API server makes outbound HTTP and HTTPS calls to mirror +[vulnerability data sources](configuring-vulnerability-sources.md), fetch package metadata from repositories, perform +OIDC discovery, deliver webhooks, and reach other integrations. In environments where outbound traffic must traverse a +corporate proxy, configure the API server to route those calls through it. Proxy configuration applies to the API server only. The frontend is a static single-page app served to the user's browser; any requests it appears to make actually originate from the browser itself. diff --git a/docs/guides/administration/configuring-internal-ca.md b/docs/guides/administration/configuring-internal-ca.md index 8a74ca2..960fa38 100644 --- a/docs/guides/administration/configuring-internal-ca.md +++ b/docs/guides/administration/configuring-internal-ca.md @@ -15,7 +15,8 @@ Common scenarios where this occurs: - **LDAPS**: connecting to an LDAP server using TLS ([Configuring LDAP](configuring-ldap.md)) - **OIDC**: the identity provider uses a privately signed certificate ([Configuring OIDC](configuring-oidc.md)) - **HTTP proxy**: an intercepting TLS proxy sits between Dependency-Track and external services -- **Internal vulnerability sources**: a private vulnerability repository or API server with an internal certificate +- **Internal vulnerability sources**: an internal mirror of NVD or OSV behind a privately signed certificate (see + [Configuring vulnerability sources](configuring-vulnerability-sources.md) and [Running air-gapped](running-air-gapped.md)) The solution is to import your internal CA certificate into the JVM truststore and mount the modified truststore into the container. diff --git a/docs/guides/administration/configuring-vulnerability-sources.md b/docs/guides/administration/configuring-vulnerability-sources.md new file mode 100644 index 0000000..e9cf9d3 --- /dev/null +++ b/docs/guides/administration/configuring-vulnerability-sources.md @@ -0,0 +1,103 @@ +# Configuring vulnerability sources + +Dependency-Track can mirror three public vulnerability data sources into its internal database: the National +Vulnerability Database (NVD), GitHub advisories, and OSV. You pick which ones to enable, configure them through the web +UI, and trigger an initial mirror so findings appear without waiting for the next scheduled run. + +For background on what each source provides, when one is enough, and how the internal analyzer turns mirrored data into +findings, see [About vulnerability data sources](../../concepts/about-vulnerability-data-sources.md). + +## Prerequisites + +For each source you plan to enable, allow outbound HTTPS access from the API server to the corresponding host: + +| Source | Host | +|:-------|:-----| +| NVD | `nvd.nist.gov` | +| GitHub advisories | `api.github.com` | +| OSV | `storage.googleapis.com` | + +If outbound traffic must go through a proxy, see [Configuring an HTTP proxy](configuring-http-proxy.md). If the proxy +intercepts TLS, see [Configuring internal CA trust](configuring-internal-ca.md). + +The GitHub advisories source also requires a GitHub personal access token (PAT). The token needs no scopes, but the +GitHub GraphQL API rejects unauthenticated requests. Create one at +[github.com/settings/tokens](https://github.com/settings/tokens). NVD and OSV do not require credentials. + +## Enabling sources + +Open **Administration > Vulnerability Sources** in the web UI. Each source has its own configuration panel. The following steps +cover the least configuration needed for findings. + +### NVD + +1. Open **Administration > Vulnerability Sources > NVD**. +2. Enable the source. +3. Select **Test** to verify the configured endpoint is reachable and that the feed file format matches what + Dependency-Track expects. +4. Select **Mirror now** to download the feed immediately. The first mirror downloads the entire dataset and can take a + while. + +![NVD configuration](../../assets/images/guides/administration/configuring-vulnerability-sources/nvd.png) + +NVD records describe affected products as CPEs. The internal analyzer skips components that lack a valid CPE when +evaluating NVD data. If you expect findings for open source packages identified by PURL and see none from NVD, that is +the reason. See [How component matching +works](../../concepts/about-vulnerability-data-sources.md#how-component-matching-works). + +### GitHub advisories + +1. Open **Administration > Vulnerability Sources > GitHub**. +2. Enable the source. +3. Enter the GitHub PAT from the prerequisites. +4. Select **Mirror now** to download advisories immediately. + +![GitHub Advisories configuration](../../assets/images/guides/administration/configuring-vulnerability-sources/github.png) + +### OSV + +1. Open **Administration > Vulnerability Sources > OSV**. +2. Enable the source. +3. Select the ecosystems you want to mirror. Dependency-Track downloads only the ecosystems you select. +4. Select **Mirror now** to download the selected ecosystems immediately. + +![OSV configuration](../../assets/images/guides/administration/configuring-vulnerability-sources/osv.png) + +!!! tip + For Debian, select the **Debian** ecosystem rather than individual Debian version ecosystems. The Debian package is + a superset of all version-specific ones. + +## Triggering an initial mirror + +After enabling a source for the first time, use **Mirror now** rather than waiting for the next scheduled run. The first +NVD mirror in particular can take a long time, and you want it underway before users start uploading BOMs and expecting +findings. + +Mirror progress and errors appear in the API server logs, so tail the logs during initial setup if you need to follow +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: + +- NVD: [`dt.task.nist.mirror.cron`](../../reference/configuration/properties.md#dttasknistmirrorcron) +- GitHub advisories: + [`dt.task.git.hub.advisory.mirror.cron`](../../reference/configuration/properties.md#dttaskgithubadvisorymirrorcron) +- OSV: [`dt.task.osv.mirror.cron`](../../reference/configuration/properties.md#dttaskosvmirrorcron) + +## Verifying findings + +Once a mirror completes, upload a BOM for a project that contains components you know to be vulnerable, or trigger +analysis on an existing project. Findings should appear within seconds of analysis completing. If they do not, check the +API server logs for mirror errors and confirm the components carry the identifier the source uses for matching (CPE for +NVD, PURL for GitHub advisories and OSV). + +## See also + +- [About vulnerability data sources](../../concepts/about-vulnerability-data-sources.md) +- [Vulnerability datasources reference](../../reference/datasources/index.md) +- [Vulnerability analyzers reference](../../reference/analyzers.md) +- [Running air-gapped](running-air-gapped.md) +- [Configuring an HTTP proxy](configuring-http-proxy.md) +- [Configuring internal CA trust](configuring-internal-ca.md) diff --git a/docs/guides/administration/migrating-from-v4.md b/docs/guides/administration/migrating-from-v4.md index 280e24a..ec714b8 100644 --- a/docs/guides/administration/migrating-from-v4.md +++ b/docs/guides/administration/migrating-from-v4.md @@ -366,6 +366,7 @@ It drops analyzer and vulnerability-source credentials as part of the encrypted- After the migration, open the **Repositories**, **Analyzers**, and **Vulnerability Sources** pages in the v5 administrator panel and re-enter each credential through the secret manager. Turn the affected repositories back on. +See [Configuring vulnerability sources](configuring-vulnerability-sources.md) for the full procedure to re-enable each mirror. See [Configuring secret management](configuring-secret-management.md) if you have not yet set the secret-encryption key for the v5 deployment. ### Encrypted property values diff --git a/docs/guides/administration/running-air-gapped.md b/docs/guides/administration/running-air-gapped.md new file mode 100644 index 0000000..fb2093c --- /dev/null +++ b/docs/guides/administration/running-air-gapped.md @@ -0,0 +1,65 @@ +# Running air-gapped + +Dependency-Track can run in environments without outbound internet access, but every integration that normally reaches a +public endpoint needs an alternative. This guide collects the relevant considerations. + +!!! warning "Incomplete" + This guide is a work in progress. It currently covers vulnerability data sources and vulnerability analyzers. Other + application areas (notifications, repository metadata for outdated-component detection) + also reach the public internet by default and will be documented here as the content is written. If your air-gapped + deployment depends on one of those areas, treat this guide as a starting point, not a complete checklist. + +If your network only routes outbound traffic through a proxy, you may not need a full air-gapped setup. See [Configuring +an HTTP proxy](configuring-http-proxy.md) and [Configuring internal CA trust](configuring-internal-ca.md) first. + +## Vulnerability data sources + +For background on the three mirrored sources and how to enable them, see [Configuring vulnerability +sources](configuring-vulnerability-sources.md). Each source has a different air-gapped story. + +### NVD + +Host files that match the [NVD JSON 2.0 feed layout](https://nvd.nist.gov/vuln/data-feeds#divJson20Feeds) on an internal +HTTP file server. Dependency-Track requires the `META` and `GZ` files. The `ZIP` files are not required. + +Point the NVD source's feed URL at the internal mirror, then use the **Test** action in the NVD configuration panel to +confirm the mirror is reachable and serves files in the expected layout. + +### OSV + +Host the [OSV data dumps](https://google.github.io/osv.dev/data/#data-dumps) on an internal HTTP file server. +Dependency-Track expects per-ecosystem `all.zip` files. Dependency-Track also requires `modified_id.csv` for incremental +mirroring. If you turn off incremental mirroring, Dependency-Track re-downloads the full dumps on every run. + +Point the OSV source's base URL at the internal mirror. + +### GitHub advisories + +The GitHub advisories integration uses GitHub's paginated GraphQL API. A static HTTP mirror cannot serve it. Forwarding +through an HTTP forward proxy may work but is not tested. + +In a strict air-gapped environment, turn off the GitHub advisories source. Use OSV for open source coverage instead. OSV +ingests GitHub advisories along with advisories from other curators, so you do not lose GHSA-prefixed records by relying +on OSV alone. + +## Vulnerability analyzers + +The [internal analyzer](../../reference/analyzers.md#internal) is air-gap safe. It queries only the local vulnerability +database and makes no outbound calls during analysis, so it works as long as you have configured the corresponding +[vulnerability data sources](#vulnerability-data-sources) above. + +[Trivy](../../reference/analyzers.md#trivy) is the other practical option. The Trivy server itself supports air-gapped +operation by loading its vulnerability database from internal storage ahead of time. See the [Trivy air-gapped +environment guide](https://trivy.dev/docs/latest/guide/advanced/air-gap/) for setup. Dependency-Track only talks to the +Trivy server you operate, so as long as the Trivy server is reachable from the API server, the analyzer works. + +The [OSS Index](../../reference/analyzers.md#oss-index), [Snyk](../../reference/analyzers.md#snyk), and +[VulnDB](../../reference/analyzers.md#vulndb) analyzers call vendor-hosted APIs on every analysis run and require +outbound connectivity to those endpoints. Routing them through a caching proxy may work but is not tested. In a strict +air-gapped environment, turn these analyzers off. + +## See also + +- [Configuring vulnerability sources](configuring-vulnerability-sources.md) +- [Configuring an HTTP proxy](configuring-http-proxy.md) +- [Configuring internal CA trust](configuring-internal-ca.md) diff --git a/docs/reference/analyzers.md b/docs/reference/analyzers.md index d3c3cba..6e16275 100644 --- a/docs/reference/analyzers.md +++ b/docs/reference/analyzers.md @@ -16,6 +16,9 @@ Matches components against Dependency-Track's own vulnerability database. This i vulnerabilities mirrored from sources such as the NVD, GitHub Advisories, and OSV. The internal analyzer is enabled by default. +For background on what each mirrored source contributes and how matching works, +see [About vulnerability data sources](../concepts/about-vulnerability-data-sources.md). + Uses both CPE and PURL matching. !!! note diff --git a/docs/reference/datasources/.pages b/docs/reference/datasources/.pages index 0eeea08..ff4f8c2 100644 --- a/docs/reference/datasources/.pages +++ b/docs/reference/datasources/.pages @@ -1,8 +1,5 @@ nav: - Overview: index.md - - NVD: nvd.md - - GitHub advisories: github-advisories.md - - OSV: osv.md - Private vulnerability repository: private-vulnerability-repository.md - Repositories: repositories.md - Internal components: internal-components.md diff --git a/docs/reference/datasources/github-advisories.md b/docs/reference/datasources/github-advisories.md deleted file mode 100644 index af53574..0000000 --- a/docs/reference/datasources/github-advisories.md +++ /dev/null @@ -1,40 +0,0 @@ -# GitHub Advisories - -The [GitHub Advisory Database](https://github.com/advisories) (GHSA) contains -security advisories for open source packages hosted on GitHub and other ecosystems. -Advisories may or may not overlap with NVD CVE records. GitHub often publishes -advisories for vulnerabilities that are not yet in the NVD, or with more ecosystem- -specific detail. - -## What It Provides - -GitHub Advisories are keyed by PURL and map directly to package ecosystems such as -npm, Maven, PyPI, Go, NuGet, and others. This makes them highly effective for -open source component matching without requiring a CPE. - -Dependency-Track automatically synchronises vulnerability aliases between GHSA and -CVE identifiers where GitHub has made the link explicit. This means a component can -be matched by either its GHSA or CVE identifier, and the finding will not be -duplicated. - -## Mirroring - -Dependency-Track mirrors GitHub Advisories via GitHub's public GraphQL API. The mirror -refreshes daily and on instance startup. - -The mirroring schedule is controlled by -[`dt.task.git.hub.advisory.mirror.cron`](../configuration/properties.md#dttaskgithubadvisorymirrorcron). - -## Configuration - -GitHub Advisory mirroring is configured in the administration UI under -**Administration → Datasources → GitHub Advisories**. - -| Setting | Description | -|:--------|:------------| -| Enabled | Whether GitHub Advisory mirroring is active. Enabled by default. | -| GitHub Personal Access Token | Required. A GitHub PAT with no scopes assigned is sufficient. Without a token, the GraphQL API rejects requests. | - -To create a token, visit [github.com/settings/tokens](https://github.com/settings/tokens) -and generate a classic or fine-grained token. No scopes are required; the public -advisory data is accessible to any authenticated user. diff --git a/docs/reference/datasources/index.md b/docs/reference/datasources/index.md index 6864d94..2c051d1 100644 --- a/docs/reference/datasources/index.md +++ b/docs/reference/datasources/index.md @@ -1,34 +1,33 @@ -# Vulnerability Datasources +# Vulnerability datasources -Vulnerability datasources are the upstream feeds from which Dependency-Track populates -its internal vulnerability database. The [internal analyzer](../analyzers.md#internal) -queries this local database when evaluating components, so no external call is made at -analysis time, only during mirroring. +Vulnerability datasources are the upstream feeds from which Dependency-Track populates its internal vulnerability +database. The [internal analyzer](../analyzers.md#internal) queries this local database during vulnerability analysis, +so no external call is made at analysis time, only during mirroring. -Mirroring runs on a configurable schedule (daily by default) and on instance startup. -Progress and errors are reported via the `DATASOURCE_MIRRORING` -[notification group](../../concepts/architecture/design/notifications.md). +For background on what each source provides and the trade-offs between them, see [About vulnerability data +sources](../../concepts/about-vulnerability-data-sources.md). For the procedure to enable and schedule mirrors, see +[Configuring vulnerability sources](../../guides/administration/configuring-vulnerability-sources.md). -## Mirrored Sources +## Mirrored sources -These sources are downloaded and stored locally. The internal analyzer queries them -without contacting any external service during vulnerability analysis. +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. -| Source | Identifier prefix | Primary use | -|:-------|:-----------------|:------------| -| [NVD](nvd.md) | `CVE-` | CPE-based matching for all component types | -| [GitHub Advisories](github-advisories.md) | `GHSA-` | PURL-based matching for open source packages | -| [OSV](osv.md) | varies by ecosystem | PURL-based matching for open source packages | +| Source | Identifier prefix | Matches on | +|:-------|:------------------|:-----------| +| NVD | `CVE-` | CPE | +| GitHub advisories | `GHSA-` | PURL | +| OSV | varies by ecosystem | PURL | -## Other Sources +## Other sources | Source | Description | |:-------|:------------| -| [Private Vulnerability Repository](private-vulnerability-repository.md) | Internally managed vulnerabilities for proprietary components or pre-disclosure research | -| [Repositories](repositories.md) | Package registry integrations used for outdated component detection | -| [Internal Components](internal-components.md) | Configuring components that should never be sent to external services | +| [Private vulnerability repository](private-vulnerability-repository.md) | Internally managed vulnerabilities for proprietary components or pre-disclosure research. | +| [Repositories](repositories.md) | Package registry integrations used for outdated component detection. Not a vulnerability source. | +| [Internal components](internal-components.md) | Marks components that must never be sent to external services. | -## Analyzers That Query External Services +## Analyzers that query external services -OSS Index, Snyk, Trivy, and VulnDB are *analyzers* that call external APIs at analysis -time. They are documented separately in the [Analyzers](../analyzers.md) reference. +OSS Index, Snyk, Trivy, and VulnDB are *analyzers* that call external APIs at analysis time. They are documented +separately in the [Analyzers](../analyzers.md) reference. diff --git a/docs/reference/datasources/internal-components.md b/docs/reference/datasources/internal-components.md index d962545..2aa8f8f 100644 --- a/docs/reference/datasources/internal-components.md +++ b/docs/reference/datasources/internal-components.md @@ -1,37 +1,34 @@ -# Internal Components +# Internal components -Dependency-Track allows organisations to mark certain component namespaces and/or names -as *internal*. Components identified as internal are excluded from all external services: -they are never sent to external vulnerability analyzers (OSS Index, Snyk, Trivy, VulnDB) -and never queried against public package repositories. +Dependency-Track allows organizations to mark certain component namespaces and names as *internal*. Components +identified as internal are excluded from all external services. They are never sent to external vulnerability analyzers +(OSS Index, Snyk, Trivy, VulnDB) and never queried against public package repositories. -This is useful when your SBOMs include first-party libraries with coordinates that could -coincide with public packages, or when you simply do not want metadata about internal -packages to leave your network. +This is useful when SBOMs include first-party libraries whose coordinates could coincide with public packages, or when +metadata about internal packages must not leave the network. -## How Matching Works +## How matching works -Internal component identification is configured in -**Administration → Internal Components** by specifying one or more namespace and/or name -patterns. +Configure internal component identification in **Administration > Internal components** by specifying one or more +namespace and name patterns. Two matching modes are available: -| Mode | Behaviour | -|:-----|:----------| -| OR (default) | A component is internal if its namespace *or* name matches any configured pattern. | -| AND | A component is internal if its namespace *and* name both match. | +| Mode | Behavior | +|:-----|:---------| +| OR (default) | A component is internal if its namespace or name matches any configured pattern. | +| AND | A component is internal if its namespace and name both match. | Patterns are matched against the component's PURL namespace and name fields. !!! note - By default, no components are identified as internal. All components are treated - as third-party and may be sent to configured external analyzers. + By default, no components are identified as internal. All components are treated as third-party and may be sent to + configured external analyzers. -## Effects of Being Marked Internal +## Effects of being marked internal -| Service | Behaviour for internal components | -|:--------|:----------------------------------| +| Service | Behavior for internal components | +|:--------|:---------------------------------| | OSS Index | Not queried | | Snyk | Not queried | | Trivy | Not queried | @@ -40,9 +37,8 @@ Patterns are matched against the component's PURL namespace and name fields. | Internal analyzer | Still evaluated against the local vulnerability database | | Private repositories | Still queried if configured | -## Use with the Private Vulnerability Repository +## Use with the private vulnerability repository -Internal components can still be matched against vulnerabilities defined in the -[private vulnerability repository](private-vulnerability-repository.md). This allows -organisations to track and triage vulnerabilities in their own codebases without -exposing component identifiers externally. +Internal components can still be matched against vulnerabilities defined in the [private vulnerability +repository](private-vulnerability-repository.md). This allows organizations to track and triage vulnerabilities in their +own codebases without exposing component identifiers externally. diff --git a/docs/reference/datasources/nvd.md b/docs/reference/datasources/nvd.md deleted file mode 100644 index 839cfd4..0000000 --- a/docs/reference/datasources/nvd.md +++ /dev/null @@ -1,51 +0,0 @@ -# National Vulnerability Database (NVD) - -The [National Vulnerability Database](https://nvd.nist.gov/) (NVD) is the largest -publicly available source of vulnerability intelligence, maintained by NIST and building -on CVE identifiers from MITRE. It contains over 200,000 CVE records spanning from the -early nineties to the present day. - -!!! note - This product uses the NVD API but is not endorsed or certified by the NVD. - -## What It Provides - -The NVD mirror populates Dependency-Track's internal database with CVE records including -descriptions, CVSS scores, CWE classifications, and affected product configurations -expressed as CPE. The [internal analyzer](../analyzers.md#internal) uses this data -to match components with valid CPEs against known vulnerabilities. - -## Mirroring - -Dependency-Track mirrors the NVD via the NVD REST API. The mirror refreshes daily and -on instance startup. The initial mirror may take significantly longer than subsequent -incremental updates. - -The mirroring schedule is controlled by -[`dt.task.nist.mirror.cron`](../configuration/properties.md#dttasknistmirrorcron). - -## Configuration - -NVD mirroring is configured through the administration UI under -**Administration → Datasources → NVD**. - -| Setting | Description | -|:--------|:------------| -| Enabled | Whether NVD mirroring is active. Enabled by default. | -| NVD API Key | Optional but strongly recommended. Unauthenticated requests are rate-limited aggressively, which can cause the initial mirror to take hours or fail. | - -Obtain a free NVD API key at [nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key). - -!!! tip - Configuring an API key is especially important for new installations, where - the entire NVD dataset must be downloaded on the first mirror run. - -## CPE Matching - -NVD records describe affected products using CPE (Common Platform Enumeration). -Dependency-Track follows the NIST CPE name matching specification with adjustments -to reduce false positives: matches are rejected when the vendor comparison yields -*SUBSET* and the product comparison yields *SUPERSET*, or vice versa. - -Components without a valid CPE are not evaluated by the internal analyzer against -NVD data. Ensure your SBOMs include CPEs for non-open-source components. diff --git a/docs/reference/datasources/osv.md b/docs/reference/datasources/osv.md deleted file mode 100644 index 99ed8d2..0000000 --- a/docs/reference/datasources/osv.md +++ /dev/null @@ -1,53 +0,0 @@ -# OSV - -[OSV](https://osv.dev/) (Open Source Vulnerabilities) is a vulnerability database -focused on open source packages, maintained by Google. It aggregates advisories from -multiple upstream sources including GitHub Advisories, PyPA, RustSec, and many others, -providing a unified PURL-keyed dataset. - -## What It Provides - -OSV advisories are natively keyed by package ecosystem and version, making them -well-suited for PURL-based matching across a wide range of languages and package managers. - -OSV supports alias linking, so vulnerabilities tracked under different IDs (CVE, GHSA, -OSV-specific IDs) across databases are correlated automatically. - -## Supported Ecosystems - -OSV data can be selectively enabled per ecosystem. Available ecosystems include: -Go, npm, PyPI, RubyGems, crates.io (Rust), Maven, NuGet, Packagist (PHP), Hex (Erlang), -pub (Dart), Alpine, Debian, Ubuntu, Android, and others. - -!!! tip - For Debian, enable **Debian** rather than individual Debian version ecosystems. - The Debian ecosystem package is a superset of all individual versions. - -## Mirroring - -Dependency-Track mirrors OSV data from Google Cloud Storage (`gs://osv-vulnerabilities`). -No authentication token is required. The mirror refreshes daily and on instance startup. - -The mirroring schedule is controlled by -[`dt.task.osv.mirror.cron`](../configuration/properties.md#dttaskosvmirrorcron). - -## Configuration - -OSV mirroring is configured in the administration UI under -**Administration → Datasources → OSV**. - -| Setting | Description | -|:--------|:------------| -| Enabled | Whether OSV mirroring is active. | -| Ecosystems | The specific ecosystems to mirror. Only selected ecosystems are downloaded. | - -!!! warning - Disabling OSV removes ecosystem selections from the UI but preserves previously - mirrored vulnerability records in the database. Previously matched findings are - not automatically removed. - -## Alias Synchronisation - -OSV supports alias synchronisation with other vulnerability databases. This is -configured on the [internal analyzer](../analyzers.md#internal) rather than on -the OSV datasource directly. diff --git a/docs/reference/datasources/private-vulnerability-repository.md b/docs/reference/datasources/private-vulnerability-repository.md index 44e7a24..a21ed25 100644 --- a/docs/reference/datasources/private-vulnerability-repository.md +++ b/docs/reference/datasources/private-vulnerability-repository.md @@ -1,35 +1,35 @@ -# Private Vulnerability Repository +# Private vulnerability repository -The private vulnerability repository stores internally managed vulnerabilities. It behaves -identically to other vulnerability sources -- findings are raised, audit trails are maintained, -and notifications fire -- but the data is entirely user-managed. +The private vulnerability repository stores internally managed vulnerabilities. It behaves identically to other +vulnerability sources. Findings are raised, audit trails are maintained, and notifications fire, but the data is +entirely user-managed. -For use cases and step-by-step creation instructions, see -[Managing private vulnerabilities](../../guides/user/managing-private-vulnerabilities.md). +For use cases and step-by-step creation instructions, see [Managing private +vulnerabilities](../../guides/user/managing-private-vulnerabilities.md). ## Vulnerability IDs -Every vulnerability in the private repository requires a unique ID within the -`INTERNAL` source. By default, Dependency-Track generates IDs using the prefix `INT` -followed by three blocks of four alphanumeric characters (for example, `INT-td11-7hzm-qzot`). +Every vulnerability in the private repository requires a unique ID within the `INTERNAL` source. By default, +Dependency-Track generates IDs using the prefix `INT` followed by three blocks of four alphanumeric characters (for +example, `INT-td11-7hzm-qzot`). -Any prefix meaningful to your organisation may be used (for example, `ACME-`, `INT-`, -`SEC-`). The only constraint is uniqueness within the `INTERNAL` source. +Any prefix meaningful to your organization may be used (for example, `ACME-`, `INT-`, `SEC-`). The only constraint is +uniqueness within the `INTERNAL` source. -## Severity and Risk Ratings +## Severity and risk ratings Severity can be set explicitly or derived from a risk score: | Rating | Description | |:-------|:------------| | Explicit severity | Choose directly: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO`. | -| CVSSv2 / CVSSv3 | Enter a CVSS vector; Dependency-Track calculates the base score and derives severity. | -| OWASP Risk Rating | Enter likelihood and impact factors; Dependency-Track calculates severity. | +| CVSSv2 / CVSSv3 | Enter a CVSS vector. Dependency-Track calculates the base score and derives severity. | +| OWASP Risk Rating | Enter likelihood and impact factors. Dependency-Track calculates severity. | -When multiple ratings are provided, CVSSv3 takes precedence over CVSSv2, and the rating -with the higher severity is preferred over OWASP Risk Rating. +When multiple ratings are provided, CVSSv3 takes precedence over CVSSv2, and the rating with the higher severity is +preferred over OWASP Risk Rating. -## Description Fields +## Description fields | Field | Purpose | |:------|:--------| @@ -39,11 +39,10 @@ with the higher severity is preferred over OWASP Risk Rating. | Recommendation | Remediation or mitigation instructions. Supports Markdown. | | References | List of external links (changelogs, advisories, blog posts, etc.). | -## Affected Components +## Affected components -For a vulnerability to be matched against components, **Affected Components** must -be configured. Each entry specifies an identifier (PURL or CPE) and either an exact -version or a version range. +For a vulnerability to be matched against components, **Affected components** must be configured. Each entry specifies +an identifier (PURL or CPE) and either an exact version or a version range. **Version ranges** use lower and/or upper bounds: @@ -54,15 +53,15 @@ version or a version range. | `<` | Less than (exclusive upper bound) | | `<=` | Less than or equal (inclusive upper bound) | -A range with only a lower bound matches all versions above it; a range with only an -upper bound matches all versions below it. +A range with only a lower bound matches all versions above it. A range with only an upper bound matches all versions +below it. !!! tip - Dependency-Track does not convert between PURL and CPE. Use the same identifier - type that your SBOM generator produces. Most modern generators emit PURLs. + Dependency-Track does not convert between PURL and CPE. Use the same identifier type your SBOM generator produces. + Most modern generators emit PURLs. -## Finding Behaviour +## Finding behavior -Internal vulnerabilities are matched by the [internal analyzer](../analyzers.md#internal) -during regular vulnerability analysis. Findings appear identically to those from public -sources and support the same triage workflow (analysis states, suppression, VEX export). +Internal vulnerabilities are matched by the [internal analyzer](../analyzers.md#internal) during regular vulnerability +analysis. Findings appear identically to those from public sources and support the same triage workflow (analysis +states, suppression, VEX export). diff --git a/docs/reference/index.md b/docs/reference/index.md index d96dc2f..a15640b 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -27,12 +27,12 @@ For background and explanations, see [Concepts](../concepts/index.md). ## Datasources -- [NVD](datasources/nvd.md) -- - National Vulnerability Database mirroring and CPE matching -- [GitHub Advisories](datasources/github-advisories.md) -- - GHSA mirroring via GitHub's GraphQL API -- [OSV](datasources/osv.md) -- - Open Source Vulnerabilities mirroring, selectable by ecosystem +For background on what data sources contribute and how to enable them, see +[About vulnerability data sources](../concepts/about-vulnerability-data-sources.md) and +[Configuring vulnerability sources](../guides/administration/configuring-vulnerability-sources.md). + +- [Datasources overview](datasources/index.md) -- + mirrored sources (NVD, GitHub Advisories, OSV) and the other sources Dependency-Track integrates with - [Private Vulnerability Repository](datasources/private-vulnerability-repository.md) -- internally managed vulnerabilities for proprietary components - [Repositories](datasources/repositories.md) --