Dependency-Track supports badges in Scalable Vector Graphics (SVG) format. Support for badges is configurable on a team basis via permission or globally for unauthenticated access.
Deprecation Notice
Unauthenticated access to badges as a global configuration is deprecated and slated for removal in Dependency-Track v4.13.
To enable badges for a team, activate the permission VIEW_BADGES. To deactivate badges, remove the permission. To
retrieve a badge, use a team’s API key either in the badge API header X-API-Key or in the URI parameter apiKey.
As a legacy feature, badges can also be accessed without authentication. On new Dependency-Track installations, this is disabled by default. On Dependency-Track installations updated from ≤ v4.11, where (unauthenticated) badge support was enabled, badges will remain accessible for unauthenticated requests. If this is disabled, badges will be accessible for authenticated and authorized requests.
Enabling unauthenticated access to badges will provide vulnerability and policy violation metric information to unauthenticated users. Any anonymous user with network access to Dependency-Track and knowledge of a projects information will be able to view the SVG badge.
Dependency-Track ships with a default team “Badge Viewers” dedicated to badges that already has the necessary permission and an API key.
As badges are typically embedded in places that more people have access to than to Dependency-Track, the API key used for the badge request should have minimal scope to prevent unintended access beyond that badge. Ideally, the API key belongs to a single-purpose team, having just the
VIEW_BADGESpermission, with only one API key and access to only the projects/project versions whose badges are displayed at one site–the latter requiring Portfolio Access Control.
In all following examples, replace {name}, {version}, {uuid}, and {apiKey} with their respective values. For
brevity, the examples use the URI query parameter as the method of authentication, however, they also work with
authentication by header.
Vulnerable components #
Create a badge for vulnerable components of the project. It either shows:
- the severity of the vulnerabilities.
- “no vulns” if there are no vulnerabilities.
- “no metrics” if metrics for the project aren’t collect yet.
Suppressed vulnerabilities are not included in the count, so a project with only suppressed vulnerabilities will show a “no vulns” badge. SVG badges may be retrieved using either the UUID of the project, or the combination of a projects name and version.
Examples
https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey}
https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey}
Policy violations #
Create a badge for policy violations of the project. It either shows:
- the state of the violation.
- “no violations” if there are no violations.
- “no metrics” if metrics for the project aren’t collect yet.
Suppressed violations are not included in the count, so a project with only suppressed violations will show a “no violations” badge. SVG badges may be retrieved using either the UUID of the project, or the combination of a projects name and version.
Examples
https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey}
https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey}
Embedding #
You can embed the badges in other documents. It allows you to display a badge in your README for example.
HTML Examples
<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey}">
<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey}">
<img src="https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey}">
<img src="https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey}">
Markdown Examples
