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

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:20.110994",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:39.264892",
+            "spec_repo_commit": "faa72400"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:20.126935",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:39.280328",
+            "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.rs

@@ -0,0 +1,19 @@
+// List findings returns "OK" response with details
+use datadog_api_client::datadog;
+use datadog_api_client::datadogV2::api_security_monitoring::ListFindingsOptionalParams;
+use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
+
+#[tokio::main]
+async fn main() {
+    let mut configuration = datadog::Configuration::new();
+    configuration.set_unstable_operation_enabled("v2.ListFindings", true);
+    let api = SecurityMonitoringAPI::with_config(configuration);
+    let resp = api
+        .list_findings(ListFindingsOptionalParams::default().detailed_findings(true))
+        .await;
+    if let Ok(value) = resp {
+        println!("{:#?}", value);
+    } else {
+        println!("{:#?}", resp.unwrap_err());
+    }
+}

src/datadogV2/api/api_security_monitoring.rs

@@ -128,6 +128,8 @@ pub struct ListFindingsOptionalParams {
     pub filter_status: Option<crate::datadogV2::model::FindingStatus>,
     /// Return findings that match the selected vulnerability types (repeatable).
     pub filter_vulnerability_type: Option<Vec<crate::datadogV2::model::FindingVulnerabilityType>>,
+    /// Return additional fields for some findings.
+    pub detailed_findings: Option<bool>,
 }
 
 impl ListFindingsOptionalParams {
@@ -199,6 +201,11 @@ impl ListFindingsOptionalParams {
         self.filter_vulnerability_type = Some(value);
         self
     }
+    /// Return additional fields for some findings.
+    pub fn detailed_findings(mut self, value: bool) -> Self {
+        self.detailed_findings = Some(value);
+        self
+    }
 }
 
 /// ListHistoricalJobsOptionalParams is a struct for passing parameters to the method [`SecurityMonitoringAPI::list_historical_jobs`]
@@ -5540,6 +5547,17 @@ impl SecurityMonitoringAPI {
     ///
     /// 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.
@@ -5625,6 +5643,17 @@ impl SecurityMonitoringAPI {
     ///
     /// 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.
@@ -5668,6 +5697,7 @@ impl SecurityMonitoringAPI {
         let filter_evaluation = params.filter_evaluation;
         let filter_status = params.filter_status;
         let filter_vulnerability_type = params.filter_vulnerability_type;
+        let detailed_findings = params.detailed_findings;
 
         let local_client = &self.client;
 
@@ -5736,6 +5766,10 @@ impl SecurityMonitoringAPI {
                     local_req_builder.query(&[("filter[vulnerability_type]", &param.to_string())]);
             }
         };
+        if let Some(ref local_query_param) = detailed_findings {
+            local_req_builder =
+                local_req_builder.query(&[("detailed_findings", &local_query_param.to_string())]);
+        };
 
         // build headers
         let mut headers = HeaderMap::new();

src/datadogV2/model/model_finding_attributes.rs

@@ -11,12 +11,21 @@ use std::fmt::{self, Formatter};
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]
 pub struct FindingAttributes {
+    /// The Datadog relative link for this finding.
+    #[serde(rename = "datadog_link")]
+    pub datadog_link: Option<String>,
+    /// The description and remediation steps for this finding.
+    #[serde(rename = "description")]
+    pub description: Option<String>,
     /// The evaluation of the finding.
     #[serde(rename = "evaluation")]
     pub evaluation: Option<crate::datadogV2::model::FindingEvaluation>,
     /// The date on which the evaluation for this finding changed (Unix ms).
     #[serde(rename = "evaluation_changed_at")]
     pub evaluation_changed_at: Option<i64>,
+    /// The cloud-based ID for the resource related to the finding.
+    #[serde(rename = "external_id")]
+    pub external_id: Option<String>,
     /// Information about the mute status of this finding.
     #[serde(rename = "mute")]
     pub mute: Option<crate::datadogV2::model::FindingMute>,
@@ -51,8 +60,11 @@ pub struct FindingAttributes {
 impl FindingAttributes {
     pub fn new() -> FindingAttributes {
         FindingAttributes {
+            datadog_link: None,
+            description: None,
             evaluation: None,
             evaluation_changed_at: None,
+            external_id: None,
             mute: None,
             resource: None,
             resource_discovery_date: None,
@@ -66,6 +78,16 @@ impl FindingAttributes {
         }
     }
 
+    pub fn datadog_link(mut self, value: String) -> Self {
+        self.datadog_link = Some(value);
+        self
+    }
+
+    pub fn description(mut self, value: String) -> Self {
+        self.description = Some(value);
+        self
+    }
+
     pub fn evaluation(mut self, value: crate::datadogV2::model::FindingEvaluation) -> Self {
         self.evaluation = Some(value);
         self
@@ -76,6 +98,11 @@ impl FindingAttributes {
         self
     }
 
+    pub fn external_id(mut self, value: String) -> Self {
+        self.external_id = Some(value);
+        self
+    }
+
     pub fn mute(mut self, value: crate::datadogV2::model::FindingMute) -> Self {
         self.mute = Some(value);
         self
@@ -151,8 +178,11 @@ impl<'de> Deserialize<'de> for FindingAttributes {
             where
                 M: MapAccess<'a>,
             {
+                let mut datadog_link: Option<String> = None;
+                let mut description: Option<String> = None;
                 let mut evaluation: Option<crate::datadogV2::model::FindingEvaluation> = None;
                 let mut evaluation_changed_at: Option<i64> = None;
+                let mut external_id: Option<String> = None;
                 let mut mute: Option<crate::datadogV2::model::FindingMute> = None;
                 let mut resource: Option<String> = None;
                 let mut resource_discovery_date: Option<i64> = None;
@@ -171,6 +201,20 @@ impl<'de> Deserialize<'de> for FindingAttributes {
 
                 while let Some((k, v)) = map.next_entry::<String, serde_json::Value>()? {
                     match k.as_str() {
+                        "datadog_link" => {
+                            if v.is_null() {
+                                continue;
+                            }
+                            datadog_link =
+                                Some(serde_json::from_value(v).map_err(M::Error::custom)?);
+                        }
+                        "description" => {
+                            if v.is_null() {
+                                continue;
+                            }
+                            description =
+                                Some(serde_json::from_value(v).map_err(M::Error::custom)?);
+                        }
                         "evaluation" => {
                             if v.is_null() {
                                 continue;
@@ -194,6 +238,13 @@ impl<'de> Deserialize<'de> for FindingAttributes {
                             evaluation_changed_at =
                                 Some(serde_json::from_value(v).map_err(M::Error::custom)?);
                         }
+                        "external_id" => {
+                            if v.is_null() {
+                                continue;
+                            }
+                            external_id =
+                                Some(serde_json::from_value(v).map_err(M::Error::custom)?);
+                        }
                         "mute" => {
                             if v.is_null() {
                                 continue;
@@ -272,8 +323,11 @@ impl<'de> Deserialize<'de> for FindingAttributes {
                 }
 
                 let content = FindingAttributes {
+                    datadog_link,
+                    description,
                     evaluation,
                     evaluation_changed_at,
+                    external_id,
                     mute,
                     resource,
                     resource_discovery_date,

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

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

tests/scenarios/cassettes/v2/security_monitoring/List-findings-returns-OK-response-with-details.json

@@ -0,0 +1,33 @@
+{
+  "http_interactions": [
+    {
+      "request": {
+        "body": "",
+        "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}}",
+          "encoding": null
+        },
+        "headers": {
+          "Content-Type": [
+            "application/vnd.api+json"
+          ]
+        },
+        "status": {
+          "code": 200,
+          "message": "OK"
+        }
+      },
+      "recorded_at": "Tue, 20 May 2025 12:11:24 GMT"
+    }
+  ],
+  "recorded_with": "VCR 6.0.0"
+}

tests/scenarios/features/v2/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