Introduction

With the release of Open-AudIT 3.2.0 we have introduced a new concept called Rules. Rules are created and run against a device when the device is discovered or an audit result is processed. Rules can be used to set a device attribute based on other attributes.

How Does it Work?

Each time a device is discovered or an audit result is processed, all rules are retrieved from the database and run against the attributes of the specific device. Rules run against one device at a time - there is no facility to say "Run the rules against all devices" or "Run the rules against these devices". An individual rule will test one or more attributes of the device and if they match the rule, the result will be applied. Several attributes can be tested. Several attributes can be set. Think of this as an If This, Then That system for Open-AudIT.

Initially we have included rules for SNMP Enterprises, MAC Addresses, SNMP OIDs and quite a few custom rules. The actual counts are:

SNMP Enterprise54006
Mac Address26432
SNMP OID10897
Custom422
Total99757


All these rules were previously hard coded into the application codebase. As a result, we have deleted many thousands of lines of code! We have still more to introduce, but this is a start (smile)

And of course you are free to add or modify the rules as you see fit. If you have a device with an SNMP OID that doesn't match a model already in the database - now you can add it easily. No more waiting for us to provide a patch and add it to the codebase for you.

When you create a Rules entry, you will need to provide a name and a list of inputs and outputs. The inputs and outputs are stored as JSON arrays within the database.

Inputs have a table and attribute, an operator and a value. When executing the condition, it works thus: If $table . $attribute $operator $value then apply the outputs.

A contrived example rule to match a type and set the model is below.

INPUTS
table = system
attribute = type
operator = eq
value = computer

OUTPUTS
table = system
attribute = model
value = My Model
value_type = string

Operators in Inputs can have the following values.

NameResult
eqEquals
neDoes Not Equal
gtGreater Than
geGreater Than or Equals
ltLess Than
leLess Than or Equals
stStarts With
liLike
nlNot Like
inIn the (comma seperated) list
niNot in the (comma seperated) list

Value Types in Outputs can have the following values.

NameDescription
stringa String
integeran Integer
timestamp

A timestamp.

If the value is set, that timestamp value will be used.

If the value is not set, the current timestamp will be used.


When the rules run in discovery, any matching rules will appear in the discovery log. See below for an example.


Hit on snmp_enterprise_id 9 eq 9 for SNMP Enterprise Number for ciscoSystems. Hit on manufacturer eq for SNMP Enterprise Number for ciscoSystems. (Rule: 10) 
Command: Rule match 
Output: {"manufacturer":"Cisco Systems","snmp_enterprise_name":"ciscoSystems"}

and anohter

Hit on snmp_oid 1.3.6.1.4.1.9.1.620 eq 1.3.6.1.4.1.9.1.620 for SNMP OID match. (Rule: 135661) 
Command: Rule match 
Output: {"model":"Cisco 1841","type":"router"}

Create Rules Entries

Rules can be created just like any other item. Menu → Manage → Rules → Create.

You can add and remove inputs and outputs as required.

Viewing Rules Details

As usual, go to menu → Manage → Rules → List Rules.

Because there are so many rules (near one hundred thousand), paging through them is unrealistic. We still retrieve the default number of entries as per the configuration item, howeever there is a search box at the top of the panel. Use this to search through the name, description, inputs and outputs to refine the list and find what you're looking for. There is also a button on the panel header that will show you all the rules you have created or edited. See below.


Database Schema

CREATE TABLE `rules` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(200) NOT NULL DEFAULT '',
  `org_id` int(10) unsigned NOT NULL DEFAULT '1',
  `description` text NOT NULL,
  `weight` int(10) unsigned NOT NULL DEFAULT '100',
  `inputs` text NOT NULL,
  `outputs` text NOT NULL,
  `edited_by` varchar(200) NOT NULL DEFAULT '',
  `edited_date` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=155875 DEFAULT CHARSET=utf8


Example Database Entry

         id: 65554
       name: Mac Address for Cisco Systems
     org_id: 1
description: Set the manufacturer based on the MAC prefix.
     weight: 90
     inputs: [{"table":"network","attribute":"mac","operator":"st","value":"cc:46:d6"},{"table":"system","attribute":"manufacturer","operator":"eq","value":""}]
    outputs: [{"table":"system","attribute":"manufacturer","value":"Cisco Systems","value_type":"string"}]
  edited_by: system
edited_date: 2001-01-01 00:00:00



API / Web Access?

You can access the /rules collection using the normal Open-AudIT JSON based API. Just like any other collection. Please see the API documentation for further details.

API Routes

Request Method

ID

Action

Resulting Function

URL Example

Notes

Example Response

GETn
collection/rulesReturns a list of rules.
GETy
read/rules/{id}Returns a rules details.
PATCHy
update/rules/{id}Update an attribute of a rules entry.
POSTn
create/rulesInsert a new rules entry.
DELETEy
delete/rules/{id}Delete a rules entry.

Web Application Routes

Only available under Open-AudIT Enterprise

Request Method

ID

Action

Resulting Function

URL Example

Notes

GETncreatecreate_form/rules/createDisplays a standard web form for submission to POST /files.