Skip to content

Commit 3aee1b8

Browse files
nathanwnnathanwn
authored
chore: add tutorial for the VSA generation feature (#702)
Signed-off-by: Nathan Nguyen <[email protected]>
1 parent 763dfd4 commit 3aee1b8

File tree

4 files changed

+134
-6
lines changed

4 files changed

+134
-6
lines changed

‎docs/source/pages/tutorials/generate_verification_summary_attestation.rst

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved.
2+
.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
3+
4+
=========================================
5+
Generate Verification Summary Attestation
6+
=========================================
7+
8+
9+
This tutorial walks through how Macaron can be used to generate Verification Summary Attestation (VSA).
10+
11+
For more information about VSAs, please refer to the :ref:`Verification Summary Attestation page<vsa>`.
12+
13+
14+
* https://slsa.dev/spec/v1.0/verification_summary
15+
* https://security.googleblog.com/2022/04/how-to-slsa-part-1-basics.html
16+
17+
.. note::
18+
19+
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.
20+
21+
22+
--------
23+
Use case
24+
--------
25+
26+
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.
27+
28+
As you are the producer of the artifact, you also have access to the provenance attesting to the build.
29+
30+
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.
31+
32+
33+
-------
34+
Example
35+
-------
36+
37+
Let's say you are the author of the Maven artifact `<https://repo1.maven.org/maven2/io/micronaut/openapi/micronaut-openapi/6.8.0/micronaut-openapi-6.8.0-javadoc.jar>`_, which can be identified with the PackageURL ``pkg:maven/io.micronaut.openapi/[email protected]?type=jar``. You used `Witness <https://github.com/in-toto/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 <pages/using:Verifying provenance expectations in CUE language>`, specified in a ``expectation.cue`` file.
38+
39+
In order to verify the artifact with Macaron, you can follow the following steps:
40+
41+
- **Step 1**: Provide Macaron with the provenance file, the PackageURL identifying the artifact, and the CUE expectation file.
42+
43+
.. code-block:: shell
44+
45+
./run_macaron.sh analyze \
46+
--package-url pkg:maven/io.micronaut.openapi/[email protected]?type=jar \
47+
--provenance-file multiple.intoto.jsonl \
48+
--provenance-expectation expectation.cue \
49+
--skip-deps
50+
51+
.. note::
52+
53+
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.
54+
55+
56+
- **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``.
57+
58+
.. code-block:: c++
59+
60+
#include "prelude.dl"
61+
62+
Policy("producer-policy", component_id, "Poducer policy for micronaut-openapi.") :-
63+
check_passed(component_id, "mcn_version_control_system_1"),
64+
check_passed(component_id, "mcn_provenance_expectation_1").
65+
66+
apply_policy_to("has-hosted-build", component_id) :-
67+
is_component(component_id, "pkg:maven/io.micronaut.openapi/[email protected]?type=jar").
68+
69+
- **Step 3**: Verify the artifact against the policy file.
70+
71+
.. code-block:: shell
72+
73+
./run_macaron.sh verify-policy --file policy.dl
74+
75+
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:
76+
77+
.. code-block:: bash
78+
79+
cat output/vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq
80+
81+
82+
If you inspect the payload of this file, you can expect the content of the file to be as follows:
83+
84+
.. code-block:: json
85+
86+
{
87+
"_type": "https://in-toto.io/Statement/v1",
88+
"subject": [
89+
{
90+
"uri": "pkg:maven/io.micronaut.openapi/[email protected]?type=jar",
91+
"digest": {
92+
"sha256": "..." // The SHA256 digest of the file
93+
}
94+
},
95+
],
96+
"predicateType": "https://slsa.dev/verification_summary/v1",
97+
"predicate": {
98+
"verifier": {
99+
"id": "https://github.com/oracle/macaron",
100+
"version": {
101+
"macaron": "0.10.0"
102+
}
103+
},
104+
"timeVerified": "2024-04-12T07:37:29.364898+00:00",
105+
"resourceUri": "pkg:maven/io.micronaut.openapi/[email protected]",
106+
"policy": {
107+
"content": "...", // The policy in plain text
108+
},
109+
"verificationResult": "PASSED",
110+
"verifiedLevels": []
111+
}
112+
}
113+
114+
115+
.. _notes-on-using-the-feature:
116+
117+
--------------------------
118+
Notes on using the feature
119+
--------------------------
120+
121+
As of version ``v0.10.0`` of Macaron, the following are supported:
122+
123+
* Artifacts:
124+
125+
* Maven artifacts: there are 4 specific artifact types being supported: ``jar``, ``pom``, ``java-doc``, and ``java-source``. Please refer to the `Maven reference <https://maven.apache.org/ref/3.9.6/maven-core/artifact-handlers.html>`_ for more information.
126+
127+
* Provenances: Witness provenances.
128+
129+
Support for other artifact types and provenance types will be added in the later versions of Macaron.

‎docs/source/pages/tutorials/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ For the full list of supported technologies, such as CI services, registries, an
2020
detect_malicious_java_dep
2121
commit_finder
2222
exclude_include_checks
23+
generate_verification_summary_attestation

‎docs/source/pages/using.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ For more detailed information on converting a given artifact into a PURL, see `P
180180
Verifying provenance expectations in CUE language
181181
-------------------------------------------------
182182

183-
When a project generates SLSA provenances, you can add a build expectation in the form of a
183+
When a project generates provenances, you can add a build expectation in the form of a
184184
`Configure Unify Execute (CUE) <https://cuelang.org/>`_ policy to check the content of provenances. For instance, the expectation
185185
can specify the accepted GitHub Actions workflows that trigger a build, which can prevent using artifacts built from attackers
186186
workflows.

‎docs/source/pages/vsa.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
.. Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved.
22
.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
33
4+
.. _vsa:
5+
46
=================================
57
Verification Summary Attestations
68
=================================
79

8-
.. _vsa:
9-
1010
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".
1111

1212
The concept of VSA in Macaron largely follows the concept of VSA in `SLSA <https://slsa.dev/spec/v1.0/verification_summary>`_ and `in-toto <https://github.com/in-toto/attestation/blob/main/spec/predicates/vsa.md>`_.
@@ -73,9 +73,7 @@ The following is the schema of the Statement layer:
7373
Identifier for the schema of the Statement layer. This follows `in-toto v1 Statement layer schema <https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md>`_ and is always ``https://in-toto.io/Statement/v1``.
7474

7575
* ``subject``: array of `ResourceDescriptor`_ objects
76-
Subjects of the VSA. Each entry is a software component being verified by Macaron.
77-
78-
*Note: In the current version of Macaron, this field only contains one single software component, identified by a* `PackageURL`_.
76+
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.
7977

8078
* ``predicateType``: string (`TypeURI`_)
8179
Identifier for the type of the Predicate. For Macaron-generated VSAs, this is always ``https://slsa.dev/verification_summary/v1``.

0 commit comments

Comments
 (0)