[Feature] Vulnerability update notifications

docs/_docs/integrations/notifications.md

@@ -37,24 +37,25 @@ Notification levels behave identical to logging levels:
 Each scope contains a set of notification groups that can be subscribed to. Some groups contain notifications of
 multiple levels, while others can only ever have a single level.
 
-| Scope     | Group                     | Level(s)      | Description                                                                                                                       |
-|-----------|---------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| SYSTEM    | ANALYZER                  | (Any)         | Notifications generated as a result of interacting with an external source of vulnerability intelligence                          |
-| SYSTEM    | DATASOURCE_MIRRORING      | (Any)         | Notifications generated when performing mirroring of one of the supported datasources such as the NVD                             |
-| SYSTEM    | INDEXING_SERVICE          | (Any)         | Notifications generated as a result of performing maintenance on Dependency-Tracks internal index used for global searching       |
-| SYSTEM    | FILE_SYSTEM               | (Any)         | Notifications generated as a result of a file system operation. These are typically only generated on error conditions            |
-| SYSTEM    | REPOSITORY                | (Any)         | Notifications generated as a result of interacting with one of the supported repositories such as Maven Central, RubyGems, or NPM |
-| SYSTEM    | USER_CREATED                | INFORMATIONAL         | Notifications generated as a result of a user creation |
-| SYSTEM    | USER_DELETED                | INFORMATIONAL         | Notifications generated as a result of a user deletion |
-| PORTFOLIO | NEW_VULNERABILITY         | INFORMATIONAL | Notifications generated whenever a new vulnerability is identified                                                                |
-| PORTFOLIO | NEW_VULNERABLE_DEPENDENCY | INFORMATIONAL | Notifications generated as a result of a vulnerable component becoming a dependency of a project                                  |
-| PORTFOLIO | GLOBAL_AUDIT_CHANGE       | INFORMATIONAL | Notifications generated whenever an analysis or suppression state has changed on a finding from a component (global)              |
-| PORTFOLIO | PROJECT_AUDIT_CHANGE      | INFORMATIONAL | Notifications generated whenever an analysis or suppression state has changed on a finding from a project                         |
-| PORTFOLIO | BOM_CONSUMED              | INFORMATIONAL | Notifications generated whenever a supported BOM is ingested and identified                                                       |
-| PORTFOLIO | BOM_PROCESSED             | INFORMATIONAL | Notifications generated after a supported BOM is ingested, identified, and successfully processed                                 |
-| PORTFOLIO | BOM_PROCESSING_FAILED     | ERROR         | Notifications generated whenever a BOM upload process fails                                                                       |
-| PORTFOLIO | BOM_VALIDATION_FAILED     | ERROR         | Notifications generated whenever an invalid BOM is uploaded                                                                       |
-| PORTFOLIO | POLICY_VIOLATION          | INFORMATIONAL | Notifications generated whenever a policy violation is identified                                                                 |
+| Scope     | Group                         | Level(s)        | Description                                                                                                                                  |
+|-----------|-------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| SYSTEM    | ANALYZER                      | (Any)           | Notifications generated as a result of interacting with an external source of vulnerability intelligence                                     |
+| SYSTEM    | DATASOURCE_MIRRORING          | (Any)           | Notifications generated when performing mirroring of one of the supported datasources such as the NVD                                        |
+| SYSTEM    | INDEXING_SERVICE              | (Any)           | Notifications generated as a result of performing maintenance on Dependency-Tracks internal index used for global searching                  |
+| SYSTEM    | FILE_SYSTEM                   | (Any)           | Notifications generated as a result of a file system operation. These are typically only generated on error conditions                       |
+| SYSTEM    | REPOSITORY                    | (Any)           | Notifications generated as a result of interacting with one of the supported repositories such as Maven Central, RubyGems, or NPM            |
+| SYSTEM    | USER_CREATED                  | INFORMATIONAL   | Notifications generated as a result of a user creation                                                                                       |
+| SYSTEM    | USER_DELETED                  | INFORMATIONAL   | Notifications generated as a result of a user deletion                                                                                       |
+| PORTFOLIO | NEW_VULNERABILITY             | INFORMATIONAL   | Notifications generated whenever a new vulnerability is identified                                                                           |
+| PORTFOLIO | NEW_VULNERABLE_DEPENDENCY     | INFORMATIONAL   | Notifications generated as a result of a vulnerable component becoming a dependency of a project                                             |
+| PORTFOLIO | PROJECT_VULNERABILITY_UPDATED | INFORMATIONAL   | Notifications generated if a vulnerability associated with a project is updated after creation. Currently only triggers on severity updates. |
+| PORTFOLIO | GLOBAL_AUDIT_CHANGE           | INFORMATIONAL   | Notifications generated whenever an analysis or suppression state has changed on a finding from a component (global)                         |
+| PORTFOLIO | PROJECT_AUDIT_CHANGE          | INFORMATIONAL   | Notifications generated whenever an analysis or suppression state has changed on a finding from a project                                    |
+| PORTFOLIO | BOM_CONSUMED                  | INFORMATIONAL   | Notifications generated whenever a supported BOM is ingested and identified                                                                  |
+| PORTFOLIO | BOM_PROCESSED                 | INFORMATIONAL   | Notifications generated after a supported BOM is ingested, identified, and successfully processed                                            |
+| PORTFOLIO | BOM_PROCESSING_FAILED         | ERROR           | Notifications generated whenever a BOM upload process fails                                                                                  |
+| PORTFOLIO | BOM_VALIDATION_FAILED         | ERROR           | Notifications generated whenever an invalid BOM is uploaded                                                                                  |
+| PORTFOLIO | POLICY_VIOLATION              | INFORMATIONAL   | Notifications generated whenever a policy violation is identified                                                                            |
 
 ## Configuring Publishers
 
@@ -233,6 +234,55 @@ This type of notification will always contain:
 
 > The `cwe` field is deprecated and will be removed in a later version. Please use `cwes` instead.
 
+#### PROJECT_VULNERABILITY_UPDATED
+This type of notification will always contain:
+* 1 vulnerability update
+* 1 component
+
+To minimise noise, a notification will only be published if the vulnerability already affects an existing project. This can be scoped down further by limiting notifications to specific projects when configuring an alert rule.
+
+```json
+{
+  "notification": {
+    "level": "INFORMATIONAL",
+    "scope": "PORTFOLIO",
+    "group": "PROJECT_VULNERABILITY_UPDATED",
+    "timestamp": "2018-08-27T23:26:22.961",
+    "title": "Vulnerability Update",
+    "content": "The vulnerability CVE-2012-5784 on component axis has changed severity from LOW to MEDIUM",
+    "subject": {
+      "vulnerability": {
+        "uuid": "941a93f5-e06b-4304-84de-4d788eeb4969",
+        "vulnId": "CVE-2012-5784",
+        "source": "NVD",
+        "aliases": [
+          {
+            "vulnId": "GHSA-55w9-c3g2-4rrh",
+            "source": "GITHUB"
+          }
+        ],
+        "old": {
+          "severity": "LOW"
+        },
+        "new": {
+          "severity": "MEDIUM"
+        }
+      },
+      "component": {
+        "uuid": "4d5cd8df-cff7-4212-a038-91ae4ab79396",
+        "group": "apache",
+        "name": "axis",
+        "version": "1.4",
+        "md5": "03dcfdd88502505cc5a805a128bfdd8d",
+        "sha1": "94a9ce681a42d0352b3ad22659f67835e560d107",
+        "sha256": "05aebb421d0615875b4bf03497e041fe861bf0556c3045d8dda47e29241ffdd3",
+        "purl": "pkg:maven/apache/[email protected]"
+      }
+    }
+  }
+}
+```
+
 #### PROJECT_AUDIT_CHANGE and GLOBAL_AUDIT_CHANGE
 This type of notification will always contain:
 * 1 component

src/main/java/org/dependencytrack/event/EventSubsystemInitializer.java

@@ -46,6 +46,7 @@
 import org.dependencytrack.tasks.VexUploadProcessingTask;
 import org.dependencytrack.tasks.VulnDbSyncTask;
 import org.dependencytrack.tasks.VulnerabilityAnalysisTask;
+import org.dependencytrack.tasks.ProjectVulnerabilityUpdateTask;
 import org.dependencytrack.tasks.metrics.ComponentMetricsUpdateTask;
 import org.dependencytrack.tasks.metrics.PortfolioMetricsUpdateTask;
 import org.dependencytrack.tasks.metrics.ProjectMetricsUpdateTask;
@@ -118,6 +119,7 @@ public void contextInitialized(final ServletContextEvent event) {
         EVENT_SERVICE.subscribe(ClearComponentAnalysisCacheEvent.class, ClearComponentAnalysisCacheTask.class);
         EVENT_SERVICE.subscribe(CallbackEvent.class, CallbackTask.class);
         EVENT_SERVICE.subscribe(NewVulnerableDependencyAnalysisEvent.class, NewVulnerableDependencyAnalysisTask.class);
+        EVENT_SERVICE.subscribe(ProjectVulnerabilityUpdateEvent.class, ProjectVulnerabilityUpdateTask.class);
         EVENT_SERVICE.subscribe(NistMirrorEvent.class, NistMirrorTask.class);
         EVENT_SERVICE.subscribe(NistApiMirrorEvent.class, NistApiMirrorTask.class);
         EVENT_SERVICE.subscribe(EpssMirrorEvent.class, EpssMirrorTask.class);
@@ -160,6 +162,7 @@ public void contextDestroyed(final ServletContextEvent event) {
         EVENT_SERVICE.unsubscribe(InternalComponentIdentificationTask.class);
         EVENT_SERVICE.unsubscribe(CallbackTask.class);
         EVENT_SERVICE.unsubscribe(NewVulnerableDependencyAnalysisTask.class);
+        EVENT_SERVICE.unsubscribe(ProjectVulnerabilityUpdateTask.class);
         EVENT_SERVICE.unsubscribe(NistMirrorTask.class);
         EVENT_SERVICE.unsubscribe(NistApiMirrorTask.class);
         EVENT_SERVICE.unsubscribe(EpssMirrorTask.class);

src/main/java/org/dependencytrack/event/ProjectVulnerabilityUpdateEvent.java

@@ -0,0 +1,42 @@
+/*
+ * 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.event;
+
+import alpine.event.framework.SingletonCapableEvent;
+import org.dependencytrack.model.Vulnerability;
+import org.dependencytrack.model.VulnerabilityUpdateDiff;
+
+
+public class ProjectVulnerabilityUpdateEvent extends SingletonCapableEvent {
+    private final VulnerabilityUpdateDiff vulnerabilityUpdateDiff;
+    private final Vulnerability vulnerability;
+
+    public ProjectVulnerabilityUpdateEvent(Vulnerability vulnerability, VulnerabilityUpdateDiff vulnerabilityUpdateDiff) {
+        this.vulnerability = vulnerability;
+        this.vulnerabilityUpdateDiff = vulnerabilityUpdateDiff;
+    }
+
+    public Vulnerability getVulnerability() {
+        return vulnerability;
+    }
+
+    public VulnerabilityUpdateDiff getVulnerabilityUpdateDiff() {
+        return vulnerabilityUpdateDiff;
+    }
+}

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

@@ -0,0 +1,33 @@
+/*
+ * 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;
+
+public class VulnerabilityUpdateDiff {
+    private Severity oldSeverity;
+    private Severity newSeverity;
+
+    public VulnerabilityUpdateDiff(Severity oldSeverity, Severity newSeverity) {
+        this.oldSeverity = oldSeverity;
+        this.newSeverity = newSeverity;
+    }
+
+    public Severity getOldSeverity() { return  oldSeverity; }
+
+    public Severity getNewSeverity() { return  newSeverity; }
+}

src/main/java/org/dependencytrack/notification/NotificationConstants.java

@@ -41,6 +41,7 @@ public static class Title {
         public static final String INTEGRATION_ERROR = "Integration Error";
         public static final String NEW_VULNERABILITY = "New Vulnerability Identified";
         public static final String NEW_VULNERABLE_DEPENDENCY = "Vulnerable Dependency Introduced";
+        public static final String VULNERABILITY_UPDATED = "Vulnerability Updated";
         public static final String ANALYSIS_DECISION_EXPLOITABLE = "Analysis Decision: Exploitable";
         public static final String ANALYSIS_DECISION_IN_TRIAGE = "Analysis Decision: In Triage";
         public static final String ANALYSIS_DECISION_FALSE_POSITIVE = "Analysis Decision: False Positive";

src/main/java/org/dependencytrack/notification/NotificationGroup.java

@@ -32,6 +32,7 @@ public enum NotificationGroup {
     // Portfolio Groups
     NEW_VULNERABILITY,
     NEW_VULNERABLE_DEPENDENCY,
+    PROJECT_VULNERABILITY_UPDATED,
     //NEW_OUTDATED_COMPONENT,
     //FIXED_VULNERABILITY,
     //FIXED_OUTDATED,

src/main/java/org/dependencytrack/notification/NotificationRouter.java

@@ -26,6 +26,8 @@
 import org.dependencytrack.model.NotificationPublisher;
 import org.dependencytrack.model.NotificationRule;
 import org.dependencytrack.model.Project;
+import org.dependencytrack.model.Component;
+import org.dependencytrack.model.ComponentIdentity;
 import org.dependencytrack.notification.publisher.PublishContext;
 import org.dependencytrack.notification.publisher.Publisher;
 import org.dependencytrack.notification.publisher.SendMailPublisher;
@@ -38,6 +40,7 @@
 import org.dependencytrack.notification.vo.PolicyViolationIdentified;
 import org.dependencytrack.notification.vo.VexConsumedOrProcessed;
 import org.dependencytrack.notification.vo.ViolationAnalysisDecisionChange;
+import org.dependencytrack.notification.vo.ProjectVulnerabilityUpdate;
 import org.dependencytrack.persistence.QueryManager;
 
 import jakarta.json.Json;
@@ -178,6 +181,33 @@ List<NotificationRule> resolveRules(final PublishContext ctx, final Notification
                         }
                     }
                 }
+            } else if (NotificationScope.PORTFOLIO.name().equals(notification.getScope())
+                    && notification.getSubject() instanceof final ProjectVulnerabilityUpdate subject) {
+                for (final NotificationRule rule: result) {
+                    // As above, reduce the execution of the notification down to those projects that the rule matches.
+                    // As we only emit a single notification per vulnerability, we need to check if any affected component
+                    // matches the rule projects, not just the component included in the notification subject.
+                    if (rule.getNotifyOn().contains(NotificationGroup.valueOf(notification.getGroup()))) {
+                        if (subject.getComponent() != null) {
+                            final List<Component> components = qm.matchIdentity(new ComponentIdentity(subject.getComponent()));
+                            if (components != null && !components.isEmpty()) {
+                                if (rule.getProjects() != null && !rule.getProjects().isEmpty()) {
+                                    for (final Component component : components) {
+                                        if (component.getProject() != null) {
+                                            for (final Project project : rule.getProjects()) {
+                                                if (component.getProject().getUuid().equals(project.getUuid()) || (Boolean.TRUE.equals(rule.isNotifyChildren() && checkIfChildrenAreAffected(project, component.getProject().getUuid())))) {
+                                                    rules.add(rule);
+                                                }
+                                            }
+                                        }
+                                    }
+                                } else {
+                                    rules.add(rule);
+                                }
+                            }
+                        }
+                    }
+                }
             } else if (NotificationScope.PORTFOLIO.name().equals(notification.getScope())
                     && notification.getSubject() instanceof final NewVulnerableDependency subject) {
                 limitToProject(ctx, rules, result, notification, subject.getComponent().getProject());