Merge pull request #4059 from SaberStrat/feature/3596-enhance-badges-…

…to-require-api-authorization

Enhance badge API to require authorization

docs/_docs/integrations/badges.md

@@ -5,14 +5,38 @@ 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 or globally for unauthenticated access.
 
-> 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.
+> **Deprecation Notice**
+> 
+> Unauthenticated access to badges as a global configuration is deprecated and slated for removal in Dependency-Track
+> v4.12.
 
-In all following examples, replace `{name}`, `{version}`, and `{uuid}` with their respective values.
+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_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 +57,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 +81,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 +91,17 @@ You can embed the badges in other documents. It allows you to display a badge in
 
 #### HTML Examples
 ```html
-<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}">
-<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}">
-<img src="https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}">
-<img src="https://dtrack.example.com/api/v1/badge/violations/project/{uuid}">
+<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
 ```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})
 ```
 

src/main/java/org/dependencytrack/auth/Permissions.java

@@ -38,7 +38,8 @@ public enum Permissions {
     SYSTEM_CONFIGURATION("Allows the configuration of the system including notifications, repositories, and email settings"),
     PROJECT_CREATION_UPLOAD("Provides the ability to optionally create project (if non-existent) on BOM or scan upload"),
     POLICY_MANAGEMENT("Allows the creation, modification, and deletion of policy"),
-    TAG_MANAGEMENT("Allows the modification and deletion of tags");
+    TAG_MANAGEMENT("Allows the modification and deletion of tags"),
+    VIEW_BADGES("Provides the ability to view badges");
 
     private final String description;
 
@@ -64,6 +65,7 @@ public static class Constants {
         public static final String PROJECT_CREATION_UPLOAD = "PROJECT_CREATION_UPLOAD";
         public static final String POLICY_MANAGEMENT = "POLICY_MANAGEMENT";
         public static final String TAG_MANAGEMENT = "TAG_MANAGEMENT";
+        public static final String VIEW_BADGES = "VIEW_BADGES";
     }
 
 }

src/main/java/org/dependencytrack/model/ConfigPropertyConstants.java

@@ -27,7 +27,7 @@
 public enum ConfigPropertyConstants {
 
     GENERAL_BASE_URL("general", "base.url", null, PropertyType.URL, "URL used to construct links back to Dependency-Track from external systems"),
-    GENERAL_BADGE_ENABLED("general", "badge.enabled", "false", PropertyType.BOOLEAN, "Flag to enable/disable SVG badge support from metrics"),
+    GENERAL_BADGE_ENABLED("general", "badge.enabled", "false", PropertyType.BOOLEAN, "Flag to enable/disable unauthenticated access to SVG badge from metrics"),
     EMAIL_SMTP_ENABLED("email", "smtp.enabled", "false", PropertyType.BOOLEAN, "Flag to enable/disable SMTP"),
     EMAIL_SMTP_FROM_ADDR("email", "smtp.from.address", null, PropertyType.STRING, "The from email address to use to send output SMTP mail"),
     EMAIL_PREFIX("email", "subject.prefix", "[Dependency-Track]", PropertyType.STRING, "The Prefix Subject email to use"),

src/main/java/org/dependencytrack/persistence/DefaultObjectGenerator.java

@@ -151,17 +151,21 @@ private void loadDefaultPersonas() {
             final Team managers = qm.createTeam("Portfolio Managers", false);
             LOGGER.debug("Creating team: Automation");
             final Team automation = qm.createTeam("Automation", true);
+            LOGGER.debug("Creating team: Badge Viewers");
+            final Team badges = qm.createTeam("Badge Viewers", true);
 
             final List<Permission> fullList = qm.getPermissions();
 
             LOGGER.debug("Assigning default permissions to teams");
             sysadmins.setPermissions(fullList);
             managers.setPermissions(getPortfolioManagersPermissions(fullList));
             automation.setPermissions(getAutomationPermissions(fullList));
+            badges.setPermissions(getBadgesPermissions(fullList));
 
             qm.persist(sysadmins);
             qm.persist(managers);
             qm.persist(automation);
+            qm.persist(badges);
 
             LOGGER.debug("Adding admin user to System Administrators");
             qm.addUserToTeam(admin, sysadmins);
@@ -194,6 +198,16 @@ private List<Permission> getAutomationPermissions(final List<Permission> fullLis
         return permissions;
     }
 
+    private List<Permission> getBadgesPermissions(final List<Permission> fullList) {
+        final List<Permission> permissions = new ArrayList<>();
+        for (final Permission permission : fullList) {
+            if (permission.getName().equals(Permissions.Constants.VIEW_BADGES)) {
+                permissions.add(permission);
+            }
+        }
+        return permissions;
+    }
+
     /**
      * Loads the default repositories
      */