Add compliance support based on OpenSSF Scorecard score (#1800)

Signed-off-by: NucleonGodX <racerpro41@gmail.com>

Author: NucleonGodX

CHANGELOG.rst

@@ -3,6 +3,13 @@ Changelog
 
 v35.2.0 (2025-08-01)
 --------------------
+- Enhanced scorecard compliance support with:
+  * New ``scorecard_compliance_alert`` in project ``extra_data``.
+  * ``/api/projects/{id}/scorecard_compliance/`` API endpoint.
+  * Scorecard compliance integration in ``check-compliance`` management command.
+  * UI template support for scorecard compliance alert.
+  * ``evaluate_scorecard_compliance()`` pipe function for compliance evaluation.
+  https://github.com/aboutcode-org/scancode.io/pull/1800
 
 - Refactor policies implementation to support more than licenses.
   The entire ``policies`` data is now stored on the ``ScanPipeConfig`` in place of the

docs/policies.rst

@@ -91,6 +91,43 @@ Accepted values for the alert level:
 - ``warning``
 - ``error``
 
+Creating Scorecard Thresholds Files
+-----------------------------------
+
+A valid scorecard thresholds file is required to **enable OpenSSF Scorecard compliance features**.
+
+The scorecard thresholds file, by default named ``policies.yml``, is a **YAML file** with a
+structure similar to the following:
+
+.. code-block:: yaml
+
+    scorecard_score_thresholds:
+      9.0: ok
+      7.0: warning
+      0: error
+
+- In the example above, the keys ``9.0``, ``7.0``, and ``0`` are numeric threshold values
+  representing **minimum scorecard scores**.
+- The values ``error``, ``warning``, and ``ok`` are the **compliance alert levels** that
+  will be triggered if the project's scorecard score meets or exceeds the
+  corresponding threshold.
+- The thresholds must be listed in **strictly descending order**.
+
+How it works:
+
+- If the scorecard score is **9.0 or above**, the alert is **``ok``**.
+- If the scorecard score is **7.0 to 8.9**, the alert is **``warning``**.
+- If the scorecard score is **below 7.0**, the alert is **``error``**.
+
+You can adjust the threshold values and alert levels to match your organization's
+security compliance requirements.
+
+Accepted values for the alert level:
+
+- ``ok``
+- ``warning``
+- ``error``
+
 App Policies
 ------------
 

docs/rest-api.rst

@@ -518,6 +518,31 @@ Data:
         "license_clarity_compliance_alert": "warning"
     }
 
+.. _rest_api_scorecard_compliance:
+
+Scorecard Compliance
+^^^^^^^^^^^^^^^^^^^^
+
+This action returns the **scorecard compliance alert** for a project.
+
+The scorecard compliance alert is a single value (``ok``, ``warning``, or ``error``)
+that summarizes the project's **OpenSSF Scorecard security compliance status**,
+based on the thresholds defined in the ``policies.yml`` file.
+
+``GET /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/scorecard_compliance/``
+
+Data:
+    - ``scorecard_compliance_alert``: The overall scorecard compliance alert
+      for the project.
+
+      Possible values: ``ok``, ``warning``, ``error``.
+
+.. code-block:: json
+
+    {
+        "scorecard_compliance_alert": "warning"
+    }
+
 Reset
 ^^^^^
 

docs/tutorial_license_policies.rst

@@ -128,6 +128,51 @@ The ``license_clarity_compliance_alert`` value (e.g., ``"error"``, ``"warning"``
 is computed automatically based on the thresholds you configured and reflects the
 overall license clarity status of the scanned codebase.
 
+Scorecard Compliance Thresholds and Alerts
+------------------------------------------
+
+ScanCode.io also supports **OpenSSF Scorecard compliance thresholds**, allowing you to enforce
+minimum security standards for open source packages in your codebase. This is managed
+through the ``scorecard_score_thresholds`` section in your ``policies.yml`` file.
+
+Defining Scorecard Thresholds
+-----------------------------
+
+Add a ``scorecard_score_thresholds`` section to your ``policies.yml`` file, for example:
+
+.. code-block:: yaml
+
+    scorecard_score_thresholds:
+      9.0: ok
+      7.0: warning
+      0: error
+
+Scorecard Compliance in Results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you run a the addon pipeline fetch_scores with scorecard thresholds defined in your
+``policies.yml``, the computed scorecard compliance alert is included in the project's
+``extra_data`` field.
+
+For example:
+
+.. code-block:: json
+
+    "extra_data": {
+      "md5": "d23df4a4",
+      "sha1": "3e9b61cc98c",
+      "size": 3095,
+      "sha256": "abacfc8bcee59067",
+      "sha512": "208f6a83c83a4c770b3c0",
+      "filename": "cuckoo_filter-1.0.6.tar.gz",
+      "sha1_git": "3fdb0f82ad59",
+      "scorecard_compliance_alert": "warning"
+    }
+
+The ``scorecard_compliance_alert`` value (e.g., ``"error"``, ``"warning"``, or ``"ok"``)
+is computed automatically based on the thresholds you configured and reflects the
+overall security compliance status of the OpenSSF Scorecard scores for packages in the scanned codebase.
+
 Run the ``check-compliance`` command
 ------------------------------------
 

scanpipe/api/views.py

@@ -497,6 +497,22 @@ def license_clarity_compliance(self, request, *args, **kwargs):
         clarity_alert = project.get_license_clarity_compliance_alert()
         return Response({"license_clarity_compliance_alert": clarity_alert})
 
+    @action(detail=True, methods=["get"])
+    def scorecard_compliance(self, request, *args, **kwargs):
+        """
+        Retrieve the scorecard compliance alert for a project.
+
+        This endpoint returns the scorecard compliance alert stored in the
+        project's extra_data.
+
+        Example:
+        GET /api/projects/{project_id}/scorecard_compliance/
+
+        """
+        project = self.get_object()
+        scorecard_alert = project.get_scorecard_compliance_alert()
+        return Response({"scorecard_compliance_alert": scorecard_alert})
+
 
 class RunViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
     """Add actions to the Run viewset."""

scanpipe/management/commands/check-compliance.py

@@ -77,7 +77,12 @@ def check_compliance(self, fail_level):
         clarity_alert = self.project.get_license_clarity_compliance_alert()
         has_clarity_issue = clarity_alert not in (None, "ok")
 
-        total_issues = count + (1 if has_clarity_issue else 0)
+        scorecard_alert = self.project.get_scorecard_compliance_alert()
+        has_scorecard_issue = scorecard_alert not in (None, "ok")
+
+        total_issues = (
+            count + (1 if has_clarity_issue else 0) + (1 if has_scorecard_issue else 0)
+        )
 
         if total_issues and self.verbosity > 0:
             self.stderr.write(f"{total_issues} compliance issues detected.")
@@ -92,6 +97,10 @@ def check_compliance(self, fail_level):
                 self.stderr.write("[license clarity]")
                 self.stderr.write(f" > {clarity_alert.upper()}")
 
+            if has_scorecard_issue:
+                self.stderr.write("[scorecard compliance]")
+                self.stderr.write(f" > {scorecard_alert.upper()}")
+
         return total_issues > 0
 
     def check_vulnerabilities(self):

scanpipe/models.py

@@ -1553,6 +1553,13 @@ def get_license_clarity_compliance_alert(self):
         """
         return self.extra_data.get("license_clarity_compliance_alert")
 
+    def get_scorecard_compliance_alert(self):
+        """
+        Return the scorecard compliance alert value for the project,
+        or None if not set.
+        """
+        return self.extra_data.get("scorecard_compliance_alert")
+
     def get_license_policy_index(self):
         """Return the policy license index for this project instance."""
         if policies_dict := self.get_policies_dict():

scanpipe/pipelines/fetch_scores.py

@@ -25,6 +25,7 @@
 
 from scanpipe.models import DiscoveredPackageScore
 from scanpipe.pipelines import Pipeline
+from scanpipe.pipes import scorecard_compliance
 
 
 class FetchScores(Pipeline):
@@ -49,6 +50,7 @@ def steps(cls):
         return (
             cls.check_scorecode_service_availability,
             cls.fetch_packages_scorecode_info,
+            cls.evaluate_compliance_alerts,
         )
 
     def check_scorecode_service_availability(self):
@@ -64,3 +66,7 @@ def fetch_packages_scorecode_info(self):
                     scorecard_data=scorecard_data,
                     package=package,
                 )
+
+    def evaluate_compliance_alerts(self):
+        """Evaluate scorecard compliance alerts for the project."""
+        scorecard_compliance.evaluate_scorecard_compliance(self.project)

scanpipe/pipes/scorecard_compliance.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# http://nexb.com and https://github.com/aboutcode-org/scancode.io
+# The ScanCode.io software is licensed under the Apache License version 2.0.
+# Data generated with ScanCode.io is provided as-is without warranties.
+# ScanCode is a trademark of nexB Inc.
+#
+# You may not use this software except in compliance with the License.
+# You may obtain a copy of the License at: http://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.
+#
+# Data Generated with ScanCode.io is provided on an "AS IS" BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, either express or implied. No content created from
+# ScanCode.io should be considered or used as legal advice. Consult an Attorney
+# for any legal advice.
+#
+# ScanCode.io is a free software code scanning tool from nexB Inc. and others.
+# Visit https://github.com/aboutcode-org/scancode.io for support and download.
+
+from scanpipe.pipes.compliance_thresholds import get_project_scorecard_thresholds
+
+
+def evaluate_scorecard_compliance(project):
+    """
+    Evaluate scorecard compliance for all discovered packages in the project.
+
+    This function checks OpenSSF Scorecard scores against project-defined
+    thresholds and determines the worst compliance alert level across all packages.
+    Updates the project's extra_data with the overall compliance status.
+    """
+    scorecard_policy = get_project_scorecard_thresholds(project)
+    if not scorecard_policy:
+        return
+
+    worst_alert = None
+    packages_with_scores = project.discoveredpackages.filter(
+        scores__scoring_tool="ossf-scorecard"
+    ).distinct()
+
+    for package in packages_with_scores:
+        latest_score = (
+            package.scores.filter(scoring_tool="ossf-scorecard")
+            .order_by("-score_date")
+            .first()
+        )
+
+        if not latest_score or latest_score.score is None:
+            continue
+
+        try:
+            score = float(latest_score.score)
+            alert = scorecard_policy.get_alert_for_score(score)
+        except Exception:
+            alert = "error"
+
+        order = {"ok": 0, "warning": 1, "error": 2}
+        if worst_alert is None or order[alert] > order.get(worst_alert, -1):
+            worst_alert = alert
+
+    if worst_alert is not None:
+        project.update_extra_data({"scorecard_compliance_alert": worst_alert})

scanpipe/templates/scanpipe/panels/project_compliance.html

@@ -1,5 +1,5 @@
 {% load humanize %}
-{% if compliance_alerts or license_clarity_compliance_alert %}
+{% if compliance_alerts or license_clarity_compliance_alert or scorecard_compliance_alert %}
   <div class="column is-half">
     <nav id="compliance-panel" class="panel is-dark">
       <p class="panel-heading">
@@ -33,6 +33,20 @@
           </span>
         </div>
       {% endif %}
+      {% if scorecard_compliance_alert %}
+          <div class="panel-block">
+            <span class="pr-1">
+              Scorecard compliance
+            </span>
+            <span class="tag is-rounded ml-1
+              {% if scorecard_compliance_alert == 'error' %}is-danger
+              {% elif scorecard_compliance_alert == 'warning' %}is-warning
+              {% elif scorecard_compliance_alert == 'ok' %}is-success
+              {% else %}is-light{% endif %}">
+              {{ scorecard_compliance_alert|title }}
+            </span>
+          </div>
+        {% endif %}
     </nav>
   </div>
 {% endif %}