Add OpenAPI documentation for signal investigation queries and suggested actions endpoints (#3851)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -59499,6 +59499,17 @@ components:
       required:
         - data
       type: object
+    SecurityMonitoringSignalInvestigationQueryTemplateVariables:
+      additionalProperties:
+        items:
+          description: A value for this template variable extracted from the signal.
+          type: string
+        type: array
+      description: Template variables applied to the investigation log query, mapping attribute paths to values extracted from the signal.
+      example:
+        "@userIdentity.arn":
+          - foo
+      type: object
     SecurityMonitoringSignalListRequest:
       description: The request for a security signal list.
       properties:
@@ -59884,6 +59895,82 @@ components:
       required:
         - data
       type: object
+    SecurityMonitoringSignalSuggestedAction:
+      description: A suggested action for a security signal.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedActionAttributes"
+        id:
+          description: The unique ID of the suggested action.
+          example: w00-t10-992
+          type: string
+        type:
+          $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedActionType"
+      required:
+        - id
+        - type
+        - attributes
+      type: object
+    SecurityMonitoringSignalSuggestedActionAttributes:
+      description: Attributes of a suggested action for a security signal. The available fields depend on the action type.
+      properties:
+        name:
+          description: The name of the investigation log query.
+          example: Cloudtrail events for user ARN
+          type: string
+        query_filter:
+          description: The log query filter for the investigation.
+          example: 'source:cloudtrail @userIdentity.arn:"foo"'
+          type: string
+        template_variables:
+          $ref: "#/components/schemas/SecurityMonitoringSignalInvestigationQueryTemplateVariables"
+        title:
+          description: The title of the recommended blog post.
+          example: Monitor Okta logs to track system access and unusual activity
+          type: string
+        url:
+          description: The URL of the suggested action.
+          example: /logs?query=source%3Acloudtrail+%40userIdentity.arn%3A%22foo%22
+          type: string
+      type: object
+    SecurityMonitoringSignalSuggestedActionList:
+      description: List of suggested actions for a security signal.
+      example:
+        - attributes:
+            name: Cloudtrail events for user ARN
+            query_filter: 'source:cloudtrail @userIdentity.arn:"foo"'
+            template_variables:
+              "@userIdentity.arn":
+                - foo
+            url: /logs?query=source%3Acloudtrail+%40userIdentity.arn%3A%22foo%22
+          id: w00-t10-992
+          type: investigation_log_queries
+        - attributes:
+            title: Monitor Okta logs to track system access and unusual activity
+            url: https://www.datadoghq.com/blog/monitor-activity-with-okta/
+          id: bxy-o8v-i1a
+          type: recommended_blog_posts
+      items:
+        $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedAction"
+      type: array
+    SecurityMonitoringSignalSuggestedActionType:
+      description: The type of the suggested action resource.
+      enum:
+        - investigation_log_queries
+        - recommended_blog_posts
+      example: investigation_log_queries
+      type: string
+      x-enum-varnames:
+        - INVESTIGATION_LOG_QUERIES
+        - RECOMMENDED_BLOG_POSTS
+    SecurityMonitoringSignalSuggestedActionsResponse:
+      description: Response with suggested actions for a security signal.
+      properties:
+        data:
+          $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedActionList"
+      required:
+        - data
+      type: object
     SecurityMonitoringSignalTriageAttributes:
       description: Attributes describing a triage state update operation over a security signal.
       properties:
@@ -106943,6 +107030,54 @@ paths:
         operator: OR
         permissions:
           - security_monitoring_signals_write
+  /api/v2/security_monitoring/signals/{signal_id}/investigation_queries:
+    get:
+      description: Get the list of investigation log queries available for a given security signal.
+      operationId: GetInvestigationLogQueriesMatchingSignal
+      parameters:
+        - $ref: "#/components/parameters/SignalID"
+      responses:
+        "200":
+          content:
+            application/json:
+              example:
+                data:
+                  - attributes:
+                      name: Cloudtrail events for user ARN
+                      query_filter: 'source:cloudtrail @userIdentity.arn:"foo"'
+                      template_variables:
+                        "@userIdentity.arn":
+                          - foo
+                      url: /logs?query=source%3Acloudtrail+%40userIdentity.arn%3A%22foo%22
+                    id: w00-t10-992
+                    type: investigation_log_queries
+                  - attributes:
+                      title: Monitor Okta logs to track system access and unusual activity
+                      url: https://www.datadoghq.com/blog/monitor-activity-with-okta/
+                    id: bxy-o8v-i1a
+                    type: recommended_blog_posts
+              schema:
+                $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedActionsResponse"
+          description: OK
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_rules_read
+            - security_monitoring_signals_read
+      summary: Get investigation queries for a signal
+      tags: ["Security Monitoring"]
+      x-permission:
+        operator: AND
+        permissions:
+          - security_monitoring_rules_read
+          - security_monitoring_signals_read
   /api/v2/security_monitoring/signals/{signal_id}/state:
     patch:
       description: |-
@@ -106983,6 +107118,54 @@ paths:
         operator: OR
         permissions:
           - security_monitoring_signals_write
+  /api/v2/security_monitoring/signals/{signal_id}/suggested_actions:
+    get:
+      description: Get the list of suggested actions for a given security signal.
+      operationId: GetSuggestedActionsMatchingSignal
+      parameters:
+        - $ref: "#/components/parameters/SignalID"
+      responses:
+        "200":
+          content:
+            application/json:
+              example:
+                data:
+                  - attributes:
+                      name: Cloudtrail events for user ARN
+                      query_filter: 'source:cloudtrail @userIdentity.arn:"foo"'
+                      template_variables:
+                        "@userIdentity.arn":
+                          - foo
+                      url: /logs?query=source%3Acloudtrail+%40userIdentity.arn%3A%22foo%22
+                    id: w00-t10-992
+                    type: investigation_log_queries
+                  - attributes:
+                      title: Monitor Okta logs to track system access and unusual activity
+                      url: https://www.datadoghq.com/blog/monitor-activity-with-okta/
+                    id: bxy-o8v-i1a
+                    type: recommended_blog_posts
+              schema:
+                $ref: "#/components/schemas/SecurityMonitoringSignalSuggestedActionsResponse"
+          description: OK
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_rules_read
+            - security_monitoring_signals_read
+      summary: Get suggested actions for a signal
+      tags: ["Security Monitoring"]
+      x-permission:
+        operator: AND
+        permissions:
+          - security_monitoring_rules_read
+          - security_monitoring_signals_read
   /api/v2/sensitive-data-scanner/config:
     get:
       description: List all the Scanning groups in your organization.

features/v2/security_monitoring.feature

@@ -1371,6 +1371,25 @@ Feature: Security Monitoring
     When the request is sent
     Then the response status is 200 Notification rule details.
 
+  @generated @skip @team:DataDog/k9-cloud-siem
+  Scenario: Get investigation queries for a signal returns "Not Found" response
+    Given new "GetInvestigationLogQueriesMatchingSignal" request
+    And request contains "signal_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @skip @team:DataDog/k9-cloud-siem
+  Scenario: Get investigation queries for a signal returns "OK" response
+    Given new "GetInvestigationLogQueriesMatchingSignal" request
+    And request contains "signal_id" parameter with value "AQAAAYG1bl5K4HuUewAAAABBWUcxYmw1S0FBQmt2RmhRN0V4ZUVnQUE"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "data[0].type" is equal to "investigation_log_queries"
+    And the response "data[0]" has field "id"
+    And the response "data[0].attributes" has field "name"
+    And the response "data[0].attributes" has field "query_filter"
+    And the response "data[0].attributes" has field "url"
+
   @skip-go @skip-java @skip-ruby @team:DataDog/k9-cloud-siem
   Scenario: Get rule version history returns "OK" response
     Given operation "GetRuleVersionHistory" enabled
@@ -1384,6 +1403,29 @@ Feature: Security Monitoring
     And the response "data.attributes.count" is equal to 1
     And the response "data.attributes.data[1].rule.name" has the same value as "security_rule.name"
 
+  @generated @skip @team:DataDog/k9-cloud-siem
+  Scenario: Get suggested actions for a signal returns "Not Found" response
+    Given new "GetSuggestedActionsMatchingSignal" request
+    And request contains "signal_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @skip @team:DataDog/k9-cloud-siem
+  Scenario: Get suggested actions for a signal returns "OK" response
+    Given new "GetSuggestedActionsMatchingSignal" request
+    And request contains "signal_id" parameter with value "AQAAAYG1bl5K4HuUewAAAABBWUcxYmw1S0FBQmt2RmhRN0V4ZUVnQUE"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "data[0].type" is equal to "investigation_log_queries"
+    And the response "data[0]" has field "id"
+    And the response "data[0].attributes" has field "name"
+    And the response "data[0].attributes" has field "query_filter"
+    And the response "data[0].attributes" has field "url"
+    And the response "data[1].type" is equal to "recommended_blog_posts"
+    And the response "data[1]" has field "id"
+    And the response "data[1].attributes" has field "title"
+    And the response "data[1].attributes" has field "url"
+
   @team:DataDog/k9-cloud-siem
   Scenario: Get suppressions affecting a specific rule returns "Not Found" response
     Given new "GetSuppressionsAffectingRule" request

features/v2/undo.json

@@ -5374,12 +5374,24 @@
       "type": "idempotent"
     }
   },
+  "GetInvestigationLogQueriesMatchingSignal": {
+    "tag": "Security Monitoring",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "EditSecurityMonitoringSignalState": {
     "tag": "Security Monitoring",
     "undo": {
       "type": "idempotent"
     }
   },
+  "GetSuggestedActionsMatchingSignal": {
+    "tag": "Security Monitoring",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "ListScanningGroups": {
     "tag": "Sensitive Data Scanner",
     "undo": {

private/bdd_runner/src/support/scenarios_model_mapping.ts

@@ -5004,6 +5004,13 @@ export const ScenariosModelMappings: { [key: string]: OperationMapping } = {
     },
     operationResponseType: "SecurityMonitoringSignalTriageUpdateResponse",
   },
+  "SecurityMonitoringApi.V2.GetInvestigationLogQueriesMatchingSignal": {
+    signalId: {
+      type: "string",
+      format: "",
+    },
+    operationResponseType: "SecurityMonitoringSignalSuggestedActionsResponse",
+  },
   "SecurityMonitoringApi.V2.EditSecurityMonitoringSignalState": {
     signalId: {
       type: "string",
@@ -5015,6 +5022,13 @@ export const ScenariosModelMappings: { [key: string]: OperationMapping } = {
     },
     operationResponseType: "SecurityMonitoringSignalTriageUpdateResponse",
   },
+  "SecurityMonitoringApi.V2.GetSuggestedActionsMatchingSignal": {
+    signalId: {
+      type: "string",
+      format: "",
+    },
+    operationResponseType: "SecurityMonitoringSignalSuggestedActionsResponse",
+  },
   "SecurityMonitoringApi.V2.ListSecurityMonitoringHistsignals": {
     filterQuery: {
       type: "string",