From 871b47b8cb073527be5a142cb959996f541685e2 Mon Sep 17 00:00:00 2001 From: "Kirill.Sybin" Date: Sun, 1 Sep 2024 19:01:00 +0200 Subject: [PATCH] Update documentation Signed-off-by: Kirill.Sybin --- docs/_docs/integrations/badges.md | 43 ++++++++++++++++++------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/_docs/integrations/badges.md b/docs/_docs/integrations/badges.md index 5f648cd7b3..c6422859dc 100644 --- a/docs/_docs/integrations/badges.md +++ b/docs/_docs/integrations/badges.md @@ -5,14 +5,21 @@ chapter: 6 order: 10 --- -Dependency-Track supports badges in Scalable Vector Graphics (SVG) format. Support for badges is a globally configurable -option and is disabled by default. +Dependency-Track supports badges in Scalable Vector Graphics (SVG) format. Support for badges is configurable on a team +basis via permission. -> Enabling badge support 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. +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`. -In all following examples, replace `{name}`, `{version}`, and `{uuid}` with their respective values. +> 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_BADGES` permission, 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: @@ -33,8 +40,8 @@ name and version. #### Examples ``` -https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version} -https://dtrack.example.com/api/v1/badge/vulns/project/{uuid} +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 @@ -57,8 +64,8 @@ projects name and version. #### Examples ``` -https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version} -https://dtrack.example.com/api/v1/badge/violations/project/{uuid} +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} ``` @@ -67,17 +74,17 @@ You can embed the badges in other documents. It allows you to display a badge in #### HTML Examples ```html - - - - + + + + ``` #### Markdown Examples ```markdown -![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}) -![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}) -![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}) -![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{uuid}) +![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey}) +![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey}) +![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey}) +![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey}) ```