.. 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) `_ generated by Macaron, using the VSAs for the `Graal Development Kit (GDK) `_ artifacts as an example. For more information about VSAs, please refer to the :ref:`Verification Summary Attestation page`. To use Macaron to generate VSAs see this :ref:`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 `_. 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/micronaut-core@4.6.5-oracle-00001`` JAR artifact which is published at ``_. 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/micronaut-core@4.6.5-oracle-00001?type=jar", "digest": { "sha256": "685644ae52ed580030550c7e4f441f39df2741c45095f1cf93583bddc413e6f8" } }, { "uri": "pkg:maven/io.micronaut/micronaut-core@4.6.5-oracle-00001?type=pom", "digest": { "sha256": "64ba60107cdf5a93bec28b73f33585b93635f1fe6ae0707e6c8b42ed2d7d5198" } }, { "uri": "pkg:maven/io.micronaut/micronaut-core@4.6.5-oracle-00001?type=java-source", "digest": { "sha256": "bcfcdb0213868100ca421f341411a5d5bc98ecb5cf44186804d27a4a34906818" } }, { "uri": "pkg:maven/io.micronaut/micronaut-core@4.6.5-oracle-00001?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/micronaut-core@4.6.5-oracle-00001", "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 `_ 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 ` check, which verifies the content of the provenance file matches a :ref:`CUE expectation `. * 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 `_ Below you can find the template CUE file that has been used by the :ref:`mcn_provenance_expectation_1 ` 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: "", predicate: { attestations: [ { attestation: { jobimage: "", projecturl: "https://", }, }, ] } } * ``target: ""``: This specifies the software component that is verified. ```` is a placeholder for the actual PURL (Package URL) of the target component, e.g., ``pkg:maven/io.micronaut/micronaut-core``. * ``jobimage: ""``: This condition checks that the ``jobimage`` attribute matches a specific pattern. ```` is a placeholder for the actual image name used at build time, e.g., ``container-registry.oracle.com/os/oraclelinux:9-slim``. * ``projecturl: "https://"``: This checks that the ``projecturl`` attribute exactly matches the expected Repository 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 `_. ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 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 ``_. 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/micronaut-core@4.6.5-oracle-00001?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/micronaut-core@4.6.5-oracle-00001?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.