NAME

Net::SDEE - Security Device Event Exchange

SYNOPSIS

use Net::SDEE;

$sdee = Net::SDEE->new(Username => 'sdeeuser', Type => 'subscription');
$sdee->Password('foobar');
$sdee->Server('192.168.1.2');

$sdee->getAll();
$sdee->closeAll();

INTRODUCTION

The Security Device Event Exchange (SDEE) protocol was developed to communicate the events generated by security devices. Currently, only IDS events are supported, but the protocol is designed to be extensible, allowing additional event types to be defined and included.

The SDEE client establishes a session with the server by successfully authenticating with that server. Once authenticated, a session ID or session cookie is given to the client, which is included with all futures requests.

SDEE supports two methods for retrieving events: an event query and an event subscription. Both methods use SSL to query the SDEE 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. Furthermore, multiple subscriptions are supported for a single session. In this case, each subscription would be configured to retrieve different events (either type or severity).

To either the query or subscription request, the server's response is received in the form of a SOAP document. The document may contain response or error messages, as well as one or more events.

For more information and the specification for SDEE, see http://www.icsalabs.com/html/communities/ids/sdee/index.shtml

DESCRIPTION

There are several ways to use this module, depending on what you're interested in doing and what you'd like to leave to the SDEE object to handle.

CONTROL METHODS

new( [Parameter => value,] )

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

open( [Subscription Object] )

This method is only used for subscriptions. If a subscription object is passed as a paramter, that subscription is opened and established. Otherwise, a new instance of a subscription object is created. The server is presented with the options in the subscription object and a subscription ID is created and returned. This ID is used by the client in all future queries so that the server might differentiate between subscriptions and return the correct set of events. Note - no events are returned at this point, the subscription is simply registered with the server.

get( subscription ID )

This method will retrieve events. If a subscription ID is passed as a paramter, then that subscription is requested of the server, otherwise, it is assumed that the desire was for an event query and that is performed.

cancel( subscription ID )

Canceling a subscription is done when a get() is blocked and the desire is to interrupt. Obviously, this needs to be sent through a different session than the currently blocked one.

close( subscription ID )

Informs the server that this subscription is no longer valid. This subscription is removed from the list of active subscriptions and no longer queried.

getAll()

Perform a get() for all established subscriptions. This should be used only when callback routines are implemented, otherwise, the results from the multiple gets are lost.

closeAll()

Performs a close() on all established subscriptions.

SESSION METHODS

The session methods describe how the client will connect to the server.

Scheme

Sets the URI scheme for the connection. The default is 'https'

Port

Sets the URI port for the connection. The default is '443'

Server

Sets the SDEE server for the session. The default is '127.0.0.1'.

Username

Sets the username to use when authenticating to the server.

Password

Sets the password to use when authenticating to the server.

RETRIEVAL METHODS

These methods specify to the server the parameters surrounding event retrieval for each subscription or query.

startTime

Specify the start time of the events to be retrieved. If not specified, collection will be started by the oldest events. This applies to both subscriptions and queries.

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.

timeout

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

maxNbrOfEvents

The maximum number of events to retrieve. 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 request's criteria. Note - the default for both queries and subscriptions is 20. This can easily be adjusted:

$sdee->maxNbrOfEvents(100);	# limit to 100
$sdee->maxNbrOfEvents(undef);	# unlimited or limited by the server, this could be dangerous!

confirm

Acknowledge that the events retrieved in the previous get() were received. The default is to confirm.

idsAlertSeverities

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

$sdee->idsAlertSeverities( 'medium', 'high');

Default is ALL IDS alert severities.

errorSeverities

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

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

Default is ALL error severities.

events

Specify the type of events to retrieve. Currently, only IDS events are supported: evIdsError, evIdsAlert, evIdsStatus, evIdsLogTransaction, evIdsShunRqst

The default is evIdsAlert messages only.

CALLBACK METHODS

There are several ways to control the behavior of the SDEE object, depending on what you want to do with it. To control this behavior, you have the ability to control how the error/response messages are handled, how the events are returned/processed, and how the SOAP document is processed. This module comes with the basic functionality for all three, but you may choose to include your own for your own purposes.

debug

Setting this will turn on debugging. There is internal debugging messages that will be reported if this flag is set. This does not affect the reporting of response messages.

debug_callback

By default, the reponse messages and SDEE object messages are handled by an internal routine that merely prints them and their calling method. This method can be used to redefine that internal routine to another one: Events $sdee->debug_callback(\$local_debug);

This routine should expect to receive a single argument being an error message.

callback

The callback method sets the routine that will handle the returned results from the get(). The callback method received two paramters. The second is the subscriptionID that the request came from. The first depends on the return setting set (see returnEvents, returnXML, and returnRawXML).

If no callback routine is set, the particular portion and format of the document is returned. Here are some examples:

my $sdee = Net::SDEE->new( returnEvents => 1, callback => \&eventProcessor );

$sdee->returnXML(1);
$sdee->callback(\&xmlProcessor);

returnEvents

If this is set, the SDEE object will execute the callback routine for EACH event. If no callback routine is set, then a structure containing all the events will be returned from the get(). Also, any response messages will be sent to the debug_callback function.

returnXML

If this is set, then the callback routine (or return value of get()) is the entire XML document returned from the response processed by XML::Simple's XMLin() function. Also, any response messages will be sent to the debug_callback function.

returnRawXML

If this is set, then the callback routine (or return value of get()) is the entire, raw, unprocessed XML document. Also, NO response messages will be sent to the debug_callback function. You should use this if you want to handle ALL processing of the return document yourself.

SUBSCRIPTION METHODS

Since an SDEE object may have multiple subscriptions, there are a few methods provided to assist in controlling the subscriptions. However, if you are intending to make use the above callback routeins, getAll() and closeAll(), you will probably not need to use any of these methods.

getNumberOfSubscriptions

Returns the number of defined and valid subscriptions.

getSubscriptionIds

Returns a reference to a list of defined and valid subscription IDs.

foreach my $subscriptionId ( @{ $sdee->getSubscriptionIds } ) { $sdee->get($subscriptionId); }

getSubscription

Takes a subscription ID as a parameter and retrieves the subscription object. Note, this does not remove it from the list, only returns are a reference to the object.

addSubscriptions

Takes a subscription object as a parameter. If no subscription object is provided, a new one is instantiated with the default parameters. Additionally, the subscription object is registered with the server.

deleteSubscriptions

Takes as a parameter, a subscription ID. This subscription is removed from the list of valid subscriptions. Note - this subscription is NOT closed, so, if you're using this method, be sure to call 'close($subscriptionId)' first.

EXAMPLE

Here's a simple way to setup an SDEE subscription and begin processing events

	sub eventCallback { my ($event, $subscriptionID) = @_; ... }
	sub errorCallback { my $message = shift; ... }

        $sdee = Net::SDEE->new(
                returnEvents => 1,
                debug => 1,
                callback => \&eventCallback,
                debug_callback => \&errorCallback
        );

        $sdee->Username($user);
        $sdee->Password($pass);
        $sdee->Server($host);
        $sdee->open(); # establish a subscription with the defaults

        # callback subs are called for each event
        for(;;) { $sdee->get(); } # probably want to sleep or something inbetween

TODO

This implementation currently supports IDS messages, as described in the SDEE specification. However, it is not possible to add additional message types at this point. Furthermore, detection of and reporting of missed events is not currently incorporated into this version.

The main reason for these limitations is my inability to test either of these. This module was tested with a beta version of Cisco's CIPS 5.0, which I did not control. I would be interested in hearing about other systems that support SDEE and would be happy to work on finishing these two options if someone could provide a system to test against.

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 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.

cpanm Net::SDEE

perl -MCPAN -e shell
install Net::SDEE