Add project filters to component identity search (#6085)

hoobio · web-flow · commit 03bae1ed321d · 2026-05-04T13:09:15.000+02:00
* Add project filters to component identity search Adds onlyActive and onlyLatestVersion query parameters to GET /v1/component/identity, allowing portfolio-wide component searches to be scoped to active projects and/or projects flagged as the latest version. Reduces noise from archived projects and older project versions when triaging components across the portfolio. Closes #4570 Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Document component search project filters Adds a short note to the Impact Analysis page describing the "Only active projects" and "Only latest project versions" toggles on the Components search page, and the matching onlyActive and onlyLatestVersion query parameters on /api/v1/component/identity. Refs #4570 Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Tighten javadoc and parameter descriptions Trim wording in the new ComponentQueryManager overload, the new @parameter descriptions on /v1/component/identity, and the Impact Analysis doc paragraph added in the previous commit. Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Rename query params to disambiguate on /component endpoint Per PR review: onlyActive and onlyLatestVersion read as if they filter on component attributes when the endpoint is scoped to components. Rename to: - excludeInactiveProjects, mirroring the existing convention used by /v1/project, /v1/vulnerability, and others. - onlyLatestProjectVersion, mirroring the existing field on Policy and its use in PolicyEngine. Refs #4570 Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Update Impact Analysis doc to match toggle framing Reflect the renamed query parameters and the toggle relabel (Show inactive projects / Show all project versions, both on by default) in the doc paragraph added by the previous commit. Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Update Impact Analysis doc for renamed latest-version toggle Track the frontend label change from "Show all project versions" to "Show non-latest project versions". Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> * Pluralize onlyLatestProjectVersions query parameter Per PR review, the parameter takes effect across all matching projects (one latest per name, multiple in aggregate), so the plural form reads more accurately. Renames the corresponding internal Java identifiers, test methods, test query strings, and the Impact Analysis doc reference. Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com> --------- Signed-off-by: hoobio <7289249+hoobio@users.noreply.github.com>
diff --git a/docs/_docs/usage/impact-analysis.md b/docs/_docs/usage/impact-analysis.md
@@ -27,3 +27,10 @@ Alternatively, if the component name and version are known, then performing a se
 reveal a list of vulnerabilities, as well as a list of all projects that have a dependency on the component.
 
 ![incident response](/images/screenshots/vulnerable-component.png)
+
+Two toggles on the Components search page narrow results during incident response:
+
+- **Show inactive projects**: when off, hides components from inactive projects (usually archived). On by default.
+- **Only show latest project versions**: when on, hides components from project versions not flagged as the latest. Off by default.
+
+Combine with **Show inactive projects** (off) and **Only show latest project versions** (on) to scope to active, latest-version projects only. They map to the `excludeInactiveProjects` and `onlyLatestProjectVersions` query parameters on `GET /api/v1/component/identity`.
diff --git a/src/main/java/org/dependencytrack/persistence/ComponentQueryManager.java b/src/main/java/org/dependencytrack/persistence/ComponentQueryManager.java
@@ -251,6 +251,21 @@ public PaginatedResult getComponents(ComponentIdentity identity, boolean include
      * @return a list of components
      */
     public PaginatedResult getComponents(ComponentIdentity identity, Project project, boolean includeMetrics) {
+        return getComponents(identity, project, includeMetrics, false, false);
+    }
+
+    /**
+     * Returns components by their identity, optionally scoped to active projects, latest-version
+     * projects, or both.
+     * @param identity the ComponentIdentity to query against
+     * @param project the {@link Project} the {@link Component}s belong to
+     * @param includeMetrics whether to include component metrics
+     * @param excludeInactiveProjects when {@code true}, return only components from active projects
+     * @param onlyLatestProjectVersions when {@code true}, return only components from projects flagged as the latest version
+     * @return a list of components
+     */
+    public PaginatedResult getComponents(ComponentIdentity identity, Project project, boolean includeMetrics,
+                                         boolean excludeInactiveProjects, boolean onlyLatestProjectVersions) {
         if (identity == null) {
             return null;
         }
@@ -262,6 +277,12 @@ public PaginatedResult getComponents(ComponentIdentity identity, Project project
             queryFilterElements.add(" project == :project ");
             queryParams.put("project", project);
         }
+        if (excludeInactiveProjects) {
+            queryFilterElements.add(" project.active == true ");
+        }
+        if (onlyLatestProjectVersions) {
+            queryFilterElements.add(" project.isLatest == true ");
+        }
 
         final PaginatedResult result;
         if (identity.getGroup() != null || identity.getName() != null || identity.getVersion() != null) {
diff --git a/src/main/java/org/dependencytrack/persistence/QueryManager.java b/src/main/java/org/dependencytrack/persistence/QueryManager.java
@@ -567,6 +567,11 @@ public PaginatedResult getComponents(ComponentIdentity identity, Project project
         return getComponentQueryManager().getComponents(identity, project, includeMetrics);
     }
 
+    public PaginatedResult getComponents(ComponentIdentity identity, Project project, boolean includeMetrics,
+                                         boolean excludeInactiveProjects, boolean onlyLatestProjectVersions) {
+        return getComponentQueryManager().getComponents(identity, project, includeMetrics, excludeInactiveProjects, onlyLatestProjectVersions);
+    }
+
     public Component createComponent(Component component, boolean commitIndex) {
         return getComponentQueryManager().createComponent(component, commitIndex);
     }
diff --git a/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java b/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java
@@ -202,7 +202,11 @@ public Response getComponentByIdentity(@Parameter(description = "The group of th
                                            @Parameter(description = "The swidTagId of the component")
                                            @QueryParam("swidTagId") String swidTagId,
                                            @Parameter(description = "The project the component belongs to", schema = @Schema(type = "string", format = "uuid"))
-                                           @QueryParam("project") @ValidUuid String projectUuid) {
+                                           @QueryParam("project") @ValidUuid String projectUuid,
+                                           @Parameter(description = "When true, only return components from active projects")
+                                           @QueryParam("excludeInactiveProjects") boolean excludeInactiveProjects,
+                                           @Parameter(description = "When true, only return components from projects flagged as the latest version")
+                                           @QueryParam("onlyLatestProjectVersions") boolean onlyLatestProjectVersions) {
         try (QueryManager qm = new QueryManager(getAlpineRequest())) {
             Project project = null;
             if (projectUuid != null) {
@@ -229,7 +233,7 @@ public Response getComponentByIdentity(@Parameter(description = "The group of th
                     && identity.getPurl() == null && identity.getCpe() == null && identity.getSwidTagId() == null) {
                 return Response.ok().header(TOTAL_COUNT_HEADER, 0).build();
             } else {
-                final PaginatedResult result = qm.getComponents(identity, project, true);
+                final PaginatedResult result = qm.getComponents(identity, project, true, excludeInactiveProjects, onlyLatestProjectVersions);
                 return Response.ok(result.getObjects()).header(TOTAL_COUNT_HEADER, result.getTotal()).build();
             }
         }
diff --git a/src/test/java/org/dependencytrack/resources/v1/ComponentResourceTest.java b/src/test/java/org/dependencytrack/resources/v1/ComponentResourceTest.java
@@ -518,6 +518,118 @@ void getComponentByIdentityWithProjectWhenProjectDoesNotExistTest() {
         assertThat(getPlainTextBody(response)).contains("The project could not be found");
     }
 
+    @Test
+    void getComponentByIdentityExcludeInactiveProjectsTest() {
+        final Project activeProject = qm.createProject("activeProject", null, "1.0", null, null, null, true, false);
+        var activeComponent = new Component();
+        activeComponent.setProject(activeProject);
+        activeComponent.setGroup("acme");
+        activeComponent.setName("library");
+        activeComponent.setVersion("1.0");
+        activeComponent.setPurl("pkg:maven/acme/library@1.0");
+        activeComponent = qm.createComponent(activeComponent, false);
+
+        final Project inactiveProject = qm.createProject("inactiveProject", null, "1.0", null, null, null, false, false);
+        var inactiveComponent = new Component();
+        inactiveComponent.setProject(inactiveProject);
+        inactiveComponent.setGroup("acme");
+        inactiveComponent.setName("library");
+        inactiveComponent.setVersion("1.0");
+        inactiveComponent.setPurl("pkg:maven/acme/library@1.0");
+        qm.createComponent(inactiveComponent, false);
+
+        final Response response = jersey.target(V1_COMPONENT + "/identity")
+                .queryParam("name", "library")
+                .queryParam("excludeInactiveProjects", "true")
+                .request()
+                .header(X_API_KEY, apiKey)
+                .get(Response.class);
+        assertThat(response.getStatus()).isEqualTo(HttpStatus.SC_OK);
+        assertThat(response.getHeaderString(TOTAL_COUNT_HEADER)).isEqualTo("1");
+
+        final JsonArray json = parseJsonArray(response);
+        assertThat(json).hasSize(1);
+        assertThat(json.getJsonObject(0).getString("uuid")).isEqualTo(activeComponent.getUuid().toString());
+    }
+
+    @Test
+    void getComponentByIdentityOnlyLatestProjectVersionTest() {
+        final Project latestProject = qm.createProject("latestProject", null, "2.0", null, null, null, true, true, false);
+        var latestComponent = new Component();
+        latestComponent.setProject(latestProject);
+        latestComponent.setGroup("acme");
+        latestComponent.setName("library");
+        latestComponent.setVersion("1.0");
+        latestComponent.setPurl("pkg:maven/acme/library@1.0");
+        latestComponent = qm.createComponent(latestComponent, false);
+
+        final Project olderProject = qm.createProject("olderProject", null, "1.0", null, null, null, true, false);
+        var olderComponent = new Component();
+        olderComponent.setProject(olderProject);
+        olderComponent.setGroup("acme");
+        olderComponent.setName("library");
+        olderComponent.setVersion("1.0");
+        olderComponent.setPurl("pkg:maven/acme/library@1.0");
+        qm.createComponent(olderComponent, false);
+
+        final Response response = jersey.target(V1_COMPONENT + "/identity")
+                .queryParam("name", "library")
+                .queryParam("onlyLatestProjectVersions", "true")
+                .request()
+                .header(X_API_KEY, apiKey)
+                .get(Response.class);
+        assertThat(response.getStatus()).isEqualTo(HttpStatus.SC_OK);
+        assertThat(response.getHeaderString(TOTAL_COUNT_HEADER)).isEqualTo("1");
+
+        final JsonArray json = parseJsonArray(response);
+        assertThat(json).hasSize(1);
+        assertThat(json.getJsonObject(0).getString("uuid")).isEqualTo(latestComponent.getUuid().toString());
+    }
+
+    @Test
+    void getComponentByIdentityExcludeInactiveAndOnlyLatestProjectVersionTest() {
+        final Project activeLatest = qm.createProject("activeLatest", null, "2.0", null, null, null, true, true, false);
+        var activeLatestComponent = new Component();
+        activeLatestComponent.setProject(activeLatest);
+        activeLatestComponent.setGroup("acme");
+        activeLatestComponent.setName("library");
+        activeLatestComponent.setVersion("1.0");
+        activeLatestComponent.setPurl("pkg:maven/acme/library@1.0");
+        activeLatestComponent = qm.createComponent(activeLatestComponent, false);
+
+        final Project activeOlder = qm.createProject("activeOlder", null, "1.0", null, null, null, true, false);
+        var activeOlderComponent = new Component();
+        activeOlderComponent.setProject(activeOlder);
+        activeOlderComponent.setGroup("acme");
+        activeOlderComponent.setName("library");
+        activeOlderComponent.setVersion("1.0");
+        activeOlderComponent.setPurl("pkg:maven/acme/library@1.0");
+        qm.createComponent(activeOlderComponent, false);
+
+        final Project inactiveLatest = qm.createProject("inactiveLatest", null, "2.0", null, null, null, false, true, false);
+        var inactiveLatestComponent = new Component();
+        inactiveLatestComponent.setProject(inactiveLatest);
+        inactiveLatestComponent.setGroup("acme");
+        inactiveLatestComponent.setName("library");
+        inactiveLatestComponent.setVersion("1.0");
+        inactiveLatestComponent.setPurl("pkg:maven/acme/library@1.0");
+        qm.createComponent(inactiveLatestComponent, false);
+
+        final Response response = jersey.target(V1_COMPONENT + "/identity")
+                .queryParam("name", "library")
+                .queryParam("excludeInactiveProjects", "true")
+                .queryParam("onlyLatestProjectVersions", "true")
+                .request()
+                .header(X_API_KEY, apiKey)
+                .get(Response.class);
+        assertThat(response.getStatus()).isEqualTo(HttpStatus.SC_OK);
+        assertThat(response.getHeaderString(TOTAL_COUNT_HEADER)).isEqualTo("1");
+
+        final JsonArray json = parseJsonArray(response);
+        assertThat(json).hasSize(1);
+        assertThat(json.getJsonObject(0).getString("uuid")).isEqualTo(activeLatestComponent.getUuid().toString());
+    }
+
     @Test
     void getComponentByHashTest() {
         Project project = qm.createProject("Acme Application", null, null, null, null, null, true, false);

Original file line number	Diff line number	Diff line change
`@@ -567,6 +567,11 @@ public PaginatedResult getComponents(ComponentIdentity identity, Project project`
`567`	`567`	`return getComponentQueryManager().getComponents(identity, project, includeMetrics);`
`568`	`568`	`}`
`569`	`569`
	`570`	`+ public PaginatedResult getComponents(ComponentIdentity identity, Project project, boolean includeMetrics,`
	`571`	`+ boolean excludeInactiveProjects, boolean onlyLatestProjectVersions) {`
	`572`	`+ return getComponentQueryManager().getComponents(identity, project, includeMetrics, excludeInactiveProjects, onlyLatestProjectVersions);`
	`573`	`+ }`
	`574`	`+`
`570`	`575`	`public Component createComponent(Component component, boolean commitIndex) {`
`571`	`576`	`return getComponentQueryManager().createComponent(component, commitIndex);`
`572`	`577`	`}`