From 2e772281a8bf8dd5b0c0b832219c3078ea08b92d Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Thu, 13 Jul 2023 17:43:19 +1000 Subject: [PATCH 1/7] docs: add documentation for analyzing GitLab repositories Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 04a312bc0..d27da5e90 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -11,6 +11,8 @@ Using Macaron .. _analyze-action: +.. contents:: :local: + ------------------------------------ Analyzing a public Github repository ------------------------------------ @@ -205,3 +207,35 @@ Thanks to Datalog’s expressive language model, it’s easy to add exception ru requirement. For example, `the Mysql Connector/J `_ dependency in the Micronaut MuShop project does not pass the ``build_service`` check, but can be manually investigated and exempted if trusted. Overall, policies expressed in Datalog can be enforced by Macaron as part of your CI/CD pipeline to detect regressions or unexpected behavior. + +----------------------------- +Analyzing a GitLab repository +----------------------------- + +Macaron supports analyzing GitLab repositories, whether they are hosted on `gitlab.com `_ or on your self-hosted GitLab instance. The set up in these two cases are a little bit different. + +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +Analyzing a repository on `gitlab.com `_ +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Analyzing a public repository on `gitlab.com `_ is quite similar to analyzing a public GitHub repository -- you just need to pass a proper GitLab repository URL to ``macaron analyze``. + +If you want to analyze some private repository hosted on ``gitlab.com``, you need to obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. + +''''''''''''''''''''''''''''''''''''''''''''''''''''''' +Analyzing a repository on a self-hosted GitLab instance +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +To analyze a repository on a self-hosted GitLab instance, you need to do the following: + +- Add the following ``[git_service.gitlab.self_hosted]`` section into your ``.ini`` config. In :ref:`the default .ini configuration `, there is already this section commented out. You can start by un-commenting this section and modifying the ``domain`` value with the domain of your self-hosted GitLab instance. + +.. code-block:: ini + + # Access to a self-hosted GitLab instance (e.g. your organization's self-hosted GitLab instance). + # If this section is enabled, an access token must be provided through the `MCN_PUBLICLY_HOSTED_GITLAB_TOKEN` environment variable. + # The `read_repository` permission is required for this token. + [git_service.gitlab.self_hosted] + domain = internal.gitlab.org + +- Obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_PUBLICLY_HOSTED_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. From b483ec997068c928f4bea17d8dae7ade92bc6f03 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 09:48:22 +1000 Subject: [PATCH 2/7] chore: fix token name for self-hosted gitlab Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index d27da5e90..552962be4 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -238,4 +238,4 @@ To analyze a repository on a self-hosted GitLab instance, you need to do the fol [git_service.gitlab.self_hosted] domain = internal.gitlab.org -- Obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_PUBLICLY_HOSTED_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. +- Obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. From 02d7d56e54d7f59c8bf0c41399457585ab8f8b4c Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 14:36:31 +1000 Subject: [PATCH 3/7] chore: fix token name for self-hosted gitlab Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 2 +- src/macaron/config/defaults.ini | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 552962be4..e5a1e2de7 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -233,7 +233,7 @@ To analyze a repository on a self-hosted GitLab instance, you need to do the fol .. code-block:: ini # Access to a self-hosted GitLab instance (e.g. your organization's self-hosted GitLab instance). - # If this section is enabled, an access token must be provided through the `MCN_PUBLICLY_HOSTED_GITLAB_TOKEN` environment variable. + # If this section is enabled, an access token must be provided through the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. # The `read_repository` permission is required for this token. [git_service.gitlab.self_hosted] domain = internal.gitlab.org diff --git a/src/macaron/config/defaults.ini b/src/macaron/config/defaults.ini index 116247b44..5dbaf1cb7 100644 --- a/src/macaron/config/defaults.ini +++ b/src/macaron/config/defaults.ini @@ -74,7 +74,7 @@ domain = github.com domain = gitlab.com # Access to a self-hosted GitLab instance (e.g. your organization's self-hosted GitLab instance). -# If this section is enabled, an access token must be provided through the `MCN_PUBLICLY_HOSTED_GITLAB_TOKEN` environment variable. +# If this section is enabled, an access token must be provided through the `MCN_SELF_HOSTED_GITLAB_TOKEN` environment variable. # The `read_repository` permission is required for this token. # [git_service.gitlab.self_hosted] # domain = example.org From ced46dc77a8983634292d2ed639d31e97c4fbd07 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 14:38:02 +1000 Subject: [PATCH 4/7] chore: reword instruction related to default ini config Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index e5a1e2de7..1277c20e5 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -228,7 +228,7 @@ Analyzing a repository on a self-hosted GitLab instance To analyze a repository on a self-hosted GitLab instance, you need to do the following: -- Add the following ``[git_service.gitlab.self_hosted]`` section into your ``.ini`` config. In :ref:`the default .ini configuration `, there is already this section commented out. You can start by un-commenting this section and modifying the ``domain`` value with the domain of your self-hosted GitLab instance. +- Add the following ``[git_service.gitlab.self_hosted]`` section into your ``.ini`` config. In the default .ini configuration (generated using ``macaron dump-default`` -- :ref:`see instructions `), there is already this section commented out. You can start by un-commenting this section and modifying the ``domain`` value with the domain of your self-hosted GitLab instance. .. code-block:: ini From 43f67569e9ff9e35e936ffd338e68b7b8de782d7 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 14:46:43 +1000 Subject: [PATCH 5/7] chore: minor rewording in GitLab instructions Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 1277c20e5..59bd78460 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -220,7 +220,7 @@ Analyzing a repository on `gitlab.com `_ Analyzing a public repository on `gitlab.com `_ is quite similar to analyzing a public GitHub repository -- you just need to pass a proper GitLab repository URL to ``macaron analyze``. -If you want to analyze some private repository hosted on ``gitlab.com``, you need to obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. +To analyze a private repository hosted on ``gitlab.com``, you need to obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. ''''''''''''''''''''''''''''''''''''''''''''''''''''''' Analyzing a repository on a self-hosted GitLab instance From f6d72ed8b1e0dd37e2571812f95913089d61e6f4 Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 15:03:23 +1000 Subject: [PATCH 6/7] chore: restructure macaron usage page to move GitLab section up top Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 72 +++++++++++++++++++------------------ 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 59bd78460..a9e537952 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -13,9 +13,13 @@ Using Macaron .. contents:: :local: ------------------------------------- +---------------------------------- +Analyzing a source code repository +---------------------------------- + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Analyzing a public Github repository ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Macaron can analyze a Github public repository (and potentially the repositories of it dependencies) to determine its SLSA posture following the specification of `SLSA v0.1 `_. @@ -54,6 +58,38 @@ With the example above, the generated output reports can be seen here: - `micronaut-core.html <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.html>`__ - `micronaut-core.json <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.json>`__ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Analyzing a GitLab repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Macaron supports analyzing GitLab repositories, whether they are hosted on `gitlab.com `_ or on your self-hosted GitLab instance. The set up in these two cases are a little bit different. + +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Analyzing a repository on `gitlab.com `_ +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Analyzing a public repository on `gitlab.com `_ is quite similar to analyzing a public GitHub repository -- you just need to pass a proper GitLab repository URL to ``macaron analyze``. + +To analyze a private repository hosted on ``gitlab.com``, you need to obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. + +""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Analyzing a repository on a self-hosted GitLab instance +""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +To analyze a repository on a self-hosted GitLab instance, you need to do the following: + +- Add the following ``[git_service.gitlab.self_hosted]`` section into your ``.ini`` config. In the default .ini configuration (generated using ``macaron dump-default`` -- :ref:`see instructions `), there is already this section commented out. You can start by un-commenting this section and modifying the ``domain`` value with the domain of your self-hosted GitLab instance. + +.. code-block:: ini + + # Access to a self-hosted GitLab instance (e.g. your organization's self-hosted GitLab instance). + # If this section is enabled, an access token must be provided through the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. + # The `read_repository` permission is required for this token. + [git_service.gitlab.self_hosted] + domain = internal.gitlab.org + +- Obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. + ------------------------------------------------- Verifying provenance expectations in CUE language ------------------------------------------------- @@ -207,35 +243,3 @@ Thanks to Datalog’s expressive language model, it’s easy to add exception ru requirement. For example, `the Mysql Connector/J `_ dependency in the Micronaut MuShop project does not pass the ``build_service`` check, but can be manually investigated and exempted if trusted. Overall, policies expressed in Datalog can be enforced by Macaron as part of your CI/CD pipeline to detect regressions or unexpected behavior. - ------------------------------ -Analyzing a GitLab repository ------------------------------ - -Macaron supports analyzing GitLab repositories, whether they are hosted on `gitlab.com `_ or on your self-hosted GitLab instance. The set up in these two cases are a little bit different. - -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' -Analyzing a repository on `gitlab.com `_ -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Analyzing a public repository on `gitlab.com `_ is quite similar to analyzing a public GitHub repository -- you just need to pass a proper GitLab repository URL to ``macaron analyze``. - -To analyze a private repository hosted on ``gitlab.com``, you need to obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. - -''''''''''''''''''''''''''''''''''''''''''''''''''''''' -Analyzing a repository on a self-hosted GitLab instance -''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -To analyze a repository on a self-hosted GitLab instance, you need to do the following: - -- Add the following ``[git_service.gitlab.self_hosted]`` section into your ``.ini`` config. In the default .ini configuration (generated using ``macaron dump-default`` -- :ref:`see instructions `), there is already this section commented out. You can start by un-commenting this section and modifying the ``domain`` value with the domain of your self-hosted GitLab instance. - -.. code-block:: ini - - # Access to a self-hosted GitLab instance (e.g. your organization's self-hosted GitLab instance). - # If this section is enabled, an access token must be provided through the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. - # The `read_repository` permission is required for this token. - [git_service.gitlab.self_hosted] - domain = internal.gitlab.org - -- Obtain a GitLab access token having at least the ``read_repository`` permission and store it into the ``MCN_SELF_HOSTED_GITLAB_TOKEN`` environment variable. For more detailed instructions, see `GitLab documentation `_. From 5909ddd13ebe415068be7622614a3ceda861e64f Mon Sep 17 00:00:00 2001 From: Nathan Nguyen Date: Mon, 17 Jul 2023 15:13:27 +1000 Subject: [PATCH 7/7] chore: fix section markers Signed-off-by: Nathan Nguyen --- docs/source/pages/using.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index a9e537952..0d8a9f6b2 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -17,9 +17,9 @@ Using Macaron Analyzing a source code repository ---------------------------------- -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +'''''''''''''''''''''''''''''''''''' Analyzing a public Github repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +'''''''''''''''''''''''''''''''''''' Macaron can analyze a Github public repository (and potentially the repositories of it dependencies) to determine its SLSA posture following the specification of `SLSA v0.1 `_. @@ -58,9 +58,9 @@ With the example above, the generated output reports can be seen here: - `micronaut-core.html <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.html>`__ - `micronaut-core.json <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.json>`__ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +''''''''''''''''''''''''''''' Analyzing a GitLab repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +''''''''''''''''''''''''''''' Macaron supports analyzing GitLab repositories, whether they are hosted on `gitlab.com `_ or on your self-hosted GitLab instance. The set up in these two cases are a little bit different.