George Budd > IPsonar-0.23 > IPsonar

Download:
IPsonar-0.23.tgz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.23   Source   Latest Release: IPsonar-0.28

NAME ^

IPsonar - Wrapper to interact with the Lumeta IPsonar API

VERSION ^

Version 0.23 (Mercurial Revision ID: 855a2750fa4f)

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).

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

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.

syntax highlighting: