NAME

Net::RDEP - Remote Data Exchange Protocol Client

SYNOPSIS

use Net::RDEP;

$rdep = Net::RDEP->new(Username => 'rdepuser', Type => 'subscription');
$rdep->Password('foobar');
$rdep->Server('192.168.1.2');

$rdep->mustHaveAlarmTraits(3,'5-10');
$rdep->alertSeverities('high', 'medium');
$rdep->events('evAlert');

$idiom_xml = $rdep->get();
$rdep->close();

DESCRIPTION

Remote Data Exchange Protocol (RDEP) is a protocol designed by Cisco Systems in order to exchange Intrusion Detection System events, configuration, log, and control messages. This protocol is supported at least the Cisco IDS version 4.0.

This implementation only supports the collection of events.

The events are retrieved in a format, also developed by Cisco, referred to as Intrusion Detection Interaction and Operations Messages (IDIOM), which is an XML document. A simple module for handling these documents is included with this distribution (XML::Idiom).

RDEP supports two methods for retrieving events: an event query and an event subscription. Both methods use SSL to query the RDEP server and retrieve the events. The event query method will retrieve all the events in a given time range. No connection is maintained in anyway. The event subscription, however, does maintain a connection and will support multiple "gets" to continue to retrieve events as they are available.

See www.cisco.com for more information in RDEP or IDIOM.

CONNECTION METHODS

new( [Parameter => value,] )

This is the constructor for a new Net::RDEP object. Parameters to the RDEP object can be specified here or later.

open()

If the Type is set to 'query', this method will perform the event query with the already set parameters. Otherwise, an event subscription will be established.

get()

If the Type is set to 'query', the get() method simply calls open() and performs an event query. If an event subscription is already established, get() will return the next maxNbrOfEvents from the server. If a subscription has not been established, then it will be established first.

close()

An event subscription should be closed when no longer being used. The serer will time out the subscription if this doesn't happen.

subscriptionID

An event subscription maintains a subscription ID. This is set automatically, but can be retrieved. If this value is corrupted during a session, the session will become invalid.

PARAMETER METHODS

These method names and case are, in general, as specified in the RDEP specification from Cisco.

Calling the method with arguments will cause that RDEP parameter to be set with those arguments. Calling the method without arguments returns the current value of the parameter. Calling the method with arguments repeatedly will cause the parameter to be reset to the latest set of arguments. If a parameter supports more than one parameter, specify them all in the same call.

Type

Set this parameter to 'subscription' to establish an event subscription and to 'query' for an event query.

startTime

Specify the start time of the events to be retrieved. If not specified, collection will be started by the oldest events.

stopTime

Events retrieved will have a creation time less than or equal to the stopTime. If not specified, collection will end with the newest events. Note - this only applies to event queries.

events

Set the type of events to retrieve. Valid event types are: evError, evAlert, evLogTransaction, evStatus, evShunRqst.

alertSeverities

Set the alert severities of events to retrieve. Valid alert severities are: informational, low, medium, and high. Multiple alert severities may be specified:

$rdep->alertSeverities( 'medium', 'high');

Default is ALL alert severities.

errorSeverities

Set the error severity of events to retrieve. Valid error severities are: warning, error, and fatal. Multiple error severities may be specified.

$rdep->errorSeverities( 'fatal', 'error');

Default is ALL error severities.

mustHaveAlarmTraits

Alarm traits are a set of 16 attribute bits. Each bit has a user-defined value classifing an evAlert into up to 16 different categories. Specify these either as single digits or ranges:

$rdep->mustHaveAlarmTraits(3, '5-10');

The mustHaveAlarmTraits parameters restricts retrieval of events to only those with the given attribute bit set.

mustNotHaveAlarmTraits

The mustNotHaveAlarmTraits parameters restricts retrieval of events to only those without the given attribute bit set.

timeout

The maximum number of seconds the server will block before returning. When this pararmeter is not specified, the request will not timeout.

maxNbrOfEvents

The maximum number of events to retrieve in the query. Some servers impose an upper-limit on the number of events that can be retrieved in a query. When this parameter is not specified, the server will return all events, up to a server imposed limit, that match the subscription's query criteria

confirm

Acknowledge that the events retrieved in the previous get() were received.

missedEvents

When performing an event subscription, it is possible that events could be lost between polls if the poll happens so infrequently that the server is forced to drop events. In this case, the missedEvents parameter will be "defined".

error

In the case of an error during parameter setting, server connection, or event retrieval, this parameter is "defined".

errorString

If the 'error' parameter is defined, an explanation of the error will be stored here.

EXAMPLES

This example shows a simple way to perform an event query:

#!/usr/local/bin/perl -w

use Net::RDEP;

my $rdep = Net::RDEP->new(
	Username => 'rdepuser',
	Password => 'rdeppass',
	Server   => 'rdephost',
	Type     => 'query' );

my $idiom_xml = $rdep->get();
if(defined($rdep->error)) {
	print "ERROR: " . $rdep->errorString;
}
print $idiom_xml;

In this example, an event subscription is performed:

#!/usr/local/bin/perl -w

use Net::RDEP;

my $rdep = Net::RDEP->new(
	Username => 'rdepuser',
	Password => 'rdeppass',
	Server   => 'rdephost' );

while (my $idiom_xml = $rdep->get()) {
	if(defined($rdep->error)) {
		print "ERROR: " . $rdep->errorString;
	}
	print $idiom_xml;
}

$rdep->close();

Printing out the IDIOM XML document is probably not all that useful. There are a few methods of handling the IDIOM document built into the XML::Idiom module that can be used. For example:

my $idiom = XML::Idiom->new();
$idiom->consume($idiom_xml);
if (defined($idiom->isError())) {
	if($idiom->errorType eq 'errNotFound') {
		# connection failed, reconnect
		...
	}
} else {
	my $number_of_events = $idiom->getNumberOfEvents();
	print "RCVD $number_of_events number of events\n";
	while(my $e = $idiom->getNextEvent()) {
		...
	}
}

SEE ALSO

XML::Idiom, MIME::Base64

AUTHOR

Joe Minieri, <jminieri@mindspring.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Joe Minieri and OpenService (www.open.com)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.