feat(scorecard): Implement exclude metrics annotation

workspaces/scorecard/.changeset/full-streets-punch.md

@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-openssf': patch
+---
+
+rework openssf client

workspaces/scorecard/.changeset/polite-sheep-prove.md

@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-scorecard-backend': minor
+---
+
+added disable metric feature to the pull metric task

workspaces/scorecard/examples/openssf-scorecard-only.yaml

@@ -5,6 +5,7 @@ metadata:
   name: openssf-scorecard-only
   annotations:
     openssf/scorecard-location: https://api.securityscorecards.dev/projects/github.com/alizard0/rhdh-plugins
+    scorecard.io/disabled-metrics: openssf.maintained
 spec:
   type: service
   owner: group:development/guests

workspaces/scorecard/plugins/scorecard-backend-module-openssf/src/clients/OpenSSFClient.test.ts

@@ -49,6 +49,13 @@ const mockOpenSSFResponse: OpenSSFResponse = {
       details: null,
       documentation: { short: '', url: '' },
     },
+    {
+      name: 'Code-Review',
+      score: 9,
+      reason: null,
+      details: null,
+      documentation: { short: '', url: '' },
+    },
   ],
 };
 

workspaces/scorecard/plugins/scorecard-backend-module-openssf/src/clients/OpenSSFClient.ts

@@ -43,8 +43,6 @@ export class OpenSSFClient {
       );
     }
 
-    const data: OpenSSFResponse = await response.json();
-
-    return data;
+    return await response.json();
   }
 }

workspaces/scorecard/plugins/scorecard-backend/README.md

@@ -100,6 +100,10 @@ To use these providers, install the corresponding backend modules:
 - Jira: [`@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-jira`](../scorecard-backend-module-jira/README.md)
 - OpenSSF: [`@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-openssf`](../scorecard-backend-module-openssf/README.md)
 
+### Disabling Metrics
+
+Administrators can disable metric checks globally via app-config, and users can disable them for concrete entity via `scorecard.io/disabled-metrics` annotation. For more details, see [disabled-metrics-logic.md](./docs/disabled-metrics-logic.md).
+
 ## Thresholds
 
 Thresholds define conditions to assign metric values to specific visual categories (`success`, `warning`, `error` or any custom category). The Scorecard plugin provides multiple ways to configure thresholds:

workspaces/scorecard/plugins/scorecard-backend/config.d.ts

@@ -21,6 +21,18 @@ export interface Config {
   scorecard?: {
     /** Number of days to retain metric data in the database. Older data will be automatically cleaned up. Default: 365 days */
     dataRetentionDays?: number;
+    /** List of metric IDs (e.g. openssf.packaging) that are disabled globally. Entity annotations cannot override this. */
+    disabledMetrics?: string[];
+    /** Control whether users can override behavior via entity annotations. */
+    entityAnnotations?: {
+      /** Whether entity scorecard.io/disabled-metrics annotation can override. Only affects annotations; global disabledMetrics is unchanged. */
+      disabledMetrics?: {
+        /** If true (default), entities can disable metrics that are not mentioned in `except` list via `scorecard.io/disabled-metrics` annotation; if false, the annotation has no effect */
+        enabled?: boolean;
+        /** When enabled is true: entity annotations cannot disable metric IDs listed here (these checks always run). */
+        except?: string[];
+      };
+    };
     /** Configuration for scorecard metric providers */
     plugins?: {
       /** Configuration for datasource */

workspaces/scorecard/plugins/scorecard-backend/docs/disabled-metrics-logic.md

@@ -0,0 +1,25 @@
+# Disabled metrics: when a metric check is skipped (not executed)
+
+Administrators can disable metric checks globally via app-config, and users can disable them for concrete entity via `scorecard.io/disabled-metrics` annotation. Administrators control whether this annotation is honored in app-config via `scorecard.entityAnnotations.disabledMetrics.enabled` (and can force specific checks to always run via `scorecard.entityAnnotations.disabledMetrics.except`). When a metric check is skipped, no data is fetched and the metric is not calculated.
+**Evaluation order:** `scorecard.disabledMetrics` is checked first. If the metric ID is in that list, the metric check is always skipped and the rest is ignored. Otherwise, `entityAnnotations.disabledMetrics` in app-config and the entity annotations are applied.
+The following table describes the result for each combination of app-config and entity annotation.
+| `scorecard.disabledMetrics` includes `metricId` | `entityAnnotations.disabledMetrics.enabled` | `entityAnnotations.disabledMetrics.except` | `scorecard.io/disabled-metrics` entity annotation has `metricId`? | Metric check skipped for `metricId` (not run) |
+| ----------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------- |
+| Yes | — | — | — | **Yes** |
+| No | `false` | ignored | No | **No** |
+| No | `false` | ignored | Yes | **No** (annotation ignored, forced to run) |
+| No | `true` (or unset) | unset / empty / does not include `metricId` | No | **No** |
+| No | `true` (or unset) | unset / empty / does not include `metricId` | Yes | **Yes** |
+| No | `true` (or unset) | includes `metricId` | No | **No** |
+| No | `true` (or unset) | includes `metricId` | Yes | **No** (annotation ignored, forced to run) |
+
+## Summary
+
+- **`scorecard.disabledMetrics`**  
+  If the metric ID is in this list, the metric check is always skipped (not executed). Entity annotations cannot override.
+- **`entityAnnotations.disabledMetrics.enabled = false`**
+  Users cannot disable metrics by `scorecard.io/disabled-metrics` annotation.
+  The `except` list is not used.
+- **`entityAnnotations.disabledMetrics.enabled = true`**
+  Users can disable metrics by `scorecard.io/disabled-metrics` annotation. When the key is absent, behavior is the same as `true`.
+  The `except` list applies: metric IDs in `except` cannot have their checks skipped by annotation (they always run). Metrics not in `except` can have their checks skipped by the entity annotation.

workspaces/scorecard/plugins/scorecard-backend/src/scheduler/tasks/PullMetricsByProviderTask.test.ts

@@ -392,6 +392,36 @@ describe('PullMetricsByProviderTask', () => {
       );
     });
 
+    it('should skip entities when scorecard.io/disabled-metrics annotation contains the provider id', async () => {
+      const entityExcluded = {
+        apiVersion: '1.0.0',
+        kind: 'Component',
+        metadata: {
+          name: 'excluded-entity',
+          annotations: {
+            'scorecard.io/disabled-metrics': 'github.test_metric',
+          },
+        },
+      };
+
+      mockCatalog.queryEntities.mockReset().mockResolvedValueOnce({
+        items: [entityExcluded],
+        pageInfo: { nextCursor: undefined },
+        totalItems: 2,
+      });
+
+      const calculateMetricSpy = jest.spyOn(mockProvider, 'calculateMetric');
+      const createMetricValuesSpy = jest.spyOn(
+        mockDatabaseMetricValues,
+        'createMetricValues',
+      );
+      await (task as any).pullProviderMetrics(mockProvider, mockLogger);
+
+      expect(calculateMetricSpy).not.toHaveBeenCalled();
+      expect(createMetricValuesSpy).toHaveBeenCalledTimes(1);
+      expect(createMetricValuesSpy).toHaveBeenCalledWith([]);
+    });
+
     it('should throw error if pullProviderMetrics fails', async () => {
       (task as any).pullProviderMetrics = jest
         .fn()

workspaces/scorecard/plugins/scorecard-backend/src/scheduler/tasks/PullMetricsByProviderTask.ts

@@ -26,6 +26,7 @@ import type { Config } from '@backstage/config';
 import { CatalogService } from '@backstage/plugin-catalog-node';
 import { MetricProvider } from '@red-hat-developer-hub/backstage-plugin-scorecard-node';
 import { mergeEntityAndProviderThresholds } from '../../utils/mergeEntityAndProviderThresholds';
+import { isMetricIdDisabled } from '../../utils/metricUtils';
 import { normalizeOwnerRef } from '../../utils/normalizeOwnerRef';
 import { v4 as uuid } from 'uuid';
 import { stringifyEntityRef } from '@backstage/catalog-model';
@@ -143,6 +144,17 @@ export class PullMetricsByProviderTask implements SchedulerTask {
             let value: MetricValue | undefined;
 
             try {
+              if (
+                isMetricIdDisabled(
+                  this.config,
+                  provider.getProviderId(),
+                  entity,
+                  logger,
+                )
+              ) {
+                return undefined;
+              }
+
               value = await provider.calculateMetric(entity);
 
               const thresholds = mergeEntityAndProviderThresholds(
@@ -184,7 +196,7 @@ export class PullMetricsByProviderTask implements SchedulerTask {
           }),
         ).then(promises =>
           promises.reduce((acc, curr) => {
-            if (curr.status === 'fulfilled') {
+            if (curr.status === 'fulfilled' && curr.value !== undefined) {
               return [...acc, curr.value];
             }
             return acc;

workspaces/scorecard/plugins/scorecard-backend/src/utils/mergeEntityAndProviderThresholds.ts

@@ -32,7 +32,7 @@ const thresholdRulesAnnotationPrefix = (providerId: string) =>
 /**
  * Extract threshold override rules from entity annotations for a given provider, doesn't validate rules.
  */
-function parseEntityOverrideThresholds(
+function parseEntityAnnotationThresholds(
   entity: Entity,
   providerId: string,
 ): ThresholdRule[] {
@@ -57,13 +57,13 @@ export function mergeEntityAndProviderThresholds(
   const providerId = provider.getProviderId();
   const providerThresholds = provider.getMetricThresholds();
   const providerMetricType = provider.getMetricType();
-  const entityOverrideThresholds = parseEntityOverrideThresholds(
+  const entityAnnotationThresholds = parseEntityAnnotationThresholds(
     entity,
     providerId,
   );
 
   const mergedRules = [...providerThresholds.rules];
-  for (const override of entityOverrideThresholds) {
+  for (const override of entityAnnotationThresholds) {
     const foundKey = mergedRules.findIndex(rule => rule.key === override.key);
     if (foundKey === -1) {
       throw new ThresholdConfigFormatError(

workspaces/scorecard/plugins/scorecard-backend/src/utils/metricUtils.test.ts

@@ -0,0 +1,163 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * 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.
+ */
+
+import { mockServices } from '@backstage/backend-test-utils';
+import { MockEntityBuilder } from '../../__fixtures__/mockEntityBuilder';
+import { isMetricIdDisabled } from './metricUtils';
+
+describe('isMetricIdDisabled', () => {
+  const metricId = 'openssf.maintained';
+  let mockLogger: ReturnType<typeof mockServices.logger.mock>;
+
+  function createConfig(
+    scorecardOverrides: {
+      disabledMetrics?: string[];
+      entityAnnotations?: {
+        disabledMetrics?: { enabled?: boolean; except?: string[] };
+      };
+    } = {},
+  ) {
+    return mockServices.rootConfig({
+      data: {
+        scorecard: {
+          ...scorecardOverrides,
+        },
+      },
+    });
+  }
+
+  function createEntity(annotationValue?: string) {
+    return new MockEntityBuilder()
+      .withMetadata({
+        name: 'test-entity',
+        namespace: 'default',
+        ...(annotationValue !== undefined && {
+          annotations: {
+            'scorecard.io/disabled-metrics': annotationValue,
+          },
+        }),
+      })
+      .build();
+  }
+
+  beforeEach(() => {
+    mockLogger = mockServices.logger.mock();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('returns true when metric is in app-config disabledMetrics', () => {
+    const config = createConfig({ disabledMetrics: [metricId] });
+    const entity = createEntity();
+
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns true when disabled by annotation (no except list)', () => {
+    const config = createConfig();
+    const entity = createEntity(metricId);
+
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns false when not disabled by app-config or annotation', () => {
+    const config = createConfig();
+    const entity = createEntity();
+
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false when no config and no annotation', () => {
+    const config = createConfig();
+    const entity = createEntity();
+
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(false);
+  });
+
+  it('When entityOverride.disabledMetrics.enabled=false, users can NO override by annotations.', () => {
+    const config = createConfig({
+      entityAnnotations: {
+        disabledMetrics: {
+          enabled: false,
+          except: [metricId],
+        },
+      },
+    });
+
+    const entity = createEntity(metricId);
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns true, when entityOverride.disabledMetrics.enabled=true, users can override by annotations, and metric is not listed in exception list', () => {
+    const config = createConfig({
+      entityAnnotations: {
+        disabledMetrics: {
+          enabled: false,
+          except: ['other-metric-id'],
+        },
+      },
+    });
+
+    const entity = createEntity(metricId);
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false when disabled by annotation but metric is in entityAnnotations.disabledMetrics.except but entityAnnotations.disabledMetrics.enabled is true', () => {
+    const config = createConfig({
+      entityAnnotations: {
+        disabledMetrics: {
+          enabled: true,
+          except: [metricId],
+        },
+      },
+    });
+
+    const entity = createEntity(metricId);
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns true when disabled by annotation but metric is NOT in entityAnnotations.disabledMetrics.except but entityAnnotations.disabledMetrics.enabled is true', () => {
+    const config = createConfig({
+      entityAnnotations: {
+        disabledMetrics: {
+          enabled: true,
+          except: [],
+        },
+      },
+    });
+
+    const entity = createEntity(metricId);
+    const result = isMetricIdDisabled(config, metricId, entity, mockLogger);
+
+    expect(result).toBe(true);
+  });
+});