From 5d80c83595a8e2cfc1b4b44e76dfb4d5b67d9c4a Mon Sep 17 00:00:00 2001
From: Dave Pisek <dpisek@gitlab.com>
Date: Tue, 23 Sep 2025 08:05:17 +0200
Subject: [PATCH] Improve total-risk score tooltip copy

This change updates the risk score tooltip
(security dashboard panel) to show a
clearer explanation of how risk scores are
calculated.

Instead of displaying dynamic vulnerability score
factors, it now shows a static formula breakdown
with three numbered components:
how vulnerability scores are calculated,
age penalties, and diminishing factors.
---
 .../shared/group_risk_score_panel.vue         | 13 +--
 .../components/shared/risk_score_tooltip.vue  | 79 ++++++++++---------
 .../shared/group_risk_score_panel_spec.js     | 14 ----
 .../shared/risk_score_tooltip_spec.js         | 78 ++++++------------
 locale/gitlab.pot                             | 20 +++--
 5 files changed, 83 insertions(+), 121 deletions(-)

diff --git a/ee/app/assets/javascripts/security_dashboard/components/shared/group_risk_score_panel.vue b/ee/app/assets/javascripts/security_dashboard/components/shared/group_risk_score_panel.vue
index f516de6dec3b62..fa3f06cd0792d9 100644
--- a/ee/app/assets/javascripts/security_dashboard/components/shared/group_risk_score_panel.vue
+++ b/ee/app/assets/javascripts/security_dashboard/components/shared/group_risk_score_panel.vue
@@ -30,7 +30,6 @@ export default {
   data() {
     return {
       riskScore: 0,
-      vulnerabilitiesAverageScore: 0,
       projects: [],
       hasFetchError: false,
       groupedBy: 'default',
@@ -53,9 +52,7 @@ export default {
         return data?.group?.securityMetrics?.riskScore?.score || 0;
       },
       result({ data }) {
-        const { factors, byProject } = data?.group?.securityMetrics?.riskScore || {};
-
-        this.vulnerabilitiesAverageScore = factors?.vulnerabilitiesAverageScore?.factor || 0;
+        const { byProject } = data?.group?.securityMetrics?.riskScore || {};
 
         const projectNodes = [...(byProject?.nodes || [])];
         projectNodes.sort((a, b) => b.score - a.score);
@@ -92,13 +89,11 @@ export default {
     :border-color-class="hasFetchError ? 'gl-border-t-red-500' : ''"
     :title-icon="hasFetchError ? 'error' : ''"
     :title-icon-class="hasFetchError ? 'gl-text-red-500' : ''"
+    :title-popover-classes="['gl-min-w-fit']"
   >
-    <template #info-popover-title>{{ s__('SecurityReports|Risk score') }}</template>
+    <template #info-popover-title>{{ s__('SecurityReports|Risk score formula') }}</template>
     <template #info-popover-content>
-      <risk-score-tooltip
-        :vulnerabilities-average-score-factor="vulnerabilitiesAverageScore"
-        :is-loading="$apollo.queries.riskScore.loading"
-      />
+      <risk-score-tooltip />
     </template>
     <template #filters>
       <gl-badge
diff --git a/ee/app/assets/javascripts/security_dashboard/components/shared/risk_score_tooltip.vue b/ee/app/assets/javascripts/security_dashboard/components/shared/risk_score_tooltip.vue
index bb3d8fa12b3e2c..6408a82f4dce62 100644
--- a/ee/app/assets/javascripts/security_dashboard/components/shared/risk_score_tooltip.vue
+++ b/ee/app/assets/javascripts/security_dashboard/components/shared/risk_score_tooltip.vue
@@ -1,54 +1,57 @@
 <script>
-import { GlSkeletonLoader } from '@gitlab/ui';
+import { GlSprintf } from '@gitlab/ui';
 import { s__ } from '~/locale';
 
 export default {
   name: 'RiskScoreTooltip',
   components: {
-    GlSkeletonLoader,
+    GlSprintf,
   },
-  props: {
-    vulnerabilitiesAverageScoreFactor: {
-      type: Number,
-      required: false,
-      default: null,
-    },
-    isLoading: {
-      type: Boolean,
-      required: true,
-    },
-  },
-  computed: {
-    riskScoreFactors() {
-      return [
-        {
-          id: 'vulnerabilities-average-score',
-          label: s__('Security Reports|Vulnerabilities average score'),
-          value: this.vulnerabilitiesAverageScoreFactor,
-        },
-      ];
-    },
+  i18n: {
+    riskScoreFormulaDescription: s__(
+      'SecurityReports|(Sum of open vulnerability scores%{supStart}1%{supEnd} + Age penalty%{supStart}2%{supEnd}) * Diminishing factor%{supStart}3%{supEnd}',
+    ),
+    explanations: [
+      {
+        id: 'open-vulnerability-scores',
+        message: s__(
+          'SecurityReports|%{supStart}1%{supEnd}Base score (associated with severity level) + EPSS modifier + KEV modifier',
+        ),
+      },
+      {
+        id: 'age-penalty',
+        message: s__(
+          'SecurityReports|%{supStart}2%{supEnd}Sum of vulnerability ages in months * 0.005',
+        ),
+      },
+      {
+        id: 'diminishing-factor',
+        message: s__(
+          'SecurityReports|%{supStart}3%{supEnd}Diminishing factor = 1.0 / √(vulnerability count)',
+        ),
+      },
+    ],
   },
 };
 </script>
 
 <template>
   <div>
-    <dl v-for="factor in riskScoreFactors" :key="factor.label" class="gl-my-0 gl-flex gl-min-w-30">
-      <dt :data-testid="`${factor.id}-label`">{{ factor.label }}</dt>
-      <dd class="gl-my-0 gl-ml-auto">
-        <gl-skeleton-loader v-if="isLoading" :width="30" :lines="1" />
-        <span v-else :data-testid="`${factor.id}-value`">{{
-          sprintf(s__('SecurityReports|%{riskFactor}x'), { riskFactor: factor.value })
-        }}</span>
-      </dd>
-    </dl>
-    <p class="gl-my-0 gl-text-gray-500" data-testid="risk-score-description">
-      ({{
-        s__(
-          'SecurityReports|Includes Severity, Age, Exploitation status, EPSS score, Reachability, and/or Secret validity',
-        )
-      }})
+    <p>
+      <gl-sprintf :message="$options.i18n.riskScoreFormulaDescription">
+        <template #sup="{ content }">
+          <sup>{{ content }}</sup>
+        </template>
+      </gl-sprintf>
     </p>
+    <ol class="gl-list-none gl-p-0 gl-text-gray-600">
+      <li v-for="explanation in $options.i18n.explanations" :key="explanation.id">
+        <gl-sprintf :message="explanation.message">
+          <template #sup="{ content }">
+            <sup class="gl-mr-1">{{ content }}</sup>
+          </template>
+        </gl-sprintf>
+      </li>
+    </ol>
   </div>
 </template>
diff --git a/ee/spec/frontend/security_dashboard/components/shared/group_risk_score_panel_spec.js b/ee/spec/frontend/security_dashboard/components/shared/group_risk_score_panel_spec.js
index bede17043b503d..618d23fb89a492 100644
--- a/ee/spec/frontend/security_dashboard/components/shared/group_risk_score_panel_spec.js
+++ b/ee/spec/frontend/security_dashboard/components/shared/group_risk_score_panel_spec.js
@@ -130,20 +130,6 @@ describe('GroupRiskScorePanel', () => {
     it('renders the risk score tooltip', () => {
       expect(findRiskScoreTooltip().exists()).toBe(true);
     });
-
-    it('passes correct props to the risk score tooltip', async () => {
-      expect(findRiskScoreTooltip().props()).toMatchObject({
-        vulnerabilitiesAverageScoreFactor: 0,
-        isLoading: true,
-      });
-
-      await waitForPromises();
-
-      expect(findRiskScoreTooltip().props()).toMatchObject({
-        vulnerabilitiesAverageScoreFactor: defaultVulnerabilitiesAverageScore,
-        isLoading: false,
-      });
-    });
   });
 
   describe('group by functionality', () => {
diff --git a/ee/spec/frontend/security_dashboard/components/shared/risk_score_tooltip_spec.js b/ee/spec/frontend/security_dashboard/components/shared/risk_score_tooltip_spec.js
index 234ed50b693bb3..2ab89dabdae5b4 100644
--- a/ee/spec/frontend/security_dashboard/components/shared/risk_score_tooltip_spec.js
+++ b/ee/spec/frontend/security_dashboard/components/shared/risk_score_tooltip_spec.js
@@ -1,72 +1,44 @@
-import { GlSkeletonLoader } from '@gitlab/ui';
+import { GlSprintf } from '@gitlab/ui';
 import { shallowMountExtended } from 'helpers/vue_test_utils_helper';
 import RiskScoreTooltip from 'ee/security_dashboard/components/shared/risk_score_tooltip.vue';
 
 describe('RiskScoreTooltip', () => {
   let wrapper;
 
-  const defaultProps = {
-    isLoading: false,
-    vulnerabilitiesAverageScoreFactor: 2.5,
-  };
-
-  const createComponent = (props = {}) => {
+  const createComponent = () => {
     wrapper = shallowMountExtended(RiskScoreTooltip, {
-      propsData: {
-        ...defaultProps,
-        ...props,
+      stubs: {
+        GlSprintf,
       },
     });
   };
 
-  const findDescription = () => wrapper.findByTestId('risk-score-description');
-  const findLabelForId = (id) => wrapper.findByTestId(`${id}-label`);
-  const findValueForId = (id) => wrapper.findByTestId(`${id}-value`);
-  const findSkeletonLoader = () => wrapper.findComponent(GlSkeletonLoader);
-
-  describe('loaded state', () => {
-    beforeEach(createComponent);
-
-    it('renders the vulnerabilities average score label', () => {
-      expect(findLabelForId('vulnerabilities-average-score').text()).toBe(
-        'Vulnerabilities average score',
-      );
-    });
-
-    it('displays the formatted score value', () => {
-      expect(findValueForId('vulnerabilities-average-score').text()).toBe(
-        `${defaultProps.vulnerabilitiesAverageScoreFactor}x`,
-      );
-    });
+  const findFormulaDescription = () => wrapper.find('p');
+  const findExplanationItems = () => wrapper.findAll('ol li');
 
-    it('renders the description text', () => {
-      expect(findDescription().text()).toBe(
-        '(Includes Severity, Age, Exploitation status, EPSS score, Reachability, and/or Secret validity)',
-      );
-    });
+  beforeEach(createComponent);
 
-    it('does not show skeleton loader', () => {
-      expect(findSkeletonLoader().exists()).toBe(false);
-    });
+  it('renders the risk score formula description', () => {
+    expect(findFormulaDescription().text()).toMatchInterpolatedText(
+      '(Sum of open vulnerability scores%{supStart}1%{supEnd} + Age penalty%{supStart}2%{supEnd}) * Diminishing factor%{supStart}3%{supEnd}',
+    );
   });
 
-  describe('loading state', () => {
-    beforeEach(() => {
-      createComponent({ isLoading: true });
-    });
-
-    it('shows skeleton loader when loading', () => {
-      expect(findSkeletonLoader().exists()).toBe(true);
-    });
+  it('renders the open vulnerability scores explanation', () => {
+    expect(findExplanationItems().at(0).text()).toMatchInterpolatedText(
+      '%{supStart}1%{supEnd}Base score (associated with severity level) + EPSS modifier + KEV modifier',
+    );
+  });
 
-    it('still shows the label when loading', () => {
-      expect(findLabelForId('vulnerabilities-average-score').text()).toBe(
-        'Vulnerabilities average score',
-      );
-    });
+  it('renders the age penalty explanation', () => {
+    expect(findExplanationItems().at(1).text()).toMatchInterpolatedText(
+      '%{supStart}2%{supEnd}Sum of vulnerability ages in months * 0.005',
+    );
+  });
 
-    it('still shows the description when loading', () => {
-      expect(findDescription().exists()).toBe(true);
-    });
+  it('renders the diminishing factor explanation', () => {
+    expect(findExplanationItems().at(2).text()).toMatchInterpolatedText(
+      '%{supStart}3%{supEnd}Diminishing factor = 1.0 / √(vulnerability count)',
+    );
   });
 });
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index ac84afc016beb3..608f0586fc48d2 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -58243,9 +58243,6 @@ msgstr ""
 msgid "Security Policy project already exists."
 msgstr ""
 
-msgid "Security Reports|Vulnerabilities average score"
-msgstr ""
-
 msgid "Security and compliance"
 msgstr ""
 
@@ -60458,7 +60455,16 @@ msgstr ""
 msgid "SecurityReports|%{rating} risk score"
 msgstr ""
 
-msgid "SecurityReports|%{riskFactor}x"
+msgid "SecurityReports|%{supStart}1%{supEnd}Base score (associated with severity level) + EPSS modifier + KEV modifier"
+msgstr ""
+
+msgid "SecurityReports|%{supStart}2%{supEnd}Sum of vulnerability ages in months * 0.005"
+msgstr ""
+
+msgid "SecurityReports|%{supStart}3%{supEnd}Diminishing factor = 1.0 / √(vulnerability count)"
+msgstr ""
+
+msgid "SecurityReports|(Sum of open vulnerability scores%{supStart}1%{supEnd} + Age penalty%{supStart}2%{supEnd}) * Diminishing factor%{supStart}3%{supEnd}"
 msgstr ""
 
 msgid "SecurityReports|1 vulnerability attached to %{nrIssues} issues"
@@ -60734,9 +60740,6 @@ msgstr ""
 msgid "SecurityReports|Inactive secret"
 msgstr ""
 
-msgid "SecurityReports|Includes Severity, Age, Exploitation status, EPSS score, Reachability, and/or Secret validity"
-msgstr ""
-
 msgid "SecurityReports|Investigate this vulnerability by creating an issue"
 msgstr ""
 
@@ -60893,6 +60896,9 @@ msgstr ""
 msgid "SecurityReports|Risk score"
 msgstr ""
 
+msgid "SecurityReports|Risk score formula"
+msgstr ""
+
 msgid "SecurityReports|Scan details"
 msgstr ""
 
-- 
GitLab