Writing Crawler Plugins

Do you have processes that would benefit from data collection? There may be a Crawler plugin that you can use. Or, you can develop one yourself to expand the types of IT data that the Crawler can discover. You can download the source code from our Subversion repository. The Crawler has a built-in Ruby interpreter, which makes writing plugins easy.

The Paglo Crawler gathers information about your IT environment using a collection of plugins, each of which discovers a different type of data. You can extend your Paglo Crawler by writing plugins that discover different kinds of data, using the Paglo Crawler API. And you can share your invention with the Paglo community.

Getting started

The Paglo Crawler is extensible via an API that allows third party developers to write plugins in the Ruby scripting language. When creating a Paglo Crawler plugin, you can choose between two plugin types:

Device plugins — Execute against every device that the Crawler encounters
Periodic plugins — Execute according to a scheduled interval

To write plugins:

Derive a class from either Paglo::DevicePlugin or Paglo::PeriodicPlugin.
Place it in a file ending in _plugin.rb located in the Plugins directory where you installed your Paglo Crawler, such as C:\Program Files\Paglo\Paglo Crawler\Plugins.

Meta information

Both types of plugins share a common set of meta-information specification keywords that you can use to define the corresponding plugin name that appears in the Crawler's configuration dialog, as well as various configuration variables that the UI can set.

Keywords

Keyword	Description	Example
name	Plugin name that is displayed in the configuration UI	name “MyPlugin”
description	Detailed description that is displayed in the configuration UI	description “This is a plugin that I wrote”
param	Defines a configuration file parameter that is editable via the Crawler’s configuration UI	param “enum_var2”, :description => “An enum test variable with only one value”, :label => “Enum Variable 2”, :type => “enum”, :values => “asdf”

The name and description keywords both take a single string as their only argument. The param keyword takes a string as it's first argument to specify what the parameter in the configuration file is called. However, you have many more options for the param keyword, because it allows you to specify the data type of the parameter. These options are:

Param Options

Option	Description	Example
:description	Define a description for the parameter. This is displayed when hovering over the parameter’s widget in the configuration UI	:description => “Test variable”
:label	Specifies the text label that is drawn immediately to the left of the parameter’s widget in the configuration UI	:label => “My Variable”
:type	Specifies the parameter’s type. If omitted it defaults to “string.” Valid values are “string,” “int,” “bool,” and “enum.” When using “enum” the :values option is required.	:type => “bool”
:values	Specify valid values for a parameter of the type “enum.”	:values => “asdf,jkl,foo,bar”
:default	Specify a default value that will be displayed in the configuration UI in the absence of the parameter being set in the configuration file.	:default => “value”

Examples

name “Test”
description “A test device plugin.”
param “test_var”, :description => “Test variable”, :label => “Variable”
param “bool_var”, :description => “A boolean test variable”, :label => “Bool Variable”, :type => “bool”
param “int_var”, :description => “An integer test variable”, :label => “Int Variable”, :type => “int”
param “enum_var”, :description => “An enum test variable”, :label => “Enum Variable”, :type => “enum”, :values => “asdf,jkl,foo,bar”
param “enum_var2”, :description => “An enum test variable with only one value”, :label => “Enum Variable 2”, :type => “enum”, :values => “asdf”

Device plugins

When creating a device plugin, the execute(target_ip) method must be overridden in your class that is derived from Paglo::DevicePlugin. The target_ip parameter is a string containing the IP of the target host.

Periodic plugins

When creating a periodically scheduled plugin, the execute() method must be overridden in your class that is derived from Paglo::PeriodicPlugin.

Accessing configuration parameters

Configuration parameters can be accessed by calling get_config("param") where "param"; is the configuration parameter you'd like to access. get_config() returns an array of strings since a parameter can appear in the configuration file multiple times.

Submitting data

Plugins can submit data to Paglo by calling submit_tree(tree) where tree is a string representation of a tree structure that complies with the syntax defined for the VALUES clause in a PQL MERGE statement.

Helper methods

The Crawler automatically performs device discovery and scans each device that it discovers. Paglo provides the following helper methods as a bridge between the Crawler and its plugins, and to enable the plugins to access the information that the Crawler gathers:

Method	Description
log_issue(string) Example: log_issue(”Access denied trying to query 192.168.0.1 via WMI.”)	Displays a message in the `Issues` widget contained in the Paglo Crawler Status window.
port_open?(ip_address, proto, port)	Asks the Crawler if a particular port/protocol is listed as open for the specified IP address. `ip_address` is a string representation of an IP address. `proto` can either be `cp` or `dp`. The method returns either `true` or `false`, depending on whether the port is listed as open or not. It returns `nil` if the IP address in question is unknown to the Crawler.
new_device(ip_address, mac_address) Example: new_device(”192.168.1.1”, ”00:DE:AD:BE:EF:00”)	Registers a new device with the Crawler. After the device is registered, it is scanned. `ip_address` is a string representation of an IP address and can be `nil. mac_address is a string representation of a MAC address and can be nil. MAC addresses are case-insensitive. The method returns true or false to signal if the device was created successfuly.`
get_guid() Example: guid = get_guid()	Returns the 12 digit GUID of the Crawler as a string.
lookup_mac(mac_address) Example: ip_address = lookup_mac(”00:DE:AD:BE:EF:00”)	Accepts a case-insensitive string representation of a MAC addresss, and returns a string representing its IP address if a device using that MAC address is known by the Crawler. `nil` is returned if no device is found.
scan_device(ip_address) Example: valign="top">scan_device(”192.168.1.1”)	Accepts a string representation of an IP address to be scanned by the Crawler. In order for the Crawler to scan the device, it must already be known by the Crawler, so you may want to use `new_device()` before calling this method. This method always returns `nil`.

Adding and removing plugins

You can add or remove plugins by adding or removing them from the Plugins directory where you installed your Crawler, such as C:\Program Files\Paglo\Paglo Crawler\Plugins).

How do I find out more?