Update Vulnerabilities endpoints documentation (#2263)

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-02-27 14:00:46.919597",
-            "spec_repo_commit": "240ec82d"
+            "regenerated": "2025-02-27 21:31:42.586534",
+            "spec_repo_commit": "0b2e3d20"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-02-27 14:00:46.936060",
-            "spec_repo_commit": "240ec82d"
+            "regenerated": "2025-02-27 21:31:42.601882",
+            "spec_repo_commit": "0b2e3d20"
         }
     }
 }

.generator/schemas/v2/openapi.yaml

@@ -32353,6 +32353,9 @@ components:
             apm_service_catalog_read: View service catalog and service definitions.
             apm_service_catalog_write: Add, modify, and delete service catalog definitions
               when those definitions are maintained by Datadog.
+            appsec_vm_read: View infrastructure, application code, and library vulnerabilities.
+              This does not restrict API or inventory SQL access to the vulnerability
+              data source.
             cases_read: View Cases.
             cases_write: Create and update cases.
             ci_visibility_pipelines_write: Create CI Visibility pipeline spans using
@@ -45204,9 +45207,14 @@ paths:
       security:
       - apiKeyAuth: []
         appKeyAuth: []
+      - AuthZ:
+        - appsec_vm_read
       summary: List vulnerable assets
       tags:
       - Security Monitoring
+      x-unstable: '**Note**: This endpoint is a private preview.
+
+        If you are interested in accessing this API, [fill out this form](https://forms.gle/kMYC1sDr6WDUBDsx9).'
   /api/v2/security/cloud_workload/policy/download:
     get:
       description: 'The download endpoint generates a Cloud Workload Security policy
@@ -45296,12 +45304,14 @@ paths:
       security:
       - apiKeyAuth: []
         appKeyAuth: []
+      - AuthZ:
+        - appsec_vm_read
       summary: Get SBOM
       tags:
       - Security Monitoring
       x-unstable: '**Note**: This endpoint is a private preview.
 
-        If you are interested in accessing this API, please [fill out this form](https://forms.gle/kMYC1sDr6WDUBDsx9).'
+        If you are interested in accessing this API, [fill out this form](https://forms.gle/kMYC1sDr6WDUBDsx9).'
   /api/v2/security/signals/notification_rules:
     get:
       description: Returns the list of notification rules for security signals.
@@ -45857,9 +45867,14 @@ paths:
       security:
       - apiKeyAuth: []
         appKeyAuth: []
+      - AuthZ:
+        - appsec_vm_read
       summary: List vulnerabilities
       tags:
       - Security Monitoring
+      x-unstable: '**Note**: This endpoint is a private preview.
+
+        If you are interested in accessing this API, [fill out this form](https://forms.gle/kMYC1sDr6WDUBDsx9).'
   /api/v2/security/vulnerabilities/notification_rules:
     get:
       description: Returns the list of notification rules for security vulnerabilities.

examples/v2/security-monitoring/ListVulnerabilities.rb

@@ -1,6 +1,9 @@
 # List vulnerabilities returns "OK" response
 
 require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.list_vulnerabilities".to_sym] = true
+end
 api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
 opts = {
   filter_cvss_base_severity: VulnerabilitySeverity::HIGH,

examples/v2/security-monitoring/ListVulnerableAssets.rb

@@ -1,6 +1,9 @@
 # List vulnerable assets returns "OK" response
 
 require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.list_vulnerable_assets".to_sym] = true
+end
 api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
 opts = {
   filter_type: AssetType::HOST,

features/v2/security_monitoring.feature

@@ -473,7 +473,7 @@ Feature: Security Monitoring
     When the request is sent
     Then the response status is 404 Not found: asset not found
 
-  @team:DataDog/asm-vm
+  @skip @team:DataDog/asm-vm
   Scenario: Get SBOM returns "OK" response
     Given operation "GetSBOM" enabled
     And new "GetSBOM" request
@@ -830,21 +830,24 @@ Feature: Security Monitoring
 
   @generated @skip @team:DataDog/asm-vm
   Scenario: List vulnerabilities returns "Bad request: The server cannot process the request due to invalid syntax in the request." response
-    Given new "ListVulnerabilities" request
+    Given operation "ListVulnerabilities" enabled
+    And new "ListVulnerabilities" request
     When the request is sent
     Then the response status is 400 Bad request: The server cannot process the request due to invalid syntax in the request.
 
   @team:DataDog/asm-vm
   Scenario: List vulnerabilities returns "Not found: There is no request associated with the provided token." response
-    Given new "ListVulnerabilities" request
+    Given operation "ListVulnerabilities" enabled
+    And new "ListVulnerabilities" request
     And request contains "page[token]" parameter with value "unknown"
     And request contains "page[number]" parameter with value 1
     When the request is sent
     Then the response status is 404 Not found: There is no request associated with the provided token.
 
   @team:DataDog/asm-vm
   Scenario: List vulnerabilities returns "OK" response
-    Given new "ListVulnerabilities" request
+    Given operation "ListVulnerabilities" enabled
+    And new "ListVulnerabilities" request
     And request contains "filter[cvss.base.severity]" parameter with value "High"
     And request contains "filter[asset.type]" parameter with value "Service"
     And request contains "filter[tool]" parameter with value "Infra"
@@ -853,21 +856,24 @@ Feature: Security Monitoring
 
   @generated @skip @team:DataDog/asm-vm
   Scenario: List vulnerable assets returns "Bad request: The server cannot process the request due to invalid syntax in the request." response
-    Given new "ListVulnerableAssets" request
+    Given operation "ListVulnerableAssets" enabled
+    And new "ListVulnerableAssets" request
     When the request is sent
     Then the response status is 400 Bad request: The server cannot process the request due to invalid syntax in the request.
 
   @team:DataDog/asm-vm
   Scenario: List vulnerable assets returns "Not found: There is no request associated with the provided token." response
-    Given new "ListVulnerableAssets" request
+    Given operation "ListVulnerableAssets" enabled
+    And new "ListVulnerableAssets" request
     And request contains "page[token]" parameter with value "unknown"
     And request contains "page[number]" parameter with value 1
     When the request is sent
     Then the response status is 404 Not found: There is no request associated with the provided token.
 
   @team:DataDog/asm-vm
   Scenario: List vulnerable assets returns "OK" response
-    Given new "ListVulnerableAssets" request
+    Given operation "ListVulnerableAssets" enabled
+    And new "ListVulnerableAssets" request
     And request contains "filter[type]" parameter with value "Host"
     And request contains "filter[repository_url]" parameter with value "github.com/datadog/dd-go"
     And request contains "filter[risks.in_production]" parameter with value true

lib/datadog_api_client/configuration.rb

@@ -247,6 +247,8 @@ def initialize
             "v2.get_sbom": false,
             "v2.list_findings": false,
             "v2.list_historical_jobs": false,
+            "v2.list_vulnerabilities": false,
+            "v2.list_vulnerable_assets": false,
             "v2.mute_findings": false,
             "v2.run_historical_job": false,
             "v2.create_scorecard_outcomes_batch": false,

lib/datadog_api_client/v2/api/security_monitoring_api.rb

@@ -1538,7 +1538,7 @@ def get_sbom_with_http_info(asset_type, filter_asset_name, opts = {})
       return_type = opts[:debug_return_type] || 'GetSBOMResponse'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
 
       new_options = opts.merge(
         :operation => :get_sbom,
@@ -2729,6 +2729,12 @@ def list_vulnerabilities(opts = {})
     # @option opts [String] :filter_asset_operating_system_version Filter by asset operating system version.
     # @return [Array<(ListVulnerabilitiesResponse, Integer, Hash)>] ListVulnerabilitiesResponse data, response status code and response headers
     def list_vulnerabilities_with_http_info(opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.list_vulnerabilities".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.list_vulnerabilities")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.list_vulnerabilities"))
+      end
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: SecurityMonitoringAPI.list_vulnerabilities ...'
@@ -2847,7 +2853,7 @@ def list_vulnerabilities_with_http_info(opts = {})
       return_type = opts[:debug_return_type] || 'ListVulnerabilitiesResponse'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
 
       new_options = opts.merge(
         :operation => :list_vulnerabilities,
@@ -2911,6 +2917,12 @@ def list_vulnerable_assets(opts = {})
     # @option opts [String] :filter_operating_system_version Filter by operating system version.
     # @return [Array<(ListVulnerableAssetsResponse, Integer, Hash)>] ListVulnerableAssetsResponse data, response status code and response headers
     def list_vulnerable_assets_with_http_info(opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.list_vulnerable_assets".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.list_vulnerable_assets")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.list_vulnerable_assets"))
+      end
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: SecurityMonitoringAPI.list_vulnerable_assets ...'
@@ -2959,7 +2971,7 @@ def list_vulnerable_assets_with_http_info(opts = {})
       return_type = opts[:debug_return_type] || 'ListVulnerableAssetsResponse'
 
       # auth_names
-      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
 
       new_options = opts.merge(
         :operation => :list_vulnerable_assets,