Xplico reads in traffic data (capture modules), dissects information from this data according to protocols (dissector modules), and then dispatches the information to a desired output destination (dispatcher modules).
Every part of the decoder is a plugin and then a module. In Xplico (decoder), we distinguish between three types of modules:
The capture modules are located in the capt_dissectors top-level directory in the source tree. The pcap capture module interfaces to PCAP traffic files. The rltm (probably stands for 'real time') captures traffic data from a live network interface (eth0, wlan0, en1, etc.)
These modules extract protocol-specific information from traffic and can be found in the dissectors top-level directory. They are divided into subdirectories for each supported protocol (eth, ip, tcp, …).
Currently, the FTP PEI.cmd component points to a filename where the plaintext of the FTP session is stored. If one wanted to extract the FTP commands and responses of a conversation (from inside a dispatcher), two options are suggested. The first (and most easiest) would be to parse the given filename and get the information that way. The second option is to modify the dissector to include this information as PEI components.
To avoid major problems of synchronization between flows (for example, FTP's command and data channel) it is suggested that you use the TCP dissector called tcp_soft. We have developed two separate TCP dissectors for two different needs. Both provide the same data to higher dissectors (FTP, POP, SMTP), but with different time constraints (between different flows). Our “application” dissectors (the dissectors over TCP) are designed to work properly with both TCP dissectors.
Dispatcher modules export data to a destination, be it a database (SQLite, Postgres, …), a set of directories and files, a network socket, or wherever else you want. These can be found in the dispatch top-level directory.
To create your own dispatcher, you will need to implement the interface located at xplico-src/dispatch/dispatch.h . Specifically, you will need to implement 3 functions: DispInit(), DispEnd(), DispInsPei() . DispInit() is typically used to set ID numbers specific to the protocols your dispatcher intends to use, and also to set up anything else your dispatcher may need (sockets, database connections, etc) - I believe this function is only called once per dispatcher. DispInsPei() is called many times, and each time it is passed a pointer to a Protocol Element Information (PEI) object (see below). DispEnd() is called to clean up anything you need to clean up (close file/socket handles, database connections, etc.)
If you are creating your own dispatcher and discover that the desired protocol information cannot be derived from the protocol's PEI components, it will be necessary to modify the corresponding dissector so that the desired information is included/constructed.
Tips: In order to output data by capture/decode time, check out pei.time and pei.time_cap .
The definition of the PEI data structure can be found at xplico-src/dispatch/include/pei.h . A PEI contains meta data, and a list of PEI Components. Each protocol supported by the tool has a dissector that can decode protocol information from traffic data and then encode that information into a protocol-specific PEI format. The PEI format for a given protocol is defined by the corresponding dissector module in the DissecRegist() function, and can be viewed from the command line with the -i option. For example, the FTP PEI is defined at xplico-src/dissectors/ftp/ftp.c:DissecRegist(). For the time being, the value of a PEI component can be either a string (populated with PeiCompAddStingBuff() by dissector) or a file (populated with PeiCompAddFile() by dissector). The dissector modules are responsible for constructing PEIs from raw packet data, and then these PEIs are given to the dispatch modules (by calling their DispInsPei() functions) for output.
Not all dissectors generate a PEI; examples of such dissectors are TCP, IP, UDP, and Ethernet.
Manipulators allow some manipulation to be performed on PEIs before they are dispatched. Their role in the capture-dissector → protocol dissector → dispatcher chain can be depicted here:
--------->manipulator (1) |--------->manipulator (2) | ... |--------->manipulator (n) Capture-dissector -> protocol dissector ---(PEI)---->| (or) --------->dispatcher
Manipulators may generate new PEIs from the original input PEIs; these generated PEIs can then be given to the dispatcher.