
spcap::RulesReader
=================================

Description
---------------------------------
The SPCap rules reader plugin reads rule data in JSON format from the filesystem.
It is capable of doing limited validation against the schema located at /etc/spcap/rules/smartpcap-rule-schema.json .

Build and install
---------------------------------

Run the following commands

  ./configure
  make
  make install #requires root privileges

Data types
---------------------------------
.. code-block:: zeek
  type RulesTableKey: record {
    key: string;
  };

  type RulesTableValue: record {
    val: string;
  };

  type RulesTable: table[string] of RulesTableValue;

  type RulesHandler: record {
    filename: string;
    version: string;
    data: RulesTable;
  };

  type MemberType: enum {
    NotFound,
    Leaf,
    Array,
    Object,
  };

Functions
---------------------------------
.. code-block:: zeek
  global start: function(handler: RulesHandler);
  global get_object_member_keys: function(this: RulesHandler, key: string): vector of string;
  global get_array_member_keys: function(this: RulesHandler, key: string): vector of string;
  global get_type: function(this: RulesHandler, key: string): MemberType;
  global get_value: function(this: RulesHandler, key: string): string;

Events
---------------------------------
.. code-block:: zeek
  global validation_error: event(name: string, source: string, invalid_schema: string, invalid_keyword :string, invalid_document :string);

Example usage
---------------------------------
.. code-block:: zeek
@load spcap/RulesReader

# Create a rules handler object
global handler = RulesReader::RulesHandler($filename="rule.json", $name="rule");

event zeek_init()
{
  # Start the reading process
  RulesReader::start(handler);
  # Queue the removal of the stream
  Input::remove(handler$name);
}

# The Input::end_of_data event is triggered after the data has been read, parsed and successfully validated
event Input::end_of_data(name: string, source: string)
{
  # Print the version of the rules data
  print RulesReader::get_value(handler, "version");
  # Print the description of the rules data
  print RulesReader::get_value(handler, "description");
  # Print the date at which the rules data was created
  print RulesReader::get_value(handler, "created");
  # Print the value of the first protocol of the first lever of the first rule in the rules data
  print RulesReader::get_value(handler, "rules.0.levers.0.protocol.0");
}

# In case of a validation error with the data, the RulesReader::validation_error event is triggered by the plugin
event RulesReader::validation_error(name: string, source: string, invalid_schema: string, invalid_keyword :string, invalid_document :string)
{
  print "Stream ", name, " from file ", source, " failed validation";
  print "Invalid schema:", invalid_schema;
  print "Invalid keyword:", invalid_keyword;
  print "Invalid document:", invalid_document;
}

