chore: add public documentation for VSA

Signed-off-by: Nathan Nguyen <nathan.nguyen@oracle.com>

docs/source/index.rst

@@ -112,5 +112,6 @@ intermediate representations as abstractions. Using such abstractions, Macaron i
    pages/cli_usage/index
    pages/tutorials/index
    pages/output_files
+   pages/vsa
    pages/supported_technologies/index
    pages/developers_guide/index

docs/source/pages/output_files.rst

@@ -9,9 +9,13 @@ Output Files Guide
 
 .. note:: Please see :ref:`pages/cli_usage/index:common options` for the instructions on how to set the output directory of Macaron.
 
--------------------
+--------------------------------
+Output files of macaron analyze
+--------------------------------
+
+^^^^^^^^^^^^^^^^^^^
 Top level structure
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 .. code-block::
 
@@ -25,9 +29,9 @@ Top level structure
         ├── macaron.db
         └── sbom_debug.json
 
--------
+^^^^^^^
 Reports
--------
+^^^^^^^
 
 The report files of Macaron (from using the :ref:`analyze command <analyze-command-cli>`) are generated into the ``reports`` directory.
 
@@ -102,9 +106,9 @@ For example, for `<https://github.com/micronaut-projects/micronaut-core>`_ the r
                     ├── dependency_2.json
                     └── ...
 
--------------------
+^^^^^^^^^^^^^^^^^^^
 Cloned repositories
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 The ``git_repos`` directory is used to clone repositories into during the analysis. Each remote repository is cloned to a unique path
 within ``git_repos`` following the same strategy as `Unique result path`_.
@@ -129,37 +133,64 @@ to the directory:
 
 .. note:: Please see :ref:`pages/using:analyzing a locally cloned repository` to know how to set the directory for analyzing local repositories.
 
+-------------------------------------
+Output files of macaron verify-policy
+-------------------------------------
+
+As part of the ``macaron verify-policy`` command, Macaron generates a :ref:`Verification Summary Attestation<vsa>` (VSA) with the following strategy:
+
+* If the Datalog policy applies to a unique software component identified by a unique PURL, a VSA is generated based on the latest analysis results for that specific software component in the Macaron database.
+* Otherwise, if the Datalog policy applies to multiple software components identified by multiple different PURLs, no VSA will be generated.
+
+The VSA file will be generated into ``output/vsa.intoto.jsonl`` by default.
+
+.. code-block::
+
+    output/
+    └── vsa.intoto.jsonl
+
+
+Users can manually inspect the VSA generated by Macaron with the following command:
+
+.. code-block:: bash
+
+    cat output/vsa.intoto.json | jq -r '.payload' | base64 -d
+
+
+For more details about the Macaron-generated VSAs, please refer to the :ref:`Verification Summary Attestation page<vsa>`.
+
+
 ------
 Others
 ------
 
-''''''''''
+^^^^^^^^^^
 macaron.db
-''''''''''
+^^^^^^^^^^
 
 The file is the SQLite database used by Macaron for storing analysis results.
 
-'''''''''
+^^^^^^^^^
 debug.log
-'''''''''
+^^^^^^^^^
 
 This file stores the log messages from the latest run of Macaron.
 
-'''''''''
+^^^^^^^^^
 build_log
-'''''''''
+^^^^^^^^^
 
 This is the directory for storing the log from running external components such as `CycloneDx SBOM Maven plugin <https://github.com/CycloneDX/cyclonedx-maven-plugin>`_, `CycloneDx SBOM Gradle plugin <https://github.com/CycloneDX/cyclonedx-gradle-plugin>`_ or the `slsa-verifier <https://github.com/slsa-framework/slsa-verifier>`_.
 
-'''''''''''''''
+^^^^^^^^^^^^^^^
 sbom_debug.json
-'''''''''''''''
+^^^^^^^^^^^^^^^
 
 This file contain the debug information for running the SBOM generator to obtain dependencies of a repository.
 
-'''''''''''''''
+^^^^^^^^^^^^^^^
 .m2 and .gradle
-'''''''''''''''
+^^^^^^^^^^^^^^^
 
 These two directories cache the content of ``~/.m2`` and ``~/.gradle`` in the Docker container between different runs (which are
 mainly updated by the CycloneDX SBOM plugins).

docs/source/pages/vsa.rst

@@ -0,0 +1,88 @@
+=================================
+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 <https://slsa.dev/spec/v1.0/verification_summary>`_ and `in-toto <https://github.com/in-toto/attestation/blob/main/spec/predicates/vsa.md>`_.
+
+
+---------
+Use cases
+---------
+
+The use cases of Macaron VSAs includes, but not limited to:
+
+- **Caching verification results**: It could be expensive or inconvenient to run a full Macaron verification in certain circumstances. A VSA helps with caching and reusing verification results.
+- **Enabling delegated verification**: This allows software consumers to make use of verification results from another party.
+
+
+------
+Schema
+------
+
+.. code-block:: js+jinja
+
+    {
+        "_type": "https://in-toto.io/Statement/v1",
+        "subject": [
+            {
+                "uri": {{ PackageURL of the software component being verified }},
+            }
+        ],
+        "predicateType": "https://slsa.dev/verification_summary/v1",
+        "predicate": {
+            "verifier": {
+                "id": "https://github.com/oracle/macaron",
+                "version": {
+                    "macaron": {{ Macaron version }}
+                }
+            },
+            "timeVerified": "2024-01-04T11:13:03.496399Z",
+            "resourceUri": {{ PackageURL of the software component being verified }},
+            "policy": {
+                "content": {{ Datalog policy applies to the software component being verified }}
+            },
+            "verificationResult": {{ Either "PASSED" or "FAILED" }},
+            "verifiedLevels": []
+        }
+    }
+
+
+-------
+Example
+-------
+
+The following is an example of Macaron VSA generated from verification on the `slsa-verifier <https://github.com/slsa-framework/slsa-verifier>`_ repository.
+
+
+.. code-block:: json
+
+    {
+        "_type": "https://in-toto.io/Statement/v1",
+        "subject": [
+            {
+                "uri": "pkg:github.com/slsa-framework/slsa-verifier@7e1e47d7d793930ab0082c15c2b971fdb53a3c95"
+            }
+        ],
+        "predicateType": "https://slsa.dev/verification_summary/v1",
+        "predicate": {
+            "verifier": {
+                "id": "https://github.com/oracle/macaron",
+                "version": {
+                    "macaron": "0.6.0"
+                }
+            },
+            "timeVerified": "2024-01-04T11:13:03.496399Z",
+            "resourceUri": "pkg:github.com/slsa-framework/slsa-verifier@7e1e47d7d793930ab0082c15c2b971fdb53a3c95",
+            "policy": {
+                "content": "#include \"prelude.dl\"\n\nPolicy(\"slsa_verifier_policy\", component_id, \"Policy for SLSA Verifier\") :-\n  check_passed(component_id, \"mcn_build_as_code_1\"),\n  check_passed(component_id, \"mcn_provenance_level_three_1\"),\n  check_passed(component_id, \"mcn_provenance_available_1\").\n\napply_policy_to(\"slsa_verifier_policy\", component_id) :-\n  is_repo(\n    _,  // repo_id\n    \"github.com/slsa-framework/slsa-verifier\",\n    component_id\n  ).\n"
+            },
+            "verificationResult": "PASSED",
+            "verifiedLevels": []
+        }
+    }
+
+For more details on using the Macaron VSA generation feature, please refer to the :ref:`Output File Guide <output_files_guide>`.