Introduction

This document desribes how to develop an OCFA module to be used in the OCFA framework. Knowledge of C++ is assumed, as is an understanding of the extractor module development in part 1 of the tutorial. You will also need a working development environment, but if you succeeded in building and installing OCFA, then you'll probably have all what you need.
The description on this page describes how to develop a basic dissector module for dissecting embedded data from compound data files. Other types of modules are extractors, described in part 1 of the tutorial, and tree-graph modules (also called tree-graph dissectors) for dissecting data files into meta-data rich components.
Extractors and Tree-graph dissectors are discussed in part 1 and part 3 of this tutorial.

Vinetto

In this section we will write a dissector based on the tool vinetto. Vinetto is an open source tool which extracts images from Windows Thumbs.db files. For more information on vinetto see the vinetto homepage.

Preparation

Since our module will basically be a wrapper around the vinetto tool, you'll need to install it before proceeding with this tutorial. Make sure the tool gets installed somewhere in a standard binaries directory like /usr/bin.
We will use the script createmodule.sh in order to create a starting point for our module development. For more information about this script see the createmodule.sh tutorial.
In order to produce the same code as is used in this example;

• run the createmodule.sh script, located in the OcfaModules/m4 directory.
• Choose vinettocfa as the modulename.
• Choose 'dissector' as module type.

The source files will be generated in OcfaModules/dissector/vinettocfa.

Implementation of processEvidence

As we saw in the extractor tutorial, the main work of your module is implemented in the method processEvidence. The declaration and (empty) body is already generated for you by the createmodule.sh script. The body with the the implementation is displayed below. The next sections describe the code in more detail.

void  Vinettocfa::processEvidence()
{
   EvidenceStoreEntity * evidence = fetchEvidenceStoreObject();
   string filename = evidence->getAsFilePath();
   getLogStream(LOG_NOTICE) << "Processing " << filename << endl;

   // do whatever you want to do with the evidence
   // your workdir can be found by getWorkDir()
   string workdir = getWorkDir();
   string outputdir = workdir + string("/ExtractedImages");
   mkdir(outputdir.c_str(), 0755);
   string cmd = string(BINARY_VINETTO) + string(" ") + filename + string(" -o ") + outputdir;
   getLogStream(LOG_NOTICE) << "Vinetto cmd: " <<  cmd << endl;
   FILE *f = popen(cmd.c_str(), "r");
   pclose(f);

   // Store metadata about the evidence, if any, e.g.
   // setMeta("MetadataName", MetadataValue);

   // get a handle on the derived evidence (assuming the evidence filename is stored in derivedfilename)
   Evidence *derived = derive("ExtractedImages", Scalar("ExtractedImages"));

   // finally, submit the derived evidence to the router
   submitEvidence(derived);

   // you need to delete the created objects
   delete derived;
   delete evidence;
}

The evidence filename

The name of the evidence is not Thumbs.db as you might expect, but a path into the OCFA repository. To access the evidence file (the Thumbs.db) by name is achieved by a call to getAsFilePath() on the evidence object. This object can be accessed by a call to fetchEvidenceStoreObject().
The two steps are displayed below;

EvidenceStoreEntity * evidence = fetchEvidenceStoreObject();
string filename = evidence->getAsFilePath();
getLogStream(LOG_NOTICE) << "Processing " << filename << endl;

The work directory

The directory where the module expects the newly derived evidence is called the 'work directory'. To get the path to your module's work directory, call the getWorkDir() method. In our example we create a subdirectory in our work directory called "ExtractedImages". We use this directory later to export the images from the Thumbs.db to.
The next code snippet shows how to prepare the subdirectory;

string workdir = getWorkDir();
string outputdir = workdir + string("/ExtractedImages");
mkdir(outputdir.c_str(), 0755);

Running Vinetto

To run the Vinetto tool, we use a call to popen(). To read any information returned by Vinetto on its standard output, we could read from the File descriptor f, although we do not use that in this example.
The call to popen expects a shell commandline string to execute. This string we have to build ourselves. The general usages of the vinetto commandline tool is

vinetto name_of_thumbs_db -o output_dir_for_extracted_images

So, basically it is a call to the binary itself, followed by the name of the Thumbs.db file and followed by the -o flag specifying the output directory for the extracted images.
Below is shown how the command is constructed and fed to popen(). Note the use of the definition of BINARY_VINETTO. See "Using the configure script" for an explanation below.

string cmd = string(BINARY_VINETTO) + string(" ") + filename + string(" -o ") + outputdir;
getLogStream(LOG_NOTICE) << "Vinetto cmd: " <<  cmd << endl;
FILE *f = popen(cmd.c_str(), "r");
pclose(f);

Submitting the extracted images into OCFA

Now that we have derived images from the Thumbs.db file, it is time to submit the output directory into OCFA for further processing.

Evidence *derived = derive("ExtractedImages", Scalar("ExtractedImages"));
submitEvidence(derived);

We create a handle to the derived evidence by specifying its location (relative to our own work directory), and we give it a name. After that we call submitEvidence() on the derived evidence. The files contained in the ExtractedImages subdirectory will now be submitted into the OCFA system for further processing.

Using the configure script

In the above code we used something called 'BINARY_VINETTO'. This is actually a string, defined by the configure script in the OcfaModules root directory. In order to let configure know it should define this string is to add the following line to targets.conf_in (also located in the OcfaModules root directory):

dissector/vinettocfa vinetto BINARY_VINETTO

The line contains three columns. The first column is the name of the module for which we are adding this line. The second column is the name of the binary ('executable') the configure script should search for. The third column is the name of the define which needs to be set to the path of the binary specified in the second column.
After adding the above line to the targets.conf_in, you should run ./configure once more. If the configurescript is able to find the binary it will add the proper #define to the file binaries.hpp. This file you should #include in your source file where you make use of the definition (in our case in vinettocfa.cpp). Thus;

// #includes snipped
#include <store/EvidenceStoreEntity.hpp>
#include "../../../binaries.hpp"
using namespace ocfa;
// rest of code snipped

Final steps

If all went well, you now should be able to just type 'make' and 'make install'.
After your module has been installed you will have to add a rule to the rulelist of the router.
In order for the router to sent Thumbs.db files to your module you might want to add a line like those shown below to your rulelist.csv (which is located in $OCFAROOT/etc).

ocfa@ocfademo-desktop:~$ grep vine etc/rulelist.csv
contenttype;DNTCR;fileinfo;OLE;DNTCR;ACT_FORWARD;vinettocfa;
fileext;DNTCR;fileextension;db;DNTCR;ACT_FORWARD;vinettocfa;