From 7a69d314e65e31a44397bf47e0478385e6e14c09 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Wed, 10 Jan 2024 13:34:57 +1000 Subject: [PATCH] chore(docs): add more detailed explanations for VSA fields and usage Signed-off-by: Nathan Nguyen --- docs/source/pages/output_files.rst | 2 +- docs/source/pages/vsa.rst | 88 +++++++++++++++++++++++++++++- 2 files changed, 86 insertions(+), 4 deletions(-) diff --git a/docs/source/pages/output_files.rst b/docs/source/pages/output_files.rst index daa507abe..77d156bf4 100644 --- a/docs/source/pages/output_files.rst +++ b/docs/source/pages/output_files.rst @@ -150,7 +150,7 @@ The VSA file will be generated into ``output/vsa.intoto.jsonl`` by default. └── vsa.intoto.jsonl -Users can manually inspect the VSA generated by Macaron with the following command: +Users can manually inspect the payload of the VSA generated by Macaron with the following command: .. code-block:: bash diff --git a/docs/source/pages/vsa.rst b/docs/source/pages/vsa.rst index ceebfc989..0c6b7a8f7 100644 --- a/docs/source/pages/vsa.rst +++ b/docs/source/pages/vsa.rst @@ -23,6 +23,20 @@ The use cases of Macaron VSAs includes, but not limited to: Schema ------ +.. Type references +.. _PackageURL: https://github.com/package-url/purl-spec +.. _Envelope: https://github.com/in-toto/attestation/blob/main/spec/v1/envelope.md +.. _TypeURI: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#TypeURI +.. _Timestamp: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#timestamp +.. _ResourceURI: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#ResourceURI +.. _ResourceDescriptor: https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md +.. _SlsaResult: https://slsa.dev/spec/v1.0/verification_summary#slsaresult + +Following in-toto attestation schema, the outermost layer if a Macaron-generated VSA is a `DSSE envelope `_ containing a base64-encoded ``payload`` of type `in-toto Statement `_. + +The following is the schema of the Statement layer: + + .. code-block:: js+jinja { @@ -40,7 +54,7 @@ Schema "macaron": {{ Macaron version }} } }, - "timeVerified": "2024-01-04T11:13:03.496399Z", + "timeVerified": {{ The timestamp of when the verification happened }}, "resourceUri": {{ PackageURL of the software component being verified }}, "policy": { "content": {{ Datalog policy applies to the software component being verified }} @@ -51,12 +65,56 @@ Schema } + +* ``_type``: string (`TypeURI`_) + 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`_.* + +* ``predicateType``: string (`TypeURI`_) + Identifier for the type of the Predicate. For Macaron-generated VSAs, this is always ``https://slsa.dev/verification_summary/v1``. + +* ``predicate``: object + The Predicate of the attestation, providing information about the verification. + +* ``predicate.verifier``: object + Information about the tool running the verification, which is Macaron. + +* ``predicate.verifier.id``: string (`TypeURI`_) + The identifier for Macaron. + +* ``predicate.timeVerified``: string (`Timestamp`_) + The timestamp of when the verification happened. + +* ``predicate.resourceUri``: string (`ResourceURI`_) + URI identifying the resource associated with the software component being verified. + + *Note: In the current version of Macaron, the value of this field is similar to the `PackageURL`_ identifying the only subject software component of the VSA.* + +* ``policy``: object + Details about the policy that the subject software component was verified against. + +* ``policy.content``: string + The Souffle datalog policy used for verification, in plain text. + +* ``verificationResult``: string, either ``"PASSED"`` or ``"FAILED"`` + The verification result. The result of ``"PASSED"`` means the subject software component conforms to the policy. + +* ``verificationResult``: array (`SlsaResult`_), required + Indicates the highest level of each SLSA track verified for the software component (and not its dependencies), or “FAILED” if policy verification failed. + + *Note: For the current version of Macaron, this is left empty.* + + ------- Example ------- -The following is an example of Macaron VSA generated from verification on the `slsa-verifier `_ repository. +The following is an example payload (Statement layer) of a Macaron VSA generated from verification on the `slsa-verifier `_ repository. .. code-block:: json @@ -85,4 +143,28 @@ The following is an example of Macaron VSA generated from verification on the `s } } -For more details on using the Macaron VSA generation feature, please refer to the :ref:`Output File Guide `. +This VSA communicates that the subject software component ``"pkg:github.com/slsa-framework/slsa-verifier@7e1e47d7d793930ab0082c15c2b971fdb53a3c95"`` passed the following policy in the ``policy.content`` field: + +.. code-block:: prolog + + #include "prelude.dl" + + Policy("slsa_verifier_policy", component_id, "Policy for SLSA Verifier") :- + check_passed(component_id, "mcn_build_as_code_1"), + check_passed(component_id, "mcn_provenance_level_three_1"), + check_passed(component_id, "mcn_provenance_available_1"). + + apply_policy_to("slsa_verifier_policy", component_id) :- + is_repo( + _, // repo_id + "github.com/slsa-framework/slsa-verifier", + component_id + ). + +This policy enforces the subject software component to pass 3 Macaron checks: + +* ``mcn_build_as_code_1`` +* ``mcn_provenance_level_three_1`` +* ``mcn_provenance_available_1`` + +For more details on using the Macaron VSA generation feature and inspecting the resulting VSA, please refer to the :ref:`Output File Guide `.