Merge pull request #378 from Icinga:feature/allow_service_plugin_to_report_not_found_as_critical

Feature: Adds support for Invoke-IcingaCheckService to report not found services as CRITICAL instead of UNKNOWN

Allows users to change the plugin output behavior for Invoke-IcingaCheckService, to report CRITICAL instead of UNKNOWN in case a service could not be found on the system

Author: LordHepipud

config/director/Invoke-IcingaCheckService.json

@@ -50,6 +50,24 @@ object CheckCommand "Invoke-IcingaCheckService" {
         "-Verbosity" = {
             description = "Changes the behavior of the plugin output which check states are printed: 0 (default): Only service checks/packages with state not OK will be printed 1: Only services with not OK will be printed including OK checks of affected check packages including Package config 2: Everything will be printed regardless of the check state 3: Identical to Verbose 2, but prints in addition the check package configuration e.g (All must be [OK])"
             value = "$IcingaCheckService_Int32_Verbosity$"
+            order = 7
+        }
+        "-OverrideNotFound" = {
+            set_if = {{
+                var str = macro("$IcingaCheckService_String_OverrideNotFound$"); if (len(str) == 0) { return false; }; return true;
+            }}
+            description = "This argument will allow you to override the default behavior of the plugin in case a service was not found on the system. By default, it will report UNKNOWN but you can set with this argument if the service state should be OK, WARNING or CRITICAL instead"
+            value = {{
+                var str = macro("$IcingaCheckService_String_OverrideNotFound$");
+                var argLen = len(str);
+                if (argLen == 0) {
+                    return;
+                }
+                if (argLen != 0 && str.substr(0,1) == "'" && str.substr(argLen - 1, argLen) == "'") {
+                    return str;
+                }
+                return ("'" + str + "'");
+            }}
             order = 6
         }
         "-Status" = {
@@ -144,6 +162,9 @@ object CheckCommand "Invoke-IcingaCheckService" {
         "Status" = {
             value = "$IcingaCheckService_String_Status$"
         }
+        "OverrideNotFound" = {
+            value = "$IcingaCheckService_String_OverrideNotFound$"
+        }
         "Exclude" = {
             value = "$IcingaCheckService_Array_Exclude$"
         }

config/director/Plugins_Bundle.json

@@ -3497,7 +3497,7 @@ object CheckCommand "Invoke-IcingaCheckUNCPath" {
 
     arguments += {
         "-WarningTotal" = {
-            description = "A warning threshold for the shares free space in either % or byte units, like '20%:' or '50GB:' Please note that this value is decreasing over time, therefor you will have to use the plugin handler and add ':' at the end of your input to check for 'current value < threshold' like in the previous example  Allowed units: %, B, KB, MB, GB, TB, PB, KiB, MiB, GiB, TiB, PiB"
+            description = "A warning threshold for the shares total free space in byte units, like '50GB:' Please note that this value is decreasing over time, therefor you will have to use the plugin handler and add ':' at the end of your input to check for 'current value < threshold' like in the previous example  Allowed units: B, KB, MB, GB, TB, PB, KiB, MiB, GiB, TiB, PiB"
             value = "$IcingaCheckUNCPath_Object_WarningTotal$"
             order = 8
         }
@@ -4122,6 +4122,24 @@ object CheckCommand "Invoke-IcingaCheckService" {
         "-Verbosity" = {
             description = "Changes the behavior of the plugin output which check states are printed: 0 (default): Only service checks/packages with state not OK will be printed 1: Only services with not OK will be printed including OK checks of affected check packages including Package config 2: Everything will be printed regardless of the check state 3: Identical to Verbose 2, but prints in addition the check package configuration e.g (All must be [OK])"
             value = "$IcingaCheckService_Int32_Verbosity$"
+            order = 7
+        }
+        "-OverrideNotFound" = {
+            set_if = {{
+                var str = macro("$IcingaCheckService_String_OverrideNotFound$"); if (len(str) == 0) { return false; }; return true;
+            }}
+            description = "This argument will allow you to override the default behavior of the plugin in case a service was not found on the system. By default, it will report UNKNOWN but you can set with this argument if the service state should be OK, WARNING or CRITICAL instead"
+            value = {{
+                var str = macro("$IcingaCheckService_String_OverrideNotFound$");
+                var argLen = len(str);
+                if (argLen == 0) {
+                    return;
+                }
+                if (argLen != 0 && str.substr(0,1) == "'" && str.substr(argLen - 1, argLen) == "'") {
+                    return str;
+                }
+                return ("'" + str + "'");
+            }}
             order = 6
         }
         "-Status" = {
@@ -4216,6 +4234,9 @@ object CheckCommand "Invoke-IcingaCheckService" {
         "Status" = {
             value = "$IcingaCheckService_String_Status$"
         }
+        "OverrideNotFound" = {
+            value = "$IcingaCheckService_String_OverrideNotFound$"
+        }
         "Exclude" = {
             value = "$IcingaCheckService_Array_Exclude$"
         }
@@ -4807,12 +4828,12 @@ object CheckCommand "Invoke-IcingaCheckUpdates" {
             order = 99
         }
         "-CriticalOther" = {
-            description = "The critical threshold for the total pending update count on the Windows machine"
+            description = "The critical threshold for all other updates on the Windows machine"
             value = "$IcingaCheckUpdates_Object_CriticalOther$"
             order = 12
         }
         "-WarningDefender" = {
-            description = "The warning threshold for the Microsoft Defender update count on the Windows machine"
+            description = "The warning threshold for the total pending update count on the Windows machine"
             value = "$IcingaCheckUpdates_Object_WarningDefender$"
             order = 9
         }
@@ -4850,7 +4871,7 @@ object CheckCommand "Invoke-IcingaCheckUpdates" {
             order = 10
         }
         "-CriticalRollups" = {
-            description = "The critical threshold for the total pending update count on the Windows machine"
+            description = "The critical threshold for the rollup update count on the Windows machine"
             value = "$IcingaCheckUpdates_Object_CriticalRollups$"
             order = 8
         }
@@ -4892,7 +4913,7 @@ object CheckCommand "Invoke-IcingaCheckUpdates" {
             order = 5
         }
         "-CriticalSecurity" = {
-            description = "The critical threshold for the total pending update count on the Windows machine"
+            description = "The critical threshold for the security update count on the Windows machine"
             value = "$IcingaCheckUpdates_Object_CriticalSecurity$"
             order = 6
         }

config/icinga/Invoke-IcingaCheckService.conf

@@ -21,6 +21,10 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 
 # 1.11.1 (2023-11-07)
 
+* [#378](https://github.com/Icinga/icinga-powershell-plugins/pull/378) Adds support for `Invoke-IcingaCheckService` to change the output for not found services from UNKNOWN to OK, WARNING or CRITICAL instead
+
+# 1.11.1 (tbd)
+
 ### Bugfixes
 
 * [#358](https://github.com/Icinga/icinga-powershell-plugins/issues/358) Fixes broken Icinga plain configuration

config/icinga/Plugins_Bundle.conf

@@ -29,6 +29,7 @@ To execute this plugin you will require to grant the following user permissions.
 | Status | String | false | Running | Status for the specified service or services to check against. |
 | FilterStartupType | Array | false | @() | Allows to include only services with a specific startup type inside the monitoring,<br /> in case you check for a list of specific services by using `-Service` |
 | MitigateUnknown | SwitchParameter | false | False | This will tell the plugin to return OK instead of UNKNOWN, in case no service was added to this<br /> check |
+| OverrideNotFound | String | false | Unknown | This argument will allow you to override the default behavior of the plugin in case a service was not found on the<br /> system. By default, it will report UNKNOWN but you can set with this argument if the service state should be<br /> OK, WARNING or CRITICAL instead |
 | Verbosity | Int32 | false | 0 | Changes the behavior of the plugin output which check states are printed:<br /> 0 (default): Only service checks/packages with state not OK will be printed<br /> 1: Only services with not OK will be printed including OK checks of affected check packages including Package config<br /> 2: Everything will be printed regardless of the check state<br /> 3: Identical to Verbose 2, but prints in addition the check package configuration e.g (All must be [OK]) |
 | NoPerfData | SwitchParameter | false | False | Disables the performance data output of this plugin |
 | ThresholdInterval | String |  |  | Change the value your defined threshold checks against from the current value to a collected time threshold of the Icinga for Windows daemon, as described [here](https://icinga.com/docs/icinga-for-windows/latest/doc/service/10-Register-Service-Checks/). An example for this argument would be 1m or 15m which will use the average of 1m or 15m for monitoring. |

doc/31-Changelog.md

@@ -51,6 +51,10 @@
 .PARAMETER MitigateUnknown
     This will tell the plugin to return OK instead of UNKNOWN, in case no service was added to this
     check
+.PARAMETER OverrideNotFound
+    This argument will allow you to override the default behavior of the plugin in case a service was not found on the
+    system. By default, it will report UNKNOWN but you can set with this argument if the service state should be
+    OK, WARNING or CRITICAL instead
 .PARAMETER NoPerfData
     Disables the performance data output of this plugin
 .PARAMETER Verbosity
@@ -67,7 +71,6 @@
     https://github.com/Icinga/icinga-powershell-plugins
 .NOTES
 #>
-
 function Invoke-IcingaCheckService()
 {
     param (
@@ -78,6 +81,8 @@ function Invoke-IcingaCheckService()
         [ValidateSet('Boot', 'System', 'Automatic', 'Manual', 'Disabled', 'Unknown')]
         [array]$FilterStartupType = @(),
         [switch]$MitigateUnknown  = $FALSE,
+        [ValidateSet('Ok', 'Warning', 'Critical', 'Unknown')]
+        [string]$OverrideNotFound = 'Unknown',
         [ValidateSet(0, 1, 2, 3)]
         [int]$Verbosity           = 0,
         [switch]$NoPerfData
@@ -167,9 +172,30 @@ function Invoke-IcingaCheckService()
                 continue;
             }
 
-            $ServicesPackage.AddCheck(
-                (New-IcingaCheck -Name ([string]::Format('{0}: Service not found', $ServiceArg)) -NoPerfData).SetUnknown()
-            );
+            $ServiceNotFound = $null;
+            $UnknownName     = [string]::Format('{0}:', $ServiceArg);
+            $UnknownValue    = 'Service not found';
+
+            switch ($OverrideNotFound.ToLower()) {
+                'ok' {
+                    $ServiceNotFound = (New-IcingaCheck -Name $UnknownName -Value $UnknownValue -NoPerfData).SetOk();
+                    break;
+                };
+                'warning' {
+                    $ServiceNotFound = (New-IcingaCheck -Name $UnknownName -Value $UnknownValue -NoPerfData).SetWarning();
+                    break;
+                };
+                'critical' {
+                    $ServiceNotFound = (New-IcingaCheck -Name $UnknownName -Value $UnknownValue -NoPerfData).SetCritical();
+                    break;
+                };
+                default {
+                    $ServiceNotFound = (New-IcingaCheck -Name $UnknownName -Value $UnknownValue -NoPerfData).SetUnknown();
+                    break;
+                };
+            }
+
+            $ServicesPackage.AddCheck($ServiceNotFound);
         }
     }