The iodef module is an extension module, which allows Orchids to produce alerts in the IODEF format (Incident Object Description Exchange Format).

Configuration options

<module iodef>

• IODEFTemplatesDir templates-dir: instructs Orchids that it should look for IODEF reporting templates in the templates-dir directory.  See below for reporting.
  Default value is $OCONF/iodef.
• IODEFOutputDir output-dir: instructs Orchids that IODEF reports should go into the output-dir directory.
  Default value is $OCONF/reports.
• CSIRTName string: sets the name of the Computer Security Incident Response Team (CSIRT) to use in the name property of the Incident/IncidentID node of the IODEF XML report.
  Default value is "Orchids.LSV", although that is not a CSIRT.

</module>

Reporting

Although the iodef module provides a few primitives to create and write IODEF reports, the recommended way to use the iodef module is to use the report() primitive.

Here is how it works. Imagine you are currently running the OrchIDS code of rule pid_tracker. (This is in file $OCONF/rules/pid_tracker_auditd.rule.) On finding an attack, this rule will enter the following state, named alert:

state alert!
  {
    $str = "Attack perpetrated by $uid=" + str_from_int($uid);
    report();
  }

The report() primitive will generate reports according to different formats. If the iodef module is loaded, IODEF will be one of these formats, and a report will be generated, as file report-dir/report-secs-msecs.xml, where secs and msecs are the current time, split into seconds and microseconds, as 8 hexadecimal digits. The report-dir directory is given as argument to the IODEFOutputDir configuration directive.

The report itself is generated from a template file. The IODEF module takes the name rule of the current rule (here, pid_tracker), and looks for a template file in the $OCONF/iodef/ directory, of name rule.iodef. In our example, it will find pid_tracker.iodef, which contains the following template:

<?xml version="1.0"?>
<IODEF-Template>
  <insert path="/*/iodef:Incident">
    <Description>PID Tracker alert</Description>
    <Description>$str</Description>
    <Assessment>
      <Impact type="policy" completion="succeeded"/>
    </Assessment>
    <Contact role="creator" type="organization">
      <ContactName>Orchids</ContactName>
      <Email>orchids@lsv.fr</Email>
    </Contact>
  </insert>
</IODEF-Template>

The report is then constructed by replacing all XML nodes that contain an OrchIDS variable name by its value. Here, the second Description node will be filled in by a message of the form "Attack perpetrated by $uid=uid", where uid is the value of the OrchIDS variable $uid.

Primitives

• iodef_new_report : str → xmldoc
  create a new IODEF report from the template file given as argument
  • the template file will be read in, parsed as an XML document, and all XML nodes containing the name of an OrchIDS variable will be replaced by the value of that variable
  • returns: 1 (true) if all went well, 0 (false) otherwise

• iodef_write_report : xmldoc → int
  write the given IODEF report into the Orchids report directory (typically /usr/local/var/orchids/reports/)
  • file name is report-directory/report-secs-msecs.xml, where secs and msecs are the current time, split into seconds and microseconds, as 8 hexadecimal digits
  • returns: 1 (true) if all went well, 0 (false) otherwise
    the causes of error can be: the reports directory is not set, or there was not enough space left on the device
• Setting additional values and attributes is done by using the primitives provided by the xml module (xml_set_str, xml_set_prop).  Contrarily to how the idmef module operates, IODEF reports are generated from template files.