/ 
XML-IDMEF-0.07
River stage zero No dependents
/ XML::IDMEF

NAME

XML::IDMEF - A module for building/parsing IDMEF messages

QUICK START

Below is an example of Alert IDMEF message.

<IDMEF-Message version="0.5">
  <Alert>
    <AdditionalData meaning="data2" type="string">value2</AdditionalData>
    <AdditionalData meaning="data1" type="string">value1</AdditionalData>
    <Target>
      <Node>
        <name>mynode</name>
      </Node>
    </Target>
    <Analyzer model="myids" />
  </Alert>
</IDMEF-Message>

The previous IDMEF message can be built with the following code snipset:

use XML::IDMEF;   

my $idmef = new XML::IDMEF();  

$idmef->add("AlertTargetNodename", "mynode");
$idmef->add("AlertAdditionalData", "value1", "data1"); 
$idmef->add("AlertAdditionalData", "value2", "data2");
$idmef->add("AlertAnalyzermodel", "myids");

print $idmef->out();

To automatically insert an Alert ident tag and set the CreateTime class to the current time, add the 2 lines:

$idmef->create_ident();
$idmef->create_time();

and you will get:

<IDMEF-Message version="0.5">
  <Alert ident="00003D9047B8722743900005A3F0001">
    <AdditionalData meaning="data2" type="string">value2</AdditionalData>
    <AdditionalData meaning="data1" type="string">value1</AdditionalData>
    <CreateTime ntpstamp="0xc4fd2d38.0x0">2002-08-24T11:08:40Z</CreateTime>
    <Target>
      <Node>
        <name>mynode</name>
      </Node>
    </Target>
    <Analyzer model="myids" />
  </Alert>
</IDMEF-Message>

DESCRIPTION

IDMEF.pm is an interface for simply creating and parsing IDMEF messages. IDMEF is an XML based standard for representing Intrusion Detection related messages (http://www.silicondefense.com/idwg/).

IDMEF.pm is compliant with IDMEF v0.5, and hence provides calls for building Alert, ToolAlert, CorrelationAlert, OverflowAlert and Heartbeat IDMEF messages.

This interface has been designed for simplifying the task of translating a key-value based format to its idmef representation, which is the most common situation when writing a log export module for a given software. A typical session involves the creation of a new IDMEF message, the initialisation of some of its fields and its conversion into an IDMEF string (see example in QUICK START).

An interface to load and parse an IDMEF message is also provided (with the 'to_hash' function).

This module contains a generic XML DTD parser and includes a class based definition of the IDMEF DTD. It can hence easily be upgraded or extended to support new XML nodes. For information on how to extend IDMEF with IDMEF.pm, read the documentation in the source code.

This code is distributed under the BSD license, and with the support of Proact Defcom AB, Stockholm, Sweden.

EXPORT

xml_encode
xml_decode
byte_to_string
extend_idmef

AUTHOR

Erwan Lemonnier - erwan@cpan.org

LICENSE

This code was developed with the support of Proact Defcom AB, Stockholm, Sweden, and is released under the BSD license.

SEE ALSO

XML::Simple, XML::Parser, XML::Parser::Expat, libexpat

SYNOPSIS

In the following, function calls and function parameters are passed in a perl object-oriented fashion. Hence, some functions (object methods) are said to not take any argument, while they in fact take an IDMEF object as first argument. Refer to the examples in case of confusion. The function listed at the end (xml_encode, xml_decode, byte_to_string are on the other hand class methods, and should not be called on an IDMEF object.

OBJECT METHODS

new()

ARGS none.
RETURN

a new empty IDMEF message.

DESC

new creates and returns a new empty IDMEF message. Use add(), create_ident() and create_time() to add fields to this message.

EXAMPLES
my $idmef = new XML::IDMEF;

$idmef->in([PATH|STRING])

ARGS

PATH|STRING: either an IDMEF message as a string or a path to a file containing an IDMEF message.

RETURN

the IDMEF object corresponding to this IDMEF message.

DESC

in creates a new IDMEF message from either a string STRING or a file located at the path PATH. If no argument is provided, an empty IDMEF message is created and returned.

EXAMPLES
my $idmef = (new XML::IDMEF)->in("idmef.file");
my $idmef = $idmef->in();

$idmef->out()

ARGS none.
RETURN

a string representing this IDMEF object.

DESC

out returns the IDMEF message as a string.

EXAMPLES
print $idmef->out;

$idmef->create_ident()

ARGS none.
RETURN nothing.
DESC

create_ident generates a unique IDMEF ident tag and inserts it into this IDMEF message. The tag is generated base on the local time, a random number, the process pid and an internal counter. If the IDMEF message does not yet have a type, it will become 'Alert' by default.

EXAMPLES
$idmef->create_ident();

$idmef->create_time([$epoch])

ARGS

$epoch: optional. an epoch time (time in secunds since January 1, 1970, UTC).

RETURN nothing.
DESC

create_time sets the IDMEF CreateTime node to the current time (if no epoch argument is provided), or to the time corresponding to the epoch value provided. It sets both the ntpstamp and the UTC time stamps of CreateTime.

EXAMPLES
$idmef->create_time();

$idmef->get_type()

ARGS none.
RETURN

the type of this IDMEF message, as a string.

DESC

get_type returns the type of this IDMEF message as a string. An 'Alert' IDMEF message would for example return "Alert".

EXAMPLES
$string_type = $idmef->get_type();

$idmef->add($tagpath, $value)

ARGS

$idmef: a hash representation of an IDMEF message, as received from new or in.

$tagpath: a string obtained by concatenating the names of the nested XML tags, from the Alert tag down to the closest tag to value.

$value: the value (content of a tag, or value of an attribute) of the last tag given in tagpath.

RETURN

1 if the field was correctly added, 0 otherwise.

DESC

Each IDMEF content/value of a given IDMEF message node can be created through an appropriate add() call. A 'tagpath' is a string obtained by concatenating the names of the XML nodes from the top 'Alert' node down to the attribute or content whose value we want to set. Hence, in the example given in introduction, the tagpath for setting the value of the Alert Analyzer model attribute is 'AlertAnalyzermodel'.

The add call was designed for easily building a new IDMEF message while parsing a log file, or any data based on a key-value format.

RESTRICTIONS

add cannot be used to change the value of an already existing content or attribute. An attempt to run add() on an attribute that already exists will just be ignored. Contents cannot be changed either, but a new tag can be created if you are adding an idmef content that can occur multiple time (ex: UserIdname, AdditionalData...).

SPECIAL CASE: AdditionalData

AdditionalData is a special tag requiring at least 2 add() calls to build a valid node. In case of multiple AdditionalData delarations, take care of building AdditionalData nodes one at a time, and always begin by adding the "AddtitionalData" field (ie the tag content). Otherwise, the idmef key insertion engine will get lost, and you will get scrap.

As a response to this issue, the 'add("AlertAdditionalData", "value")' call accepts an extended syntax compared with other calls:

add("AlertAdditionalData", <value>);   
   => add the content <value> to Alert AdditionalData

add("AlertAdditionalData", <value>, <meaning>); 
   => same as:  (type "string" is assumed by default)
      add("AlertAdditionalData", <value>); 
      add("AlertAdditionalDatameaning", <meaning>); 
      add("AlertAdditionalDatatype", "string");

add("AlertAdditionalData", <value>, <meaning>, <type>); 
   => same as: 
      add("AlertAdditionalData", <value>); 
      add("AlertAdditionalDatameaning", <meaning>); 
      add("AlertAdditionalDatatype", <type>);

The use of add("AlertAdditionalData", <arg1>, <arg2>, <arg3>) is prefered to the simple add call, since it creates the whole AdditionalData node at once. In the case of multiple arguments add("AlertAdditionalData"...), the returned value is 1 if the type key was inserted, 0 otherwise.

EXAMPLES
my $idmef = new XML::IDMEF();

$idmef->add("Alertimpact", "<value>");     

$idmef->add($idmef, "AlertTargetUserUserIdname", "<value>");

# AdditionalData case:
# DO:
$idmef->add("AlertAdditionalData", "value");           # content add first
$idmef->add("AlertAdditionalDatatype", "string");      # ok
$idmef->add("AlertAdditionalDatameaning", "meaning");  # ok

$idmef->add("AlertAdditionalData", "value2");          # content add first
$idmef->add("AlertAdditionalDatatype", "string");      # ok
$idmef->add("AlertAdditionalDatameaning", "meaning2"); # ok

# or BETTER:
$idmef->add("AlertAdditionalData", "value", "meaning", "string");  # VERY GOOD
$idmef->add("AlertAdditionalData", "value2", "meaning2");          # VERY GOOD (string type is default)


# DO NOT DO:
$idmef->add("AlertAdditionalData", "value");           # BAD!! content should be declared first
$idmef->add("AlertAdditionalDatameaning", "meaning2"); # BAD!! content first!

# DO NOT DO:
$idmef->add("AlertAdditionalData", "value");           # BAD!!!!! mixing node declarations
$idmef->add("AlertAdditionalData", "value2");          # BAD!!!!! for value & value2
$idmef->add("AlertAdditionalDatatype", "string");      # BAD!!!!! 
$idmef->add("AlertAdditionalDatatype", "string");      # BAD!!!!!

$idmef->contains($tagpath)

ARGS

$tagpath: a tagpath (see add).

RETURN

1 if there exists in this idmef message a value associated to the given tagpath. 0 otherwise.

DESC

contains is a test function, used to determine whether a value has already been set at a given tagpath.

$idmef->to_hash()

ARGS none.
RETURN

the IDMEF message flattened inside a hash.

DESC

to_hash returns a hash enumerating all the contents and attributes of this IDMEF message. Each key is a concatenated sequence of XML tags (a 'tagpath', see add()) leading to the content/attribute, and the corresponding value is an array containing the content/attribute itself. In case of multiple occurences of one 'tagpath', the corresponding values are listed as elements of the array (See the example). All IDMEF contents and values are converted from IDMEF format (STRING or BYTE) back to the original ascii string.

EXAMPLES
<IDMEF-message version="0.5">
  <Alert ident="myalertidentity">
    <Target>
      <Node category="dns">
        <name>node2</name>
      </Node>
    </Target>
    <AdditionalData meaning="datatype1">data1</AdditionalData>
    <AdditionalData meaning="datatype2">data2</AdditionalData>
  </Alert>
</IDMEF-message>

becomes:
 
{ "version"                    => [ "0.5" ],
  "Alertident"                 => [ "myalertidentity" ],
  "AlertTargetNodecategory"    => [ "dns" ],
  "AlertTargetNodename"        => [ "node2" ],
  "AlertAdditionalDatameaning" => [ "datatype1", "datatype2" ],   # meaning & contents are
  "AlertAdditionalData"        => [ "type1", "type2" ],           # listed in same order
}

CLASS METHODS

xml_encode($string)

ARGS

$string: a usual string

RETURN

the xml encoded string equivalent to $string.

DESC

You do not need this function if you are using add() calls (which already calls it). To convert a string into an idmef STRING, xml_encode basically replaces the following characters: with:

&                 &amp;
<                 &lt;
>                 &gt;
"                 &quot;
'                 &apos;

REM: if you want to convert data to the BYTE[] format, use 'byte_to_string' instead

xml_decode($string)

ARGS

$string: a string encoded using xml_encode.

RETURN

the corresponding decoded string.

DESC

You do not need this function with 'to_hash' (which already calls it). It decodes <xmlstring> into a string, ie replaces the following characters: with: &amp; & &lt; < &gt; > &quot " &apos ' &#xx; xx in base 10 &#xxxx; xxxx in base 16

It also decodes strings encoded with 'byte_to_string'

byte_to_string($bytes)

ARGS

$bytes: a binary string.

RETURN

The string obtained by converting <bytes> into its IDMEF representation, refered to as type BYTE[] in the IDMEF rfc.

DESC

converts a binary string into its BYTE[] representation, according to the IDMEF rfc.

extend_subclass($IDMEF-class, $Extended-subclass)

ARGS

$IDMEF-class: an extension class DTD

$Extended-subclass: the name of the extended class's root

RETURN nothing.
DESC

extend_subclass allows to extend the IDMEF DTD by registring new subclasses to classes from the standard IDMEF DTD. Internally, the IDMEF.pm module is built around a DTD parser, which reads an XML DTD (written in a proprietary but straightforward format) and provides functions to build and parse XML messages compliant with this DTD. This DTD parser and its API could be used for any other XML format than IDMEF, provided that the appropriate DTD gets loaded in the module. extend_subclass allows to inject new subclasses of pre-loaded DTD classes into the IDMEF.pm DTD engine.

ex: extend_sublass($IDMEF-class, $Extended-subclass);

The format of the $xxx-class is too complex to be described here. Refer to the documentation inside the source code.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1640:

You forgot a '=back' before '=head2'