docs: add tutorial for find source command (#920)

Signed-off-by: Ben Selwyn-Smith <[email protected]>

docs/source/pages/cli_usage/command_find-source.rst

@@ -0,0 +1,38 @@
+.. Copyright (c) 2023 - 2023, 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/.
+
+.. _find-source-command-cli:
+
+===========
+Find Source
+===========
+
+-----------
+Description
+-----------
+
+Find the source commit, and optionally source repository, of a target artifact.
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+    usage: ./run_macaron.sh find-source -purl PURL [-rp REPO_PATH]
+
+-------
+Options
+-------
+
+.. option:: -h, --help
+
+    Show this help message and exit
+
+.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
+
+    The PURL string used to uniquely identify the artifact.
+
+.. option:: -rp REPO_PATH, --repo-path REPO_PATH
+
+    The path to the repository.

docs/source/pages/developers_guide/apidoc/macaron.repo_finder.rst

@@ -65,6 +65,14 @@ macaron.repo\_finder.repo\_finder\_java module
    :undoc-members:
    :show-inheritance:
 
+macaron.repo\_finder.repo\_utils module
+---------------------------------------
+
+.. automodule:: macaron.repo_finder.repo_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 macaron.repo\_finder.repo\_validator module
 -------------------------------------------
 

docs/source/pages/developers_guide/apidoc/macaron.slsa_analyzer.checks.rst

@@ -41,6 +41,14 @@ macaron.slsa\_analyzer.checks.build\_service\_check module
    :undoc-members:
    :show-inheritance:
 
+macaron.slsa\_analyzer.checks.build\_tool\_check module
+-------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.checks.build_tool_check
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 macaron.slsa\_analyzer.checks.check\_result module
 --------------------------------------------------
 

docs/source/pages/tutorials/index.rst

@@ -24,3 +24,4 @@ For the full list of supported technologies, such as CI services, registries, an
    generate_verification_summary_attestation
    use_verification_summary_attestation
    exclude_include_checks
+   source_finder

docs/source/pages/tutorials/source_finder.rst

@@ -0,0 +1,80 @@
+.. 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/.
+
+-------------
+Source Finder
+-------------
+
+This tutorial demonstrates how Macaron can find the source commit of a given artifact, and optionally the source repository, while performing no analyses. This operation exists as a standalone feature, using the ``find-source`` command, for users that wish to utilise only these features of Macaron without spending time performing additional unnecessary steps.
+
+Unlike the integrated commit finder (demonstrated in another tutorial :doc:`here </pages/tutorials/source_finder>`), the ``find-source`` command does not require cloning the target repository, thereby saving time in many cases, and disk space in all cases. For those who still wish to clone the repository as part of the process, a configuration option exists and will be explained below.
+
+******************************
+Installation and Prerequisites
+******************************
+
+Skip this section if you already know how to install Macaron.
+
+.. toggle::
+
+    Please follow the instructions :ref:`here <installation-guide>`. In summary, you need:
+
+        * Docker
+        * the ``run_macaron.sh``  script to run the Macaron image.
+
+    .. note:: At the moment, Docker alternatives (e.g. podman) are not supported.
+
+
+    You also need to provide Macaron with a GitHub token through the ``GITHUB_TOKEN``  environment variable.
+
+    To obtain a GitHub Token:
+
+    * Go to ``GitHub settings`` → ``Developer Settings`` (at the bottom of the left side pane) → ``Personal Access Tokens`` → ``Fine-grained personal access tokens`` → ``Generate new token``. Give your token a name and an expiry period.
+    * Under ``"Repository access"``, choosing ``"Public Repositories (read-only)"`` should be good enough in most cases.
+
+    Now you should be good to run Macaron. For more details, see the documentation :ref:`here <prepare-github-token>`.
+
+*********
+Execution
+*********
+
+To use the ``find-source`` command and find the repository and commit for an artifact, Macaron can be run with the following command:
+
+.. code-block:: shell
+
+    ./run_macaron.sh find-source -purl pkg:npm/[email protected]
+
+The output of the command will be written to the command line, and to a report file in the JSON format. The report can be found within the ``output`` folder under the respective path of the artifact that was passed to the command.  (See :ref:`Output Files Guide <output_files_guide>`). In this case, Macaron created a report file: ``output/reports/npm/semver/semver.source.json``, which contains the repository and commit that was found.
+
+To open the report and view the contents, you can use the following:
+
+.. code-block:: shell
+
+  open output/reports/npm/semver/semver.source.json
+
+Inside you will find the ``repo`` and ``commit`` properties have been populated with ``https://github.com/npm/node-semver`` and ``eb1380b1ecd74f6572831294d55ef4537dfe1a2a`` respectively. As this is a GitHub repository, Macaron also creates a URL that leads directly to the reported commit, found under the ``url`` property.
+
+If the repository for an artifact is already known, the ``find-source`` command can be given it to save looking it up again. To do this, the command changes to:
+
+.. code-block:: shell
+
+    ./run_macaron.sh find-source -purl pkg:npm/[email protected] -rp https://github.com/npm/node-semver
+
+.. note:: If you are unfamiliar with PackageURLs (purl), see this link: `PURLs <https://github.com/package-url/purl-spec>`_.
+
+********************
+Execution with Clone
+********************
+
+For the case where cloning the repository is desirable, perhaps because further use of the contents are planned, Macaron requires this to be specified in a custom ``ini`` configuration file that is passed as input. See `How to change the default configuration </pages/using#change-config>`_ for more details. Within the configuration file the following option should be set:
+
+.. code-block:: ini
+
+    [repofinder]
+    find_source_should_clone = True
+
+Then Macaron can be run with:
+
+.. code-block:: shell
+
+      ./run_macaron.sh -dp <path-to-modified-default.ini> find-source -purl pkg:npm/[email protected]

tests/integration/cases/tutorial_source_finder/check_output.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# 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/.
+
+[[ "$(jq -r '.commit' output/reports/npm/semver/semver.source.json)" = "eb1380b1ecd74f6572831294d55ef4537dfe1a2a" ]] &&
+[[ "$(jq -r '.repo' output/reports/npm/semver/semver.source.json)" = "https://github.com/npm/node-semver" ]]

tests/integration/cases/tutorial_source_finder/test.yaml

@@ -0,0 +1,20 @@
+# 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/.
+
+description: |
+  Performing the examples provided within the related tutorial.
+
+tags:
+- tutorial
+
+steps:
+- name: Run macaron find source
+  kind: find-source
+  options:
+    command_args:
+    - -purl
+    - pkg:npm/[email protected]
+- name: Check the report contents
+  kind: shell
+  options:
+    cmd: ./check_output.sh