Date-related

In some cases, the user will want to know if something has happened or is about to happen.

We represent dates in the system as seconds-since-epoch (in double metrics).
It must have a "name" tag, and that name is also used to display the certificate's name when alerting.

This type of rule will soon be converted to a template.

CertificateExpirationRule

An alert will be sent 56 days before a certificate expired.
certificate-expiration is a double metric representing when a certificate is set to expire.

Complicated state

These are generally similar to StateDownTemplateRule's, except that instead of just looking at a given double metric and alerting if it's 0, we add a condition regarding another metric.

ClusterConfigNotSyncedRule
Alert will be sent if a device is the active member of the cluster.

PortIsDownRule
Alert will be sent if the port is set to admin-up.

ConfigChangeOnStandbyMemberRule

Double metric ratio

If we want to alert how many packets were dropped on a port, we want to take the total number of received packets into account.

This type of rule will soon be converted to a template.

NicRxDropsRule

We divide one metric by the other, and compare the result to a threshold. Note that in this specific case, both metrics are "counter" metrics, so we're not using the total number of packets to date, but rather the rate of drops compared to the rate of packets received.

Metric disappearance

In some cases, we know when a certain thing is up, but we don't know when it's down. VPN tunnels are often an example of this - a firewall will tell us when it's up, but won't tell us anything if it's down (unless it's a monitored VPN tunnel).
So we need to write an alert that says "If I hadn't seen the tunnel as up for at least X minutes, it's probably down and I should alert".

This type of rule will soon be converted to a template.

VpnTunnelIsDownRule
OspfNeighborIsDownRule

Snapshot list analysis

For our NextHopRouterInaccessibleRule we needed to cross two lists - the device's routing table, with the ARP failures list. Essentially, we want to alert if a next-hop if a given route is deemed inaccessible at the ARP level. These are two complex metrics - arp-table and static-routing-table. In this rule, you'll notice that we pull both and ask the rule engine to find all the next-hops that are unsuccessful in the ARP table. This is one of the more tricky rules out there.

NextHopRouterInaccessibleRule

rule_type

non-templated rule: core-rule

String

author

Author of the yaml file

String

rule_name

short name of the rule

String

rule_friendly_name

Longer, friendlier, name of the rule

String

rule_description

Description

String

configuration_parameters

(Optional)

The keys are strings denoting the name of the configuration parameter.

The values are themselves maps expected to contain exactly two keys: 'type' and 'defaultValue'.

The value of 'type' should be either 'string' or 'double'

The value of 'defaultValue' is expected to be of a type corresponding to the value of 'type'

Map

alert_severity

'INFO' | 'WARN' | ERROR' | 'CRITICAL'

String

alert_headline

(Optional)

If not specified, alert headline will automatically be generated from the rule's friendly name.
Note that currently this is a constant string, i.e., no support for templating in this field's value.

String

alert_description

Note that currently this is a constant string, i.e., no support for templating in this field's value.

String

alert_items

(Optional)

The keys are strings denoting the chosen alert_item_id (see how to define one in the documentation of metrics_condition below)

The values are themselves maps expected to contain exactly three keys: 'title', 'headline' and 'description'

The value of 'title' should be of type string, and denotes the title of alert items produced from this id. The value of this field does not support templating.

The value of 'headline' should be of type string, and denotes the headline of alert items produced from this id. The value of this field does support templating: expressions like ${config:a_config_parameter} or ${metricTag:a_metric_tag_name} are supported. At the moment the only two sections of substitution variables allowed are 'config' and 'metricTag', the former denoting configuration parameters and the latter denoting names of metric tags that are relevant to alert items generated by this id. See more in the documentation of metric_condition below. Note that currently the value of the 'headline' field is not allowed to contain '%' or '$' characters.

The value of 'description' should be of type string, and denotes the description of alert items produced from this id. The value of this field does support templating: expressions like ${config:a_config_parameter} or ${metricTag:a_metric_tag_name} are supported. At the moment the only two sections of substitution variables allowed are 'config' and 'metricTag', the former denoting configuration parameters and the latter denoting names of metric tags that are relevant to alert items generated by this id. See more in the documentation of metric_condition below. Note that currently the value of the 'description' field is not allowed to contain '%' or '$' characters.

Map

rule_categories

Of type list and denotes the rule categories this rule belongs to. This list may be empty, and should contain only elements of type string that are one of: 'OrganizationStandards', 'HealthChecks', 'HighAvailability', 'OngoingMaintenance', 'SecurityRisks', 'VendorBestPractices'. This list may not contain duplicates. For detail, please see: Rule Categories

List

device_category

The allowed values for this field are:

• 'AllDevices'

• 'AllDevicesNonVSX'

• 'AllDevicesVSX'

• 'BlueCoatDevices'

• 'ChassisDevices'

• 'CheckPointCluster'

• 'CheckPointClusterNonVSX'

• 'CheckPointClusterVSX'

• 'CheckPointClusterXL'

• 'CheckPointClusterXLNonVSX'

• 'CheckPointClusterXLVSX'

• 'CheckPointDevices'

• 'CheckPointFirewalls'

• 'CheckPointFirewallsNonVSX'

• 'CheckPointFirewallsVSX'

• 'CheckPointVSX'

• 'CiscoDevices'

• 'CiscoNexus'

• 'ClusteredDevices'

• 'ClusteredDevicesNonVS'

• 'ClusteredDevicesVS'

• 'ComplianceCheck'

• 'DevicesWithMultiplePSU'

• 'DevicesWithVS'

• 'F5ComplianceCheck'

• 'F5Devices'

• 'F5DevicesVCMP'

• 'FirewallDevices'

• 'FortinetDevices'

• 'LinuxbasedDevices'

• 'LoadBalancers'

• 'ManagementDevices'

• 'PaloAltoNetworksDevices'

• 'PaloAltoNetworksFirewalls'

• 'PaloAltoNetworks'

• 'RadwareAlteon'

• 'RadwareDevice'

• 'SwitchingDevices'

String

base_remediation_text

(Optional)
The value of this field currently does not support templating.

String

vendor_to_remediation_text

(Optional)
Gives a specific remediation steps text per vendor, to be appended to the base remediation steps text

The keys are of type string, denote a specific device vendor, and are expected to be one of:

• VENDOR_BLUECOAT

• VENDOR_CISCO

• VENDOR_CP

• VENDOR_F5

• VENDOR_FIREEYE

• VENDOR_FORTINET

• VENDOR_GIGAMON

• VENDOR_IMPERVA

• VENDOR_JUNIPER

• VENDOR_OTHER

• VENDOR_PANOS

• VENDOR_RADWARE

• VENDOR_SYMANTECCAS

• OS_CISCO_ASA
  
  

• OS_CISCO_NXOS

• OS_CISCO_IOS

• OS_CP_GAIA

• OS_CP_GAIA_EMBEDDED

• OS_CP_IPSO

• OS_CP_SECUREPLATFORM

The values are of type string, and denote the remediation steps text for that vendor. That text will be appended to the base remediation steps text. The value of this field currently does not support templating.

Map

requires_condition

Denotes a condition used as the tags condition for the rule, i.e. a condition on the device tags that only if satisfied, the rule will run. We will now define what constitutes a valid condition and what a condition means.

A condition is either an basic condition or an expression composed of basic conditions combined with the and, or, not operators. The order of precedence between this operators is: 1. not, 2. and, 3. or. Parentheses are allowed in the condition to create different precedence or to make a condition more readable.

A basic condition is a condition of either of these two forms:

Tag(a_tag_name) == "a_string_literal". The meaning of such a condition is that the device tag a_tag_name exists and its value is equal to a_string_literal

Tag(a_tag_name) != "a_string_literal". The meaning of such a condition is that the device tag a_tag_name either does not exist or exists with a value different from a_stirng_literal

Note that the '!=' operator can be written also as '<>'. There is no semantic difference between the two forms.

String

metrics_condition

Denotes a condition used as the metrics condition of the rule, i.e. a condition on the metric values that defines when the rule issues an alert.
We will now define what constitutes a valid condition and what a condition means.

A condition is either a basic full condition or an expression composed of basic full conditions combined with the and, or, not operators. The order of precedence between this operators is: 1. not, 2. and, 3. or. Parentheses are allowed in the condition to create different precedence or to make a condition more readable.

A basic full condition is composed of a tags aggregation followed by parentheses containing a simple condition (note: do not confuse simple with basic).

A tags aggregation is can be of any of these forms:

any[] : Denotes that the simple condition following this aggregation examins the value of a metric or metrics that does not depend on any metric tags and so has only one value per device. No alert items will be produced.

any[a_metric_tag1, a_metric_tag2] : Denotes that the simple condition following this aggregation examines the value of a metric or metrics that depend on the value of the metric tags a_metric_tag1, a_metric_tag2. The simple condition will be evaluated separately on each set of values for a_metric_tag1, a_metric_tag2 that exists in the device, and the metrics will be evaluated separately for each such set of values. An alert will be produced if for any of the sets evaluated, the simple condition evaluated on the metric values corresponding to that set yielded true. No alert items will be produced.

Note that this is an example with two tags, but this works with one tag, or with 3 or more tags with a similar syntax.

any[a_metric_tag1, a_metric_tag2 => an_id] : Denotes the same as any[a_metric_tag1, a_metric_tag2], except that this also creates an alert item for each pair of values of the tags that caused the simple condition to evaluate to true. The alert items parameters will be defined in the alert_items section (see above) under the id an_id.

Note that this is an example with two tags, but this works with one tag, or with 3 or more tags with a similar syntax.

at-least-k{an_integer}[a_metric_tag1, a_metric_tag2]: Denotes the same as any[a_metric_tag1, a_metric_tag2], except that the alert will only be issued if the number of sets of values of the metric tags which caused the simple condition's evaluation to yield true is greater than or equal to the integer denoted by an_integer

at-least-k{an_integer][a_metric_tag1, a_metric_tag2 => an_id]: Denotes the same as at-least-k{an_integer}[a_metric_tag1, a_metric_tag2] except that this also creates an alert item for each set of values of the tags that caused the simple condition to evaluate to true.

A simple condition is either a basic simple condition or an expression composed of basic simple conditions combined with the and, or, not operators. The order of precedence between this operators is: 1. not, 2. and, 3. or. Parentheses are allowed in the condition to create different precedence or to make a condition more readable.

A basic simple condition can be of any of these forms:

StrMetric(m1) == "an interesting string value"

StrMetric(m1) in ["value1", "value2", "value3"]

DoubleMetric(m2) == 17.0

DoubleMetric(m2) < 100

Also available are the operators: <=, >, >=, !=, <> ( != and <> are synonymous)

ObjArrayMetric(m3) contains "an interesting string value" atKey "keyName"

ObjArrayMetric(m3) isEmpty

String