fix: rename domain to hostname in Git service configuration (#453)

Rename the attribute `domain` to `hostname` in Git service sections in Macaron's .ini config.

---------

Signed-off-by: Nathan Nguyen <[email protected]>

Author: nathanwn

docs/source/pages/using.rst

@@ -78,15 +78,15 @@ 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 <action_dump_defaults>`), 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 <action_dump_defaults>`), there is already this section commented out. You can start by un-commenting this section and modifying the ``hostname`` value with the hostname 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
+    hostname = 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 <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token>`_.
 
@@ -100,7 +100,7 @@ To simplify the examples, we use the same configurations as above if needed (e.g
 
 .. code-block::
 
-  pkg:<git_service_domain>/<organization>/<name>
+  pkg:<git_service_hostname>/<organization>/<name>
 
 The list bellow shows examples for the corresponding PURL strings for different git repositories:
 

src/macaron/config/defaults.ini

@@ -59,25 +59,25 @@ parent_limit = 10
 artifact_ignore_list =
 
 # Git services that Macaron has access to clone repositories.
-# For security purposes, Macaron will only clone repositories from the domains specified.
+# For security purposes, Macaron will only clone repositories from the hostnames specified.
 
 # Access to GitHub is required in most case for Macaron to analyse not only the main
 # repo but also its dependencies.
 [git_service.github]
-domain = github.com
+hostname = github.com
 
 # Access to public GitLab (gitlab.com).
 # An optional access token can be provided through the `MCN_GITLAB_TOKEN` environment variable.
 # This access token is optional, only necessary when you need to clone private repositories.
 # The `read_repository` permission is required for this token.
 [git_service.gitlab.publicly_hosted]
-domain = gitlab.com
+hostname = 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_SELF_HOSTED_GITLAB_TOKEN` environment variable.
 # The `read_repository` permission is required for this token.
 # [git_service.gitlab.self_hosted]
-# domain = example.org
+# hostname = example.org
 
 # This is the spec for trusted Maven build tools.
 [builder.maven]

src/macaron/slsa_analyzer/analyzer.py

@@ -624,7 +624,7 @@ def add_component(
             The component is already analyzed in the same session.
         """
         # Note: the component created in this function will be added to the database.
-        available_domains = [git_service.domain for git_service in GIT_SERVICES if git_service.domain]
+        available_domains = [git_service.hostname for git_service in GIT_SERVICES if git_service.hostname]
         try:
             analysis_target = Analyzer.to_analysis_target(config, available_domains)
         except InvalidPURLError as error:

src/macaron/slsa_analyzer/git_service/base_git_service.py

@@ -24,20 +24,20 @@ def __init__(self, name: str) -> None:
             The name of the git service.
         """
         self.name = name
-        self.domain: str | None = None
+        self.hostname: str | None = None
 
     @abstractmethod
     def load_defaults(self) -> None:
         """Load the values for this git service from the ini configuration."""
 
-    def load_domain(self, section_name: str) -> str | None:
-        """Load the domain of the git service from the ini configuration section ``section_name``.
+    def load_hostname(self, section_name: str) -> str | None:
+        """Load the hostname of the git service from the ini configuration section ``section_name``.
 
         The section may or may not be available in the configuration. In both cases,
         the method should not raise ``ConfigurationError``.
 
         Meanwhile, if the section is present but there is a schema violation (e.g. a key such as
-        ``domain`` is missing), this method will raise a ``ConfigurationError``.
+        ``hostname`` is missing), this method will raise a ``ConfigurationError``.
 
         Parameters
         ----------
@@ -47,7 +47,7 @@ def load_domain(self, section_name: str) -> str | None:
         Returns
         -------
         str | None
-            The domain. This can be ``None`` if the git service section is not found in
+            The hostname. This can be ``None`` if the git service section is not found in
             the ini configuration file, meaning the user does not enable the
             corresponding git service.
 
@@ -61,17 +61,17 @@ def load_domain(self, section_name: str) -> str | None:
             # to have all available git services in the ini config.
             return None
         section = defaults[section_name]
-        domain = section.get("domain")
-        if not domain:
+        hostname = section.get("hostname")
+        if not hostname:
             raise ConfigurationError(
-                f'The "domain" key is missing in section [{section_name}] of the .ini configuration file.'
+                f'The "hostname" key is missing in section [{section_name}] of the .ini configuration file.'
             )
-        return domain
+        return hostname
 
     def is_detected(self, url: str) -> bool:
         """Check if the remote repo at the given ``url`` is hosted on this git service.
 
-        This check is done by checking the URL of the repo against the domain of this
+        This check is done by checking the URL of the repo against the hostname of this
         git service.
 
         Parameters
@@ -84,12 +84,12 @@ def is_detected(self, url: str) -> bool:
         bool
             True if the repo is indeed hosted on this git service.
         """
-        if self.domain is None:
+        if self.hostname is None:
             return False
         return (
             git_url.parse_remote_url(
                 url,
-                allowed_git_service_domains=[self.domain],
+                allowed_git_service_hostnames=[self.hostname],
             )
             is not None
         )

src/macaron/slsa_analyzer/git_service/github.py

@@ -29,7 +29,7 @@ def load_defaults(self) -> None:
             If there is an error loading the configuration.
         """
         try:
-            self.domain = self.load_domain(section_name="git_service.github")
+            self.hostname = self.load_hostname(section_name="git_service.github")
         except ConfigurationError as error:
             raise error
 

src/macaron/slsa_analyzer/git_service/gitlab.py

@@ -65,14 +65,14 @@ def construct_clone_url(self, url: str) -> str:
         CloneError
             If there is an error parsing the URL.
         """
-        if not self.domain:
+        if not self.hostname:
             # This should not happen.
-            logger.debug("Cannot clone with a Git service having no domain.")
+            logger.debug("Cannot clone with a Git service having no hostname.")
             raise CloneError(f"Cannot clone the repo '{url}' due to an internal error.")
 
         url_parse_result = git_url.parse_remote_url(
             url,
-            allowed_git_service_domains=[self.domain],
+            allowed_git_service_hostnames=[self.hostname],
         )
         if not url_parse_result:
             raise CloneError(
@@ -83,9 +83,9 @@ def construct_clone_url(self, url: str) -> str:
         # https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#clone-using-a-token
         access_token = os.environ.get(self.access_token_env_name)
         if access_token:
-            clone_url_netloc = f"oauth2:{access_token}@{self.domain}"
+            clone_url_netloc = f"oauth2:{access_token}@{self.hostname}"
         else:
-            clone_url_netloc = self.domain
+            clone_url_netloc = self.hostname
 
         clone_url = urlunparse(
             ParseResult(
@@ -241,17 +241,17 @@ def load_defaults(self) -> None:
             If there is an error loading the configuration.
         """
         try:
-            self.domain = self.load_domain(section_name="git_service.gitlab.self_hosted")
+            self.hostname = self.load_hostname(section_name="git_service.gitlab.self_hosted")
         except ConfigurationError as error:
             raise error
 
-        if not self.domain:
+        if not self.hostname:
             return
 
         if not os.environ.get(self.access_token_env_name):
             raise ConfigurationError(
                 f"Environment variable '{self.access_token_env_name}' is not set "
-                + f"for private GitLab service '{self.domain}'."
+                + f"for private GitLab service '{self.hostname}'."
             )
 
 
@@ -274,6 +274,6 @@ def load_defaults(self) -> None:
             If there is an error loading the configuration.
         """
         try:
-            self.domain = self.load_domain(section_name="git_service.gitlab.publicly_hosted")
+            self.hostname = self.load_hostname(section_name="git_service.gitlab.publicly_hosted")
         except ConfigurationError as error:
             raise error

src/macaron/slsa_analyzer/git_url.py

@@ -485,11 +485,11 @@ def get_remote_origin_of_local_repo(git_obj: Git) -> str:
             logger.error("Error occurs while processing the remote URL of repo %s.", git_obj.project_name)
             return ""
 
-        _, _, domain = url_parse_result.netloc.rpartition("@")
+        _, _, hostname = url_parse_result.netloc.rpartition("@")
 
         new_url_parse_result = urllib.parse.ParseResult(
             scheme=url_parse_result.scheme,
-            netloc=domain,
+            netloc=hostname,
             path=url_parse_result.path,
             params=url_parse_result.params,
             query=url_parse_result.query,
@@ -548,7 +548,9 @@ def get_remote_vcs_url(url: str, clean_up: bool = True) -> str:
     return url_as_str
 
 
-def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = None) -> urllib.parse.ParseResult | None:
+def parse_remote_url(
+    url: str, allowed_git_service_hostnames: list[str] | None = None
+) -> urllib.parse.ParseResult | None:
     """Verify if the given repository path is a valid vcs.
 
     This method converts the url to a ``https://`` url and return a
@@ -559,8 +561,8 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
     ----------
     url: str
         The path of the repository to check.
-    allowed_git_service_domains: list[str] | None
-        The list of allowed git service domains.
+    allowed_git_service_hostnames: list[str] | None
+        The list of allowed git service hostnames.
         If this is ``None``, fall back to the  ``.ini`` configuration.
         (Default: None).
 
@@ -574,8 +576,8 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
     >>> parse_remote_url("ssh://[email protected]:7999/owner/org.git")
     ParseResult(scheme='https', netloc='github.com', path='owner/org.git', params='', query='', fragment='')
     """
-    if allowed_git_service_domains is None:
-        allowed_git_service_domains = get_allowed_git_service_domains(defaults)
+    if allowed_git_service_hostnames is None:
+        allowed_git_service_hostnames = get_allowed_git_service_hostnames(defaults)
 
     try:
         # Remove prefixes, such as "scm:" and "git:".
@@ -596,7 +598,7 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
 
     # e.g., https://github.com/owner/project.git
     if parsed_url.scheme in ("http", "https", "ftp", "ftps", "git+https"):
-        if parsed_url.netloc not in allowed_git_service_domains:
+        if parsed_url.netloc not in allowed_git_service_hostnames:
             return None
         path_params = parsed_url.path.strip("/").split("/")
         if len(path_params) < 2:
@@ -613,7 +615,7 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
         user_host, _, port = parsed_url.netloc.partition(":")
         user, _, host = user_host.rpartition("@")
 
-        if not user or host not in allowed_git_service_domains:
+        if not user or host not in allowed_git_service_hostnames:
             return None
 
         path = ""
@@ -641,7 +643,7 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
         if not user_host or not port_path:
             return None
         user, _, host = user_host.rpartition("@")
-        if not user or host not in allowed_git_service_domains:
+        if not user or host not in allowed_git_service_hostnames:
             return None
 
         path = ""
@@ -677,16 +679,16 @@ def parse_remote_url(url: str, allowed_git_service_domains: list[str] | None = N
         return None
 
 
-def get_allowed_git_service_domains(config: ConfigParser) -> list[str]:
-    """Load allowed git service domains from ini configuration.
+def get_allowed_git_service_hostnames(config: ConfigParser) -> list[str]:
+    """Load allowed git service hostnames from ini configuration.
 
     Some notes for future improvements:
 
     The fact that this method is here is not ideal.
 
     Q: Why do we need this method here in this ``git_url`` module in the first place?
     A: A number of functions in this module also do "URL validation" as part of their logic.
-    This requires loading in the allowed git service domains from the ini config.
+    This requires loading in the allowed git service hostnames from the ini config.
 
     Q: Why don't we use the ``GIT_SERVICES`` list from the ``macaron.slsa_analyzer.git_service``
     instead of having this second place of loading git service configuration?
@@ -697,18 +699,18 @@ def get_allowed_git_service_domains(config: ConfigParser) -> list[str]:
         section_name for section_name in config.sections() if section_name.startswith("git_service")
     ]
 
-    allowed_git_service_domains = []
+    allowed_git_service_hostnames = []
 
     for section_name in git_service_section_names:
         git_service_section = config[section_name]
 
-        domain = git_service_section.get("domain")
-        if not domain:
+        hostname = git_service_section.get("hostname")
+        if not hostname:
             continue
 
-        allowed_git_service_domains.append(domain)
+        allowed_git_service_hostnames.append(hostname)
 
-    return allowed_git_service_domains
+    return allowed_git_service_hostnames
 
 
 def get_repo_dir_name(url: str, sanitize: bool = True) -> str:

tests/slsa_analyzer/git_service/test_gitlab.py

@@ -59,7 +59,7 @@ def test_construct_clone_url_with_token(repo_url: str, clone_url: str) -> None:
         pytest.param(
             """
             [git_service.gitlab.self_hosted]
-            domain = internal.gitlab.org
+            hostname = internal.gitlab.org
             """,
             "https://internal.gitlab.org/owner/repo.git",
             "https://oauth2:[email protected]/owner/repo.git",
@@ -68,7 +68,7 @@ def test_construct_clone_url_with_token(repo_url: str, clone_url: str) -> None:
         pytest.param(
             """
             [git_service.gitlab.self_hosted]
-            domain = internal.gitlab.org
+            hostname = internal.gitlab.org
             """,
             "https://internal.gitlab.org/owner/repo",
             "https://oauth2:[email protected]/owner/repo",
@@ -98,7 +98,7 @@ def test_self_hosted_gitlab_without_env_set(tmp_path: Path) -> None:
     """Test if the ``load_defaults`` method raises error if the required env variable is not set."""
     user_config_input = """
     [git_service.gitlab.self_hosted]
-    domain = internal.gitlab.org
+    hostname = internal.gitlab.org
     """
     user_config_path = os.path.join(tmp_path, "config.ini")
     with open(user_config_path, "w", encoding="utf-8") as user_config_file:
@@ -178,7 +178,7 @@ def test_origin_remote_url_masking(self_hosted_gitlab: Git, expected_origin_url:
     """
     user_config_input = """
     [git_service.gitlab.self_hosted]
-    domain = internal.gitlab.org
+    hostname = internal.gitlab.org
     """
     user_config_path = os.path.join(tmp_path, "config.ini")
     with open(user_config_path, "w", encoding="utf-8") as user_config_file: