chore: improve the check table and tutorial descriptions

Signed-off-by: behnazh-w <[email protected]>

docs/source/index.rst

@@ -50,43 +50,43 @@ the requirements that are currently supported by Macaron.
    :widths: 20 40 40
    :header-rows: 1
 
-   * - SLSA level
+   * - Check ID
      - SLSA requirement
      - Concrete check
-   * - 1
+   * - ``mcn_build_script_1``
      - **Scripted build** - All build steps were fully defined in a “build script”.
      - Identify and validate build script(s).
-   * - 1
+   * - ``mcn_provenance_available_1``
      - **Provenance available** - Provenances are available.
      - Check for existence of provenances, which can be :term:`SLSA` or :term:`Witness` provenances. If there is no provenance, the repo can still be compliant to level 1 given the build script is available.
-   * - 1
+   * - ``mcn_provenance_available_1``
      - **Witness provenance** - One or more :term:`Witness` provenances are discovered.
      - Check for existence of :term:`Witness` provenances, and whether artifact digests match those in the provenances.
-   * - 2
+   * - ``mcn_build_service_1``
      - **Build service** - All build steps are run using some build service (e.g. GitHub Actions)
      - Identify and validate the CI service(s) used for the build process.
-   * - 2+
+   * - ``mcn_provenance_verified_1``
      - **Provenance verified** - Provenance is available and verified.
      - See :doc:`SLSA Build Levels </pages/checks/slsa_builds>`
-   * - 3
+   * - ``mcn_trusted_builder_level_three_1``
      - **Trusted builders** - Guarantees the identification of the top-level build configuration used to initiate the build. The build is verified to be hermetic, isolated, parameterless, and executed in an ephemeral environment.
      - Identify and validate that the builder used in the CI pipeline is a trusted one.
-   * - 3
+   * - ``mcn_build_as_code_1``
      - **Build as code** - If a trusted builder is not present, this requirement determines that the build definition and configuration executed by the build service is verifiably derived from text file definitions stored in a version control system.
      - Identify and validate the CI service(s) used to build and deploy/publish an artifact.
-   * - 3
+   * - ``mcn_infer_artifact_pipeline_1``
      - **Infer artifact publish pipeline** - When a provenance is not available, checks whether a CI workflow run has automatically published the artifact.
      - Identify a workflow run that has triggered the deploy step determined by the ``Build as code`` check.
-   * - 3
+   * - ``mcn_provenance_level_three_1``
      - **Provenance Level three** - Check whether the target has SLSA provenance level 3.
      - Use the `slsa-verifier <https://github.com/slsa-framework/slsa-verifier>`_ to attest to the subjects in the SLSA provenance that accompanies an artifact.
-   * - 3
+   * - ``mcn_provenance_expectation_1``
      - **Provenance expectation** - Check if the provenance meets an expectation.
-     - The user can provide an expectation for the provenance as a CUE policy, which will be compared against the SLSA provenance.
-   * - 3
+     - The user can provide an expectation for the provenance as a CUE expectation file, which will be compared against the provenance.
+   * - ``mcn_provenance_derived_repo_1``
      - **Provenance derived repo** - Check if the analysis target's repository matches the repository in the provenance.
      - If there is no provenance, this check will fail.
-   * - 3
+   * - ``mcn_provenance_derived_commit_1``
      - **Provenance derived commit** - Check if the analysis target's commit matches the commit in the provenance.
      - If there is no commit, this check will fail.
 
@@ -98,9 +98,9 @@ Macaron checks that report integrity issues but do not map to SLSA requirements
    :widths: 20 40
    :header-rows: 1
 
-   * - Check name
+   * - Check ID
      - Description
-   * - Detect malicious metadata
+   * - ``mcn_detect_malicious_metadata_1``
      - This check analyzes the metadata of a package and reports malicious behavior. This check currently supports PyPI packages.
 
 ----------------------

docs/source/pages/tutorials/use_verification_summary_attestation.rst

@@ -96,7 +96,9 @@ The output of the this command should look like below:
       }
 
 
-The VSA adheres to the `schema <https://slsa.dev/spec/v1.0/verification_summary>`_ provided by SLSA. However, rather than specifying a URI for the policy, it includes the policy directly within the VSA under the ``predicate.policy.content`` field. Below is a pretty-printed format of the policy as it appears in the VSA.
+The VSA adheres to the `schema <https://slsa.dev/spec/v1.0/verification_summary>`_ provided by SLSA. However, rather than specifying a URI for the policy, it includes the policy directly within the VSA under the ``predicate.policy.content`` field. The VSA also includes the list of subjects and their corresponding checksums that have been verified, the version of Macaron used, the timestamp of the verification, and the result of the verification.
+
+Here is a pretty-printed version of the policy as it appears in the VSA, along with its description.
 
 .. toggle::
 
@@ -107,25 +109,54 @@ The VSA adheres to the `schema <https://slsa.dev/spec/v1.0/verification_summary>
         Policy("gdk_provenance_policy", component_id, "Policy for GDK builds") :-
             check_passed(component_id, "mcn_provenance_expectation_1")
 
-        apply_policy_to("has-hosted-build", component_id) :-
+        apply_policy_to("gdk_provenance_policy", component_id) :-
             is_component(component_id, purl),
             match("^pkg:maven/io.micronaut/micronaut-core@.*$", purl).
 
-This policy makes sure the :ref:`mcn_provenance_expectation_1 <checks>` check, which verifies the content of the provenance file matches :ref:`CUE expectation <pages/using:Verifying provenance expectations in CUE language>`. You can find the template policy files for GDK builds below:
+    This policy makes sure the :ref:`mcn_provenance_expectation_1 <checks>` check, which verifies the content of the provenance file matches :ref:`CUE expectation <pages/using:Verifying provenance expectations in CUE language>`.
+
+    * Policy prelude (``#include "prelude.dl"``): Copies all the pre-written rules and the generated fact import statements into the policy program. All user-written policy files must begin with ``#include "prelude.dl"``.
+
+    * Policy Validation (``Policy``): This rule ensures that the component satisfies the ``mcn_provenance_expectation_1`` check.
+
+    * Applying the Policy (``apply_policy_to``): To apply the ``gcn_provenance_policy``, Macaron first determines if the ``component_id`` is a valid component and if its ``PURL`` conforms to the pattern defined in the ``match`` predicate. If both conditions are met, the policy is applied.
+
+    * The template Datalog policy file can be downloaded from `here <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/policy.dl.template>`_
+
+    Below you can find the template CUE file that has been used by the :ref:`mcn_provenance_expectation_1 <checks>` check at verification time to verify the provenance. It contains place holders for expected values that are populated by the GDK maintainers.
+
+    .. code-block:: javascript
 
-* `Template CUE expectation <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/expectation.cue.template>`_
-* `Template Datalog policy file <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/policy.dl.template>`_
+        {
+            predicate: {
+                attestations: [
+                    {
+                        attestation: {
+                            jobimage: "<IMAGE-ADDRESS>",
+                            projecturl: "https://<REPO_URL>",
+                        },
+                    },
+                ]
+            }
+        }
+
+
+    * ``jobimage: "<IMAGE-ADDRESS>"``: This condition checks that the ``jobimage`` attribute matches a specific pattern. ``<IMAGE-ADDRESS>`` is a placeholder for the actual image name used at build time.
+
+    * ``projecturl: "https://<REPO_URL>"``: This checks that the ``projecturl`` attribute exactly matches the expected Repository URL. ``<REPO_URL>`` is a placeholder for the actual repository URL.
+
+    * The template CUE expectation can be downloaded in `this location <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/expectation.cue.template>`_.
 
-The VSA also includes the list of subjects and their corresponding checksums that have been verified, the version of Macaron used, the timestamp of the verification, and the result of the verification.
 
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 Automatically check the artifact checksum and verification result
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 To verify that the artifact checksum matches the subject listed in the VSA and that the verification process has passed, follow these steps:
 
-
-**Prerequisites**
++++++++++++++
+Prerequisites
++++++++++++++
 
 Before running the script, ensure that the following tools are installed and available on your system’s PATH:
 
@@ -135,19 +166,25 @@ Before running the script, ensure that the following tools are installed and ava
 * ``shasum``
 * ``awk``
 
-**Download the check_vsa.sh script:**
+++++++++++++++++++++++++++++++++
+Download the check_vsa.sh script
+++++++++++++++++++++++++++++++++
 
 .. code-block:: shell
 
     curl -O https://raw.githubusercontent.com/oracle/macaron/main/scripts/release_scripts/check_vsa.sh
 
-**Make the script executable:**
+++++++++++++++++++++++++++
+Make the script executable
+++++++++++++++++++++++++++
 
 .. code-block:: shell
 
     chmod +x check_vsa.sh
 
-**Run the script with the appropriate arguments:**
++++++++++++++++++++++++++++++++++++++++++++++
+Run the script with the appropriate arguments
++++++++++++++++++++++++++++++++++++++++++++++
 
 Following our example, let’s verify that the VSA has passed for the artifact available at `<https://maven.oracle.com/public/io/micronaut/micronaut-core/4.6.5-oracle-00001/micronaut-core-4.6.5-oracle-00001.jar>`_. You can either download the JAR from the repository or, if you have built the GDK project, obtain the artifact from your local Maven repository at ``~/.m2/repository/io/micronaut/micronaut-core/4.6.5-oracle-00001/micronaut-core-4.6.5-oracle-00001.jar``. Then, run the following command:
 
@@ -157,12 +194,14 @@ Following our example, let’s verify that the VSA has passed for the artifact a
 
 The artifact and VSA paths should be valid paths on your filesystem. Ensure you replace ``micronaut-core-4.6.5-oracle-00001.jar``, ``vsa.intoto.jsonl``, and ``pkg:maven/io.micronaut/[email protected]?type=jar`` with your actual file paths and package URL.
 
-**Verify the output:**
++++++++++++++++++
+Verify the output
++++++++++++++++++
 
 If the verification is successful, the script will print:
 
 .. code-block:: shell
 
-    passed
+    PASSED
 
 If there is an issue, the script will return an error code ``1`` and print an appropriate error message.

scripts/release_scripts/check_vsa.sh

@@ -136,7 +136,7 @@ fi
 
 # Check whether the verification has passed.
 if [ "$verify_result" = "PASSED" ]; then
-    echo "passed"
+    echo "PASSED"
 else
     echo "The verification has failed."
     exit 1

src/macaron/resources/policies/gdk/expectation.cue.template

@@ -4,7 +4,7 @@
         attestations: [
             {
                 attestation: {
-                    jobimage: =~"<IMAGE>:.*",
+                    jobimage: "<IMAGE-ADDRESS>",
                     projecturl: "https://<REPO_URL>",
                 },
             },