From 042d479f25dd32361be4694518de33abe5bb187e Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Fri, 12 Apr 2024 19:10:17 +1000 Subject: [PATCH 1/4] chore: add tutorial for VSA generation feature Signed-off-by: Nathan Nguyen --- ...erate_verification_summary_attestation.rst | 128 ++++++++++++++++++ docs/source/pages/tutorials/index.rst | 1 + docs/source/pages/vsa.rst | 8 +- 3 files changed, 132 insertions(+), 5 deletions(-) create mode 100644 docs/source/pages/tutorials/generate_verification_summary_attestation.rst diff --git a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst new file mode 100644 index 000000000..746ea74fe --- /dev/null +++ b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst @@ -0,0 +1,128 @@ +.. 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/. + +========================================= +Generate Verification Summary Attestation +========================================= + + +This tutorial walks through how Macaron can be used to generate Verification Summary Attestation (VSA). + +For more information about VSAs, please refer to the :ref:`Verification Summary Attestation page`. + + +* https://slsa.dev/spec/v1.0/verification_summary +* https://security.googleblog.com/2022/04/how-to-slsa-part-1-basics.html + +.. note:: + + At the moment, this feature only supports a limited number of artifact types and provenance types. Please refer to the :ref:`notes-on-using-the-feature` section for more information. + + +-------- +Use case +-------- + +Imagine you are the producer of an artifact. You want consumers of this artifact to be able to verify it. In order to simplify the verification process, you can use Macaron to verify the artifact prior to publishing it to consumers and generate a Verification Summary Attestation (VSA), thus allowing for delegated verification on consumers' side if they trust you as a verifier. + +As you are the producer of the artifact, you also have access to the provenance attesting to the build. + +As a tool, Macaron can support this particular use case quite well. Given a provenance of a build as input, Macaron can then analyze different aspects of the build, verify the data gathered against a Datalog policy, and generate VSA attesting to artifacts produced by the build. + + +------- +Example +------- + +Let's say you are the author of the Maven artifact ``_, which can be identified with the PackageURL ``pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar``. In addition, you also used `Witness `_ to generate a build provenance file ``multiple.intoto.jsonl``. + +In order to verify the artifact with Macaron, you can follow the following steps: + +- **Step 1**: Provide Macaron with the provenance file and the PackageURL identifying the artifact. + +.. code-block:: shell + + ./run_macaron.sh analyze \ + --package-url pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar \ + --provenance-file multiple.intoto.jsonl \ + --skip-deps + +.. note:: + + If your build produces more than one artifact, you can use the same command once for each artifact and substitute in the appropriate PURL for the respective artifact. + + +- **Step 2**: Compose a policy to verify the artifact against. The following is a sample policy enforcing the two checks ``mcn_version_control_system_1`` and ``mcn_provenance_available_1`` passing for the artifact. Let's put this policy in a file ``policy.dl``. + +.. code-block:: c++ + + #include "prelude.dl" + + Policy("producer-policy", component_id, "Poducer policy for micronaut-openapi.") :- + check_passed(component_id, "mcn_version_control_system_1"), + check_passed(component_id, "mcn_provenance_available_1"). + + apply_policy_to("has-hosted-build", component_id) :- + is_component(component_id, "pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar"). + +- **Step 3**: Verify the artifact against the policy file. + +.. code-block:: shell + + ./run_macaron.sh verify-policy --file policy.dl + +After step 3, if the artifact satisfies the policy, there will be a VSA file generated in the output directory at ``output/vsa.intoto.jsonl``. You can inspect the payload of this VSA using the following command: + +.. code-block:: bash + + cat output/vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq + + +If you inspect the payload of this file, you can expect the content of the file to be as follows: + +.. code-block:: json + + { + "_type": "https://in-toto.io/Statement/v1", + "subject": [ + { + "uri": "pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar", + "digest": { + "sha256": "..." // The SHA256 digest of the file + } + }, + ], + "predicateType": "https://slsa.dev/verification_summary/v1", + "predicate": { + "verifier": { + "id": "https://github.com/oracle/macaron", + "version": { + "macaron": "0.10.0" + } + }, + "timeVerified": "2024-04-12T07:37:29.364898+00:00", + "resourceUri": "pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0", + "policy": { + "content": "...", // The policy in plain text + }, + "verificationResult": "PASSED", + "verifiedLevels": [] + } + } + + +.. _notes-on-using-the-feature: + +-------------------------- +Notes on using the feature +-------------------------- + +As of version ``v0.10.0`` of Macaron, the following are supported: + +* Artifacts: + + * Maven artifacts: there are 4 specific artifact types being supported: ``jar``, ``pom``, ``java-doc``, and ``java-source``. Please refer to the `Maven reference `_ for more information. + +* Provenances: Witness provenances. + +Support for other artifact types and provenance types will be added in the later versions of Macaron. diff --git a/docs/source/pages/tutorials/index.rst b/docs/source/pages/tutorials/index.rst index 9b6ae5a59..c30c12269 100644 --- a/docs/source/pages/tutorials/index.rst +++ b/docs/source/pages/tutorials/index.rst @@ -20,3 +20,4 @@ For the full list of supported technologies, such as CI services, registries, an detect_malicious_java_dep commit_finder exclude_include_checks + generate_verification_summary_attestation diff --git a/docs/source/pages/vsa.rst b/docs/source/pages/vsa.rst index 1c5910b43..55d16f09b 100644 --- a/docs/source/pages/vsa.rst +++ b/docs/source/pages/vsa.rst @@ -1,12 +1,12 @@ .. 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/. +.. _vsa: + ================================= Verification Summary Attestations ================================= -.. _vsa: - Macaron generates Verification Summary Attestations (VSAs) as part of its verification to communicate the fact that "some software component has been verified against a policy". The concept of VSA in Macaron largely follows the concept of VSA in `SLSA `_ and `in-toto `_. @@ -73,9 +73,7 @@ The following is the schema of the Statement layer: Identifier for the schema of the Statement layer. This follows `in-toto v1 Statement layer schema `_ and is always ``https://in-toto.io/Statement/v1``. * ``subject``: array of `ResourceDescriptor`_ objects - Subjects of the VSA. Each entry is a software component being verified by Macaron. - - *Note: In the current version of Macaron, this field only contains one single software component, identified by a* `PackageURL`_. + Subjects of the VSA. Each entry is a software component being verified by Macaron. If the software component is also an artifact, a SHA256 digest is also recorded. * ``predicateType``: string (`TypeURI`_) Identifier for the type of the Predicate. For Macaron-generated VSAs, this is always ``https://slsa.dev/verification_summary/v1``. From eaa2486b3df5da754d4ad6375b951711f958854a Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Tue, 16 Apr 2024 11:54:07 +1000 Subject: [PATCH 2/4] chore: add comment about publishing the VSA Signed-off-by: Nathan Nguyen --- .../tutorials/generate_verification_summary_attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst index 746ea74fe..a3c06ecd1 100644 --- a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst +++ b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst @@ -23,7 +23,7 @@ For more information about VSAs, please refer to the :ref:`Verification Summary Use case -------- -Imagine you are the producer of an artifact. You want consumers of this artifact to be able to verify it. In order to simplify the verification process, you can use Macaron to verify the artifact prior to publishing it to consumers and generate a Verification Summary Attestation (VSA), thus allowing for delegated verification on consumers' side if they trust you as a verifier. +Imagine you are the producer of an artifact. You want consumers of this artifact to be able to verify it. In order to simplify the verification process, you can use Macaron to verify the artifact prior to publishing it to consumers and generate a Verification Summary Attestation (VSA), thus allowing for delegated verification on consumers' side if they trust you as a verifier. For easy access to the generated VSA on consumers' side, it can be published alongside the artifact, for example. As you are the producer of the artifact, you also have access to the provenance attesting to the build. From 916b9c1bfe0a5d51d197b28a348553e145f98f75 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Tue, 16 Apr 2024 12:34:06 +1000 Subject: [PATCH 3/4] chore: mention the provenance expectation check in the tutorial Signed-off-by: Nathan Nguyen --- .../generate_verification_summary_attestation.rst | 9 +++++---- docs/source/pages/using.rst | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst index a3c06ecd1..f83e56250 100644 --- a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst +++ b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst @@ -34,17 +34,18 @@ As a tool, Macaron can support this particular use case quite well. Given a prov Example ------- -Let's say you are the author of the Maven artifact ``_, which can be identified with the PackageURL ``pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar``. In addition, you also used `Witness `_ to generate a build provenance file ``multiple.intoto.jsonl``. +Let's say you are the author of the Maven artifact ``_, which can be identified with the PackageURL ``pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar``. You used `Witness `_ to generate a build provenance file ``multiple.intoto.jsonl``. In addition, for security purposes, you also want to enforce certain properties of the build based on the content of the provenance through :ref:`CUE expectation `, specified in a ``expectation.cue`` file. In order to verify the artifact with Macaron, you can follow the following steps: -- **Step 1**: Provide Macaron with the provenance file and the PackageURL identifying the artifact. +- **Step 1**: Provide Macaron with the provenance file, the PackageURL identifying the artifact, and the CUE expectation file. .. code-block:: shell ./run_macaron.sh analyze \ --package-url pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar \ --provenance-file multiple.intoto.jsonl \ + --provenance-expectation expectation.cue \ --skip-deps .. note:: @@ -52,7 +53,7 @@ In order to verify the artifact with Macaron, you can follow the following steps If your build produces more than one artifact, you can use the same command once for each artifact and substitute in the appropriate PURL for the respective artifact. -- **Step 2**: Compose a policy to verify the artifact against. The following is a sample policy enforcing the two checks ``mcn_version_control_system_1`` and ``mcn_provenance_available_1`` passing for the artifact. Let's put this policy in a file ``policy.dl``. +- **Step 2**: Compose a policy to verify the artifact against. The following is a sample policy enforcing the two checks ``mcn_version_control_system_1`` and ``mcn_provenance_expectation_1`` passing for the artifact. Let's put this policy in a file ``policy.dl``. .. code-block:: c++ @@ -60,7 +61,7 @@ In order to verify the artifact with Macaron, you can follow the following steps Policy("producer-policy", component_id, "Poducer policy for micronaut-openapi.") :- check_passed(component_id, "mcn_version_control_system_1"), - check_passed(component_id, "mcn_provenance_available_1"). + check_passed(component_id, "mcn_provenance_expectation_1"). apply_policy_to("has-hosted-build", component_id) :- is_component(component_id, "pkg:maven/io.micronaut.openapi/micronaut-openapi@6.8.0?type=jar"). diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 7dfab7b24..367b46f99 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -180,7 +180,7 @@ For more detailed information on converting a given artifact into a PURL, see `P Verifying provenance expectations in CUE language ------------------------------------------------- -When a project generates SLSA provenances, you can add a build expectation in the form of a +When a project generates provenances, you can add a build expectation in the form of a `Configure Unify Execute (CUE) `_ policy to check the content of provenances. For instance, the expectation can specify the accepted GitHub Actions workflows that trigger a build, which can prevent using artifacts built from attackers workflows. From 26690fc74a698205ad5ab425de941cbcbb0a4783 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Tue, 16 Apr 2024 15:34:55 +1000 Subject: [PATCH 4/4] chore: minor wording adjustment Signed-off-by: Nathan Nguyen --- .../tutorials/generate_verification_summary_attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst index f83e56250..7b4958681 100644 --- a/docs/source/pages/tutorials/generate_verification_summary_attestation.rst +++ b/docs/source/pages/tutorials/generate_verification_summary_attestation.rst @@ -16,7 +16,7 @@ For more information about VSAs, please refer to the :ref:`Verification Summary .. note:: - At the moment, this feature only supports a limited number of artifact types and provenance types. Please refer to the :ref:`notes-on-using-the-feature` section for more information. + At the moment, this feature only supports a limited number of artifact and provenance types. Please refer to the :ref:`notes-on-using-the-feature` section for more information. --------