[[PageOutline]]

!PreludeEasy is a project to create high-level bindings (Perl and Python) for the Prelude library, using SWIG.

It can be used to:
 * Create or manipulate IDMEF alerts easily
 * Create a sensor in a few lines of code (to send alerts)
 * Create a Prelude client, which will receive all alerts

It does not (and probably will never) have all features from libpreludedb: it was created to provide an easy access to basic functions. It is designed to have a specific API, different from libprelude : libprelude is designed for performance, while !PreludeEasy is designed for ease of use.

If you need complete access to libprelude, you can use the standard bindings (perl and python, wrapping exactly the C functions with the same API) or the C library directly.

= Compilation =

For the moment, there is no release as !PreludeEasy is still in development.

The project is hosted as a separate branch of libprelude by Prelude IDS.

To extract the development branch:
{{{
svn co https://svn.prelude-ids.org/libprelude/branches/libprelude-easy-bindings
}}}

The following packages are needed:
 * swig
 * flex
 * bison
 * libperl-dev
 * python-dev

Configure, build and install the package as usual:
{{{
./configure --enable-easy-bindings [arguments]
}}}
You may want to specify at least a prefix for installation.
Check that swig, Perl and Python are detected properly before continuing.
{{{
make
make install
}}}

= Python Bindings =

== Loading the module ==

Just import the module, as for any python module:
{{{
import PreludeEasy
}}}

If it is not found, you may have to specify the directory before importing it:
{{{
import sys
sys.path.append('/path/to/module_installation')
import PreludeEasy
}}}

== IDMEF alerts ==

=== Creation ===

To create an IDMEF alert, just create the corresponding object:
{{{
idmef = PreludeEasy.IDMEF()
}}}
This will create an empty alert, initialized with the creation time.

To add or modify IDMEF properties, use the ''Set'' method:
{{{
idmef.Set("alert.classification.text","blah")
}}}

''Note'': If the IDMEF path is invalid, an Exception will be raised.

=== Accessing properties ===

To get the value of a property, use the ''Get'' method:
{{{
value = idmef.Get("alert.assessment.impact.completion")
if value:
       print value
}}}

''Note'': The property is '''always''' returned as a string, or ''None'' if not present.

=== Debug ===

The alert can be printed to standard output:
{{{
idmef.PrintToStdout()
}}}

=== Saving to a file ===

The alert can be saved to a file (for later use):
{{{
idmef.WriteToFile("foo.bin")
}}}

=== Loading from a file ===

To load an alert, just create an empty object, then load the file:
{{{
idmef = PreludeEasy.IDMEF()
idmef.ReadFromFile("foo.bin")
}}}

== Client (writing alerts) ==

As a prerequisite, you need to have created a profile by [https://trac.prelude-ids.org/wiki/RegisteringASensor registering a sensor], with write permission.

Use the ''Client'' object, with the profile name:
{{{
client = PreludeEasy.Client("MyTest")
client.Init()
client.Start()
}}}

You are now able to send alerts:
{{{
idmef = PreludeEasy.IDMEF()
idmef.Set("alert.classification.text", "Bar")
...
client.SendIDMEF(idmef)
}}}

== Client (reading alerts) ==

You need a profile with IDMEF read permission.

The client will connect to the manager and use pooling to retrieve alerts.

The following example checks for alerts every 2 seconds, and prints some IDMEF properties when 
{{{
client = PreludeEasy.Client("PoolingTest")
client.Init()
client.Start()

ret = client.PoolInit("192.168.33.215", 1)

def handle_alert(idmef):
        try:
                #idmef.PrintToStdout()
                print idmef.Get("alert.create_time")
                print idmef.Get("alert.classification.text")
                print idmef.Get("alert.assessment.impact.severity")
                print idmef.Get("alert.additional_data(0).data")
        except RuntimeError,_e:
                print "An exception occured: ",_e

import time

while 1:
        sys.stdout.write(".")
        sys.stdout.flush()
        idmef = client.ReadIDMEF(1)
        if idmef:
                handle_alert(idmef)
        time.sleep(2)
}}}

= Real life uses =

As stated before, this is work in progress.

It has been used to:
 * [http://www.gscore.org/blog/index.php/post/2007/11/28/Visualizing-Security-Events display security events graphically]
 * create a [http://www.gscore.org/blog/index.php/post/2008/01/03/3D-visualization-and-security 3D representation of security alerts] using [https://www.secdev.org/projects/rtgraph3d RTGraph3D].

If you have any other use just tell me.

----
Written on 2008/01/06 by Pierre Chifflier