/ 
IPsonar-0.32
River stage zero No dependents
/ IPsonar

NAME

IPsonar - Wrapper to interact with the Lumeta IPsonar API

VERSION

Version 0.32 (Mercurial Revision ID: 8cc8c5b56c62+)

SYNOPSIS

This module wraps the IPsonar RESTful API. It handles the paging and https stuff so you can concentrate on extracting information from reports.

"Lumeta" and "IPsonar" are both registered trademarks of the Lumeta Coporation

EXAMPLE

# Script to get all the IP address for all the devices that have
# port 23 open:

my $rsn = IPsonar->new('rsn_address_or_name','username','password');
my $test_report = 23;

my $results = $rsn->query('detail.devices',
    {
        'q.f.report.id'                 =>  $test_report,
        'q.f.servicediscovery.ports'    =>  23
    }) or die "Problem ".$rsn->error;

while (my $x = $rsn->next_result) {
   print "IP: $x->{ip}\n";
}

CONSTRUCTORS

new (rsn, username, password)

Setup a connection to a report server using username / password Note: This doesn't actually initiate a connection until you issue a query. The rsn can either be a hostname or IP address. The username and password are for one of the GUI users.

new_with_cert (rsn, path_to_cert, password)

Setup a connection to a report server using SSL certificate Note: This doesn't actually initiate a connection until you issue a query. The rsn can either be a hostname or IP address. The password is the password required to unlock your certificate (as required).

new_localhost

Setup a connection to the report server you're on

METHODS

$rsn->query ( method, hashref_of_parameters)

Issue a query (get results for non-paged queries). If you're getting back paged data we'll return the number of items available in the query. If we're getting back a single result we return a hashref to those results.

If the query fails we'll leave the reason in $rsn->error

$rsn->next_result ()

Get next paged results as a hashref. Returns 0 when we've got no more results.

Note: Currently, we always return a hashref to the same (only) non-paged results.

$rsn->error

Get error information

METHODS

$rsn->reports ()

Returns an array representing the reports on this RSN. This array is sorted by ascending report id. Do not run this while you're iterating through another query as it will reset its internal state. Timestamps are converted to epoch time.

An example of how you might use this:

#!/usr/bin/perl

use strict;
use warnings;

use IPsonar;

my $rsn = IPsonar->new('s2','username','password');
my @reports = $rsn->reports;

USAGE

The way I've settled on using this is to build the query I want using the built-in IPsonar query builder. Once I've got that fine tuned I translate the url into a query.

For example, if I build a query to get all the routers from report 49 (showing port information), I'd wind up with the following URL:

https://s2/reporting/api/service/detail.devices?fmt=xml&q.page=0&q.pageSize=100&q.details=Ports&q.f.report&q.f.report.id=49&q.f.router&q.f.router.router=true

This module takes care of the fmt, q.page, and q.pageSize parameters for you (you can specify q.pageSize if you really want). I might translate that into the following code:

#!/usr/bin/perl

use strict;
use warnings;

use IPsonar;
use Data::Dumper;

my $rsn = IPsonar->new('s2','username','password');

my $results = $rsn->query('detail.devices',
    {
        'q.details'                     =>  'Ports',
        'q.f.report.id'                 =>  49,
        'q.f.router.router'             =>  'true',
    }) or die "Problem ".$rsn->error;

while ( my $x = $rsn->next_result ) {
    print Dumper($x);
    my $ports = $x->{ports}->{closedPorts}->{integer};
    print ref($ports) eq 'ARRAY' ? join ',' , @{$ports} : $ports ;
}

And get this as a result:

$VAR1 = {
    'ports' => {
        'openPorts' => {
            'integer' => '23'
        },
        'closedPorts' => {
            'integer' => [
                '21',
                '22',
                '25',
            ]
    }
},
'ip' => '10.2.0.2'
};
21,23,25

Note that things like ports might come back as an Arrayref or might come back as a single item. I find there's some tweaking involved as you figure out how the data is laid out.