From 9b8a3d302f86fb42e56a27dcbd3110d1ccef4a8d Mon Sep 17 00:00:00 2001 From: Trong Nhan Mai Date: Thu, 1 Jun 2023 14:59:12 +1000 Subject: [PATCH 1/4] docs: update CLI Usage page in the Sphinx documentation Signed-off-by: Trong Nhan Mai --- docs/source/index.rst | 2 +- docs/source/pages/cli_options.rst | 10 --- .../source/pages/cli_usage/action_analyze.rst | 67 +++++++++++++++++ .../pages/cli_usage/action_dump_defaults.rst | 25 +++++++ .../pages/cli_usage/action_verify-policy.rst | 37 ++++++++++ docs/source/pages/cli_usage/index.rst | 72 +++++++++++++++++++ docs/source/pages/installation.rst | 10 ++- docs/source/pages/using.rst | 14 ++-- 8 files changed, 216 insertions(+), 21 deletions(-) delete mode 100644 docs/source/pages/cli_options.rst create mode 100644 docs/source/pages/cli_usage/action_analyze.rst create mode 100644 docs/source/pages/cli_usage/action_dump_defaults.rst create mode 100644 docs/source/pages/cli_usage/action_verify-policy.rst create mode 100644 docs/source/pages/cli_usage/index.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 4bdfa4387..30154c073 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,5 +10,5 @@ Macaron documentation pages/installation pages/using pages/output_files - pages/cli_options + pages/cli_usage/index pages/apidoc/index diff --git a/docs/source/pages/cli_options.rst b/docs/source/pages/cli_options.rst deleted file mode 100644 index 60b7e4ffe..000000000 --- a/docs/source/pages/cli_options.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. 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/. - -.. _cli-options: - -=========== -CLI Options -=========== - -TBD diff --git a/docs/source/pages/cli_usage/action_analyze.rst b/docs/source/pages/cli_usage/action_analyze.rst new file mode 100644 index 000000000..43384026f --- /dev/null +++ b/docs/source/pages/cli_usage/action_analyze.rst @@ -0,0 +1,67 @@ +======= +Analyze +======= + +----------- +Description +----------- + +Analyze a Github public repository (and potentially the repositories of it dependencies) to determine its SLSA posture following the specification of `SLSA v0.1 `_. + +----- +Usage +----- + +.. code-block:: shell + + usage: macaron analyze + [-h] [-sbom SBOM_PATH] [-rp REPO_PATH] [-b BRANCH] + [-d DIGEST] [-pe PROVENANCE_EXPECTATION] [-c CONFIG_PATH] + [--skip-deps] [-g TEMPLATE_PATH] + +------- +Options +------- + +.. option:: -h, --help + + Show this help message and exit + +.. option:: -sbom SBOM_PATH, --sbom-path SBOM_PATH + + The path to the SBOM of the analysis target. + +.. option:: -rp REPO_PATH, --repo-path REPO_PATH + + The path to the repository, can be local or remote + + +.. option:: -b BRANCH, --branch BRANCH + + The branch of the repository that we want to checkout. If not set, Macaron will use the default branch + +.. option:: -d DIGEST, --digest DIGEST + + The digest of the commit we want to checkout in the branch. If not set, Macaron will use the latest commit + +.. option:: -pe PROVENANCE_EXPECTATION, --provenance-expectation PROVENANCE_EXPECTATION + + The path to provenance expectation file or directory. + +.. option:: -c CONFIG_PATH, --config-path CONFIG_PATH + + The path to the user configuration. + +.. option:: --skip-deps + + Skip automatic dependency analysis. + +.. option:: -g TEMPLATE_PATH, --template-path TEMPLATE_PATH + + The path to the Jinja2 html template (please make sure to use .html or .j2 extensions). + +----------- +Environment +----------- + +``GITHUB_TOKEN`` – The GitHub personal access token needed for Macaron to run the analysis. For more information on how to obtain a token for Macaron, please see instructions in :ref:`Prepare GitHub access token `. diff --git a/docs/source/pages/cli_usage/action_dump_defaults.rst b/docs/source/pages/cli_usage/action_dump_defaults.rst new file mode 100644 index 000000000..b850238a4 --- /dev/null +++ b/docs/source/pages/cli_usage/action_dump_defaults.rst @@ -0,0 +1,25 @@ +============= +Dump Defaults +============= + +----------- +Description +----------- + +Dumps the ``defaults.ini`` file to the output directory. + +----- +Usage +----- + +.. code-block:: shell + + usage: macaron dump-defaults [-h] + +------- +Options +------- + +.. option:: -h, --help + + Show this help message and exit diff --git a/docs/source/pages/cli_usage/action_verify-policy.rst b/docs/source/pages/cli_usage/action_verify-policy.rst new file mode 100644 index 000000000..3e6a6a3af --- /dev/null +++ b/docs/source/pages/cli_usage/action_verify-policy.rst @@ -0,0 +1,37 @@ +============= +Verify Policy +============= + +----------- +Description +----------- + +Verify the analysis results against a Souffle Datalog policy. + +----- +Usage +----- + +.. code-block:: shell + + usage: macaron verify-policy [-h] -d DATABASE -f FILE [-s] + +------- +Options +------- + +.. option:: -h, --help + + Show this help message and exit + +.. option:: -d DATABASE, --database DATABASE + + Path to the database. + +.. option:: -f FILE, --file FILE + + Path to the Datalog policy. + +.. option:: -s, --show-prelude + + Show policy prelude. diff --git a/docs/source/pages/cli_usage/index.rst b/docs/source/pages/cli_usage/index.rst new file mode 100644 index 000000000..b167329ef --- /dev/null +++ b/docs/source/pages/cli_usage/index.rst @@ -0,0 +1,72 @@ +.. 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/. + +.. _cli-usage: + +================== +Command Line Usage +================== + +You could use the bash script ``run_macaron.sh`` we provided to run Macaron as a Docker image (For more information please see :ref:`Download Macaron `). All of the command line options we included in this section can be provide to ``run_macaron.sh`` directly. + +For example, with the following command line options: + +.. code-block:: shell + + macaron --help + +You could run it with: + +.. code-block:: shell + + ./run_macaron.sh macaron --help + +----- +Usage +----- + +.. code-block:: shell + + usage: macaron [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ... + +Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different action commands (e.g. ``analyze``) each has its own set of flags. + +.. note:: Running ``--help`` on the main entry ``macaron`` will only print out the help for common flags. To print the help messages for action-specific flags, please provide the name of the action you want to know about. For example: ``./run_macaron.sh analyze --help``. + +-------------- +Common Options +-------------- + +.. option:: -h, --help + + Show this help message and exit + +.. option:: -V, --version + + Show Macaron's version number and exit + +.. option:: -v, --verbose + + Run Macaron with more debug logs + +.. option:: -o OUTPUT_DIR, --output-dir OUTPUT_DIR + + The output destination path for Macaron + +.. option:: -dp DEFAULTS_PATH, --defaults-path DEFAULTS_PATH + + The path to the defaults configuration file. + +.. option:: -lr LOCAL_REPOS_PATH, --local-repos-path LOCAL_REPOS_PATH + + The directory where Macaron looks for already cloned repositories. + +-------- +See Also +-------- + +.. toctree:: + :glob: + :maxdepth: 1 + + action* diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst index 08cacc430..c521885db 100644 --- a/docs/source/pages/installation.rst +++ b/docs/source/pages/installation.rst @@ -13,6 +13,8 @@ Prerequisites - Installations of ``wget`` or ``curl`` and ``bash`` must be available and on the path. - Docker (or docker equivalent for your host OS) must be installed, with a docker command line equivalent to Docker 17.06 (Oracle Container Runtime 19.03) and the user should be a member of the operating system group ``docker`` (to run Docker in `rootless mode `_). +.. _download-macaron: + -------- Download -------- @@ -36,12 +38,14 @@ To verify your setup, go to the directory containing the downloaded ``run_macaro .. code-block:: shell - ./run_macaron.sh --help + ./run_macaron.sh macaron --help .. note:: In the first execution, this script will download the Macaron Docker image from ``ghcr.io/oracle-samples/macaron`` which can take some time. However, the next time you run it, the docker image available on your local host will be used. -.. note:: By default, ``latest`` is used as the tag for the downloaded image. You could specify the tag you want to run by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1: ``MACARON_IMAGE_TAG=0.1 && ./run_macaron.sh --help`` +.. note:: By default, ``latest`` is used as the tag for the downloaded image. You could specify the tag you want to run by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1: ``MACARON_IMAGE_TAG=0.1 && ./run_macaron.sh macaron --help`` + +.. _prepare-github-token: --------------------------- Prepare GitHub access token @@ -51,7 +55,7 @@ A GitHub access token is **always** required when using the **analyze** command .. code-block:: shell - ./run_macaron.sh analyze + ./run_macaron.sh macaron analyze To obtain a GitHub access token, please see the official instructions `here `_. diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 81051ae03..dc4adffa5 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -19,7 +19,7 @@ To run Macaron on a Github public repository, we use the following command: .. code-block:: shell - ./run_macaron.sh analyze -rp + ./run_macaron.sh macaron analyze -rp With ``repo_path`` being the remote path to your target repository. @@ -27,13 +27,13 @@ By default, Macaron will analyze the latest commit of the default branch. Howeve .. code-block:: shell - ./run_macaron.sh analyze -rp -b -d + ./run_macaron.sh macaron analyze -rp -b -d For example, to analyze the SLSA posture of `micronaut-core `_ at branch 4.0.x and commit ``82d115b4901d10226552ac67b0a10978cd5bc603`` we could use the following command: .. code-block:: shell - ./run_macaron.sh analyze -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 + ./run_macaron.sh macaron analyze -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 .. note:: Macaron automatically detects and analyzes **direct** dependencies for Java Maven and Gradle projects. This process might take a while and can be skipped by using the ``--skip-deps`` option. @@ -41,7 +41,7 @@ Take the same example as above, to disable analyzing `micronaut-core `. @@ -67,7 +67,7 @@ To run the analysis against that SBOM, run this command: .. code-block:: shell - ./run_macaron.sh analyze -rp https://github.com/micronaut-projects/micronaut-core -sbom + ./run_macaron.sh macaron analyze -rp https://github.com/micronaut-projects/micronaut-core -sbom With ``path_to_sbom`` is the path to the SBOM you want to use. @@ -94,10 +94,10 @@ We can run Macaron against the local repository at ``target`` by using this comm .. code-block:: shell - ./run_macaron.sh -lr path/to/boo/foo analyze -rp target + ./run_macaron.sh macaron -lr path/to/boo/foo analyze -rp target With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``-b``, ``-d`` or ``--skip-deps`` similar to two previous examples) -The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`CLI options `. +The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`CLI options `. .. note:: If ``-lr`` is not provided, Macaron will looks inside ``/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``. From a490c31e791311e62b8df97a753de6779a1b86e4 Mon Sep 17 00:00:00 2001 From: Trong Nhan Mai Date: Fri, 2 Jun 2023 10:34:40 +1000 Subject: [PATCH 2/4] chore: address PR comments Signed-off-by: Trong Nhan Mai --- .../source/pages/cli_usage/action_analyze.rst | 2 +- .../pages/cli_usage/action_dump_defaults.rst | 2 +- .../pages/cli_usage/action_verify-policy.rst | 2 +- docs/source/pages/cli_usage/index.rst | 25 ++++++------------- docs/source/pages/installation.rst | 4 +-- 5 files changed, 12 insertions(+), 23 deletions(-) diff --git a/docs/source/pages/cli_usage/action_analyze.rst b/docs/source/pages/cli_usage/action_analyze.rst index 43384026f..ded087237 100644 --- a/docs/source/pages/cli_usage/action_analyze.rst +++ b/docs/source/pages/cli_usage/action_analyze.rst @@ -14,7 +14,7 @@ Usage .. code-block:: shell - usage: macaron analyze + usage: ./run_macaron.sh analyze [-h] [-sbom SBOM_PATH] [-rp REPO_PATH] [-b BRANCH] [-d DIGEST] [-pe PROVENANCE_EXPECTATION] [-c CONFIG_PATH] [--skip-deps] [-g TEMPLATE_PATH] diff --git a/docs/source/pages/cli_usage/action_dump_defaults.rst b/docs/source/pages/cli_usage/action_dump_defaults.rst index b850238a4..3141d8d5b 100644 --- a/docs/source/pages/cli_usage/action_dump_defaults.rst +++ b/docs/source/pages/cli_usage/action_dump_defaults.rst @@ -14,7 +14,7 @@ Usage .. code-block:: shell - usage: macaron dump-defaults [-h] + usage: ./run_macaron.sh dump-defaults [-h] ------- Options diff --git a/docs/source/pages/cli_usage/action_verify-policy.rst b/docs/source/pages/cli_usage/action_verify-policy.rst index 3e6a6a3af..c46b97709 100644 --- a/docs/source/pages/cli_usage/action_verify-policy.rst +++ b/docs/source/pages/cli_usage/action_verify-policy.rst @@ -14,7 +14,7 @@ Usage .. code-block:: shell - usage: macaron verify-policy [-h] -d DATABASE -f FILE [-s] + usage: ./run_macaron.sh verify-policy [-h] -d DATABASE -f FILE [-s] ------- Options diff --git a/docs/source/pages/cli_usage/index.rst b/docs/source/pages/cli_usage/index.rst index b167329ef..e7495aed4 100644 --- a/docs/source/pages/cli_usage/index.rst +++ b/docs/source/pages/cli_usage/index.rst @@ -7,19 +7,8 @@ Command Line Usage ================== -You could use the bash script ``run_macaron.sh`` we provided to run Macaron as a Docker image (For more information please see :ref:`Download Macaron `). All of the command line options we included in this section can be provide to ``run_macaron.sh`` directly. +You could use the bash script ``run_macaron.sh`` we provided to run Macaron as a Docker image (For more information on how to get this script, please see :ref:`Download Macaron `). -For example, with the following command line options: - -.. code-block:: shell - - macaron --help - -You could run it with: - -.. code-block:: shell - - ./run_macaron.sh macaron --help ----- Usage @@ -27,11 +16,11 @@ Usage .. code-block:: shell - usage: macaron [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ... + usage: ./run_macaron.sh [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ... -Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different action commands (e.g. ``analyze``) each has its own set of flags. +Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different action commands (e.g. ``analyze``), which have their own set of flags. -.. note:: Running ``--help`` on the main entry ``macaron`` will only print out the help for common flags. To print the help messages for action-specific flags, please provide the name of the action you want to know about. For example: ``./run_macaron.sh analyze --help``. +.. note:: Running ``--help`` on the main entry ``macaron`` will only print out the help for common flags. To print the help messages for action-specific flags, please provide the name of the action you want to know about. For example: ``./run_macaron.sh analyze --help``. The documented flags for each action can be found at `Action Commands`_. -------------- Common Options @@ -61,9 +50,9 @@ Common Options The directory where Macaron looks for already cloned repositories. --------- -See Also --------- +--------------- +Action Commands +--------------- .. toctree:: :glob: diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst index c521885db..4e995d0ad 100644 --- a/docs/source/pages/installation.rst +++ b/docs/source/pages/installation.rst @@ -38,7 +38,7 @@ To verify your setup, go to the directory containing the downloaded ``run_macaro .. code-block:: shell - ./run_macaron.sh macaron --help + ./run_macaron.sh --help .. note:: In the first execution, this script will download the Macaron Docker image from ``ghcr.io/oracle-samples/macaron`` which can take some time. However, the next time you run it, the docker image available on your local host will be used. @@ -55,7 +55,7 @@ A GitHub access token is **always** required when using the **analyze** command .. code-block:: shell - ./run_macaron.sh macaron analyze + ./run_macaron.sh analyze To obtain a GitHub access token, please see the official instructions `here `_. From 35893b49559aad2a3abedfd6d8acf1dff89dceb2 Mon Sep 17 00:00:00 2001 From: Trong Nhan Mai Date: Fri, 2 Jun 2023 12:03:05 +1000 Subject: [PATCH 3/4] chore: update CLI options for the verify-policy action Signed-off-by: Trong Nhan Mai --- docs/source/pages/cli_usage/action_verify-policy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/cli_usage/action_verify-policy.rst b/docs/source/pages/cli_usage/action_verify-policy.rst index c46b97709..5b2d7bccd 100644 --- a/docs/source/pages/cli_usage/action_verify-policy.rst +++ b/docs/source/pages/cli_usage/action_verify-policy.rst @@ -14,7 +14,7 @@ Usage .. code-block:: shell - usage: ./run_macaron.sh verify-policy [-h] -d DATABASE -f FILE [-s] + usage: ./run_macaron.sh verify-policy [-h] -d DATABASE (-f FILE | -s) ------- Options From 602d68376381eb591484d8df2ecaee0e26dd0e7e Mon Sep 17 00:00:00 2001 From: Trong Nhan Mai Date: Fri, 2 Jun 2023 14:27:02 +1000 Subject: [PATCH 4/4] chore: address more PR comments Signed-off-by: Trong Nhan Mai --- docs/source/pages/cli_usage/action_analyze.rst | 6 ++++-- .../pages/cli_usage/action_dump_defaults.rst | 2 +- docs/source/pages/cli_usage/index.rst | 3 +-- docs/source/pages/installation.rst | 6 +++--- docs/source/pages/using.rst | 16 ++++++++-------- 5 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/source/pages/cli_usage/action_analyze.rst b/docs/source/pages/cli_usage/action_analyze.rst index ded087237..ac37a3060 100644 --- a/docs/source/pages/cli_usage/action_analyze.rst +++ b/docs/source/pages/cli_usage/action_analyze.rst @@ -1,3 +1,5 @@ +.. _analyze-action-cli: + ======= Analyze ======= @@ -6,7 +8,7 @@ Analyze Description ----------- -Analyze a Github public repository (and potentially the repositories of it dependencies) to determine its SLSA posture following the specification of `SLSA v0.1 `_. +Analyze a public GitHub repository (and optionally the repositories of its dependencies) to determine its SLSA posture. We currently support `SLSA v0.1 `_. The support for `SLSA v1.0 `_ will be added in future. ----- Usage @@ -64,4 +66,4 @@ Options Environment ----------- -``GITHUB_TOKEN`` – The GitHub personal access token needed for Macaron to run the analysis. For more information on how to obtain a token for Macaron, please see instructions in :ref:`Prepare GitHub access token `. +``GITHUB_TOKEN`` – The GitHub personal access token is needed for to run the analysis. For more information on how to obtain a GitHub token, see instructions in :ref:`Prepare GitHub access token `. diff --git a/docs/source/pages/cli_usage/action_dump_defaults.rst b/docs/source/pages/cli_usage/action_dump_defaults.rst index 3141d8d5b..ee67bc057 100644 --- a/docs/source/pages/cli_usage/action_dump_defaults.rst +++ b/docs/source/pages/cli_usage/action_dump_defaults.rst @@ -6,7 +6,7 @@ Dump Defaults Description ----------- -Dumps the ``defaults.ini`` file to the output directory. +Dumps the ``defaults.ini`` configuration file used by Macaron to the output directory. You can make changes to this configuration file and pass it to Macaron using the ``--defaults-path`` option. See :ref:`Analyze ` for more information. ----- Usage diff --git a/docs/source/pages/cli_usage/index.rst b/docs/source/pages/cli_usage/index.rst index e7495aed4..6db011444 100644 --- a/docs/source/pages/cli_usage/index.rst +++ b/docs/source/pages/cli_usage/index.rst @@ -7,8 +7,7 @@ Command Line Usage ================== -You could use the bash script ``run_macaron.sh`` we provided to run Macaron as a Docker image (For more information on how to get this script, please see :ref:`Download Macaron `). - +Use the bash script ``run_macaron.sh`` to run Macaron as a Docker container (for more information on how to get this script, please see :ref:`Download `). ----- Usage diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst index 4e995d0ad..51fe2502e 100644 --- a/docs/source/pages/installation.rst +++ b/docs/source/pages/installation.rst @@ -43,7 +43,7 @@ To verify your setup, go to the directory containing the downloaded ``run_macaro .. note:: In the first execution, this script will download the Macaron Docker image from ``ghcr.io/oracle-samples/macaron`` which can take some time. However, the next time you run it, the docker image available on your local host will be used. -.. note:: By default, ``latest`` is used as the tag for the downloaded image. You could specify the tag you want to run by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1: ``MACARON_IMAGE_TAG=0.1 && ./run_macaron.sh macaron --help`` +.. note:: By default, ``latest`` is used as the tag for the downloaded image. You can choose a specific tag by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1.0 run: ``MACARON_IMAGE_TAG=v0.1.0 && ./run_macaron.sh --help`` .. _prepare-github-token: @@ -51,7 +51,7 @@ To verify your setup, go to the directory containing the downloaded ``run_macaro Prepare GitHub access token --------------------------- -A GitHub access token is **always** required when using the **analyze** command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in :ref:`Using Guide `. +A GitHub access token is **always** required when using the **analyze** command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in :ref:`Using Macaron `. .. code-block:: shell @@ -66,4 +66,4 @@ Ideally, the GitHub token must have **read** permissions for the repositories th After generating a GitHub personal-access token, please store its value in an environment variable called ``GITHUB_TOKEN``. This environment variable will be read by Macaron for its **analyze** command. -Now that you have successfully downloaded and installed Macaron, please refer to :ref:`Using Guide ` for the instructions on how to use Macaron. +Now that you have successfully downloaded and installed Macaron, please refer to :ref:`Using Macaron ` for the instructions on how to use Macaron. diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index dc4adffa5..2592819ad 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -1,7 +1,7 @@ .. 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/. -.. _using-guide: +.. _using-macaron: ============= Using Macaron @@ -19,7 +19,7 @@ To run Macaron on a Github public repository, we use the following command: .. code-block:: shell - ./run_macaron.sh macaron analyze -rp + ./run_macaron.sh analyze -rp With ``repo_path`` being the remote path to your target repository. @@ -27,13 +27,13 @@ By default, Macaron will analyze the latest commit of the default branch. Howeve .. code-block:: shell - ./run_macaron.sh macaron analyze -rp -b -d + ./run_macaron.sh analyze -rp -b -d For example, to analyze the SLSA posture of `micronaut-core `_ at branch 4.0.x and commit ``82d115b4901d10226552ac67b0a10978cd5bc603`` we could use the following command: .. code-block:: shell - ./run_macaron.sh macaron analyze -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 + ./run_macaron.sh analyze -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 .. note:: Macaron automatically detects and analyzes **direct** dependencies for Java Maven and Gradle projects. This process might take a while and can be skipped by using the ``--skip-deps`` option. @@ -41,7 +41,7 @@ Take the same example as above, to disable analyzing `micronaut-core `. @@ -67,7 +67,7 @@ To run the analysis against that SBOM, run this command: .. code-block:: shell - ./run_macaron.sh macaron analyze -rp https://github.com/micronaut-projects/micronaut-core -sbom + ./run_macaron.sh analyze -rp https://github.com/micronaut-projects/micronaut-core -sbom With ``path_to_sbom`` is the path to the SBOM you want to use. @@ -94,10 +94,10 @@ We can run Macaron against the local repository at ``target`` by using this comm .. code-block:: shell - ./run_macaron.sh macaron -lr path/to/boo/foo analyze -rp target + ./run_macaron.sh -lr path/to/boo/foo analyze -rp target With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``-b``, ``-d`` or ``--skip-deps`` similar to two previous examples) -The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`CLI options `. +The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage `. .. note:: If ``-lr`` is not provided, Macaron will looks inside ``/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.