Document secmon-public-api rule-health, batch-migrations, baseline, and matching-signals endpoints

.generator/schemas/v2/openapi.yaml

@@ -68731,6 +68731,68 @@ components:
       type: string
       x-enum-varnames:
         - MANAGED_ORGS
+    MatchingSignalAttributes:
+      description: Attributes of a matching security signal.
+      properties:
+        event_tracker_id:
+          description: The tracker ID linking the signal back to the originating event. Distinct from `id`, which identifies the matching signal itself.
+          example: AAAAAWgOAX0mtsWfeQAAAABzX1RyYWNrZXJfMTIzNDU2Nzg5MA
+          type: string
+        severity:
+          description: The severity of the signal.
+          example: high
+          type: string
+        title:
+          description: The title of the signal.
+          example: Unusual login activity detected
+          type: string
+        trigger_time_ms:
+          description: The Unix timestamp (in milliseconds) at which the signal was triggered.
+          example: 1707393746000
+          format: int64
+          type: integer
+      required:
+        - event_tracker_id
+        - severity
+        - title
+        - trigger_time_ms
+      type: object
+    MatchingSignalData:
+      description: A security signal that matches the queried event.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/MatchingSignalAttributes"
+        id:
+          description: The ID of the matching signal.
+          example: AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA
+          type: string
+        type:
+          $ref: "#/components/schemas/MatchingSignalType"
+      required:
+        - id
+        - type
+        - attributes
+      type: object
+    MatchingSignalType:
+      default: matching_signal
+      description: The type of the resource. The value should always be `matching_signal`.
+      enum:
+        - matching_signal
+      example: matching_signal
+      type: string
+      x-enum-varnames:
+        - MATCHING_SIGNAL
+    MatchingSignalsResponse:
+      description: Response containing the list of security signals matching an event.
+      properties:
+        data:
+          description: Array of matching signals.
+          items:
+            $ref: "#/components/schemas/MatchingSignalData"
+          type: array
+      required:
+        - data
+      type: object
     MaxSessionDurationType:
       description: Data type of a maximum session duration update.
       enum: [max_session_duration]
@@ -211106,6 +211168,63 @@ paths:
       x-unstable: |-
         **Note**: This endpoint is in Preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
+  /api/v2/security_monitoring/events/{event_id}/matching_signals:
+    get:
+      description: Returns the list of security signals that match a given event on the given track.
+      operationId: GetMatchingSignals
+      parameters:
+        - description: The ID of the event to find matching signals for.
+          in: path
+          name: event_id
+          required: true
+          schema:
+            type: string
+        - description: The product track that the event belongs to.
+          in: query
+          name: track
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    data:
+                      - attributes:
+                          event_tracker_id: AAAAAWgOAX0mtsWfeQAAAABzX1RyYWNrZXJfMTIzNDU2Nzg5MA
+                          severity: high
+                          title: Unusual login activity detected
+                          trigger_time_ms: 1707393746000
+                        id: AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA
+                        type: matching_signal
+              schema:
+                $ref: "#/components/schemas/MatchingSignalsResponse"
+          description: OK
+        "400":
+          $ref: "#/components/responses/BadRequestResponse"
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_signals_read
+      summary: Get signals matching an event
+      tags: ["Security Monitoring"]
+      x-permission:
+        operator: OR
+        permissions:
+          - security_monitoring_signals_read
+      x-unstable: |-
+        **Note**: This endpoint is in preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/security_monitoring/rules:
     get:
       description: List rules.

examples/v2/security-monitoring/GetMatchingSignals.py

@@ -0,0 +1,17 @@
+"""
+Get signals matching an event returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
+
+configuration = Configuration()
+configuration.unstable_operations["get_matching_signals"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = SecurityMonitoringApi(api_client)
+    response = api_instance.get_matching_signals(
+        event_id="event_id",
+        track="track",
+    )
+
+    print(response)

src/datadog_api_client/configuration.py

@@ -404,6 +404,7 @@ def __init__(
                 "v2.get_finding": False,
                 "v2.get_historical_job": False,
                 "v2.get_indicator_of_compromise": False,
+                "v2.get_matching_signals": False,
                 "v2.get_rule_version_history": False,
                 "v2.get_secrets_rules": False,
                 "v2.get_security_findings_automation_default_inbox_rule": False,

src/datadog_api_client/v2/api/security_monitoring_api.py

@@ -197,6 +197,7 @@
 )
 from datadog_api_client.v2.model.entity_context_response import EntityContextResponse
 from datadog_api_client.v2.model.single_entity_context_response import SingleEntityContextResponse
+from datadog_api_client.v2.model.matching_signals_response import MatchingSignalsResponse
 from datadog_api_client.v2.model.security_monitoring_list_rules_response import SecurityMonitoringListRulesResponse
 from datadog_api_client.v2.model.security_monitoring_rule_sort import SecurityMonitoringRuleSort
 from datadog_api_client.v2.model.security_monitoring_rule_response import SecurityMonitoringRuleResponse
@@ -2063,6 +2064,35 @@ def __init__(self, api_client=None):
             api_client=api_client,
         )
 
+        self._get_matching_signals_endpoint = _Endpoint(
+            settings={
+                "response_type": (MatchingSignalsResponse,),
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
+                "endpoint_path": "/api/v2/security_monitoring/events/{event_id}/matching_signals",
+                "operation_id": "get_matching_signals",
+                "http_method": "GET",
+                "version": "v2",
+            },
+            params_map={
+                "event_id": {
+                    "required": True,
+                    "openapi_types": (str,),
+                    "attribute": "event_id",
+                    "location": "path",
+                },
+                "track": {
+                    "required": True,
+                    "openapi_types": (str,),
+                    "attribute": "track",
+                    "location": "query",
+                },
+            },
+            headers_map={
+                "accept": ["application/json"],
+            },
+            api_client=api_client,
+        )
+
         self._get_resource_evaluation_filters_endpoint = _Endpoint(
             settings={
                 "response_type": (GetResourceEvaluationFiltersResponse,),
@@ -6517,6 +6547,28 @@ def get_investigation_log_queries_matching_signal(
 
         return self._get_investigation_log_queries_matching_signal_endpoint.call_with_http_info(**kwargs)
 
+    def get_matching_signals(
+        self,
+        event_id: str,
+        track: str,
+    ) -> MatchingSignalsResponse:
+        """Get signals matching an event.
+
+        Returns the list of security signals that match a given event on the given track.
+
+        :param event_id: The ID of the event to find matching signals for.
+        :type event_id: str
+        :param track: The product track that the event belongs to.
+        :type track: str
+        :rtype: MatchingSignalsResponse
+        """
+        kwargs: Dict[str, Any] = {}
+        kwargs["event_id"] = event_id
+
+        kwargs["track"] = track
+
+        return self._get_matching_signals_endpoint.call_with_http_info(**kwargs)
+
     def get_resource_evaluation_filters(
         self,
         *,

src/datadog_api_client/v2/model/matching_signal_attributes.py

@@ -0,0 +1,51 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+class MatchingSignalAttributes(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        return {
+            "event_tracker_id": (str,),
+            "severity": (str,),
+            "title": (str,),
+            "trigger_time_ms": (int,),
+        }
+
+    attribute_map = {
+        "event_tracker_id": "event_tracker_id",
+        "severity": "severity",
+        "title": "title",
+        "trigger_time_ms": "trigger_time_ms",
+    }
+
+    def __init__(self_, event_tracker_id: str, severity: str, title: str, trigger_time_ms: int, **kwargs):
+        """
+        Attributes of a matching security signal.
+
+        :param event_tracker_id: The tracker ID linking the signal back to the originating event. Distinct from ``id`` , which identifies the matching signal itself.
+        :type event_tracker_id: str
+
+        :param severity: The severity of the signal.
+        :type severity: str
+
+        :param title: The title of the signal.
+        :type title: str
+
+        :param trigger_time_ms: The Unix timestamp (in milliseconds) at which the signal was triggered.
+        :type trigger_time_ms: int
+        """
+        super().__init__(kwargs)
+
+        self_.event_tracker_id = event_tracker_id
+        self_.severity = severity
+        self_.title = title
+        self_.trigger_time_ms = trigger_time_ms

src/datadog_api_client/v2/model/matching_signal_data.py

@@ -0,0 +1,54 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.matching_signal_attributes import MatchingSignalAttributes
+    from datadog_api_client.v2.model.matching_signal_type import MatchingSignalType
+
+
+class MatchingSignalData(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.matching_signal_attributes import MatchingSignalAttributes
+        from datadog_api_client.v2.model.matching_signal_type import MatchingSignalType
+
+        return {
+            "attributes": (MatchingSignalAttributes,),
+            "id": (str,),
+            "type": (MatchingSignalType,),
+        }
+
+    attribute_map = {
+        "attributes": "attributes",
+        "id": "id",
+        "type": "type",
+    }
+
+    def __init__(self_, attributes: MatchingSignalAttributes, id: str, type: MatchingSignalType, **kwargs):
+        """
+        A security signal that matches the queried event.
+
+        :param attributes: Attributes of a matching security signal.
+        :type attributes: MatchingSignalAttributes
+
+        :param id: The ID of the matching signal.
+        :type id: str
+
+        :param type: The type of the resource. The value should always be ``matching_signal``.
+        :type type: MatchingSignalType
+        """
+        super().__init__(kwargs)
+
+        self_.attributes = attributes
+        self_.id = id
+        self_.type = type

src/datadog_api_client/v2/model/matching_signal_type.py

@@ -0,0 +1,35 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class MatchingSignalType(ModelSimple):
+    """
+    The type of the resource. The value should always be `matching_signal`.
+
+    :param value: If omitted defaults to "matching_signal". Must be one of ["matching_signal"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "matching_signal",
+    }
+    MATCHING_SIGNAL: ClassVar["MatchingSignalType"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+MatchingSignalType.MATCHING_SIGNAL = MatchingSignalType("matching_signal")