Added new optional field definition to include more detail in findings for '/api/v2/posture_management/findings' (#2413)

Co-authored-by: ci.datadog-api-spec <[email protected]>

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

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:21.288492",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:42.393551",
+            "spec_repo_commit": "faa72400"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:21.310506",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:42.410269",
+            "spec_repo_commit": "faa72400"
         }
     }
 }

.generator/schemas/v2/openapi.yaml

@@ -15279,10 +15279,16 @@ components:
     FindingAttributes:
       description: The JSON:API attributes of the finding.
       properties:
+        datadog_link:
+          $ref: '#/components/schemas/FindingDatadogLink'
+        description:
+          $ref: '#/components/schemas/FindingDescription'
         evaluation:
           $ref: '#/components/schemas/FindingEvaluation'
         evaluation_changed_at:
           $ref: '#/components/schemas/FindingEvaluationChangedAt'
+        external_id:
+          $ref: '#/components/schemas/FindingExternalId'
         mute:
           $ref: '#/components/schemas/FindingMute'
         resource:
@@ -15300,6 +15306,22 @@ components:
         vulnerability_type:
           $ref: '#/components/schemas/FindingVulnerabilityType'
       type: object
+    FindingDatadogLink:
+      description: The Datadog relative link for this finding.
+      example: /security/compliance?panels=cpfinding%7Cevent%7CruleId%3Adef-000-u5t%7CresourceId%3Ae8c9ab7c52ebd7bf2fdb4db641082d7d%7CtabId%3Aoverview
+      type: string
+    FindingDescription:
+      description: The description and remediation steps for this finding.
+      example: '## Remediation
+
+
+        1. In the console, go to **Storage Account**.
+
+        2. For each Storage Account, navigate to **Data Protection**.
+
+        3. Select **Set soft delete enabled** and enter the number of days to retain
+        soft deleted data.'
+      type: string
     FindingEvaluation:
       description: The evaluation of the finding.
       enum:
@@ -15317,6 +15339,10 @@ components:
       format: int64
       minimum: 1
       type: integer
+    FindingExternalId:
+      description: The cloud-based ID for the resource related to the finding.
+      example: arn:aws:s3:::my-example-bucket
+      type: string
     FindingID:
       description: The unique ID for this finding.
       example: ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==
@@ -53082,13 +53108,19 @@ paths:
         the equal sign: `filter[evaluation_changed_at]=>=1678809373257`.\n\nQuery
         parameters must be only among the documented ones and with values of correct
         types. Duplicated query parameters (e.g. `filter[status]=low&filter[status]=info`)
-        are not allowed.\n\n### Response\n\nThe response includes an array of finding
-        objects, pagination metadata, and a count of items that match the query.\n\nEach
-        finding object contains the following:\n\n- The finding ID that can be used
-        in a `GetFinding` request to retrieve the full finding details.\n- Core attributes,
-        including status, evaluation, high-level resource details, muted state, and
-        rule details.\n- `evaluation_changed_at` and `resource_discovery_date` time
-        stamps.\n- An array of associated tags.\n"
+        are not allowed.\n\n### Additional extension fields\n\nAdditional extension
+        fields are available for some findings.\n\nThe data is available when you
+        include the query parameter `?detailed_findings=true` in the request.\n\nThe
+        following fields are available for findings:\n- `external_id`: The resource
+        external ID related to the finding.\n- `description`: The description and
+        remediation steps for the finding.\n- `datadog_link`: The Datadog relative
+        link for the finding.\n\n### Response\n\nThe response includes an array of
+        finding objects, pagination metadata, and a count of items that match the
+        query.\n\nEach finding object contains the following:\n\n- The finding ID
+        that can be used in a `GetFinding` request to retrieve the full finding details.\n-
+        Core attributes, including status, evaluation, high-level resource details,
+        muted state, and rule details.\n- `evaluation_changed_at` and `resource_discovery_date`
+        time stamps.\n- An array of associated tags.\n"
       operationId: ListFindings
       parameters:
       - description: Limit the number of findings returned. Must be <= 1000.
@@ -53191,6 +53223,14 @@ paths:
           items:
             $ref: '#/components/schemas/FindingVulnerabilityType'
           type: array
+      - description: Return additional fields for some findings.
+        example:
+        - true
+        in: query
+        name: detailed_findings
+        required: false
+        schema:
+          type: boolean
       responses:
         '200':
           content:

cassettes/features/v2/security_monitoring/List-findings-returns-OK-response-with-details.frozen

@@ -0,0 +1 @@
+2025-05-20T12:11:24.321Z

cassettes/features/v2/security_monitoring/List-findings-returns-OK-response-with-details.yml

@@ -0,0 +1,11 @@
+# List findings returns "OK" response with details
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.list_findings".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
+opts = {
+  detailed_findings: true,
+}
+p api_instance.list_findings(opts)

examples/v2/security-monitoring/ListFindings_2932019633.rb

@@ -1183,6 +1183,7 @@
             "filter_evaluation" => "FindingEvaluation",
             "filter_status" => "FindingStatus",
             "filter_vulnerability_type" => "Array<FindingVulnerabilityType>",
+            "detailed_findings" => "Boolean",
     },
     "v2.MuteFindings" => {
             "body" => "BulkMuteFindingsRequest",

features/scenarios_model_mapping.rb

@@ -840,6 +840,14 @@ Feature: Security Monitoring
     Then the response status is 200 OK
     And the response "data[0].type" is equal to "finding"
 
+  @team:DataDog/cloud-security-posture-management
+  Scenario: List findings returns "OK" response with details
+    Given operation "ListFindings" enabled
+    And new "ListFindings" request
+    And request contains "detailed_findings" parameter with value true
+    When the request is sent
+    Then the response status is 200 OK
+
   @generated @skip @team:DataDog/cloud-security-posture-management @with-pagination
   Scenario: List findings returns "OK" response with pagination
     Given operation "ListFindings" enabled

features/v2/security_monitoring.feature

@@ -2376,6 +2376,17 @@ def list_findings(opts = {})
     #
     # Query parameters must be only among the documented ones and with values of correct types. Duplicated query parameters (e.g. `filter[status]=low&filter[status]=info`) are not allowed.
     #
+    # ### Additional extension fields
+    #
+    # Additional extension fields are available for some findings.
+    #
+    # The data is available when you include the query parameter `?detailed_findings=true` in the request.
+    #
+    # The following fields are available for findings:
+    # - `external_id`: The resource external ID related to the finding.
+    # - `description`: The description and remediation steps for the finding.
+    # - `datadog_link`: The Datadog relative link for the finding.
+    #
     # ### Response
     #
     # The response includes an array of finding objects, pagination metadata, and a count of items that match the query.
@@ -2402,6 +2413,7 @@ def list_findings(opts = {})
     # @option opts [FindingEvaluation] :filter_evaluation Return only `pass` or `fail` findings.
     # @option opts [FindingStatus] :filter_status Return only findings with the specified status.
     # @option opts [Array<FindingVulnerabilityType>] :filter_vulnerability_type Return findings that match the selected vulnerability types (repeatable).
+    # @option opts [Boolean] :detailed_findings Return additional fields for some findings.
     # @return [Array<(ListFindingsResponse, Integer, Hash)>] ListFindingsResponse data, response status code and response headers
     def list_findings_with_http_info(opts = {})
       unstable_enabled = @api_client.config.unstable_operations["v2.list_findings".to_sym]
@@ -2449,6 +2461,7 @@ def list_findings_with_http_info(opts = {})
       query_params[:'filter[evaluation]'] = opts[:'filter_evaluation'] if !opts[:'filter_evaluation'].nil?
       query_params[:'filter[status]'] = opts[:'filter_status'] if !opts[:'filter_status'].nil?
       query_params[:'filter[vulnerability_type]'] = @api_client.build_collection_param(opts[:'filter_vulnerability_type'], :multi) if !opts[:'filter_vulnerability_type'].nil?
+      query_params[:'detailed_findings'] = opts[:'detailed_findings'] if !opts[:'detailed_findings'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}

lib/datadog_api_client/v2/api/security_monitoring_api.rb

@@ -21,12 +21,21 @@ module DatadogAPIClient::V2
   class FindingAttributes
     include BaseGenericModel
 
+    # The Datadog relative link for this finding.
+    attr_accessor :datadog_link
+
+    # The description and remediation steps for this finding.
+    attr_accessor :description
+
     # The evaluation of the finding.
     attr_accessor :evaluation
 
     # The date on which the evaluation for this finding changed (Unix ms).
     attr_reader :evaluation_changed_at
 
+    # The cloud-based ID for the resource related to the finding.
+    attr_accessor :external_id
+
     # Information about the mute status of this finding.
     attr_accessor :mute
 
@@ -57,8 +66,11 @@ class FindingAttributes
     # @!visibility private
     def self.attribute_map
       {
+        :'datadog_link' => :'datadog_link',
+        :'description' => :'description',
         :'evaluation' => :'evaluation',
         :'evaluation_changed_at' => :'evaluation_changed_at',
+        :'external_id' => :'external_id',
         :'mute' => :'mute',
         :'resource' => :'resource',
         :'resource_discovery_date' => :'resource_discovery_date',
@@ -74,8 +86,11 @@ def self.attribute_map
     # @!visibility private
     def self.openapi_types
       {
+        :'datadog_link' => :'String',
+        :'description' => :'String',
         :'evaluation' => :'FindingEvaluation',
         :'evaluation_changed_at' => :'Integer',
+        :'external_id' => :'String',
         :'mute' => :'FindingMute',
         :'resource' => :'String',
         :'resource_discovery_date' => :'Integer',
@@ -105,6 +120,14 @@ def initialize(attributes = {})
         end
       }
 
+      if attributes.key?(:'datadog_link')
+        self.datadog_link = attributes[:'datadog_link']
+      end
+
+      if attributes.key?(:'description')
+        self.description = attributes[:'description']
+      end
+
       if attributes.key?(:'evaluation')
         self.evaluation = attributes[:'evaluation']
       end
@@ -113,6 +136,10 @@ def initialize(attributes = {})
         self.evaluation_changed_at = attributes[:'evaluation_changed_at']
       end
 
+      if attributes.key?(:'external_id')
+        self.external_id = attributes[:'external_id']
+      end
+
       if attributes.key?(:'mute')
         self.mute = attributes[:'mute']
       end
@@ -203,8 +230,11 @@ def to_hash
     def ==(o)
       return true if self.equal?(o)
       self.class == o.class &&
+          datadog_link == o.datadog_link &&
+          description == o.description &&
           evaluation == o.evaluation &&
           evaluation_changed_at == o.evaluation_changed_at &&
+          external_id == o.external_id &&
           mute == o.mute &&
           resource == o.resource &&
           resource_discovery_date == o.resource_discovery_date &&
@@ -220,7 +250,7 @@ def ==(o)
     # @return [Integer] Hash code
     # @!visibility private
     def hash
-      [evaluation, evaluation_changed_at, mute, resource, resource_discovery_date, resource_type, rule, status, tags, vulnerability_type, additional_properties].hash
+      [datadog_link, description, evaluation, evaluation_changed_at, external_id, mute, resource, resource_discovery_date, resource_type, rule, status, tags, vulnerability_type, additional_properties].hash
     end
   end
 end