feat(honeytokens): add GGClient.create_honeytoken_with_context method

Author: gg-cedric

changelog.d/20240124_104631_cedric.bosselut.md

@@ -0,0 +1,41 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+
+### Added
+
+- Add `GGClient.create_honeytoken_with_context()` method
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

pygitguardian/client.py

@@ -30,6 +30,7 @@
     DocumentSchema,
     HealthCheckResponse,
     HoneytokenResponse,
+    HoneytokenWithContextResponse,
     JWTResponse,
     JWTService,
     MultiScanResult,
@@ -513,6 +514,54 @@ def create_honeytoken(
             result.status_code = resp.status_code
         return result
 
+    def create_honeytoken_with_context(
+        self,
+        *,
+        name: str,
+        type_: str,
+        description: Optional[str] = None,
+        project_extensions: List[str] = [],
+        filename: Optional[str] = None,
+        language: Optional[str] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Union[Detail, HoneytokenWithContextResponse]:
+        """
+        Create a honeytoken via the /honeytokens/with-context endpoint of the API,
+        the honeytoken is inserted in a file.
+
+        :param name: the honeytoken name
+        :param type_: the honeytoken type
+        :param description: the honeytoken description
+        :param project_extensions: list of file extensions in the project
+        :param filename: name of requested file
+        :param language: language of requested file
+        :param extra_headers: additional headers to add to the request
+        :return: Detail or Honeytoken with context response and status code
+        """
+        try:
+            resp = self.post(
+                endpoint="honeytokens/with-context",
+                extra_headers=extra_headers,
+                data={
+                    "name": name,
+                    "type": type_,
+                    "description": description,
+                    "project_extensions": ",".join(project_extensions),
+                    "filename": filename,
+                    "language": language,
+                },
+            )
+        except requests.exceptions.ReadTimeout:
+            result = Detail("The request timed out.")
+            result.status_code = 504
+        else:
+            if resp.ok:
+                result = HoneytokenWithContextResponse.from_dict(resp.json())
+            else:
+                result = load_detail(resp)
+            result.status_code = resp.status_code
+        return result
+
     def iac_directory_scan(
         self,
         directory: Path,

pygitguardian/models.py

@@ -616,6 +616,65 @@ def __repr__(self) -> str:
         return f"honeytoken:{self.id} {self.name}"
 
 
+class HoneytokenWithContextResponseSchema(BaseSchema):
+    content = fields.String()
+    filename = fields.String()
+    language = fields.String()
+    suggested_commit_message = fields.String()
+    honeytoken_id = fields.UUID()
+    gitguardian_url = fields.URL()
+
+    @post_load
+    def make_honeytoken_with_context_response(
+        self, data: Dict[str, Any], **kwargs: Any
+    ) -> "HoneytokenWithContextResponse":
+        return HoneytokenWithContextResponse(**data)
+
+
+class HoneytokenWithContextResponse(Base, FromDictMixin):
+    """
+    honeytoken creation with context in the GitGuardian API.
+    Allows users to get a file where a new honeytoken is.
+    Example:
+        {
+            "content": "def return_aws_credentials():\n \
+                            aws_access_key_id = XXXXXXXX\n \
+                            aws_secret_access_key = XXXXXXXX\n \
+                            aws_region = us-west-2",\n \
+                            return (aws_access_key_id, aws_secret_access_key, aws_region)\n",
+            "filename": "aws.py",
+            "language": "python",
+            "suggested_commit_message": "Add AWS credentials",
+            "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
+            "gitguardian_url":
+                "https://dashboard.gitguardian.com/workspace/1/honeytokens/d45a123f-b15d-4fea-abf6-ff2a8479de5b",
+        }
+    """
+
+    SCHEMA = HoneytokenWithContextResponseSchema()
+
+    def __init__(
+        self,
+        content: str,
+        filename: str,
+        language: str,
+        suggested_commit_message: str,
+        honeytoken_id: UUID,
+        gitguardian_url: str,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__()
+        self.content = content
+        self.filename = filename
+        self.language = language
+        self.suggested_commit_message = suggested_commit_message
+        self.honeytoken_id = honeytoken_id
+        self.gitguardian_url = gitguardian_url
+
+    def __repr__(self) -> str:
+        return f"honeytoken_context:{self.filename}"
+
+
 class HealthCheckResponseSchema(BaseSchema):
     detail = fields.String(allow_none=False)
     status_code = fields.Int(allow_none=False)

tests/test_client.py

@@ -22,6 +22,7 @@
 from pygitguardian.models import (
     Detail,
     HoneytokenResponse,
+    HoneytokenWithContextResponse,
     JWTResponse,
     JWTService,
     MultiScanResult,
@@ -818,6 +819,74 @@ def test_create_honeytoken_error(
     assert isinstance(result, Detail)
 
 
+@responses.activate
+def test_create_honeytoken_with_context(
+    client: GGClient,
+):
+    """
+    GIVEN a ggclient
+    WHEN calling create_honeytoken_with_context with parameters
+    THEN the parameters are passed in the request
+    AND the returned honeytoken use the parameters
+    """
+    mock_response = responses.post(
+        url=client._url_from_endpoint("honeytokens/with-context", "v1"),
+        content_type="application/json",
+        status=201,
+        json={
+            "content": "def return_aws_credentials():\n \
+                            aws_access_key_id = XXXXXXXX\n \
+                            aws_secret_access_key = XXXXXXXX\n \
+                            aws_region = us-west-2,\n \
+                            return (aws_access_key_id, aws_secret_access_key, aws_region)\n",
+            "filename": "aws.py",
+            "language": "python",
+            "suggested_commit_message": "Add AWS credentials",
+            "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
+            "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/honeytokens/d45a123f-b15d-4fea-abf6-ff2a8479de5b",  # noqa: E501
+        },
+    )
+
+    result = client.create_honeytoken_with_context(
+        name="honeytoken A",
+        description="honeytoken used in the repository AA",
+        type_="AWS",
+        filename="aws.yaml",
+    )
+
+    assert mock_response.call_count == 1
+    assert isinstance(result, HoneytokenWithContextResponse)
+
+
+@responses.activate
+def test_create_honeytoken_with_context_error(
+    client: GGClient,
+):
+    """
+    GIVEN a ggclient
+    WHEN calling create_honeytoken_with_context with parameters without the right access
+    THEN I get a Detail object containing the error detail
+    """
+    mock_response = responses.post(
+        url=client._url_from_endpoint("honeytokens/with-context", "v1"),
+        content_type="application/json",
+        status=400,
+        json={
+            "detail": "Not authorized",
+        },
+    )
+
+    result = client.create_honeytoken_with_context(
+        name="honeytoken A",
+        description="honeytoken used in the repository AA",
+        type_="AWS",
+        filename="aws.yaml",
+    )
+
+    assert mock_response.call_count == 1
+    assert isinstance(result, Detail)
+
+
 @responses.activate
 def test_create_jwt(
     client: GGClient,

tests/test_models.py

@@ -10,6 +10,8 @@
     HealthCheckResponseSchema,
     HoneytokenResponse,
     HoneytokenResponseSchema,
+    HoneytokenWithContextResponse,
+    HoneytokenWithContextResponseSchema,
     Match,
     MatchSchema,
     MultiScanResult,
@@ -159,6 +161,22 @@ def test_document_handle_surrogates(self):
                     "tags": ["publicly_exposed"],
                 },
             ),
+            (
+                HoneytokenWithContextResponseSchema,
+                HoneytokenWithContextResponse,
+                {
+                    "content": "def return_aws_credentials():\n \
+                                    aws_access_key_id = XXXXXXXX\n \
+                                    aws_secret_access_key = XXXXXXXX\n \
+                                    aws_region = us-west-2\n \
+                                    return (aws_access_key_id, aws_secret_access_key, aws_region)\n",
+                    "filename": "aws.py",
+                    "language": "python",
+                    "suggested_commit_message": "Add AWS credentials",
+                    "honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
+                    "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/honeytokens/d45a123f-b15d-4fea-abf6-ff2a8479de5b",  # noqa: E501
+                },
+            ),
         ],
     )
     def test_schema_loads(self, schema_klass, expected_klass, instance_data):