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

.generator/schemas/v2/openapi.yaml

@@ -68667,6 +68667,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]
@@ -209832,6 +209894,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: AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA
+                          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.java

@@ -0,0 +1,25 @@
+// Get signals matching an event returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.SecurityMonitoringApi;
+import com.datadog.api.client.v2.model.MatchingSignalsResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.getMatchingSignals", true);
+    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
+
+    try {
+      MatchingSignalsResponse result = apiInstance.getMatchingSignals("event_id", "track");
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling SecurityMonitoringApi#getMatchingSignals");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/ApiClient.java

@@ -1057,6 +1057,7 @@ public class ApiClient {
           put("v2.getFinding", false);
           put("v2.getHistoricalJob", false);
           put("v2.getIndicatorOfCompromise", false);
+          put("v2.getMatchingSignals", false);
           put("v2.getRuleVersionHistory", false);
           put("v2.getSecretsRules", false);
           put("v2.getSecurityFindingsAutomationDefaultInboxRule", false);

src/main/java/com/datadog/api/client/v2/api/SecurityMonitoringApi.java

@@ -70,6 +70,7 @@
 import com.datadog.api.client.v2.model.ListSecurityFindingsResponse;
 import com.datadog.api.client.v2.model.ListVulnerabilitiesResponse;
 import com.datadog.api.client.v2.model.ListVulnerableAssetsResponse;
+import com.datadog.api.client.v2.model.MatchingSignalsResponse;
 import com.datadog.api.client.v2.model.MuteFindingsRequest;
 import com.datadog.api.client.v2.model.MuteFindingsResponse;
 import com.datadog.api.client.v2.model.MuteRuleCreateRequest;
@@ -12393,6 +12394,186 @@ public SecurityMonitoringSignalSuggestedActionsResponse getInvestigationLogQueri
         new GenericType<SecurityMonitoringSignalSuggestedActionsResponse>() {});
   }
 
+  /**
+   * Get signals matching an event.
+   *
+   * <p>See {@link #getMatchingSignalsWithHttpInfo}.
+   *
+   * @param eventId The ID of the event to find matching signals for. (required)
+   * @param track The product track that the event belongs to. (required)
+   * @return MatchingSignalsResponse
+   * @throws ApiException if fails to make API call
+   */
+  public MatchingSignalsResponse getMatchingSignals(String eventId, String track)
+      throws ApiException {
+    return getMatchingSignalsWithHttpInfo(eventId, track).getData();
+  }
+
+  /**
+   * Get signals matching an event.
+   *
+   * <p>See {@link #getMatchingSignalsWithHttpInfoAsync}.
+   *
+   * @param eventId The ID of the event to find matching signals for. (required)
+   * @param track The product track that the event belongs to. (required)
+   * @return CompletableFuture&lt;MatchingSignalsResponse&gt;
+   */
+  public CompletableFuture<MatchingSignalsResponse> getMatchingSignalsAsync(
+      String eventId, String track) {
+    return getMatchingSignalsWithHttpInfoAsync(eventId, track)
+        .thenApply(
+            response -> {
+              return response.getData();
+            });
+  }
+
+  /**
+   * Returns the list of security signals that match a given event on the given track.
+   *
+   * @param eventId The ID of the event to find matching signals for. (required)
+   * @param track The product track that the event belongs to. (required)
+   * @return ApiResponse&lt;MatchingSignalsResponse&gt;
+   * @throws ApiException if fails to make API call
+   * @http.response.details
+   *     <table border="1">
+   *    <caption>Response details</caption>
+   *       <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
+   *       <tr><td> 200 </td><td> OK </td><td>  -  </td></tr>
+   *       <tr><td> 400 </td><td> Bad Request </td><td>  -  </td></tr>
+   *       <tr><td> 403 </td><td> Not Authorized </td><td>  -  </td></tr>
+   *       <tr><td> 404 </td><td> Not Found </td><td>  -  </td></tr>
+   *       <tr><td> 429 </td><td> Too many requests </td><td>  -  </td></tr>
+   *     </table>
+   */
+  public ApiResponse<MatchingSignalsResponse> getMatchingSignalsWithHttpInfo(
+      String eventId, String track) throws ApiException {
+    // Check if unstable operation is enabled
+    String operationId = "getMatchingSignals";
+    if (apiClient.isUnstableOperationEnabled("v2." + operationId)) {
+      apiClient.getLogger().warning(String.format("Using unstable operation '%s'", operationId));
+    } else {
+      throw new ApiException(0, String.format("Unstable operation '%s' is disabled", operationId));
+    }
+    Object localVarPostBody = null;
+
+    // verify the required parameter 'eventId' is set
+    if (eventId == null) {
+      throw new ApiException(
+          400, "Missing the required parameter 'eventId' when calling getMatchingSignals");
+    }
+
+    // verify the required parameter 'track' is set
+    if (track == null) {
+      throw new ApiException(
+          400, "Missing the required parameter 'track' when calling getMatchingSignals");
+    }
+    // create path and map variables
+    String localVarPath =
+        "/api/v2/security_monitoring/events/{event_id}/matching_signals"
+            .replaceAll("\\{" + "event_id" + "\\}", apiClient.escapeString(eventId.toString()));
+
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
+    Map<String, String> localVarHeaderParams = new HashMap<String, String>();
+
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "track", track));
+
+    Invocation.Builder builder =
+        apiClient.createBuilder(
+            "v2.SecurityMonitoringApi.getMatchingSignals",
+            localVarPath,
+            localVarQueryParams,
+            localVarHeaderParams,
+            new HashMap<String, String>(),
+            new String[] {"application/json"},
+            new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
+    return apiClient.invokeAPI(
+        "GET",
+        builder,
+        localVarHeaderParams,
+        new String[] {},
+        localVarPostBody,
+        new HashMap<String, Object>(),
+        false,
+        new GenericType<MatchingSignalsResponse>() {});
+  }
+
+  /**
+   * Get signals matching an event.
+   *
+   * <p>See {@link #getMatchingSignalsWithHttpInfo}.
+   *
+   * @param eventId The ID of the event to find matching signals for. (required)
+   * @param track The product track that the event belongs to. (required)
+   * @return CompletableFuture&lt;ApiResponse&lt;MatchingSignalsResponse&gt;&gt;
+   */
+  public CompletableFuture<ApiResponse<MatchingSignalsResponse>>
+      getMatchingSignalsWithHttpInfoAsync(String eventId, String track) {
+    // Check if unstable operation is enabled
+    String operationId = "getMatchingSignals";
+    if (apiClient.isUnstableOperationEnabled("v2." + operationId)) {
+      apiClient.getLogger().warning(String.format("Using unstable operation '%s'", operationId));
+    } else {
+      CompletableFuture<ApiResponse<MatchingSignalsResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(
+          new ApiException(0, String.format("Unstable operation '%s' is disabled", operationId)));
+      return result;
+    }
+    Object localVarPostBody = null;
+
+    // verify the required parameter 'eventId' is set
+    if (eventId == null) {
+      CompletableFuture<ApiResponse<MatchingSignalsResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(
+          new ApiException(
+              400, "Missing the required parameter 'eventId' when calling getMatchingSignals"));
+      return result;
+    }
+
+    // verify the required parameter 'track' is set
+    if (track == null) {
+      CompletableFuture<ApiResponse<MatchingSignalsResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(
+          new ApiException(
+              400, "Missing the required parameter 'track' when calling getMatchingSignals"));
+      return result;
+    }
+    // create path and map variables
+    String localVarPath =
+        "/api/v2/security_monitoring/events/{event_id}/matching_signals"
+            .replaceAll("\\{" + "event_id" + "\\}", apiClient.escapeString(eventId.toString()));
+
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
+    Map<String, String> localVarHeaderParams = new HashMap<String, String>();
+
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "track", track));
+
+    Invocation.Builder builder;
+    try {
+      builder =
+          apiClient.createBuilder(
+              "v2.SecurityMonitoringApi.getMatchingSignals",
+              localVarPath,
+              localVarQueryParams,
+              localVarHeaderParams,
+              new HashMap<String, String>(),
+              new String[] {"application/json"},
+              new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
+    } catch (ApiException ex) {
+      CompletableFuture<ApiResponse<MatchingSignalsResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(ex);
+      return result;
+    }
+    return apiClient.invokeAPIAsync(
+        "GET",
+        builder,
+        localVarHeaderParams,
+        new String[] {},
+        localVarPostBody,
+        new HashMap<String, Object>(),
+        false,
+        new GenericType<MatchingSignalsResponse>() {});
+  }
+
   /** Manage optional parameters to getResourceEvaluationFilters. */
   public static class GetResourceEvaluationFiltersOptionalParameters {
     private String cloudProvider;