docs: add tutorial for finding malicious artifact uploads

docs/source/index.rst

@@ -40,6 +40,8 @@ To start with Macaron, see the :doc:`Installation </pages/installation>` and :do
 
 For all services and technologies that Macaron supports, see the :doc:`Supported Technologies </pages/supported_technologies/index>` page.
 
+.. _checks:
+
 -------------------------
 Current checks in Macaron
 -------------------------
@@ -106,7 +108,8 @@ intermediate representations as abstractions. Using such abstractions, Macaron i
 
    pages/installation
    pages/using
-   pages/output_files
    pages/cli_usage/index
+   pages/tutorials/index
+   pages/output_files
    pages/supported_technologies/index
    pages/developers_guide/index

docs/source/pages/tutorials/index.rst

@@ -0,0 +1,104 @@
+.. 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/.
+
+.. _tutorials:
+
+=========
+Tutorials
+=========
+
+On this page, you will find tutorials to get you started with Macaron. The tutorials show Macaron
+in action, analyzing a software component and its dependencies that are built using GitHub Actions
+or GitLab. Macaron supports artifacts published on GitHub release, `Maven Central <https://central.sonatype.com>`_,
+or privately hosted registries, such as `JFrog <https://jfrog.com/>`_.
+
+---------------------------------------------------------------------
+Detect a malicious Java dependency uploaded manually to Maven Central
+---------------------------------------------------------------------
+
+In this tutorial we show how Macaron can determine whether the dependencies of a Java project are built
+and published via transparent CI workflows or manually uploaded to Maven Central. When an artifact is
+manually uploaded, the artifact distributor can modify the artifact and potentially include malicious
+code without being detected.
+
+The example project we analyze in this tutorial is `example-maven-app <https://github.com/behnazh-w/example-maven-app>`_,
+which is hosted on GitHub. This example application uses Maven to build and manage dependencies, and has two
+dependencies:
+
+
+.. list-table::
+   :widths: 25 50
+   :header-rows: 1
+
+   * - Artifact name
+     - `Package URL (PURL) <https://github.com/package-url/purl-spec>`_
+   * - `guava <https://central.sonatype.com/artifact/com.google.guava/guava>`_
+     - ``pkg:maven/com.google.guava/[email protected]?type=jar``
+   * - `jackson-databind <https://central.sonatype.com/artifact/io.github.behnazh-w.demo/jackson-databind>`_
+     - ``pkg:maven/io.github.behnazh-w.demo/[email protected]?type=jar``
+
+While the ``guava`` dependency follows best practices to publish artifacts automatically with minimal human
+intervention, ``jackson-databind`` is a malicious dependency that pretends to provide data-binding functionalities
+like `the official jackson-databind <https://github.com/FasterXML/jackson-databind>`_ library (note that
+this artifact is created for demonstration purposes and is not actually malicious).
+
+Now let's see how Macaron can help us with evaluating the supply chain security posture of
+``example-maven-app`` and its dependencies.
+
+************
+Installation
+************
+
+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.
+
+*************
+Prerequisites
+*************
+
+You 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>`.
+
+
+***********************
+Run ``analyze`` command
+***********************
+
+First, we need to run the ``analyze`` command of Macaron to run a number of :ref:`checks <checks>` and collect evidence for  ``example-maven-app`` and its dependencies.
+
+.. code-block:: shell
+
+  ./run_macaron.sh analyze -rp https://github.com/behnazh-w/example-maven-app
+
+.. note:: By default, Macaron clones the repositories and creates output files under the ``output`` directory. To understand the structure of this directory please see :ref:`Output Files Guide <output_files_guide>`.
+
+After running the ``analyze`` command, we can view the data that Macaron has gathered about the ``example-maven-app`` repository in an HTML report.
+
+.. code-block:: shell
+
+  open output/reports/github_com/behnazh-w/example-maven-app/example-maven-app.html
+
+.. _fig_example-maven-app:
+
+.. figure:: ../../_static/images/tutorial_example_maven_app_report.png
+   :alt: HTML report for ``example-maven-app``
+   :align: center
+
+|
+| As you scroll down in the HTML report, you will see a section for the dependencies that were automatically identified:
+
+.. _fig_example-maven-app-deps:
+
+.. figure:: ../../_static/images/tutorial_example_maven_app_report_dependencies.png
+   :alt: HTML report for dependencies of ``example-maven-app``
+   :align: center