feat: allow defining a git service from defaults.ini

Author: Trong Nhan Mai

docs/source/pages/supported_technologies/index.rst

@@ -24,6 +24,8 @@ such as GitHub Actions workflows.
 * Docker
 
 
+.. _supported_git_services:
+
 ------------
 Git Services
 ------------

docs/source/pages/using.rst

@@ -314,7 +314,53 @@ Analyzing a locally cloned repository
 
 If you have a local repository that you want to analyze, Macaron also supports running the analysis against a local repository.
 
-Assume that the dir tree at the local repository has the following components:
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+Analyzing a repository whose git service is not supported by Macaron
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If the repository remote URL is from an unknown git service (see :ref:`Git Services <supported_git_services>` for a list of supported git services in Macaron), Macaron won't recognize it when analyzing the repository.
+
+You would need to tell Macaron about that git service through the ``defaults.ini`` config.
+For example, let's say you want to analyze the Bitbucket repository at ``https://bitbucket.org/snakeyaml/snakeyaml``. First, you need to create a ``defaults.ini`` file in the current workspace with the following content:
+
+.. code-block:: ini
+
+  [git_service.local_repo]
+  hostname = bitbucket.org
+
+In which ``hostname`` contains the domain of the git service URL. In this example it's ``bitbucket.org``.
+
+.. note::
+
+  This ``defaults.ini`` section must only be used for analyzing a locally cloned repository. If the domain name has already been supported in other services, it doesn't need to be defined again here.
+
+Assume that the dir tree at the current workspace has the following structure:
+
+.. code-block:: shell
+
+  boo
+  ├── foo
+  │   └── snakeyaml
+
+We can run Macaron against the local repository at ``snakeyaml`` by using this command:
+
+.. code-block:: shell
+
+  ./run_macaron.sh --local-repos-path ./boo/foo --defaults-path ./defaults.ini analyze -rp snakeyaml <rest_of_args>
+
+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 tells Macaron to look into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
+
+.. note:: If ``-lr`` is not provided, Macaron will looks inside ``<current_working_directory>/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.
+
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+Analyzing a local repository with supported git service
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If the local repository you want to analyze has remote origin hosted on a supported git service, you can run the analysis directly without having to prepare ``defaults.ini`` as above.
+
+Assume that the dir tree at the current workspace has the following structure:
 
 .. code-block:: shell
 
@@ -326,13 +372,13 @@ 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 <rest_of_args>
+  ./run_macaron.sh --local-repos-path ./boo/foo analyze -rp target <rest_of_args>
 
-With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``-b``, ``-d`` or ``--skip-deps`` similar to two previous examples)
+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:`Command Line Usage <cli-usage>`.
+The ``-lr`` flag tells Macaron to look into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
 
-.. note:: If ``-lr`` is not provided, Macaron will looks inside ``<working_directory>/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.
+.. note:: If ``-lr`` is not provided, Macaron will looks inside ``<current_working_directory>/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.
 
 -------------------------
 Running the policy engine

src/macaron/config/defaults.ini

@@ -90,6 +90,12 @@ hostname = gitlab.com
 # [git_service.gitlab.self_hosted]
 # hostname = example.org
 
+# This section defines a git service that Macaron doesn't recognize yet.
+# It must only be used for analyzing a locally cloned repository.
+# If the host name is already supported in other services, it doesn't need to be defined again here.
+# [git_service.local_repo]
+# hostname = example.org
+
 # This is the spec for trusted Maven build tools.
 [builder.maven]
 entry_conf = settings.xml

src/macaron/slsa_analyzer/git_service/__init__.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 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/.
 
 """The git_service package contains the supported git services for Macaron."""
@@ -7,7 +7,14 @@
 from .bitbucket import BitBucket
 from .github import GitHub
 from .gitlab import PubliclyHostedGitLab, SelfHostedGitLab
+from .local_repo_git_service import LocalRepoGitService
 
 # The list of supported git services. The order of the list determines the order
 # in which each git service is checked against the target repository.
-GIT_SERVICES: list[BaseGitService] = [GitHub(), PubliclyHostedGitLab(), SelfHostedGitLab(), BitBucket()]
+GIT_SERVICES: list[BaseGitService] = [
+    GitHub(),
+    PubliclyHostedGitLab(),
+    SelfHostedGitLab(),
+    BitBucket(),
+    LocalRepoGitService(),
+]

src/macaron/slsa_analyzer/git_service/local_repo_git_service.py

@@ -0,0 +1,42 @@
+# 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/.
+
+"""This module contains the spec for the local repo git service."""
+
+import logging
+
+from pydriller.git import Git
+
+from macaron.errors import ConfigurationError, RepoCheckOutError
+from macaron.slsa_analyzer import git_url
+from macaron.slsa_analyzer.git_service.base_git_service import BaseGitService
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class LocalRepoGitService(BaseGitService):
+    """This class contains the spec of the local repo git service."""
+
+    def __init__(self) -> None:
+        """Initialize instance."""
+        super().__init__("generic")
+
+    def load_defaults(self) -> None:
+        """Load the values for this git service from the ini configuration."""
+        try:
+            self.hostname = self.load_hostname(section_name="git_service.local_repo")
+        except ConfigurationError as error:
+            raise error
+
+    def clone_repo(self, _clone_dir: str, _url: str) -> None:
+        """Cloning from a local repo git service is not supported."""
+        raise NotImplementedError
+
+    def check_out_repo(self, git_obj: Git, branch: str, digest: str, offline_mode: bool) -> Git:
+        """Checkout the branch and commit specified by the user of a repository."""
+        if not git_url.check_out_repo_target(git_obj, branch, digest, offline_mode):
+            raise RepoCheckOutError(
+                f"Failed to check out branch {branch} and commit {digest} for repo {git_obj.project_name}."
+            )
+
+        return git_obj