feat(scan_results): Add detector_name, detector_group_name and documentation url

salome-voltz · salome-voltz · commit fb15a1c77775 · 2025-04-16T14:31:09.000+02:00
diff --git a/changelog.d/20250416_142945_salome.voltz_scrt_5438_ggshield_for_each_detected_secret_add_a_link_towards_our.md b/changelog.d/20250416_142945_salome.voltz_scrt_5438_ggshield_for_each_detected_secret_add_a_link_towards_our.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 extra information to scan results: detector name, detector group name, and documentation URL.
+
+<!--
+### 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.
+
+-->
diff --git a/pygitguardian/models.py b/pygitguardian/models.py
@@ -216,6 +216,11 @@ class DiffKind(str, Enum):
 
 class PolicyBreakSchema(BaseSchema):
     break_type = fields.String(data_key="type", required=True)
+    detector_name = fields.String(required=True)
+    detector_group_name = fields.String(required=True)
+    documentation_url = fields.String(
+        required=False, load_default=None, dump_default=None
+    )
     policy = fields.String(required=True)
     validity = fields.String(required=False, load_default=None, dump_default=None)
     known_secret = fields.Boolean(required=False, load_default=False, dump_default=None)
@@ -245,9 +250,12 @@ class PolicyBreak(FromDictWithBase):
     def __init__(
         self,
         break_type: str,
+        detector_name: str,
+        detector_group_name: str,
         policy: str,
         validity: str,
         matches: List[Match],
+        documentation_url: Optional[str] = None,
         known_secret: bool = False,
         incident_url: Optional[str] = None,
         is_excluded: bool = False,
@@ -257,6 +265,9 @@ def __init__(
     ) -> None:
         super().__init__()
         self.break_type = break_type
+        self.detector_name = detector_name
+        self.detector_group_name = detector_group_name
+        self.documentation_url = documentation_url
         self.policy = policy
         self.validity = validity
         self.known_secret = known_secret
diff --git a/tests/cassettes/secret.yaml b/tests/cassettes/secret.yaml
@@ -15,52 +15,49 @@ interactions:
         Content-Type:
           - application/json
         User-Agent:
-          - pygitguardian/1.3.4 (Linux;py3.8.10)
+          - pygitguardian/1.20.0 (Linux;py3.10.13)
       method: POST
       uri: https://api.gitguardian.com/v1/scan
     response:
       body:
         string:
-          '{"policy_break_count":1,"policies":["File extensions","Filenames","Secrets
-          detection"],"policy_breaks":[{"type":"Basic Auth String","policy":"Secrets
-          detection","matches":[{"type":"username","match":"jen_barber","index_start":40,"index_end":49,"line_start":2,"line_end":2},{"type":"password","match":"correcthorsebatterystaple","index_start":51,"index_end":75,"line_start":2,"line_end":2},{"type":"host","match":"cake.gitguardian.com","index_start":77,"index_end":96,"line_start":2,"line_end":2}],"validity":"no_checker"}]}'
+          '{"policy_break_count":1,"policies":["Secrets detection"],"policy_breaks":[{"type":"Basic
+          Auth String","detector_name":"basic_auth_string","detector_group_name":"basic_auth_string","documentation_url":"https://docs.gitguardian.com/secrets-detection/secrets-detection-engine/detectors/generics/basic_auth_string","policy":"Secrets
+          detection","matches":[{"type":"username","match":"jen_barber","index_start":45,"index_end":54,"line_start":3,"line_end":3},{"type":"password","match":"correcthorsebatterystaple","index_start":56,"index_end":80,"line_start":3,"line_end":3},{"type":"host","match":"cake.gitguardian.com","index_start":82,"index_end":101,"line_start":3,"line_end":3}],"is_excluded":false,"exclude_reason":null,"incident_url":"","known_secret":false,"validity":"no_checker","diff_kind":null}],"is_diff":false}'
       headers:
-        Access-Control-Expose-Headers:
+        access-control-expose-headers:
           - X-App-Version
-        Allow:
+        allow:
           - POST, OPTIONS
-        Connection:
-          - keep-alive
-        Content-Length:
-          - '523'
-        Content-Type:
+        content-length:
+          - '817'
+        content-type:
           - application/json
-        Date:
-          - Thu, 30 Jun 2022 10:29:37 GMT
-        Referrer-Policy:
+        cross-origin-opener-policy:
+          - same-origin
+        date:
+          - Wed, 16 Apr 2025 09:38:48 GMT
+        referrer-policy:
           - strict-origin-when-cross-origin
-        Server:
-          - nginx
-        Set-Cookie:
-          - AWSALB=1NmYXJP22kKYZ+2ZLAbbWA3Blwfokr7BL9/Vocl6/No3eAYPjl3Yy7M2i99hnGKmsPCbzJ8uuQ+oENgQOmrgBVZ5v3nzY7HvQvo76ABup3ibFUvhc8o9cLFsBgYE;
-            Expires=Thu, 07 Jul 2022 10:29:37 GMT; Path=/
-          - AWSALBCORS=1NmYXJP22kKYZ+2ZLAbbWA3Blwfokr7BL9/Vocl6/No3eAYPjl3Yy7M2i99hnGKmsPCbzJ8uuQ+oENgQOmrgBVZ5v3nzY7HvQvo76ABup3ibFUvhc8o9cLFsBgYE;
-            Expires=Thu, 07 Jul 2022 10:29:37 GMT; Path=/; SameSite=None; Secure
-        Strict-Transport-Security:
+        server:
+          - istio-envoy
+        strict-transport-security:
           - max-age=31536000; includeSubDomains
-        Vary:
+        vary:
           - Cookie
-        X-App-Version:
-          - v2.8.1
-        X-Content-Type-Options:
+        x-app-version:
+          - v2.189.0
+        x-content-type-options:
           - nosniff
           - nosniff
-        X-Frame-Options:
+        x-envoy-upstream-service-time:
+          - '99'
+        x-frame-options:
           - DENY
           - SAMEORIGIN
-        X-Secrets-Engine-Version:
-          - 2.70.0
-        X-XSS-Protection:
+        x-secrets-engine-version:
+          - 2.135.3
+        x-xss-protection:
           - 1; mode=block
       status:
         code: 200
diff --git a/tests/cassettes/secret_validity.yaml b/tests/cassettes/secret_validity.yaml
@@ -15,52 +15,49 @@ interactions:
         Content-Type:
           - application/json
         User-Agent:
-          - pygitguardian/1.3.4 (Linux;py3.8.10)
+          - pygitguardian/1.20.0 (Linux;py3.10.13)
       method: POST
       uri: https://api.gitguardian.com/v1/scan
     response:
       body:
         string:
-          '{"policy_break_count":1,"policies":["File extensions","Filenames","Secrets
-          detection"],"policy_breaks":[{"type":"Basic Auth String","policy":"Secrets
-          detection","matches":[{"type":"username","match":"jen_barber","index_start":40,"index_end":49,"line_start":2,"line_end":2},{"type":"password","match":"correcthorsebatterystaple","index_start":51,"index_end":75,"line_start":2,"line_end":2},{"type":"host","match":"cake.gitguardian.com","index_start":77,"index_end":96,"line_start":2,"line_end":2}],"validity":"no_checker"}]}'
+          '{"policy_break_count":1,"policies":["Secrets detection"],"policy_breaks":[{"type":"Basic
+          Auth String","detector_name":"basic_auth_string","detector_group_name":"basic_auth_string","documentation_url":"https://docs.gitguardian.com/secrets-detection/secrets-detection-engine/detectors/generics/basic_auth_string","policy":"Secrets
+          detection","matches":[{"type":"username","match":"jen_barber","index_start":45,"index_end":54,"line_start":3,"line_end":3},{"type":"password","match":"correcthorsebatterystaple","index_start":56,"index_end":80,"line_start":3,"line_end":3},{"type":"host","match":"cake.gitguardian.com","index_start":82,"index_end":101,"line_start":3,"line_end":3}],"is_excluded":false,"exclude_reason":null,"incident_url":"","known_secret":false,"validity":"no_checker","diff_kind":null}],"is_diff":false}'
       headers:
-        Access-Control-Expose-Headers:
+        access-control-expose-headers:
           - X-App-Version
-        Allow:
+        allow:
           - POST, OPTIONS
-        Connection:
-          - keep-alive
-        Content-Length:
-          - '523'
-        Content-Type:
+        content-length:
+          - '817'
+        content-type:
           - application/json
-        Date:
-          - Thu, 30 Jun 2022 10:29:38 GMT
-        Referrer-Policy:
+        cross-origin-opener-policy:
+          - same-origin
+        date:
+          - Wed, 16 Apr 2025 09:38:50 GMT
+        referrer-policy:
           - strict-origin-when-cross-origin
-        Server:
-          - nginx
-        Set-Cookie:
-          - AWSALB=kwFXju+/3iAAD5HsuV7S8IIopfFRek/dMa1Ud809xgIQGdS6rxMRMsFCBCZpSj0mtddQ4zt018cmw+E3BpsOdamB5Y2XfMMfIVu9deJ/BYWX0519QFcbjfPJoe1B;
-            Expires=Thu, 07 Jul 2022 10:29:38 GMT; Path=/
-          - AWSALBCORS=kwFXju+/3iAAD5HsuV7S8IIopfFRek/dMa1Ud809xgIQGdS6rxMRMsFCBCZpSj0mtddQ4zt018cmw+E3BpsOdamB5Y2XfMMfIVu9deJ/BYWX0519QFcbjfPJoe1B;
-            Expires=Thu, 07 Jul 2022 10:29:38 GMT; Path=/; SameSite=None; Secure
-        Strict-Transport-Security:
+        server:
+          - istio-envoy
+        strict-transport-security:
           - max-age=31536000; includeSubDomains
-        Vary:
+        vary:
           - Cookie
-        X-App-Version:
-          - v2.8.1
-        X-Content-Type-Options:
+        x-app-version:
+          - v2.189.0
+        x-content-type-options:
           - nosniff
           - nosniff
-        X-Frame-Options:
+        x-envoy-upstream-service-time:
+          - '66'
+        x-frame-options:
           - DENY
           - SAMEORIGIN
-        X-Secrets-Engine-Version:
-          - 2.70.0
-        X-XSS-Protection:
+        x-secrets-engine-version:
+          - 2.135.3
+        x-xss-protection:
           - 1; mode=block
       status:
         code: 200
diff --git a/tests/cassettes/with_breaks.yaml b/tests/cassettes/with_breaks.yaml
@@ -16,28 +16,29 @@ interactions:
         Content-Type:
           - application/json
         User-Agent:
-          - pygitguardian/1.19.0 (Linux;py3.10.12)
+          - pygitguardian/1.20.0 (Linux;py3.10.13)
       method: POST
       uri: https://api.gitguardian.com/v1/multiscan
     response:
       body:
         string:
           '[{"policy_break_count":1,"policies":["Secrets detection"],"policy_breaks":[{"type":"Basic
-          Auth String","policy":"Secrets detection","matches":[{"type":"username","match":"jen_barber","index_start":45,"index_end":54,"line_start":3,"line_end":3},{"type":"password","match":"correcthorsebatterystaple","index_start":56,"index_end":80,"line_start":3,"line_end":3},{"type":"host","match":"cake.gitguardian.com","index_start":82,"index_end":101,"line_start":3,"line_end":3}],"is_excluded":false,"exclude_reason":null,"incident_url":"https://dashboard.gitguardian.com/workspace/8/incidents/10114685","known_secret":true,"validity":"no_checker","diff_kind":null}],"is_diff":false},{"policy_break_count":0,"policies":["Secrets
+          Auth String","detector_name":"basic_auth_string","detector_group_name":"basic_auth_string","documentation_url":"https://docs.gitguardian.com/secrets-detection/secrets-detection-engine/detectors/generics/basic_auth_string","policy":"Secrets
+          detection","matches":[{"type":"username","match":"jen_barber","index_start":45,"index_end":54,"line_start":3,"line_end":3},{"type":"password","match":"correcthorsebatterystaple","index_start":56,"index_end":80,"line_start":3,"line_end":3},{"type":"host","match":"cake.gitguardian.com","index_start":82,"index_end":101,"line_start":3,"line_end":3}],"is_excluded":false,"exclude_reason":null,"incident_url":"","known_secret":false,"validity":"no_checker","diff_kind":null}],"is_diff":false},{"policy_break_count":0,"policies":["Secrets
           detection"],"policy_breaks":[],"is_diff":false}]'
       headers:
         access-control-expose-headers:
           - X-App-Version
         allow:
           - POST, OPTIONS
         content-length:
-          - '766'
+          - '912'
         content-type:
           - application/json
         cross-origin-opener-policy:
           - same-origin
         date:
-          - Mon, 24 Feb 2025 12:49:30 GMT
+          - Wed, 16 Apr 2025 09:42:21 GMT
         referrer-policy:
           - strict-origin-when-cross-origin
         server:
@@ -47,17 +48,17 @@ interactions:
         vary:
           - Cookie
         x-app-version:
-          - v2.155.0
+          - v2.189.0
         x-content-type-options:
           - nosniff
           - nosniff
         x-envoy-upstream-service-time:
-          - '490'
+          - '88'
         x-frame-options:
           - DENY
           - SAMEORIGIN
         x-secrets-engine-version:
-          - 2.132.2
+          - 2.135.3
         x-xss-protection:
           - 1; mode=block
       status:
diff --git a/tests/test_client.py b/tests/test_client.py
@@ -581,6 +581,9 @@ def test_multiscan_parameters(client: GGClient, ignore_known_secrets, all_secret
                 "policy_breaks": [
                     {
                         "type": "break",
+                        "detector_name": "break",
+                        "detector_group_name": "break",
+                        "documentation_url": None,
                         "policy": "mypol",
                         "matches": [
                             {
diff --git a/tests/test_models.py b/tests/test_models.py
@@ -95,6 +95,9 @@ def test_document_handle_surrogates(self):
                             "policy_breaks": [
                                 {
                                     "type": "break",
+                                    "detector_name": "hello",
+                                    "detector_group_name": "hello",
+                                    "documentation_url": None,
                                     "policy": "mypol",
                                     "matches": [
                                         {
@@ -114,6 +117,9 @@ def test_document_handle_surrogates(self):
                 PolicyBreak,
                 {
                     "type": "hello",
+                    "detector_name": "hello",
+                    "detector_group_name": "hello",
+                    "documentation_url": None,
                     "policy": "hello",
                     "validity": "hey",
                     "matches": [{"match": "hello", "type": "hello"}],
@@ -124,6 +130,9 @@ def test_document_handle_surrogates(self):
                 PolicyBreak,
                 {
                     "type": "hello",
+                    "detector_name": "hello",
+                    "detector_group_name": "hello",
+                    "documentation_url": None,
                     "policy": "hello",
                     "validity": "hey",
                     "known_secret": True,
@@ -136,6 +145,9 @@ def test_document_handle_surrogates(self):
                 PolicyBreak,
                 {
                     "type": "hello",
+                    "detector_name": "hello",
+                    "detector_group_name": "hello",
+                    "documentation_url": None,
                     "policy": "hello",
                     "validity": "hey",
                     "known_secret": True,
@@ -150,6 +162,9 @@ def test_document_handle_surrogates(self):
                 PolicyBreak,
                 {
                     "type": "hello",
+                    "detector_name": "hello",
+                    "detector_group_name": "hello",
+                    "documentation_url": None,
                     "policy": "hello",
                     "validity": "hey",
                     "known_secret": True,
@@ -165,6 +180,9 @@ def test_document_handle_surrogates(self):
                 PolicyBreak,
                 {
                     "type": "hello",
+                    "detector_name": "hello",
+                    "detector_group_name": "hello",
+                    "documentation_url": None,
                     "policy": "hello",
                     "validity": "hey",
                     "known_secret": True,
@@ -482,6 +500,9 @@ def test_policy_break_known_secret_field(self, known_secret):
         """
         data = {
             "type": "hello",
+            "detector_name": "hello",
+            "detector_group_name": "hello",
+            "documentation_url": None,
             "policy": "hello",
             "validity": "hey",
             "matches": [{"match": "hello", "type": "hello"}],

Original file line number	Diff line number	Diff line change
`@@ -581,6 +581,9 @@ def test_multiscan_parameters(client: GGClient, ignore_known_secrets, all_secret`
`581`	`581`	`"policy_breaks": [`
`582`	`582`	`{`
`583`	`583`	`"type": "break",`
	`584`	`+ "detector_name": "break",`
	`585`	`+ "detector_group_name": "break",`
	`586`	`+ "documentation_url": None,`
`584`	`587`	`"policy": "mypol",`
`585`	`588`	`"matches": [`
`586`	`589`	`{`