feat: add a script to check VSA (#858)

This PR adds the check_vsa.sh script, which takes an artifact, VSA, and the package URL as the artifact identifier and reports whether the verification result has been successful.

This PR also adds a tutorial for the VSAs published for the Graal Development Kit (GDK) artifacts.

The integration test checks [email protected] with a manually generated VSA as well as [email protected] whose VSA is published on Oracle Maven.

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

Author: behnazh-w

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_witness_level_one_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/generate_verification_summary_attestation.rst

@@ -1,6 +1,8 @@
 .. Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved.
 .. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
+.. _gen-vsa_tutorial:
+
 =========================================
 Generate Verification Summary Attestation
 =========================================

docs/source/pages/tutorials/index.rst

@@ -22,4 +22,5 @@ For the full list of supported technologies, such as CI services, registries, an
    npm_provenance
    detect_malicious_java_dep
    generate_verification_summary_attestation
+   use_verification_summary_attestation
    exclude_include_checks

docs/source/pages/tutorials/use_verification_summary_attestation.rst

@@ -0,0 +1,210 @@
+.. Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved.
+.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+============================================
+How to use Verification Summary Attestations
+============================================
+
+This tutorial explains how to use the `Verification Summary Attestations (VSA) <https://slsa.dev/spec/v1.0/verification_summary>`_ generated by Macaron, using the VSAs for the `Graal Development Kit (GDK) <https://graal.cloud/gdk/>`_ artifacts as an example.
+
+For more information about VSAs, please refer to the :ref:`Verification Summary Attestation page<vsa>`. To use Macaron to generate VSAs see this :ref:`tutorial <gen-vsa_tutorial>`.
+
+.. contents:: :local:
+
+--------
+Use case
+--------
+
+Imagine you are a consumer of GDK artifacts and want to verify whether they are produced by a secure, :term:`SLSA`-compliant build service and sourced from a trusted source code repository. You need to confirm whether a provenance record for this artifact is published and has been verified. The GDK team must keep the details of their build pipeline confidential while still communicating that verification has occurred.
+
+A VSA allows you to assess the security properties of an artifact without needing direct access to the provenance details. This process involves delegating the policy decision to Macaron. Macaron receives the provenance of the build as input, analyzes various aspects of the build, and verifies the gathered data against a Datalog policy. It then generates a VSA that is published alongside the artifacts, attesting to the artifacts produced by the build.
+
+-------
+Example
+-------
+
+GDK is an Oracle build of the open source Micronaut® framework. GDK provides a curated set of Micronaut framework modules which are built from source and published on the `Oracle Maven repository <https://maven.oracle.com/public>`_. If a GDK artifact is verified by Macaron, you should be able to to find a corresponding VSA on Oracle Maven repository. Let's consider, the ``io.micronaut/[email protected]`` JAR artifact which is published at `<https://maven.oracle.com/public/io/micronaut/micronaut-core/4.6.5-oracle-00001/micronaut-core-4.6.5-oracle-00001.jar>`_. In order to verify the artifact with Macaron, you can follow the following steps:
+
+''''''''''''''''
+Download the VSA
+''''''''''''''''
+
+Check wether a VSA is published for the artifact and download it for further examination.
+
+.. code-block:: shell
+
+  curl -O https://maven.oracle.com/public/io/micronaut/micronaut-core/4.6.5-oracle-00001/vsa.intoto.jsonl
+
+''''''''''''''''''''''''''''''''''''
+Manual inspection of the VSA content
+''''''''''''''''''''''''''''''''''''
+
+.. code-block:: shell
+
+    cat vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq
+
+The output of the this command should look like below:
+
+.. toggle::
+
+    .. code-block:: json
+
+      {
+        "_type": "https://in-toto.io/Statement/v1",
+        "subject": [
+          {
+            "uri": "pkg:maven/io.micronaut/[email protected]?type=jar",
+            "digest": {
+              "sha256": "685644ae52ed580030550c7e4f441f39df2741c45095f1cf93583bddc413e6f8"
+            }
+          },
+          {
+            "uri": "pkg:maven/io.micronaut/[email protected]?type=pom",
+            "digest": {
+              "sha256": "64ba60107cdf5a93bec28b73f33585b93635f1fe6ae0707e6c8b42ed2d7d5198"
+            }
+          },
+          {
+            "uri": "pkg:maven/io.micronaut/[email protected]?type=java-source",
+            "digest": {
+              "sha256": "bcfcdb0213868100ca421f341411a5d5bc98ecb5cf44186804d27a4a34906818"
+            }
+          },
+          {
+            "uri": "pkg:maven/io.micronaut/[email protected]?type=javadoc",
+            "digest": {
+              "sha256": "33f720a21faad105f2566944a2e49b198eb310a1f9cfaa7742fdae8f46677e46"
+            }
+          }
+        ],
+        "predicateType": "https://slsa.dev/verification_summary/v1",
+        "predicate": {
+          "verifier": {
+            "id": "https://github.com/oracle/macaron",
+            "version": {
+              "macaron": "0.10.0"
+            }
+          },
+          "timeVerified": "2024-09-10T06:35:56.559568+00:00",
+          "resourceUri": "pkg:maven/io.micronaut/[email protected]",
+          "policy": {
+            "content": "#include \"prelude.dl\"\n\nPolicy(\"gdk_provenance_policy\", component_id, \"Policy for GDK builds\") :-\n    check_passed(component_id, \"mcn_provenance_expectation_1\").\n\napply_policy_to(\"gdk_provenance_policy\", component_id) :-\n    is_component(component_id, purl),\n    match(\"^pkg:maven/io.micronaut/micronaut-core@.*$\", purl)."
+          },
+          "verificationResult": "PASSED",
+          "verifiedLevels": []
+        }
+      }
+
+
+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::
+
+    .. code-block:: prolog
+
+        #include "prelude.dl"
+
+        Policy("gdk_provenance_policy", component_id, "Policy for GDK builds") :-
+            check_passed(component_id, "mcn_provenance_expectation_1")
+
+        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 a :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
+
+        {
+            target: "<EXPECTATION_PURL>",
+            predicate: {
+                attestations: [
+                    {
+                        attestation: {
+                            jobimage: "<IMAGE-NAME>",
+                            projecturl: "https://<REPO_URL>",
+                        },
+                    },
+                ]
+            }
+        }
+
+
+    * ``target: "<EXPECTATION_PURL>"``: This specifies the software component that is verified. ``<EXPECTATION_PURL>`` is a placeholder for the actual PURL (Package URL) of the target component, e.g., ``pkg:maven/io.micronaut/micronaut-core``.
+
+    * ``jobimage: "<IMAGE-NAME>"``: This condition checks that the ``jobimage`` attribute matches a specific pattern. ``<IMAGE-NAME>`` is a placeholder for the actual image name used at build time, e.g., ``container-registry.oracle.com/os/oraclelinux:9-slim``.
+
+    * ``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, e.g., ``internal.repo.com/micronaut-projects/micronaut-core``.
+
+    * The template CUE expectation can be downloaded from `this location <https://github.com/oracle/macaron/tree/main/src/macaron/resources/policies/gdk/expectation.cue.template>`_.
+
+
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+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
++++++++++++++
+
+Before running the script, ensure that the following tools are installed and available on your system’s PATH:
+
+* ``bash``: This script has been tested with ``bash 5.1.16(1)-release``.
+* ``curl``
+* ``jq``
+* ``shasum``
+* ``awk``
+
+++++++++++++++++++++++++++++++++
+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
+++++++++++++++++++++++++++
+
+.. code-block:: shell
+
+    chmod +x check_vsa.sh
+
++++++++++++++++++++++++++++++++++++++++++++++
+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:
+
+.. code-block:: shell
+
+    ./check_vsa.sh --artifact-path micronaut-core-4.6.5-oracle-00001.jar --vsa-path vsa.intoto.jsonl --purl "pkg:maven/io.micronaut/[email protected]?type=jar"
+
+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
++++++++++++++++++
+
+If the verification is successful, the script will print:
+
+.. code-block:: shell
+
+    PASSED
+
+If there is an issue, the script will return an error code ``1`` and print an appropriate error message.