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

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:19.271303",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:40.724881",
+            "spec_repo_commit": "faa72400"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:19.287369",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:40.740637",
+            "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/v2/Security-Monitoring_1187227211/List-findings-returns-OK-response-with-details_1509011827/frozen.json

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

cassettes/v2/Security-Monitoring_1187227211/List-findings-returns-OK-response-with-details_1509011827/recording.har

@@ -0,0 +1,62 @@
+{
+  "log": {
+    "_recordingName": "Security Monitoring/List findings returns \"OK\" response with details",
+    "creator": {
+      "comment": "persister:fs",
+      "name": "Polly.JS",
+      "version": "6.0.5"
+    },
+    "entries": [
+      {
+        "_id": "0b731c8b9bbe98674f8ad005c800b7d6",
+        "_order": 0,
+        "cache": {},
+        "request": {
+          "bodySize": 0,
+          "cookies": [],
+          "headers": [
+            {
+              "_fromType": "array",
+              "name": "accept",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 543,
+          "httpVersion": "HTTP/1.1",
+          "method": "GET",
+          "queryString": [
+            {
+              "name": "detailed_findings",
+              "value": "true"
+            }
+          ],
+          "url": "https://api.datadoghq.com/api/v2/posture_management/findings?detailed_findings=true"
+        },
+        "response": {
+          "bodySize": 89,
+          "content": {
+            "mimeType": "application/vnd.api+json",
+            "size": 89,
+            "text": "{\"data\":[],\"meta\":{\"page\":{\"total_filtered_count\":0},\"snapshot_timestamp\":1747743085077}}"
+          },
+          "cookies": [],
+          "headers": [
+            {
+              "name": "content-type",
+              "value": "application/vnd.api+json"
+            }
+          ],
+          "headersSize": 524,
+          "httpVersion": "HTTP/1.1",
+          "redirectURL": "",
+          "status": 200,
+          "statusText": "OK"
+        },
+        "startedDateTime": "2025-05-20T12:11:24.786Z",
+        "time": 462
+      }
+    ],
+    "pages": [],
+    "version": "1.2"
+  }
+}

examples/v2/security-monitoring/ListFindings_2932019633.ts

@@ -0,0 +1,22 @@
+/**
+ * List findings returns "OK" response with details
+ */
+
+import { client, v2 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+configuration.unstableOperations["v2.listFindings"] = true;
+const apiInstance = new v2.SecurityMonitoringApi(configuration);
+
+const params: v2.SecurityMonitoringApiListFindingsRequest = {
+  detailedFindings: true,
+};
+
+apiInstance
+  .listFindings(params)
+  .then((data: v2.ListFindingsResponse) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));

features/support/scenarios_model_mapping.ts

@@ -3332,6 +3332,10 @@ export const ScenariosModelMappings: {[key: string]: {[key: string]: any}} = {
             "type": "Array<FindingVulnerabilityType>",
             "format": "",
             },
+        "detailedFindings": {
+            "type": "boolean",
+            "format": "",
+            },
         "operationResponseType": "ListFindingsResponse",
     },
     "v2.MuteFindings": {

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

packages/datadog-api-client-v2/apis/SecurityMonitoringApi.ts

@@ -1532,6 +1532,7 @@ export class SecurityMonitoringApiRequestFactory extends BaseAPIRequestFactory {
     filterEvaluation?: FindingEvaluation,
     filterStatus?: FindingStatus,
     filterVulnerabilityType?: Array<FindingVulnerabilityType>,
+    detailedFindings?: boolean,
     _options?: Configuration
   ): Promise<RequestContext> {
     const _config = _options || this.configuration;
@@ -1647,6 +1648,13 @@ export class SecurityMonitoringApiRequestFactory extends BaseAPIRequestFactory {
         "multi"
       );
     }
+    if (detailedFindings !== undefined) {
+      requestContext.setQueryParam(
+        "detailed_findings",
+        ObjectSerializer.serialize(detailedFindings, "boolean", ""),
+        ""
+      );
+    }
 
     // Apply auth methods
     applySecurityAuthentication(_config, requestContext, [
@@ -7029,6 +7037,11 @@ export interface SecurityMonitoringApiListFindingsRequest {
    * @type Array<FindingVulnerabilityType>
    */
   filterVulnerabilityType?: Array<FindingVulnerabilityType>;
+  /**
+   * Return additional fields for some findings.
+   * @type boolean
+   */
+  detailedFindings?: boolean;
 }
 
 export interface SecurityMonitoringApiListHistoricalJobsRequest {
@@ -8338,6 +8351,17 @@ export class 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.
@@ -8368,6 +8392,7 @@ export class SecurityMonitoringApi {
       param.filterEvaluation,
       param.filterStatus,
       param.filterVulnerabilityType,
+      param.detailedFindings,
       options
     );
     return requestContextPromise.then((requestContext) => {
@@ -8406,6 +8431,7 @@ export class SecurityMonitoringApi {
         param.filterEvaluation,
         param.filterStatus,
         param.filterVulnerabilityType,
+        param.detailedFindings,
         options
       );
       const responseContext = await this.configuration.httpApi.send(

packages/datadog-api-client-v2/models/FindingAttributes.ts

@@ -15,6 +15,14 @@ import { AttributeTypeMap } from "../../datadog-api-client-common/util";
  * The JSON:API attributes of the finding.
  */
 export class FindingAttributes {
+  /**
+   * The Datadog relative link for this finding.
+   */
+  "datadogLink"?: string;
+  /**
+   * The description and remediation steps for this finding.
+   */
+  "description"?: string;
   /**
    * The evaluation of the finding.
    */
@@ -23,6 +31,10 @@ export class FindingAttributes {
    * The date on which the evaluation for this finding changed (Unix ms).
    */
   "evaluationChangedAt"?: number;
+  /**
+   * The cloud-based ID for the resource related to the finding.
+   */
+  "externalId"?: string;
   /**
    * Information about the mute status of this finding.
    */
@@ -72,6 +84,14 @@ export class FindingAttributes {
    * @ignore
    */
   static readonly attributeTypeMap: AttributeTypeMap = {
+    datadogLink: {
+      baseName: "datadog_link",
+      type: "string",
+    },
+    description: {
+      baseName: "description",
+      type: "string",
+    },
     evaluation: {
       baseName: "evaluation",
       type: "FindingEvaluation",
@@ -81,6 +101,10 @@ export class FindingAttributes {
       type: "number",
       format: "int64",
     },
+    externalId: {
+      baseName: "external_id",
+      type: "string",
+    },
     mute: {
       baseName: "mute",
       type: "FindingMute",