python-gitlab · JohnVillalovos · Oct 13, 2023 · May 1, 2022 · Oct 12, 2023
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -406,6 +406,27 @@ user. For example:
 
    p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')
 
+Logging
+=======
+
+To enable debug logging from the underlying ``requests`` and ``http.client`` calls,
+you can use ``enable_debug()`` on your ``Gitlab`` instance. For example:
+
+.. code-block:: python
+
+   import os
+   import gitlab
+
+   gl = gitlab.Gitlab(private_token=os.getenv("GITLAB_TOKEN"))
+   gl.enable_debug()
+
+By default, python-gitlab will mask the token used for authentication in logging output.
+If you'd like to debug credentials sent to the API, you can disable masking explicitly:
+
+.. code-block:: python
+
+   gl.enable_debug(mask_credentials=False)
+
 .. _object_attributes:
 
 Attributes in updated objects

diff --git a/gitlab/client.py b/gitlab/client.py
@@ -517,18 +517,39 @@ def _set_auth_info(self) -> None:
                 self.http_username, self.http_password
             )
 
-    @staticmethod
-    def enable_debug() -> None:
+    def enable_debug(self, mask_credentials: bool = True) -> None:
         import logging
-        from http.client import HTTPConnection  # noqa
+        from http import client
 
-        HTTPConnection.debuglevel = 1
+        client.HTTPConnection.debuglevel = 1
         logging.basicConfig()
-        logging.getLogger().setLevel(logging.DEBUG)
+        logger = logging.getLogger()
+        logger.setLevel(logging.DEBUG)
+
+        httpclient_log = logging.getLogger("http.client")
+        httpclient_log.propagate = True
+        httpclient_log.setLevel(logging.DEBUG)
+
         requests_log = logging.getLogger("requests.packages.urllib3")
         requests_log.setLevel(logging.DEBUG)
         requests_log.propagate = True
 
+        # shadow http.client prints to log()
+        # https://stackoverflow.com/a/16337639
+        def print_as_log(*args: Any) -> None:
+            httpclient_log.log(logging.DEBUG, " ".join(args))
+
+        setattr(client, "print", print_as_log)
+
+        if not mask_credentials:
+            return
+
+        token = self.private_token or self.oauth_token or self.job_token
+        handler = logging.StreamHandler()
+        handler.setFormatter(utils.MaskingFormatter(masked=token))
+        logger.handlers.clear()
+        logger.addHandler(handler)
+
     def _get_session_opts(self) -> Dict[str, Any]:
         return {
             "headers": self.headers.copy(),

diff --git a/gitlab/utils.py b/gitlab/utils.py
@@ -1,9 +1,10 @@
 import email.message
+import logging
 import pathlib
 import traceback
 import urllib.parse
 import warnings
-from typing import Any, Callable, Dict, Iterator, Optional, Tuple, Type, Union
+from typing import Any, Callable, Dict, Iterator, Literal, Optional, Tuple, Type, Union
 
 import requests
 
@@ -22,6 +23,31 @@ def get_content_type(content_type: Optional[str]) -> str:
     return message.get_content_type()
 
 
+class MaskingFormatter(logging.Formatter):
+    """A logging formatter that can mask credentials"""
+
+    def __init__(
+        self,
+        fmt: Optional[str] = logging.BASIC_FORMAT,
+        datefmt: Optional[str] = None,
+        style: Literal["%", "{", "$"] = "%",
+        validate: bool = True,
+        masked: Optional[str] = None,
+    ) -> None:
+        super().__init__(fmt, datefmt, style, validate)
+        self.masked = masked
+
+    def _filter(self, entry: str) -> str:
+        if not self.masked:
+            return entry
+
+        return entry.replace(self.masked, "[MASKED]")
+
+    def format(self, record: logging.LogRecord) -> str:
+        original = logging.Formatter.format(self, record)
+        return self._filter(original)
+
+
 def response_content(
     response: requests.Response,
     streamed: bool,

diff --git a/tests/functional/cli/test_cli.py b/tests/functional/cli/test_cli.py
@@ -198,3 +198,12 @@ def test_cli_display_without_fields_warns(gitlab_cli, project):
 
     assert "No default fields to show" in ret.stdout
     assert "merged_yaml" not in ret.stdout
+
+
+def test_cli_does_not_print_token(gitlab_cli, gitlab_token):
+    ret = gitlab_cli(["--debug", "current-user", "get"])
+    assert ret.success
+
+    assert gitlab_token not in ret.stdout
+    assert gitlab_token not in ret.stderr
+    assert "[MASKED]" in ret.stderr
diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py
@@ -1,4 +1,5 @@
 import json
+import logging
 import warnings
 
 import pytest
@@ -197,3 +198,19 @@ def test_transform_types_not_params_array():
     assert new_data is not data
     assert new_data == data
     assert files == {}
+
+
+def test_masking_formatter_masks_token(capsys: pytest.CaptureFixture):
+    token = "glpat-private-token"
+
+    logger = logging.getLogger()
+    handler = logging.StreamHandler()
+    handler.setFormatter(utils.MaskingFormatter(masked=token))
+    logger.handlers.clear()
+    logger.addHandler(handler)
+
+    logger.info(token)
+    captured = capsys.readouterr()
+
+    assert "[MASKED]" in captured.err
+    assert token not in captured.err