Add OpenAPI documentation for signal investigation queries and suggested actions endpoints

.generator/schemas/v2/openapi.yaml

@@ -58510,6 +58510,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:
@@ -58895,6 +58906,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:
@@ -104670,6 +104757,56 @@ 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:
+              examples:
+                default:
+                  value:
+                    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: |-
@@ -104710,6 +104847,56 @@ 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:
+              examples:
+                default:
+                  value:
+                    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.

examples/v2/security-monitoring/GetInvestigationLogQueriesMatchingSignal.rb

@@ -0,0 +1,5 @@
+# Get investigation queries for a signal returns "OK" response
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+p api_instance.get_investigation_log_queries_matching_signal("AQAAAYG1bl5K4HuUewAAAABBWUcxYmw1S0FBQmt2RmhRN0V4ZUVnQUE")

examples/v2/security-monitoring/GetSuggestedActionsMatchingSignal.rb

@@ -0,0 +1,5 @@
+# Get suggested actions for a signal returns "OK" response
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+p api_instance.get_suggested_actions_matching_signal("AQAAAYG1bl5K4HuUewAAAABBWUcxYmw1S0FBQmt2RmhRN0V4ZUVnQUE")

features/scenarios_model_mapping.rb

@@ -1761,10 +1761,16 @@
             "signal_id" => "String",
             "body" => "SecurityMonitoringSignalIncidentsUpdateRequest",
     },
+    "v2.GetInvestigationLogQueriesMatchingSignal" => {
+            "signal_id" => "String",
+    },
     "v2.EditSecurityMonitoringSignalState" => {
             "signal_id" => "String",
             "body" => "SecurityMonitoringSignalStateUpdateRequest",
     },
+    "v2.GetSuggestedActionsMatchingSignal" => {
+            "signal_id" => "String",
+    },
     "v2.ListSecurityMonitoringHistsignals" => {
             "filter_query" => "String",
             "filter_from" => "Time",

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-security-platform
+  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-security-platform
+  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-security-platform
   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-security-platform
+  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-security-platform
+  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-security-platform
   Scenario: Get suppressions affecting a specific rule returns "Not Found" response
     Given new "GetSuppressionsAffectingRule" request

features/v2/undo.json

@@ -5302,12 +5302,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": {

lib/datadog_api_client/inflector.rb

@@ -4830,6 +4830,10 @@ def overrides
           "v2.security_monitoring_signal_state_update_attributes" => "SecurityMonitoringSignalStateUpdateAttributes",
           "v2.security_monitoring_signal_state_update_data" => "SecurityMonitoringSignalStateUpdateData",
           "v2.security_monitoring_signal_state_update_request" => "SecurityMonitoringSignalStateUpdateRequest",
+          "v2.security_monitoring_signal_suggested_action" => "SecurityMonitoringSignalSuggestedAction",
+          "v2.security_monitoring_signal_suggested_action_attributes" => "SecurityMonitoringSignalSuggestedActionAttributes",
+          "v2.security_monitoring_signal_suggested_actions_response" => "SecurityMonitoringSignalSuggestedActionsResponse",
+          "v2.security_monitoring_signal_suggested_action_type" => "SecurityMonitoringSignalSuggestedActionType",
           "v2.security_monitoring_signal_triage_attributes" => "SecurityMonitoringSignalTriageAttributes",
           "v2.security_monitoring_signal_triage_update_data" => "SecurityMonitoringSignalTriageUpdateData",
           "v2.security_monitoring_signal_triage_update_response" => "SecurityMonitoringSignalTriageUpdateResponse",