ADE Quick Start Guide with Python Parser
Introduction
In this quick start guide, we will demonstrate the end to end flow on how to create a rule using the StateDown template.
We will write an ADE to raise an alert if a Bluecoat ProxySG device is using SSH version 1 which is considered a security risk on the device.
Before we can write the rule, we need to first have a script that can produce the metric used by the rule template. In Indeni, a script is split into two files, a yaml file and a python file. The yaml file contains meta data about the script and the command that will be run on the device. The python file is used to parse the output of the command from the device into metrics.
show-ssh-console-versions.ind.yaml
name: bluecoat-proxysg-ssh-version
description: Bluecoat ProxySG SSH Versions
type: monitoring
monitoring_interval: 59 minutes
requires:
vendor: bluecoat
os.name: sgos
comments:
ssh-version-1-enabled:
why: |
The ProxySG appliance can accept management Secure Shell (SSH) connections. It is recommended to use the SSHv2 protocol since SSHv1 suffers from know security vulnerabilities.
how: |
This script login into the Bluecoat ProxySG using SSH and retrieves the ssh status by using the output of the command "show ssh-console versions-enabled".
without-indeni: |
The user would have to login to the device and use the "show ssh-console versions-enabled" commands to identify the enabled ssh versions on the device.
can-with-snmp: false
can-with-syslog: false
steps:
- run:
type: SSH
command: show ssh-console versions-enabled
parse:
type: PYTHON
file: show-ssh-console-versions.pyname needs to be unique across all scripts
description details what information this script will be polling
type needs to be monitoring. There is another script type for interrogation which we will not cover in this guide.
monitoring_interval is how often Indeni will run the script to retrieve the metrics. The longer the monitoring interval, the longer it will take for the alert to trigger since alert trigger depends on the metrics to be available. For testing purpose, it can be configured to 1 minute. However, for production deployment, it’s recommended to keep the polling interval to a reasonable higher value to reduce load on the device.
requires section restricts on what type of devices that this script will be running on. In this particular example, we are limiting it to run on Bluecoat devices with “sgos” operation system. The exact values of vendor and os.name can be found on the Indeni UI when searching for the devices of interest.
comments section details the metric name and why it’s needed and how to get the output etc
steps section tells Indeni what command needs to be run and which parser will be used to parse the output of the command
A command can either be type HTTP or SSH
An example for HTTP:
steps: - run: type: HTTP command: /api?type=op&cmd=<show><counter><global><name>proxy_flow_alloc_failure</name></global></counter></show>&key=${api-key} parse: type: XML file: panos-show-counter-global-name-proxy_flow_alloc_failure.parser.1.xml.yaml
parse section links the yaml file with parser file. Indeni supports various parser language. For this guide, we will focus on parser language using PYTHON only.
show-ssh-console-versions.py
from parser_service.public import helper_methods
from parser_service.public.base_parser import BaseParser
class ShowSshVersions(BaseParser):
def parse(self, raw_data: str, dynamic_var: dict, device_tags: dict):
sshv1_enabled = 0
lines = raw_data.splitlines()
for line in lines:
if 'SSHv1 is enabled.' in line:
sshv1_enabled = 1
self.write_double_metric('ssh-version-1-enabled', {}, 'gauge', sshv1_enabled, False)
return self.outputAlways copy the import statement
Class name needs to be unique
The data processing is rather straight-forward. The output of the command is stored in raw_data. We will split the output into multiple lines and we search each line for ‘SSHv1 is enabled’. If found, then it means SSHv1 is enabled on this device.
regex is supported as well.
self.write_double_metric method publishes the metric to Indeni.
First parameter is the name of the metric
Second parameter is the tags which is not used here.
Third parameter is the metric type. There are two types, gauge and counter. Counter is only used for metrics that increases overtime, for example, interface inbound bytes. Majority of metrics are gauge type.
Fourth parameter is the value of the metric
Fifth parameter if True we will show the metric on the Indeni UI under the Device Info page. For simplicity of the guide, we will leave it as False which means we do not want the metric to show up under Device Info page.
Use a online Python syntax checker to make sure parser file’s syntax is correct
After reboot, got to Knowledge Explorer page to make sure the your rule shows up in the table.
2. If your rule doesn’t show up, check for errors in
/usr/share/indeni/logs/rules/general.log
3. If your custom rule shows up, but the alert is not triggering, change the monitoring_interval to 1 minute and reboot the Indeni service
4. If still no luck, check for errors in
/usr/share/indeni-collector/logs/collector.log and /usr/share/indeni-collector/logs/devices/device_ip.log
5. Contact Indeni Support. We are more than happy to help you get your custom rules working! Please feel free to reach out to us.