[NOJIRA] Document content packs SIEM endpoints

.generator/schemas/v2/openapi.yaml

@@ -60787,19 +60787,23 @@ components:
         - DONE
         - TIMEOUT
     SecurityMonitoringContentPackActivation:
-      description: The activation status of a content pack
+      description: The activation lifecycle state of a content pack.
       enum:
         - never_activated
         - activated
         - deactivated
       example: activated
       type: string
+      x-enum-descriptions:
+        - Pack has never been activated for this organization.
+        - Pack is currently activated.
+        - Pack was previously activated but has since been deactivated.
       x-enum-varnames:
         - NEVER_ACTIVATED
         - ACTIVATED
         - DEACTIVATED
     SecurityMonitoringContentPackIntegrationStatus:
-      description: The installation status of the related integration
+      description: The installation status of the related Datadog integration.
       enum:
         - installed
         - available
@@ -60808,6 +60812,12 @@ components:
         - error
       example: installed
       type: string
+      x-enum-descriptions:
+        - Integration is fully installed.
+        - Integration exists in the catalog but is not installed.
+        - Integration is only partially configured.
+        - Integration detected (for example, logs are flowing) but not explicitly installed.
+        - Integration is in an error state.
       x-enum-varnames:
         - INSTALLED
         - AVAILABLE
@@ -60824,15 +60834,16 @@ components:
         cp_activation:
           $ref: "#/components/schemas/SecurityMonitoringContentPackActivation"
         filters_configured_for_logs:
-          description: Whether filters (Security Filters or Index Query depending on the pricing model) are configured for logs
+          description: Whether filters (Security Filters or Index Query depending on the pricing model) are present and correctly configured to route logs into Cloud SIEM.
           example: true
           type: boolean
         integration_installed_status:
           $ref: "#/components/schemas/SecurityMonitoringContentPackIntegrationStatus"
         logs_last_collected:
           $ref: "#/components/schemas/SecurityMonitoringContentPackTimestampBucket"
         logs_seen_from_any_index:
-          description: Whether logs have been seen from any index
+          description: >-
+            Whether logs for this content pack have been seen in any Datadog index within the last 72 hours, regardless of whether the Cloud SIEM filter is configured.
           example: true
           type: boolean
         state:
@@ -60897,7 +60908,7 @@ components:
         - meta
       type: object
     SecurityMonitoringContentPackStatus:
-      description: The current status of a content pack
+      description: The current operational status of a content pack.
       enum:
         - install
         - activate
@@ -60907,6 +60918,13 @@ components:
         - broken
       example: active
       type: string
+      x-enum-descriptions:
+        - Not activated; no logs detected in the last 72 hours.
+        - Not activated; logs are flowing into a Datadog index but not yet routed through Cloud SIEM.
+        - Activated; awaiting first log ingestion.
+        - Activated; logs received within the last 24 hours.
+        - Activated; integration not installed or logs last seen 24 to 72 hours ago.
+        - Activated; no logs for over 72 hours, filter missing, or Cloud SIEM index incorrectly ordered.
       x-enum-varnames:
         - INSTALL
         - ACTIVATE
@@ -60915,7 +60933,7 @@ components:
         - WARNING
         - BROKEN
     SecurityMonitoringContentPackTimestampBucket:
-      description: Timestamp bucket indicating when logs were last collected
+      description: When logs were last collected through the content pack's Cloud SIEM filter or index query.
       enum:
         - not_seen
         - within_24_hours
@@ -60924,6 +60942,12 @@ components:
         - over_30d
       example: within_24_hours
       type: string
+      x-enum-descriptions:
+        - No logs observed.
+        - Logs received within the last 24 hours.
+        - Logs last seen 24 to 72 hours ago.
+        - Logs last seen 3 to 30 days ago.
+        - Logs last seen more than 30 days ago.
       x-enum-varnames:
         - NOT_SEEN
         - WITHIN_24_HOURS
@@ -62014,7 +62038,7 @@ components:
         - $ref: "#/components/schemas/SecurityMonitoringSignalRulePayload"
         - $ref: "#/components/schemas/CloudConfigurationRulePayload"
     SecurityMonitoringSKU:
-      description: The SIEM pricing model (SKU) for the organization
+      description: The Cloud SIEM pricing model (SKU) for the organization.
       enum:
         - per_gb_analyzed
         - per_event_in_siem_index_2023
@@ -111561,10 +111585,7 @@ paths:
         - Security Monitoring
   /api/v2/security_monitoring/content_packs/states:
     get:
-      description: |-
-        Get the activation and configuration states for all security monitoring content packs.
-        This endpoint returns status information about each content pack including activation state,
-        integration status, and log collection status.
+      description: Get the activation and operational state for all Cloud SIEM content packs.
       operationId: GetContentPacksStates
       responses:
         "200":
@@ -111574,11 +111595,7 @@ paths:
                 $ref: "#/components/schemas/SecurityMonitoringContentPackStatesResponse"
           description: OK
         "403":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/JSONAPIErrorResponse"
-          description: Forbidden
+          $ref: "#/components/responses/NotAuthorizedResponse"
         "404":
           content:
             application/json:
@@ -111587,21 +111604,31 @@ paths:
           description: Not Found
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_filters_read
       summary: Get content pack states
       tags:
         - Security Monitoring
+      "x-permission":
+        operator: OR
+        permissions:
+          - security_monitoring_filters_read
+          - logs_read_index_data
       x-unstable: |-
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/security_monitoring/content_packs/{content_pack_id}/activate:
     put:
       description: |-
-        Activate a security monitoring content pack. This operation configures the necessary
+        Activate a Cloud SIEM content pack. This operation configures the necessary
         log filters or security filters depending on the pricing model and updates the content
         pack activation state.
       operationId: ActivateContentPack
       parameters:
-        - description: The ID of the content pack to activate.
+        - description: The ID of the content pack to activate (for example, `aws-cloudtrail`).
           in: path
           name: content_pack_id
           required: true
@@ -111612,11 +111639,7 @@ paths:
         "202":
           description: Accepted
         "403":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/JSONAPIErrorResponse"
-          description: Forbidden
+          $ref: "#/components/responses/NotAuthorizedResponse"
         "404":
           content:
             application/json:
@@ -111625,20 +111648,30 @@ paths:
           description: Not Found
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_filters_write
       summary: Activate content pack
       tags:
         - Security Monitoring
+      "x-permission":
+        operator: OR
+        permissions:
+          - security_monitoring_filters_write
+          - logs_modify_indexes
       x-unstable: |-
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/security_monitoring/content_packs/{content_pack_id}/deactivate:
     put:
       description: |-
-        Deactivate a security monitoring content pack. This operation removes the content pack's
+        Deactivate a Cloud SIEM content pack. This operation removes the content pack's
         configuration from log filters or security filters and updates the content pack activation state.
       operationId: DeactivateContentPack
       parameters:
-        - description: The ID of the content pack to deactivate.
+        - description: The ID of the content pack to deactivate (for example, `aws-cloudtrail`).
           in: path
           name: content_pack_id
           required: true
@@ -111649,11 +111682,7 @@ paths:
         "202":
           description: Accepted
         "403":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/JSONAPIErrorResponse"
-          description: Forbidden
+          $ref: "#/components/responses/NotAuthorizedResponse"
         "404":
           content:
             application/json:
@@ -111662,9 +111691,19 @@ paths:
           description: Not Found
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - security_monitoring_filters_write
       summary: Deactivate content pack
       tags:
         - Security Monitoring
+      "x-permission":
+        operator: OR
+        permissions:
+          - security_monitoring_filters_write
+          - logs_modify_indexes
       x-unstable: |-
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).

src/datadog_api_client/v2/api/security_monitoring_api.py

@@ -174,7 +174,7 @@ def __init__(self, api_client=None):
         self._activate_content_pack_endpoint = _Endpoint(
             settings={
                 "response_type": None,
-                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
                 "endpoint_path": "/api/v2/security_monitoring/content_packs/{content_pack_id}/activate",
                 "operation_id": "activate_content_pack",
                 "http_method": "PUT",
@@ -569,7 +569,7 @@ def __init__(self, api_client=None):
         self._deactivate_content_pack_endpoint = _Endpoint(
             settings={
                 "response_type": None,
-                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
                 "endpoint_path": "/api/v2/security_monitoring/content_packs/{content_pack_id}/deactivate",
                 "operation_id": "deactivate_content_pack",
                 "http_method": "PUT",
@@ -880,7 +880,7 @@ def __init__(self, api_client=None):
         self._get_content_packs_states_endpoint = _Endpoint(
             settings={
                 "response_type": (SecurityMonitoringContentPackStatesResponse,),
-                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
                 "endpoint_path": "/api/v2/security_monitoring/content_packs/states",
                 "operation_id": "get_content_packs_states",
                 "http_method": "GET",
@@ -2777,11 +2777,11 @@ def activate_content_pack(
     ) -> None:
         """Activate content pack.
 
-        Activate a security monitoring content pack. This operation configures the necessary
+        Activate a Cloud SIEM content pack. This operation configures the necessary
         log filters or security filters depending on the pricing model and updates the content
         pack activation state.
 
-        :param content_pack_id: The ID of the content pack to activate.
+        :param content_pack_id: The ID of the content pack to activate (for example, ``aws-cloudtrail`` ).
         :type content_pack_id: str
         :rtype: None
         """
@@ -3134,10 +3134,10 @@ def deactivate_content_pack(
     ) -> None:
         """Deactivate content pack.
 
-        Deactivate a security monitoring content pack. This operation removes the content pack's
+        Deactivate a Cloud SIEM content pack. This operation removes the content pack's
         configuration from log filters or security filters and updates the content pack activation state.
 
-        :param content_pack_id: The ID of the content pack to deactivate.
+        :param content_pack_id: The ID of the content pack to deactivate (for example, ``aws-cloudtrail`` ).
         :type content_pack_id: str
         :rtype: None
         """
@@ -3375,9 +3375,7 @@ def get_content_packs_states(
     ) -> SecurityMonitoringContentPackStatesResponse:
         """Get content pack states.
 
-        Get the activation and configuration states for all security monitoring content packs.
-        This endpoint returns status information about each content pack including activation state,
-        integration status, and log collection status.
+        Get the activation and operational state for all Cloud SIEM content packs.
 
         :rtype: SecurityMonitoringContentPackStatesResponse
         """

src/datadog_api_client/v2/model/security_monitoring_content_pack_activation.py

@@ -14,7 +14,7 @@
 
 class SecurityMonitoringContentPackActivation(ModelSimple):
     """
-    The activation status of a content pack
+    The activation lifecycle state of a content pack.
 
     :param value: Must be one of ["never_activated", "activated", "deactivated"].
     :type value: str

src/datadog_api_client/v2/model/security_monitoring_content_pack_integration_status.py

@@ -14,7 +14,7 @@
 
 class SecurityMonitoringContentPackIntegrationStatus(ModelSimple):
     """
-    The installation status of the related integration
+    The installation status of the related Datadog integration.
 
     :param value: Must be one of ["installed", "available", "partially_installed", "detected", "error"].
     :type value: str

src/datadog_api_client/v2/model/security_monitoring_content_pack_state_attributes.py

@@ -79,22 +79,22 @@ def __init__(
         :param cloud_siem_index_incorrect: Whether the cloud SIEM index configuration is incorrect (only applies to certain pricing models)
         :type cloud_siem_index_incorrect: bool
 
-        :param cp_activation: The activation status of a content pack
+        :param cp_activation: The activation lifecycle state of a content pack.
         :type cp_activation: SecurityMonitoringContentPackActivation
 
-        :param filters_configured_for_logs: Whether filters (Security Filters or Index Query depending on the pricing model) are configured for logs
+        :param filters_configured_for_logs: Whether filters (Security Filters or Index Query depending on the pricing model) are present and correctly configured to route logs into Cloud SIEM.
         :type filters_configured_for_logs: bool
 
-        :param integration_installed_status: The installation status of the related integration
+        :param integration_installed_status: The installation status of the related Datadog integration.
         :type integration_installed_status: SecurityMonitoringContentPackIntegrationStatus, optional
 
-        :param logs_last_collected: Timestamp bucket indicating when logs were last collected
+        :param logs_last_collected: When logs were last collected through the content pack's Cloud SIEM filter or index query.
         :type logs_last_collected: SecurityMonitoringContentPackTimestampBucket
 
-        :param logs_seen_from_any_index: Whether logs have been seen from any index
+        :param logs_seen_from_any_index: Whether logs for this content pack have been seen in any Datadog index within the last 72 hours, regardless of whether the Cloud SIEM filter is configured.
         :type logs_seen_from_any_index: bool
 
-        :param state: The current status of a content pack
+        :param state: The current operational status of a content pack.
         :type state: SecurityMonitoringContentPackStatus
         """
         if integration_installed_status is not unset:

src/datadog_api_client/v2/model/security_monitoring_content_pack_state_meta.py

@@ -37,7 +37,7 @@ def __init__(self_, cloud_siem_index_incorrect: bool, sku: SecurityMonitoringSKU
         :param cloud_siem_index_incorrect: Whether the cloud SIEM index configuration is incorrect at the organization level
         :type cloud_siem_index_incorrect: bool
 
-        :param sku: The SIEM pricing model (SKU) for the organization
+        :param sku: The Cloud SIEM pricing model (SKU) for the organization.
         :type sku: SecurityMonitoringSKU
         """
         super().__init__(kwargs)

src/datadog_api_client/v2/model/security_monitoring_content_pack_status.py

@@ -14,7 +14,7 @@
 
 class SecurityMonitoringContentPackStatus(ModelSimple):
     """
-    The current status of a content pack
+    The current operational status of a content pack.
 
     :param value: Must be one of ["install", "activate", "initializing", "active", "warning", "broken"].
     :type value: str

src/datadog_api_client/v2/model/security_monitoring_content_pack_timestamp_bucket.py

@@ -14,7 +14,7 @@
 
 class SecurityMonitoringContentPackTimestampBucket(ModelSimple):
     """
-    Timestamp bucket indicating when logs were last collected
+    When logs were last collected through the content pack's Cloud SIEM filter or index query.
 
     :param value: Must be one of ["not_seen", "within_24_hours", "within_24_to_72_hours", "over_72h_to_30d", "over_30d"].
     :type value: str

src/datadog_api_client/v2/model/security_monitoring_sku.py

@@ -14,7 +14,7 @@
 
 class SecurityMonitoringSKU(ModelSimple):
     """
-    The SIEM pricing model (SKU) for the organization
+    The Cloud SIEM pricing model (SKU) for the organization.
 
     :param value: Must be one of ["per_gb_analyzed", "per_event_in_siem_index_2023", "add_on_2024"].
     :type value: str