add documentation and changelog

Signed-off-by: NucleonGodX <[email protected]>

Author: NucleonGodX

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
 ------------------------------------