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

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

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.207273",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:43.090375",
+            "spec_repo_commit": "faa72400"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:21.224587",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:43.107941",
+            "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:

examples/v2/security-monitoring/ListFindings_2932019633.py

@@ -0,0 +1,16 @@
+"""
+List findings returns "OK" response with details
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
+
+configuration = Configuration()
+configuration.unstable_operations["list_findings"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = SecurityMonitoringApi(api_client)
+    response = api_instance.list_findings(
+        detailed_findings=True,
+    )
+
+    print(response)

src/datadog_api_client/v2/api/security_monitoring_api.py

@@ -1000,6 +1000,11 @@ def __init__(self, api_client=None):
                     "location": "query",
                     "collection_format": "multi",
                 },
+                "detailed_findings": {
+                    "openapi_types": (bool,),
+                    "attribute": "detailed_findings",
+                    "location": "query",
+                },
             },
             headers_map={
                 "accept": ["application/json"],
@@ -2462,6 +2467,7 @@ def list_findings(
         filter_evaluation: Union[FindingEvaluation, UnsetType] = unset,
         filter_status: Union[FindingStatus, UnsetType] = unset,
         filter_vulnerability_type: Union[List[FindingVulnerabilityType], UnsetType] = unset,
+        detailed_findings: Union[bool, UnsetType] = unset,
     ) -> ListFindingsResponse:
         """List findings.
 
@@ -2487,6 +2493,18 @@ def list_findings(
 
         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.
@@ -2524,6 +2542,8 @@ def list_findings(
         :type filter_status: FindingStatus, optional
         :param filter_vulnerability_type: Return findings that match the selected vulnerability types (repeatable).
         :type filter_vulnerability_type: [FindingVulnerabilityType], optional
+        :param detailed_findings: Return additional fields for some findings.
+        :type detailed_findings: bool, optional
         :rtype: ListFindingsResponse
         """
         kwargs: Dict[str, Any] = {}
@@ -2566,6 +2586,9 @@ def list_findings(
         if filter_vulnerability_type is not unset:
             kwargs["filter_vulnerability_type"] = filter_vulnerability_type
 
+        if detailed_findings is not unset:
+            kwargs["detailed_findings"] = detailed_findings
+
         return self._list_findings_endpoint.call_with_http_info(**kwargs)
 
     def list_findings_with_pagination(
@@ -2584,6 +2607,7 @@ def list_findings_with_pagination(
         filter_evaluation: Union[FindingEvaluation, UnsetType] = unset,
         filter_status: Union[FindingStatus, UnsetType] = unset,
         filter_vulnerability_type: Union[List[FindingVulnerabilityType], UnsetType] = unset,
+        detailed_findings: Union[bool, UnsetType] = unset,
     ) -> collections.abc.Iterable[Finding]:
         """List findings.
 
@@ -2615,6 +2639,8 @@ def list_findings_with_pagination(
         :type filter_status: FindingStatus, optional
         :param filter_vulnerability_type: Return findings that match the selected vulnerability types (repeatable).
         :type filter_vulnerability_type: [FindingVulnerabilityType], optional
+        :param detailed_findings: Return additional fields for some findings.
+        :type detailed_findings: bool, optional
 
         :return: A generator of paginated results.
         :rtype: collections.abc.Iterable[Finding]
@@ -2659,6 +2685,9 @@ def list_findings_with_pagination(
         if filter_vulnerability_type is not unset:
             kwargs["filter_vulnerability_type"] = filter_vulnerability_type
 
+        if detailed_findings is not unset:
+            kwargs["detailed_findings"] = detailed_findings
+
         local_page_size = get_attribute_from_path(kwargs, "page_limit", 100)
         endpoint = self._list_findings_endpoint
         set_attribute_from_path(kwargs, "page_limit", local_page_size, endpoint.params_map)

src/datadog_api_client/v2/model/finding_attributes.py

@@ -40,8 +40,11 @@ def openapi_types(_):
         from datadog_api_client.v2.model.finding_vulnerability_type import FindingVulnerabilityType
 
         return {
+            "datadog_link": (str,),
+            "description": (str,),
             "evaluation": (FindingEvaluation,),
             "evaluation_changed_at": (int,),
+            "external_id": (str,),
             "mute": (FindingMute,),
             "resource": (str,),
             "resource_discovery_date": (int,),
@@ -53,8 +56,11 @@ def openapi_types(_):
         }
 
     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",
@@ -67,8 +73,11 @@ def openapi_types(_):
 
     def __init__(
         self_,
+        datadog_link: Union[str, UnsetType] = unset,
+        description: Union[str, UnsetType] = unset,
         evaluation: Union[FindingEvaluation, UnsetType] = unset,
         evaluation_changed_at: Union[int, UnsetType] = unset,
+        external_id: Union[str, UnsetType] = unset,
         mute: Union[FindingMute, UnsetType] = unset,
         resource: Union[str, UnsetType] = unset,
         resource_discovery_date: Union[int, UnsetType] = unset,
@@ -82,12 +91,21 @@ def __init__(
         """
         The JSON:API attributes of the finding.
 
+        :param datadog_link: The Datadog relative link for this finding.
+        :type datadog_link: str, optional
+
+        :param description: The description and remediation steps for this finding.
+        :type description: str, optional
+
         :param evaluation: The evaluation of the finding.
         :type evaluation: FindingEvaluation, optional
 
         :param evaluation_changed_at: The date on which the evaluation for this finding changed (Unix ms).
         :type evaluation_changed_at: int, optional
 
+        :param external_id: The cloud-based ID for the resource related to the finding.
+        :type external_id: str, optional
+
         :param mute: Information about the mute status of this finding.
         :type mute: FindingMute, optional
 
@@ -112,10 +130,16 @@ def __init__(
         :param vulnerability_type: The vulnerability type of the finding.
         :type vulnerability_type: FindingVulnerabilityType, optional
         """
+        if datadog_link is not unset:
+            kwargs["datadog_link"] = datadog_link
+        if description is not unset:
+            kwargs["description"] = description
         if evaluation is not unset:
             kwargs["evaluation"] = evaluation
         if evaluation_changed_at is not unset:
             kwargs["evaluation_changed_at"] = evaluation_changed_at
+        if external_id is not unset:
+            kwargs["external_id"] = external_id
         if mute is not unset:
             kwargs["mute"] = mute
         if resource is not unset:

tests/v2/cassettes/test_scenarios/test_list_findings_returns_ok_response_with_details.frozen

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

tests/v2/cassettes/test_scenarios/test_list_findings_returns_ok_response_with_details.yaml

@@ -0,0 +1,18 @@
+interactions:
+- request:
+    body: null
+    headers:
+      accept:
+      - application/json
+    method: GET
+    uri: https://api.datadoghq.com/api/v2/posture_management/findings?detailed_findings=true
+  response:
+    body:
+      string: '{"data":[],"meta":{"page":{"total_filtered_count":0},"snapshot_timestamp":1747743085077}}'
+    headers:
+      content-type:
+      - application/vnd.api+json
+    status:
+      code: 200
+      message: OK
+version: 1

tests/v2/features/security_monitoring.feature

@@ -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