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 Verification Summary Attestation page. To use Macaron to generate VSAs see this tutorial.

Use case 

Imagine you are a consumer of GDK artifacts and want to verify whether they are produced by a secure, 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 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.

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 

cat vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq

The output of the this command should look like below:

{
  "_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.

#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 mcn_provenance_expectation_1 check, which verifies the content of the provenance file matches a 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 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.

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

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 

curl -O https://raw.githubusercontent.com/oracle/macaron/main/scripts/release_scripts/check_vsa.sh

Make the script executable 

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:

./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:

PASSED

If there is an issue, the script will return an error code 1 and print an appropriate error message.