cfn-guardian 0.13.3 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6499c49242499318fb5e91766a52219a941f2993bc6d8236734a95c47c67f392
-  data.tar.gz: 6caf244eeb6ffbf88fa299fd9c908f84f4c4866fac81a470141aa971f5a6d461
+  metadata.gz: e4595a270016361e041e9aa0bfc6a4921388036bc224152e63b4d71fa3c0f3c8
+  data.tar.gz: 0fc14a5114332c794335432edfc28907d5080a5faeab449118da714b17b1b54f
 SHA512:
-  metadata.gz: ffbcd0281d97cc3b4ff01e4dd4de1f5cd5f3db76759a9e2b93a831d346acbd3849702d450039bd54e1031bb9782d7a3ff9109ebda738a4c18a39a425ab728fe5
-  data.tar.gz: 679154efbf9054ffabde0511df35e7b618cd602e170b687f496f6e8ec0710219badcc050a2ea5562914f5ce11e8e09eca74522ac048c200dd0b1feb2e081b670
+  metadata.gz: 053dc2627f05cfda432920324f0b7c5b171fe9121b6d46f528c99c3c6042eb1660d508c41ba65f00cd38a67befdea8936a7ceb9bedc96e8ab83ea02a7bea2c60
+  data.tar.gz: 31ad2da72a21a7952b93934f1b67dd8e3f78849dd1957355efb799b796eda2d69ee7e270abee63aa64140db940c16f5c607ca06316b361bfb719f68c7f3662f9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cfn-guardian (0.13.3)
+    cfn-guardian (0.14.0)
       aws-sdk-cloudformation (~> 1.76, < 2)
       aws-sdk-cloudwatch (~> 1.72, < 2)
       aws-sdk-codecommit (~> 1.53, < 2)

data/docs/alarm_templates.md

@@ -141,4 +141,20 @@ Templates:
       Period: 60
       EvaluationPeriods: 10
       DatapointsToAlarm: 6
-```
+```
+
+## Anomaly Detection
+
+Instead of a static `Threshold`, an alarm can compare a metric against a CloudWatch anomaly detection band by setting `AnomalyDetection: true` along with one of the anomaly-specific `ComparisonOperator` values. `StandardDeviation` (default `2`) controls how wide the expected band is.
+
+```yaml
+Templates:
+  Ec2Instance:
+    CPUUtilizationHigh:
+      AnomalyDetection: true
+      StandardDeviation: 2
+      ComparisonOperator: GreaterThanUpperThreshold
+      EvaluationPeriods: 3
+```
+
+`Threshold` cannot be combined with `AnomalyDetection`. See [Anomaly Detection Alarms](anomaly_detection.md) for the full property reference, valid `ComparisonOperator` values, and more examples.

data/docs/anomaly_detection.md

@@ -0,0 +1,74 @@
+# Anomaly Detection Alarms
+
+Anomaly detection alarms use CloudWatch [anomaly detection](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Anomaly_Detection.html) to alarm on a metric's expected behaviour rather than a fixed number. CloudWatch builds a model of the metric's normal range (a "band") from up to two weeks of history and the alarm fires when the metric strays outside that band, instead of crossing a static `Threshold`.
+
+## The Problem
+
+A static `Threshold` works well when "too high" or "too low" is a known constant, but many metrics (queue depth, request count, CPU on a workload with a daily cycle) have a normal range that varies by time of day or day of week. A fixed threshold set high enough to avoid false alarms on the daily peak is too high to catch a real problem during the trough, and vice versa.
+
+## How It Works
+
+Instead of emitting a CloudWatch alarm with a static `Threshold`, an anomaly detection alarm emits the CloudFormation `Metrics` property (a list of `MetricDataQuery` objects) with:
+
+1. A `MetricStat` entry (`m1`) that returns the raw metric, built from the alarm's usual `MetricName`, `Namespace`, `Dimensions`, `Period` and `Statistic`.
+2. An `ANOMALY_DETECTION_BAND(m1, <StandardDeviation>)` expression entry (`ad1`) that computes the expected value band for that metric.
+
+The alarm then sets `ThresholdMetricId: ad1` instead of a `Threshold`, and compares the metric against the band using one of the anomaly-specific `ComparisonOperator` values. This implicitly creates the underlying `AWS::CloudWatch::AnomalyDetector` model in CloudWatch - no separate CloudFormation resource is required.
+
+## Configuration
+
+Add `AnomalyDetection: true` and a `ComparisonOperator` to an alarm template. Optionally set `StandardDeviation` to control the width of the expected band.
+
+### Properties
+
+| Property | Required | Default | Description |
+| --- | --- | --- | --- |
+| `AnomalyDetection` | Yes | `false` | Set to `true` to alarm on an anomaly detection band instead of a static Threshold. |
+| `StandardDeviation` | No | `2` | The width of the expected value band, in standard deviations. A larger number widens the band (fewer, larger anomalies alarm); a smaller number narrows it. |
+| `ComparisonOperator` | Yes | - | Must be one of `GreaterThanUpperThreshold`, `LessThanLowerThreshold`, or `LessThanLowerOrGreaterThanUpperThreshold`. |
+
+`Threshold` must not be set on an anomaly detection alarm - CloudFormation treats `Threshold` and `ThresholdMetricId` as mutually exclusive, and `cfn-guardian` will fail validation if both are supplied.
+
+### Overriding Default Alarms
+
+You can convert an existing default alarm to use anomaly detection by overriding it in the template:
+
+```yaml
+Templates:
+  Ec2Instance:
+    CPUUtilizationHigh:
+      AnomalyDetection: true
+      StandardDeviation: 2
+      ComparisonOperator: GreaterThanUpperThreshold
+      EvaluationPeriods: 3
+```
+
+### Creating New Alarms
+
+You can also create new anomaly detection alarms that don't override any defaults. `MetricName` and `Namespace` are still required, the same as any other alarm, since they identify the metric CloudWatch builds the anomaly detection model from:
+
+```yaml
+Templates:
+  SQSQueue:
+    ApproximateNumberOfMessagesVisibleAnomaly:
+      MetricName: ApproximateNumberOfMessagesVisible
+      Statistic: Average
+      AnomalyDetection: true
+      StandardDeviation: 3
+      ComparisonOperator: LessThanLowerOrGreaterThanUpperThreshold
+      EvaluationPeriods: 3
+      DatapointsToAlarm: 2
+      AlarmAction: Warning
+```
+
+## Choosing A Comparison Operator
+
+- `GreaterThanUpperThreshold` - alarm only when the metric goes above the expected band (e.g. an unexpected spike in queue depth or error count).
+- `LessThanLowerThreshold` - alarm only when the metric drops below the expected band (e.g. request count dropping to zero when traffic is expected).
+- `LessThanLowerOrGreaterThanUpperThreshold` - alarm on either side of the band. This is the most common choice when you don't know in advance which direction is abnormal.
+
+## Limitations
+
+- **Training period**: CloudWatch needs data to learn the metric's normal pattern; a newly created anomaly detector can take some time (often a few hours, up to a few days for metrics with a weekly pattern) before the band is reliable.
+- **Cannot combine with `SearchExpression`**: both features rely on the alarm's `Metrics` property, so `AnomalyDetection` and `SearchExpression` cannot be set on the same alarm.
+- See the [CloudWatch anomaly detection documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Anomaly_Detection.html) for how the model is trained and how to inspect it in the console.

data/docs/overview.md

@@ -23,4 +23,5 @@
 9. [Alarms for Custom Metrics](custom_metrics.md)
 10. [Dimension Variables](variables.md)
 11. [Search Expression Alarms](search_expressions.md)
-12. [Alarm Tags](alarm_tags.md)
+12. [Alarm Tags](alarm_tags.md)
+13. [Anomaly Detection Alarms](anomaly_detection.md)

data/lib/cfnguardian/compile.rb

@@ -190,6 +190,22 @@ module CfnGuardian
       @resources.each do |resource|
         case resource.type
         when 'Alarm'
+          unless [true, false].include?(resource.anomaly_detection)
+            @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has invalid AnomalyDetection value '#{resource.anomaly_detection.inspect}'. Must be a boolean (true or false)."
+          end
+
+          unless resource.standard_deviation.nil?
+            if !resource.standard_deviation.is_a?(Numeric) || !resource.standard_deviation.finite? || resource.standard_deviation <= 0
+              @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has invalid StandardDeviation '#{resource.standard_deviation}'. Must be a finite positive number."
+            elsif resource.anomaly_detection != true
+              @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} sets StandardDeviation but AnomalyDetection is not true. StandardDeviation only applies to anomaly detection alarms; either remove it or set AnomalyDetection: true."
+            end
+          end
+
+          if resource.search_expression && resource.anomaly_detection == true
+            @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} cannot set both SearchExpression and AnomalyDetection. They both rely on the mutually exclusive Metrics property."
+          end
+
           if resource.search_expression
             if !resource.search_expression.is_a?(String) || resource.search_expression.strip.empty?
               @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has an invalid SearchExpression. Must be a non-empty string."
@@ -203,7 +219,27 @@ module CfnGuardian
                 @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has invalid SearchAggregation '#{resource.search_aggregation}'. Must be one of: #{valid_aggregations.join(', ')}."
               end
             end
+          elsif resource.anomaly_detection == true
+            valid_operators = %w(GreaterThanUpperThreshold LessThanLowerOrGreaterThanUpperThreshold LessThanLowerThreshold)
+            unless valid_operators.include?(resource.comparison_operator)
+              @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has invalid ComparisonOperator '#{resource.comparison_operator}' for an AnomalyDetection alarm. Must be one of: #{valid_operators.join(', ')}."
+            end
+
+            if resource.threshold_overridden
+              @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} cannot set both Threshold and AnomalyDetection. Anomaly detection alarms use StandardDeviation to size the expected band instead of a static Threshold."
+            end
+
+            %w(metric_name namespace).each do |property|
+              if resource.send(property).nil?
+                @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has nil value for property #{property.to_camelcase}. This could be due to incorrect spelling of a default alarm name or missing property #{property.to_camelcase} on a new alarm."
+              end
+            end
           else
+            anomaly_only_operators = %w(GreaterThanUpperThreshold LessThanLowerOrGreaterThanUpperThreshold LessThanLowerThreshold)
+            if anomaly_only_operators.include?(resource.comparison_operator)
+              @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has ComparisonOperator '#{resource.comparison_operator}' which requires AnomalyDetection to be true. Either set AnomalyDetection: true or use a static-threshold ComparisonOperator."
+            end
+
             %w(metric_name namespace).each do |property|
               if resource.send(property).nil?
                 @errors << "CfnGuardian::AlarmPropertyError - alarm #{resource.name} for resource #{resource.resource_id} has nil value for property #{property.to_camelcase}. This could be due to incorrect spelling of a default alarm name or missing property #{property.to_camelcase} on a new alarm."

data/lib/cfnguardian/display_formatter.rb

@@ -14,6 +14,8 @@ module CfnGuardian
       
       @alarms.each do |alarm|
         alarm_name = CfnGuardian::CloudWatch.get_alarm_name(alarm)
+        use_anomaly_detection = alarm.anomaly_detection == true
+
         rows = [
           ['ResourceId', alarm.resource_id],
           ['ResourceHash', alarm.resource_hash],
@@ -21,7 +23,8 @@ module CfnGuardian
           ['Enabled', alarm.enabled],
           ['MetricName', alarm.metric_name],
           ['Dimensions', alarm.dimensions],
-          ['Threshold', alarm.threshold],
+          # An anomaly detection alarm uses ThresholdMetricId/StandardDeviation instead of a static Threshold.
+          ['Threshold', use_anomaly_detection ? nil : alarm.threshold],
           ['Period', alarm.period],
           ['EvaluationPeriods', alarm.evaluation_periods],
           ['ComparisonOperator', alarm.comparison_operator],
@@ -33,9 +36,11 @@ module CfnGuardian
           ['Unit', alarm.unit],
           ['AlarmAction', alarm.alarm_action],
           ['OkActionDisabled', alarm.ok_action_disabled],
-          ['TreatMissingData', alarm.treat_missing_data]
+          ['TreatMissingData', alarm.treat_missing_data],
+          ['AnomalyDetection', use_anomaly_detection ? alarm.anomaly_detection : nil],
+          ['StandardDeviation', use_anomaly_detection ? (alarm.standard_deviation || 2) : nil]
         ]
-        
+
         rows.select! {|row| !row[1].nil?}
         
         resp << {
@@ -53,30 +58,65 @@ module CfnGuardian
       @alarms.each do |alarm|
         alarm_name = CfnGuardian::CloudWatch.get_alarm_name(alarm)
         metric_alarm = metric_alarms.find {|ma| ma.alarm_name.include? alarm_name}
-        dimensions = metric_alarm.dimensions.map {|dim| {dim.name.to_sym => dim.value}}.inject(:merge)
-        
+        use_anomaly_detection = alarm.anomaly_detection == true
+        deployed_anomaly_detection = anomaly_detection_deployed?(metric_alarm)
+
+        # A real deployed anomaly detection alarm has no top-level MetricName/Statistic/
+        # Period/Unit/Dimensions - CloudWatch only populates those nested inside the raw
+        # metric's MetricStat (see #deployed_metric_stat). Fall back to the top-level fields
+        # when the deployed alarm isn't a metric-math alarm at all (e.g. local config wants
+        # anomaly detection but the deployed alarm is still a plain static alarm).
+        metric_stat = deployed_metric_stat(metric_alarm)
+        if metric_stat
+          deployed_metric_name = metric_stat.metric.metric_name
+          deployed_dimensions = (metric_stat.metric.dimensions || []).map {|dim| {dim.name.to_sym => dim.value}}.inject(:merge)
+          deployed_period = metric_stat.period
+          deployed_statistic = metric_stat.stat
+          deployed_unit = metric_stat.unit
+        else
+          deployed_metric_name = metric_alarm.metric_name
+          deployed_dimensions = (metric_alarm.dimensions || []).map {|dim| {dim.name.to_sym => dim.value}}.inject(:merge)
+          deployed_period = metric_alarm.period
+          deployed_statistic = metric_alarm.statistic
+          deployed_unit = metric_alarm.unit
+        end
+
+        # An anomaly detection alarm's MetricStat.Stat holds whichever of Statistic/
+        # ExtendedStatistic cfn-guardian generated (see stacks/resources.rb#add_alarm), so
+        # compare that combined value here and suppress the separate ExtendedStatistic row
+        # below - the same way Threshold is already suppressed for anomaly alarms.
+        local_statistic = use_anomaly_detection ? (alarm.extended_statistic || alarm.statistic) : alarm.statistic
+
         rows = [
           ['ResourceId', alarm.resource_id, alarm.resource_id],
           ['ResourceHash', alarm.resource_hash, alarm.resource_hash],
           ['ResourceName', alarm.resource_name, alarm.resource_name],
           ['Enabled', alarm.enabled, true],
-          ['MetricName', alarm.metric_name, metric_alarm.metric_name],
-          ['Dimensions', alarm.dimensions, dimensions],
-          ['Threshold', alarm.threshold.to_f, metric_alarm.threshold],
-          ['Period', alarm.period, metric_alarm.period],
+          ['MetricName', alarm.metric_name, deployed_metric_name],
+          ['Dimensions', alarm.dimensions, deployed_dimensions],
+          # A correctly deployed anomaly detection alarm has no static Threshold (it uses
+          # ThresholdMetricId/Metrics instead), so comparing Threshold here would always show
+          # as different. Compare AnomalyDetection/StandardDeviation below instead.
+          ['Threshold', use_anomaly_detection ? nil : alarm.threshold.to_f, use_anomaly_detection ? nil : metric_alarm.threshold],
+          ['Period', alarm.period, deployed_period],
           ['EvaluationPeriods', alarm.evaluation_periods, metric_alarm.evaluation_periods],
           ['ComparisonOperator', alarm.comparison_operator, metric_alarm.comparison_operator],
-          ['Statistic', alarm.statistic, metric_alarm.statistic],
+          ['Statistic', local_statistic, deployed_statistic],
           ['ActionsEnabled', alarm.actions_enabled, metric_alarm.actions_enabled],
           ['DatapointsToAlarm', alarm.datapoints_to_alarm, metric_alarm.datapoints_to_alarm],
-          ['ExtendedStatistic', alarm.extended_statistic, metric_alarm.extended_statistic],
+          ['ExtendedStatistic', use_anomaly_detection ? nil : alarm.extended_statistic, use_anomaly_detection ? nil : metric_alarm.extended_statistic],
           ['EvaluateLowSampleCountPercentile', alarm.evaluate_low_sample_count_percentile, metric_alarm.evaluate_low_sample_count_percentile],
-          ['Unit', alarm.unit, metric_alarm.unit],
+          ['Unit', alarm.unit, deployed_unit],
           ['TreatMissingData', alarm.treat_missing_data, metric_alarm.treat_missing_data],
           ['AlarmAction', alarm.alarm_action, alarm.alarm_action],
           ['OkActionDisabled', alarm.ok_action_disabled]
         ]
-        
+
+        if use_anomaly_detection || deployed_anomaly_detection
+          rows << ['AnomalyDetection', use_anomaly_detection, deployed_anomaly_detection]
+          rows << ['StandardDeviation', use_anomaly_detection ? (alarm.standard_deviation || 2).to_f : nil, deployed_standard_deviation(metric_alarm)]
+        end
+
         rows.select! {|row| !row[1].nil?}.each {|row| colour_compare_row(row)}
         
         if has_config_difference?(rows)
@@ -148,7 +188,40 @@ module CfnGuardian
     end
     
     private
-    
+
+    # An anomaly detection alarm is identified on the deployed side by having a
+    # ThresholdMetricId set (it references the ANOMALY_DETECTION_BAND expression in Metrics).
+    def anomaly_detection_deployed?(metric_alarm)
+      !metric_alarm.threshold_metric_id.nil? && !metric_alarm.threshold_metric_id.to_s.empty?
+    end
+
+    # For an anomaly detection alarm, CloudWatch does not populate the top-level MetricName/
+    # Namespace/Statistic/Period/Unit/Dimensions fields on describe_alarms - those live nested
+    # inside the raw metric's MetricStat, referenced by the Metrics array entry cfn-guardian
+    # generates with Id 'm1' (see stacks/resources.rb#add_alarm). Returns nil when the deployed
+    # alarm has no such entry (e.g. it's a plain static alarm, not managed via Metrics/MetricStat).
+    def deployed_metric_stat(metric_alarm)
+      raw_metric = (metric_alarm.metrics || []).find {|m| m.id == 'm1' && !m.metric_stat.nil?}
+      raw_metric.nil? ? nil : raw_metric.metric_stat
+    end
+
+    # Extracts the StandardDeviation from the deployed ANOMALY_DETECTION_BAND(m1, <stddev>)
+    # expression referenced by ThresholdMetricId. This is approximate: it assumes the band
+    # expression is in the same shape cfn-guardian generates, and returns nil if it can't be
+    # found or parsed (e.g. an anomaly alarm not managed by cfn-guardian). The number pattern
+    # also matches scientific notation (e.g. "1.0e-06"), since add_alarm embeds Ruby's
+    # Float#to_s form of StandardDeviation and to_s switches to that notation for very
+    # small (or very large) finite values.
+    def deployed_standard_deviation(metric_alarm)
+      return nil unless anomaly_detection_deployed?(metric_alarm)
+
+      band_metric = (metric_alarm.metrics || []).find {|m| m.id == metric_alarm.threshold_metric_id}
+      return nil if band_metric.nil? || band_metric.expression.nil?
+
+      match = band_metric.expression.match(/ANOMALY_DETECTION_BAND\([^,]+,\s*(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\s*\)/)
+      match.nil? ? nil : match[1].to_f
+    end
+
     def has_config_difference?(rows)
       rows.each do |row| 
         unless row[1].eql?(row[2])

data/lib/cfnguardian/models/alarm.rb

@@ -6,8 +6,9 @@ module CfnGuardian
     class BaseAlarm
       
       attr_reader :type,
-        :resource_hash
-        
+        :resource_hash,
+        :threshold_overridden
+
       attr_accessor :group,
         :name,
         :metric_name,
@@ -33,8 +34,10 @@ module CfnGuardian
         :additional_notifiers,
         :tags,
         :search_expression,
-        :search_aggregation
-      
+        :search_aggregation,
+        :anomaly_detection,
+        :standard_deviation
+
       def initialize(resource)
         @type = 'Alarm'
         @group = nil
@@ -43,6 +46,7 @@ module CfnGuardian
         @namespace = nil
         @dimensions = nil
         @threshold = 0
+        @threshold_overridden = false
         @period = 60
         @evaluation_periods = 1
         @comparison_operator = 'GreaterThanThreshold'
@@ -64,12 +68,23 @@ module CfnGuardian
         @tags = {}
         @search_expression = nil
         @search_aggregation = nil
+        @anomaly_detection = false
+        @standard_deviation = nil
       end
-      
+
       def metric_name=(metric_name)
         raise ArgumentError.new("metric_name '#{metric_name}' must be of type String, provided type '#{metric_name.class}'") unless metric_name.is_a?(String)
         @metric_name=metric_name
-      end      
+      end
+
+      # Internal-only marker used to track that Threshold was explicitly set via a
+      # config override (as opposed to a resource group's own default_alarms
+      # definition). This is intentionally not exposed as a public writer so a
+      # YAML config cannot set ThresholdOverridden directly and bypass the
+      # "can't combine Threshold and AnomalyDetection" validation.
+      def mark_threshold_overridden!
+        @threshold_overridden = true
+      end
     end
     
     class AcmAlarm < BaseAlarm

data/lib/cfnguardian/resources/base.rb

@@ -251,6 +251,12 @@ module CfnGuardian::Resource
       logger.debug("overriding #{obj.type} property '#{attr}' with value #{value} for resource id: #{obj.resource_id}")
       begin
         obj.send("#{attr.to_underscore}=",value.clone)
+        # Track that Threshold was set via a config override (as opposed to a resource
+        # group's own default_alarms definition) so validate_resources can detect a
+        # config that sets both a static Threshold and AnomalyDetection. This uses a
+        # dedicated marker method (not a public threshold_overridden= writer) so a
+        # config can't set ThresholdOverridden directly to bypass that validation.
+        obj.mark_threshold_overridden! if attr.to_underscore == 'threshold' && obj.respond_to?(:mark_threshold_overridden!)
       rescue NoMethodError => e
         if !e.message.match?(/inherit/)
           logger.warn "Unknown property '#{attr}' for type: #{obj.type} and resource id: #{obj.resource_id}"

data/lib/cfnguardian/stacks/resources.rb

@@ -34,6 +34,7 @@ module CfnGuardian
         actions = alarm.alarm_action.kind_of?(Array) ? alarm.alarm_action.map{|action| Ref(action)} : [Ref(alarm.alarm_action)]
         actions.concat alarm.maintenance_groups.map {|mg| Ref(mg)} if alarm.maintenance_groups.any?
         use_search = alarm.search_expression.is_a?(String) && !alarm.search_expression.strip.empty?
+        use_anomaly_detection = alarm.anomaly_detection == true
 
         @template.declare do
           CloudWatch_Alarm("#{alarm.resource_hash}#{alarm.group}#{alarm.name.gsub(/[^0-9a-zA-Z]/i, '')}#{alarm.type}"[0..255]) do
@@ -42,7 +43,9 @@ module CfnGuardian
             AlarmName CfnGuardian::CloudWatch.get_alarm_name(alarm)
             ComparisonOperator alarm.comparison_operator
             EvaluationPeriods alarm.evaluation_periods
-            Threshold alarm.threshold
+            # Threshold and ThresholdMetricId are mutually exclusive on AWS::CloudWatch::Alarm -
+            # an anomaly detection alarm uses ThresholdMetricId (set below) instead of a static Threshold.
+            Threshold alarm.threshold unless use_anomaly_detection
             AlarmActions actions
             OKActions actions unless alarm.ok_action_disabled
             TreatMissingData alarm.treat_missing_data unless alarm.treat_missing_data.nil?
@@ -63,6 +66,34 @@ module CfnGuardian
                   ReturnData: true
                 }
               ]
+            elsif use_anomaly_detection
+              band_width = alarm.standard_deviation || 2
+              metric_stat = {
+                Metric: {
+                  Namespace: alarm.namespace,
+                  MetricName: alarm.metric_name
+                },
+                Period: alarm.period,
+                Stat: alarm.extended_statistic.nil? ? alarm.statistic : alarm.extended_statistic
+              }
+              metric_stat[:Metric][:Dimensions] = alarm.dimensions.map {|k,v| {Name: k, Value: v}} unless alarm.dimensions.nil?
+              metric_stat[:Unit] = alarm.unit unless alarm.unit.nil?
+
+              Metrics [
+                {
+                  Id: 'm1',
+                  MetricStat: metric_stat,
+                  ReturnData: true
+                },
+                {
+                  Id: 'ad1',
+                  Expression: "ANOMALY_DETECTION_BAND(m1, #{band_width})",
+                  Label: "#{alarm.metric_name} (expected)",
+                  ReturnData: true
+                }
+              ]
+              ThresholdMetricId 'ad1'
+              EvaluateLowSampleCountPercentile alarm.evaluate_low_sample_count_percentile unless alarm.evaluate_low_sample_count_percentile.nil?
             else
               Dimensions alarm.dimensions.map {|k,v| {Name: k, Value: v}} unless alarm.dimensions.nil?
               Statistic alarm.statistic if alarm.extended_statistic.nil?

data/lib/cfnguardian/version.rb

@@ -1,4 +1,4 @@
 module CfnGuardian
-  VERSION = "0.13.3"
+  VERSION = "0.14.0"
   CHANGE_SET_VERSION = VERSION.gsub('.', '-').freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cfn-guardian
 version: !ruby/object:Gem::Version
-  version: 0.13.3
+  version: 0.14.0
 platform: ruby
 authors:
 - Guslington
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -312,6 +312,7 @@ files:
 - cfn-guardian.gemspec
 - docs/alarm_tags.md
 - docs/alarm_templates.md
+- docs/anomaly_detection.md
 - docs/cli.md
 - docs/composite_alarms.md
 - docs/custom_checks/azure_file_check.md