feat(ai): route to send number of secrets detected by ai agent hook

Author: pbeslin-gg

changelog.d/20260622_174356_paul.beslin-ext_ai_hook_secrets_count.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
+
+- New endpoint log_secret_block to send metadata when a ggshield AI agent hook catches a secret.
+
+<!--
+### 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

@@ -49,6 +49,7 @@
     QuotaResponse,
     RemediationMessages,
     ScanResult,
+    SecretBlockRequest,
     SecretIncident,
     SecretScanPreferences,
     ServerMetadata,
@@ -1261,6 +1262,25 @@ def log_mcp_activities_bulk(
         obj.status_code = response.status_code
         return obj
 
+    def log_secret_block(
+        self,
+        block: SecretBlockRequest,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Optional[Detail]:
+        """Report a secret blocked by an AI hook.
+
+        The endpoint returns 204 No Content on success, so this returns None on
+        success and a Detail on error.
+        """
+        response = self.post(
+            endpoint="agent-activity/secret-block",
+            data=block.to_dict(),
+            extra_headers=extra_headers,
+        )
+
+        if not is_delete_ok(response):
+            return load_detail(response)
+
     def send_agent_activity(
         self,
         events: List[Dict[str, Any]],

pygitguardian/models.py

@@ -1837,6 +1837,34 @@ def make_mcp_activity_request(self, data: Dict[str, Any], **kwargs: Any):
 MCPActivityRequest.SCHEMA = MCPActivityRequestSchema()
 
 
+@dataclass
+class SecretBlockRequest(FromDictMixin, ToDictMixin):
+    user: UserInfo
+    tool: str
+    agent: str
+    cwd: str
+    secret_count: int
+    detectors: List[str] = field(default_factory=list)
+    timestamp: Optional[datetime] = None
+
+
+class SecretBlockRequestSchema(BaseSchema):
+    user = fields.Nested(UserInfoSchema, required=True)
+    tool = fields.Str(required=True)
+    agent = fields.Str(required=True)
+    cwd = fields.Str(required=True)
+    secret_count = fields.Int(required=True)
+    detectors = fields.List(fields.Str(), load_default=[], dump_default=[])
+    timestamp = fields.DateTime(load_default=None, allow_none=True)
+
+    @post_load
+    def make_secret_block_request(self, data: Dict[str, Any], **kwargs: Any):
+        return SecretBlockRequest(**data)
+
+
+SecretBlockRequest.SCHEMA = SecretBlockRequestSchema()
+
+
 @dataclass
 class MCPActivityResponse(FromDictWithBase):
     allowed: bool

tests/cassettes/test_log_secret_block.yaml

@@ -0,0 +1,39 @@
+interactions:
+  - request:
+      body: '{"user": {"hostname": "toto-laptop", "username": "toto", "machine_id":
+        "1234567890", "user_email": "toto@gitguardian.com"}, "tool": "Write", "agent":
+        "claude", "cwd": "/home/user/project", "secret_count": 2, "detectors": ["AWS
+        Keys", "GitHub Token"]}'
+      headers:
+        Accept:
+          - '*/*'
+        Accept-Encoding:
+          - gzip, deflate
+        Connection:
+          - keep-alive
+        Content-Type:
+          - application/json
+        User-Agent:
+          - pygitguardian/1.29.0 (Linux;py3.11.15)
+      method: POST
+      uri: https://api.gitguardian.com/v1/agent-activity/secret-block
+    response:
+      body:
+        string: ''
+      headers:
+        Allow:
+          - POST, OPTIONS
+        Connection:
+          - keep-alive
+        Content-Length:
+          - '0'
+        Date:
+          - Tue, 21 Apr 2026 09:57:44 GMT
+        Server:
+          - nginx/1.29.1
+        X-App-Version:
+          - dev
+      status:
+        code: 204
+        message: No Content
+    version: 1

tests/test_client.py

@@ -53,6 +53,7 @@
     MultiScanResult,
     QuotaResponse,
     ScanResult,
+    SecretBlockRequest,
     Source,
     SourceParameters,
     Team,
@@ -1974,6 +1975,32 @@ def test_log_mcp_activity(client: GGClient):
     assert isinstance(result, MCPActivityResponse), result
 
 
+@my_vcr.use_cassette("test_log_secret_block.yaml", ignore_localhost=False)
+def test_log_secret_block(client: GGClient):
+    """
+    GIVEN a client
+    WHEN calling POST /agent-activity/secret-block endpoint
+    THEN the secret block is logged and None is returned on success (204)
+    """
+    result = client.log_secret_block(
+        SecretBlockRequest(
+            user=UserInfo(
+                user_email="toto@gitguardian.com",
+                hostname="toto-laptop",
+                username="toto",
+                machine_id="1234567890",
+            ),
+            tool="Write",
+            agent="claude",
+            cwd="/home/user/project",
+            secret_count=2,
+            detectors=["AWS Keys", "GitHub Token"],
+        )
+    )
+
+    assert result is None, result
+
+
 @my_vcr.use_cassette(
     "test_log_mcp_activities_bulk_posts_to_correct_endpoint.yaml",
     ignore_localhost=False,

tests/test_models.py

@@ -32,6 +32,8 @@
     QuotaSchema,
     ScanResult,
     ScanResultSchema,
+    SecretBlockRequest,
+    SecretBlockRequestSchema,
     SecretIncident,
     SecretIncidentSchema,
     SecretOccurrence,
@@ -528,6 +530,23 @@ def test_document_handle_surrogates(self):
                     "reason": "test",
                 },
             ),
+            (
+                SecretBlockRequestSchema,
+                SecretBlockRequest,
+                {
+                    "user": {
+                        "user_email": "toto@gitguardian.com",
+                        "machine_id": "1234567890",
+                        "hostname": "toto-laptop",
+                        "username": "toto",
+                    },
+                    "tool": "Write",
+                    "agent": "claude",
+                    "cwd": "/home/user/project",
+                    "secret_count": 2,
+                    "detectors": ["AWS Keys", "GitHub Token"],
+                },
+            ),
             (
                 AgentActivityResponseSchema,
                 AgentActivityResponse,