doc/output-plugin.rst

   1 Howto write PRADS output plugins
   2 ================================
   3
   4
   5 PRADS exposes a callback API for its output,
   6 so that you can send the data directly to your application,
   7 or write to a different file format.
   8
   9 The output plugins reside in `src/output-plugins/`.
  10
  11 The classic output plugin is `log_file.c`, it is recommended to use
  12 it as an example.
  13
  14 To write an output plugin you need to create one or more callbacks
  15 for each of the different asset types, and then fill in an output_plugin
  16 struct with one or more callbacks:
  17
  18 ::
  19
  20   output_plugin p_stdout = {
  21       .init = &init_myoutput,
  22       .arp = &myoutput_arp,
  23       .os = &myoutput_os,
  24       .service = &myoutput_service,
  25       .connection = NULL,
  26       .denit = &end_myoutput,
  27       .data = NULL,
  28   };
  29
  30 As you can see, you can specify NULL for any output type you are not
  31 interested in. The init and denit functions, which are called upon
  32 PRADS start and end, respectively, are also optional, and `data` is a
  33 void pointer to any arbitrary data you would like to pass around
  34 between calls into your plugin.
  35
  36 For instance, if you want to output asset data you will need to
  37 write a callback with the type:
  38 `void log_os (output_plugin *log, asset *main, os_asset *os, connection *cxt)`
  39
  40 Here, `*log` is the output_plugin struct,
  41 `*main` is the main PRADS asset, `*os` is the matching operating system fingerprint and
  42 `*cxt` is PRADS connection data defined in prads.h.
  43
  44 A simple output plugin that only writes IP addresses and OS on new assets would look
  45 thusly:
  46
  47 ::
  48
  49   void simpl_os(output_plugin *log, asset *main, os_asset *os, connection *cxt){
  50       static char ip_addr_s[INET6_ADDRSTRLEN];
  51       u_ntop(main->ip_addr, main->af, ip_addr_s);
  52       printf("%s", ip_addr_s);
  53       printf(" : ");
  54       if(os->fp.os != NULL)
  55         printf("%s", os->fp.os);
  56   }
  57
  58   output_plugin p_stdout = {
  59       .os = &simpl_os,
  60       .data = NULL,
  61   };
  62
  63
  64 The last thing we need to do then is add the plugin to `log.h:log_types`:
  65
  66 `enum { LOG_STDOUT, LOG_FILE, LOG_FIFO, LOG_UNIFIED, LOG_SGUIL, LOG_RINGBUFFER, LOG_SIMPL, LOG_MAX } log_types;`
  67
  68 and `log_dispatch.c:init_logging()`:
  69
  70 ::
  71
  72    #include "log_simpl.h"
  73
  74 and
  75
  76 ::
  77
  78         switch(logtype)
  79         {
  80       case LOG_SIMPL:
  81          log_fun = init_log_simpl();
  82          break;
  83
  84 Since prads doesn't auto-load plugns (yet?) you will also need to add it to
  85 the main function, near where we do the other `init_logging()`:
  86
  87 ::
  88
  89     if(config.fifo) {
  90         olog("logging to FIFO '%s'\n", config.fifo);
  91         rc = init_logging(LOG_FIFO, config.fifo, config.cflags);
  92         if(rc) perror("Logging to fifo failed!");
  93     }
  94           init_logging(LOG_SIMPL, NULL, 0);
  95
  96
  97 You will want to add your new files to the build system, so go into `src/Makefile` and add your file:
  98
  99 ::
 100
 101   LOG_OBJ = output-plugins/log_dispatch.o output-plugins/log_stdout.o output-plugins/log_file.o output-plugins/log_fifo.o output-plugins/log_ringbuffer.o output-plugins/log_sguil.o output-plugins/log_simpl.o
 102
 103
 104 Now, when you type `make` in the src/ directory, the build process should compile and link in your very own output plugin!
 105
 106 We deeply encourage you to send us a patch with your output plugins!
 107
 108