DependencyTrack · nscuro · Dec 10, 2024 · Dec 2, 2023 · Dec 2, 2023 · Dec 2, 2023
diff --git a/docs/_docs/usage/collection-projects.md b/docs/_docs/usage/collection-projects.md
@@ -0,0 +1,39 @@
+---
+title: Collection Projects
+category: Usage
+chapter: 2
+order: 8
+---
+
+Dependency-Track does support organizing projects in a tree structure 
+via parent-child relationships. This can be used to organize projects 
+for example by department or team, but also to structure a project itself 
+into different sub-projects and to organize their versions. 
+
+Since v4.13 it also supports configuring parents as "Collection Projects", 
+which allows to define that a parent itself does not host any components,
+but instead aggregates metrics of vulnerabilities and policy violations of
+its children with one of three possible calculation methods:
+* Aggregate all direct children
+* Aggregate all direct children which have a tag of your choice
+* Aggregate all direct children which are marked as latest version
+
+This allows a wide range use cases to be displayed. See following screenshot 
+which demonstrates a combination of all 3 possibilities within one product, 
+which consists of a Web Frontend (tracking DEV, QA, PROD environment), a Backend 
+with multiple MicroServices (tracked separated by DEV, QA, PROD environment), 
+and a mobile app (tracking each released version of the app).
+
+![collection project structure](/images/screenshots/collection-projects-structure.png)
+
+This is just one example how you could structure your projects and make use of 
+collection projects to better visualize the projects state without going down into 
+each single level. There are many other possibilities how you can organize the portfolio.
+
+Collection projects do not show the usual tabs for components, vulnerabilities etc.
+Instead they show a list of projects contained in this collection and their metrics:
+
+![collection projects details](/images/screenshots/collection-projects-details.png)
+
+Collection projects can be easily identified via the "culculator" icon, and hovering it
+displays the applied collection logic.
diff --git a/docs/images/screenshots/collection-projects-details.png b/docs/images/screenshots/collection-projects-details.png
diff --git a/docs/images/screenshots/collection-projects-structure.png b/docs/images/screenshots/collection-projects-structure.png
diff --git a/src/main/java/org/dependencytrack/model/Classifier.java b/src/main/java/org/dependencytrack/model/Classifier.java
@@ -25,6 +25,7 @@
  * @since 3.0.0
  */
 public enum Classifier {
+    NONE,
     APPLICATION,
     FRAMEWORK,
     LIBRARY,

diff --git a/src/main/java/org/dependencytrack/model/Project.java b/src/main/java/org/dependencytrack/model/Project.java
@@ -34,7 +34,6 @@
 import com.github.packageurl.MalformedPackageURLException;
 import com.github.packageurl.PackageURL;
 import io.swagger.v3.oas.annotations.media.Schema;
-
 import org.dependencytrack.parser.cyclonedx.util.ModelConverter;
 import org.dependencytrack.persistence.converter.OrganizationalContactsJsonConverter;
 import org.dependencytrack.persistence.converter.OrganizationalEntityJsonConverter;
@@ -104,11 +103,19 @@
         }),
         @FetchGroup(name = "METRICS_UPDATE", members = {
                 @Persistent(name = "id"),
+                @Persistent(name = "parent"),
+                @Persistent(name = "collectionLogic"),
+                @Persistent(name = "collectionTag"),
                 @Persistent(name = "lastInheritedRiskScore"),
                 @Persistent(name = "uuid")
         }),
         @FetchGroup(name = "PARENT", members = {
                 @Persistent(name = "parent")
+        }),
+        @FetchGroup(name = "PORTFOLIO_METRICS_UPDATE", members = {
+                @Persistent(name = "id"),
+                @Persistent(name = "lastInheritedRiskScore"),
+                @Persistent(name = "uuid")
         })
 })
 @JsonInclude(JsonInclude.Include.NON_NULL)
@@ -123,7 +130,8 @@ public enum FetchGroup {
         ALL,
         METADATA,
         METRICS_UPDATE,
-        PARENT
+        PARENT,
+        PORTFOLIO_METRICS_UPDATE
     }
 
     @PrimaryKey
@@ -189,6 +197,15 @@ public enum FetchGroup {
     @Extension(vendorName = "datanucleus", key = "enum-check-constraint", value = "true")
     private Classifier classifier;
 
+    @Persistent
+    @Column(name = "COLLECTION_LOGIC", jdbcType = "VARCHAR", allowsNull = "true")
+    @Extension(vendorName = "datanucleus", key = "enum-check-constraint", value = "true")
+    private ProjectCollectionLogic collectionLogic;
+
+    @Persistent(defaultFetchGroup = "true")
+    @Column(name = "COLLECTION_TAG", allowsNull = "true")
+    private Tag collectionTag;
+
     @Persistent
     @Index(name = "PROJECT_CPE_IDX")
     @Size(max = 255)
@@ -395,6 +412,26 @@ public void setClassifier(Classifier classifier) {
         this.classifier = classifier;
     }
 
+    public ProjectCollectionLogic getCollectionLogic() {
+        return collectionLogic == null
+                ? ProjectCollectionLogic.NONE
+                : collectionLogic;
+    }
+
+    public void setCollectionLogic(ProjectCollectionLogic collectionLogic) {
+        this.collectionLogic = collectionLogic != ProjectCollectionLogic.NONE
+                ? collectionLogic
+                : null;
+    }
+
+    public Tag getCollectionTag() {
+        return collectionTag;
+    }
+
+    public void setCollectionTag(Tag collectionTag) {
+        this.collectionTag = collectionTag;
+    }
+
     public String getCpe() {
         return cpe;
     }

diff --git a/src/main/java/org/dependencytrack/model/ProjectCollectionLogic.java b/src/main/java/org/dependencytrack/model/ProjectCollectionLogic.java
@@ -0,0 +1,48 @@
+/*
+ * This file is part of Dependency-Track.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) OWASP Foundation. All Rights Reserved.
+ */
+package org.dependencytrack.model;
+
+/**
+ * Defines various types of logics to be applied to collection projects.
+ * Collection projects don't contain own components, instead collect their metrics and
+ * data from their children. The logic to apply when calculating this data is defined
+ * by this type.
+ *
+ * @author Ralf King
+ * @since 4.13.0
+ */
+public enum ProjectCollectionLogic {
+    /**
+     * Project is not a collection project
+     */
+    NONE,
+    /**
+     * Aggregate data from all direct children. Respects collection logic of
+     * direct children collections.
+     */
+    AGGREGATE_DIRECT_CHILDREN,
+    /**
+     * Aggregate all direct children which have a specific tag
+     */
+    AGGREGATE_DIRECT_CHILDREN_WITH_TAG,
+    /**
+     * Aggregate all direct children marked with isLatest flag.
+     */
+    AGGREGATE_LATEST_VERSION_CHILDREN
+}
diff --git a/src/main/java/org/dependencytrack/model/ProjectMetrics.java b/src/main/java/org/dependencytrack/model/ProjectMetrics.java
@@ -171,6 +171,14 @@ public class ProjectMetrics implements Serializable {
     @Column(name = "POLICYVIOLATIONS_OPERATIONAL_UNAUDITED", allowsNull = "true") // New column, must allow nulls on existing data bases)
     private Integer policyViolationsOperationalUnaudited;
 
+    @Persistent
+    @Column(name = "COLLECTION_LOGIC", allowsNull = "true")
+    private ProjectCollectionLogic collectionLogic;
+
+    @Persistent
+    @Column(name = "COLLECTION_LOGIC_CHANGED", allowsNull = "false", defaultValue = "false")
+    private boolean collectionLogicChanged = false;
+
     @Persistent
     @Column(name = "FIRST_OCCURRENCE", allowsNull = "false")
     @NotNull
@@ -425,6 +433,26 @@ public void setPolicyViolationsOperationalUnaudited(int policyViolationsOperatio
         this.policyViolationsOperationalUnaudited = policyViolationsOperationalUnaudited;
     }
 
+    public ProjectCollectionLogic getCollectionLogic() {
+        return collectionLogic == null
+                ? ProjectCollectionLogic.NONE
+                : collectionLogic;
+    }
+
+    public void setCollectionLogic(ProjectCollectionLogic collectionLogic) {
+        this.collectionLogic = collectionLogic != ProjectCollectionLogic.NONE
+                ? collectionLogic
+                : null;
+    }
+
+    public boolean isCollectionLogicChanged() {
+        return collectionLogicChanged;
+    }
+
+    public void setCollectionLogicChanged(boolean collectionLogicChanged) {
+        this.collectionLogicChanged = collectionLogicChanged;
+    }
+
     public Date getFirstOccurrence() {
         return firstOccurrence;
     }

diff --git a/src/main/java/org/dependencytrack/persistence/ComponentQueryManager.java b/src/main/java/org/dependencytrack/persistence/ComponentQueryManager.java
@@ -835,6 +835,18 @@ public long deleteComponentPropertyByUuid(final Component component, final UUID
         }
     }
 
+    @Override
+    public boolean hasComponents(final Project project) {
+        final Query<Component> query = pm.newQuery(Component.class, "project == :project");
+        query.setParameters(project);
+        query.setResult("count(this)");
+        try {
+            return query.executeResultUnique(Long.class) > 0;
+        } finally {
+            query.closeAll();
+        }
+    }
+
     public void synchronizeComponentProperties(final Component component, final List<ComponentProperty> properties) {
         assertPersistent(component, "component must be persistent");