Add anomaly detection options to security monitoring rules (#3017)

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

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -47320,6 +47320,86 @@ components:
           description: The name of the reference table.
           type: string
       type: object
+    SecurityMonitoringRuleAnomalyDetectionOptions:
+      additionalProperties: {}
+      description: Options on anomaly detection method.
+      properties:
+        bucketDuration:
+          $ref: '#/components/schemas/SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration'
+        detectionTolerance:
+          $ref: '#/components/schemas/SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance'
+        learningDuration:
+          $ref: '#/components/schemas/SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration'
+        learningPeriodBaseline:
+          description: An optional override baseline to apply while the rule is in
+            the learning period. Must be greater than or equal to 0.
+          format: int64
+          minimum: 0
+          type: integer
+      type: object
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration:
+      description: 'Duration in seconds of the time buckets used to aggregate events
+        matched by the rule.
+
+        Must be greater than or equal to 300.'
+      enum:
+      - 300
+      - 600
+      - 900
+      - 1800
+      - 3600
+      - 10800
+      example: 300
+      format: int32
+      type: integer
+      x-enum-varnames:
+      - FIVE_MINUTES
+      - TEN_MINUTES
+      - FIFTEEN_MINUTES
+      - THIRTY_MINUTES
+      - ONE_HOUR
+      - THREE_HOURS
+    SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance:
+      description: 'An optional parameter that sets how permissive anomaly detection
+        is.
+
+        Higher values require higher deviations before triggering a signal.'
+      enum:
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      example: 5
+      format: int32
+      type: integer
+      x-enum-varnames:
+      - ONE
+      - TWO
+      - THREE
+      - FOUR
+      - FIVE
+    SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration:
+      description: Learning duration in hours. Anomaly detection waits for at least
+        this amount of historical data before it starts evaluating.
+      enum:
+      - 1
+      - 6
+      - 12
+      - 24
+      - 48
+      - 168
+      - 336
+      format: int32
+      type: integer
+      x-enum-varnames:
+      - ONE_HOUR
+      - SIX_HOURS
+      - TWELVE_HOURS
+      - ONE_DAY
+      - TWO_DAYS
+      - ONE_WEEK
+      - TWO_WEEKS
     SecurityMonitoringRuleCase:
       description: Case when signal is generated.
       properties:
@@ -47685,6 +47765,8 @@ components:
     SecurityMonitoringRuleOptions:
       description: Options.
       properties:
+        anomalyDetectionOptions:
+          $ref: '#/components/schemas/SecurityMonitoringRuleAnomalyDetectionOptions'
         complianceRuleOptions:
           $ref: '#/components/schemas/CloudConfigurationComplianceRuleOptions'
         decreaseCriticalityBasedOnEnv:
@@ -55124,6 +55206,8 @@ components:
     ThreatHuntingJobOptions:
       description: Job options.
       properties:
+        anomalyDetectionOptions:
+          $ref: '#/components/schemas/SecurityMonitoringRuleAnomalyDetectionOptions'
         detectionMethod:
           $ref: '#/components/schemas/SecurityMonitoringRuleDetectionMethod'
         evaluationWindow:

docs/datadog_api_client.v2.model.rst

@@ -21032,6 +21032,34 @@ datadog\_api\_client.v2.model.security\_monitoring\_reference\_table module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.security\_monitoring\_rule\_anomaly\_detection\_options module
+--------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.security\_monitoring\_rule\_anomaly\_detection\_options\_bucket\_duration module
+--------------------------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_bucket_duration
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.security\_monitoring\_rule\_anomaly\_detection\_options\_detection\_tolerance module
+------------------------------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_detection_tolerance
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.security\_monitoring\_rule\_anomaly\_detection\_options\_learning\_duration module
+----------------------------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_learning_duration
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.security\_monitoring\_rule\_case module
 ---------------------------------------------------------------------
 

examples/v2/security-monitoring/CreateSecurityMonitoringRule_2323193894.py

@@ -0,0 +1,88 @@
+"""
+Create a detection rule with detection method 'anomaly_detection' returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
+from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options import (
+    SecurityMonitoringRuleAnomalyDetectionOptions,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_bucket_duration import (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_detection_tolerance import (
+    SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_learning_duration import (
+    SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_case_create import SecurityMonitoringRuleCaseCreate
+from datadog_api_client.v2.model.security_monitoring_rule_detection_method import SecurityMonitoringRuleDetectionMethod
+from datadog_api_client.v2.model.security_monitoring_rule_evaluation_window import (
+    SecurityMonitoringRuleEvaluationWindow,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_keep_alive import SecurityMonitoringRuleKeepAlive
+from datadog_api_client.v2.model.security_monitoring_rule_max_signal_duration import (
+    SecurityMonitoringRuleMaxSignalDuration,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_options import SecurityMonitoringRuleOptions
+from datadog_api_client.v2.model.security_monitoring_rule_query_aggregation import (
+    SecurityMonitoringRuleQueryAggregation,
+)
+from datadog_api_client.v2.model.security_monitoring_rule_severity import SecurityMonitoringRuleSeverity
+from datadog_api_client.v2.model.security_monitoring_rule_type_create import SecurityMonitoringRuleTypeCreate
+from datadog_api_client.v2.model.security_monitoring_standard_data_source import SecurityMonitoringStandardDataSource
+from datadog_api_client.v2.model.security_monitoring_standard_rule_create_payload import (
+    SecurityMonitoringStandardRuleCreatePayload,
+)
+from datadog_api_client.v2.model.security_monitoring_standard_rule_query import SecurityMonitoringStandardRuleQuery
+
+body = SecurityMonitoringStandardRuleCreatePayload(
+    name="Example-Security-Monitoring",
+    type=SecurityMonitoringRuleTypeCreate.LOG_DETECTION,
+    is_enabled=True,
+    queries=[
+        SecurityMonitoringStandardRuleQuery(
+            aggregation=SecurityMonitoringRuleQueryAggregation.COUNT,
+            data_source=SecurityMonitoringStandardDataSource.LOGS,
+            distinct_fields=[],
+            group_by_fields=[
+                "@usr.email",
+                "@network.client.ip",
+            ],
+            has_optional_group_by_fields=False,
+            name="",
+            query="service:app status:error",
+        ),
+    ],
+    cases=[
+        SecurityMonitoringRuleCaseCreate(
+            name="",
+            status=SecurityMonitoringRuleSeverity.INFO,
+            notifications=[],
+            condition="a > 0.995",
+        ),
+    ],
+    message="An anomaly detection rule",
+    options=SecurityMonitoringRuleOptions(
+        detection_method=SecurityMonitoringRuleDetectionMethod.ANOMALY_DETECTION,
+        evaluation_window=SecurityMonitoringRuleEvaluationWindow.FIFTEEN_MINUTES,
+        keep_alive=SecurityMonitoringRuleKeepAlive.ONE_HOUR,
+        max_signal_duration=SecurityMonitoringRuleMaxSignalDuration.ONE_DAY,
+        anomaly_detection_options=SecurityMonitoringRuleAnomalyDetectionOptions(
+            bucket_duration=SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.FIVE_MINUTES,
+            learning_duration=SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration.ONE_DAY,
+            detection_tolerance=SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance.THREE,
+            learning_period_baseline=10,
+        ),
+    ),
+    tags=[],
+    filters=[],
+)
+
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = SecurityMonitoringApi(api_client)
+    response = api_instance.create_security_monitoring_rule(body=body)
+
+    print(response)

src/datadog_api_client/v2/model/security_monitoring_rule_anomaly_detection_options.py

@@ -0,0 +1,94 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_bucket_duration import (
+        SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration,
+    )
+    from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_detection_tolerance import (
+        SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance,
+    )
+    from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_learning_duration import (
+        SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration,
+    )
+
+
+class SecurityMonitoringRuleAnomalyDetectionOptions(ModelNormal):
+    validations = {
+        "learning_period_baseline": {
+            "inclusive_minimum": 0,
+        },
+    }
+
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_bucket_duration import (
+            SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration,
+        )
+        from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_detection_tolerance import (
+            SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance,
+        )
+        from datadog_api_client.v2.model.security_monitoring_rule_anomaly_detection_options_learning_duration import (
+            SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration,
+        )
+
+        return {
+            "bucket_duration": (SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration,),
+            "detection_tolerance": (SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance,),
+            "learning_duration": (SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration,),
+            "learning_period_baseline": (int,),
+        }
+
+    attribute_map = {
+        "bucket_duration": "bucketDuration",
+        "detection_tolerance": "detectionTolerance",
+        "learning_duration": "learningDuration",
+        "learning_period_baseline": "learningPeriodBaseline",
+    }
+
+    def __init__(
+        self_,
+        bucket_duration: Union[SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration, UnsetType] = unset,
+        detection_tolerance: Union[SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance, UnsetType] = unset,
+        learning_duration: Union[SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration, UnsetType] = unset,
+        learning_period_baseline: Union[int, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        Options on anomaly detection method.
+
+        :param bucket_duration: Duration in seconds of the time buckets used to aggregate events matched by the rule.
+            Must be greater than or equal to 300.
+        :type bucket_duration: SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration, optional
+
+        :param detection_tolerance: An optional parameter that sets how permissive anomaly detection is.
+            Higher values require higher deviations before triggering a signal.
+        :type detection_tolerance: SecurityMonitoringRuleAnomalyDetectionOptionsDetectionTolerance, optional
+
+        :param learning_duration: Learning duration in hours. Anomaly detection waits for at least this amount of historical data before it starts evaluating.
+        :type learning_duration: SecurityMonitoringRuleAnomalyDetectionOptionsLearningDuration, optional
+
+        :param learning_period_baseline: An optional override baseline to apply while the rule is in the learning period. Must be greater than or equal to 0.
+        :type learning_period_baseline: int, optional
+        """
+        if bucket_duration is not unset:
+            kwargs["bucket_duration"] = bucket_duration
+        if detection_tolerance is not unset:
+            kwargs["detection_tolerance"] = detection_tolerance
+        if learning_duration is not unset:
+            kwargs["learning_duration"] = learning_duration
+        if learning_period_baseline is not unset:
+            kwargs["learning_period_baseline"] = learning_period_baseline
+        super().__init__(kwargs)

src/datadog_api_client/v2/model/security_monitoring_rule_anomaly_detection_options_bucket_duration.py

@@ -0,0 +1,63 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(ModelSimple):
+    """
+    Duration in seconds of the time buckets used to aggregate events matched by the rule.
+        Must be greater than or equal to 300.
+
+    :param value: Must be one of [300, 600, 900, 1800, 3600, 10800].
+    :type value: int
+    """
+
+    allowed_values = {
+        300,
+        600,
+        900,
+        1800,
+        3600,
+        10800,
+    }
+    FIVE_MINUTES: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+    TEN_MINUTES: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+    FIFTEEN_MINUTES: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+    THIRTY_MINUTES: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+    ONE_HOUR: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+    THREE_HOURS: ClassVar["SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (int,),
+        }
+
+
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.FIVE_MINUTES = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(300)
+)
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.TEN_MINUTES = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(600)
+)
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.FIFTEEN_MINUTES = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(900)
+)
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.THIRTY_MINUTES = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(1800)
+)
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.ONE_HOUR = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(3600)
+)
+SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration.THREE_HOURS = (
+    SecurityMonitoringRuleAnomalyDetectionOptionsBucketDuration(10800)
+)