User Tools

Site Tools


pom-ng:lua

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pom-ng:lua [2012/10/22 08:10] 2001:7e8:2221:600:901a:feff:fe05:41fepom-ng:lua [2020/05/26 21:59] (current) – external edit 127.0.0.1
Line 3: Line 3:
 Currently, the lua API allows the creation of scripted pom-ng output. Currently, the lua API allows the creation of scripted pom-ng output.
  
 +Quick link : [[pom-ng:lua:plugins|List of plugins]].
  
 ===== Tutorial ===== ===== Tutorial =====
Line 8: Line 9:
 ==== Register an output ==== ==== Register an output ====
  
-To create a new output, you simply call **output.new(name, parameters)**. Each parameter is declared the following way : **{name, ptype, default_value, description}**. +To create a new output, you simply call **output.new(name, parameters)**. Each parameter is declared the following way : **{name, ptype, default_value, description}**. The output will be registered in the system automatically.
- +
-After creating your output you need to register it. This is achieved by calling **output.register(my_output)**. When loading the lua script, the function **<filename>_register()** will be called. This means that if you save your output in the file **my_output.lua**, the function **my_output_register()** will be called when loading the lua script to register the output with the system.+
  
 When the output is started, the function **open()** will be called. Similarily, the function **close()** will be called when the output is stopped. When the output is started, the function **open()** will be called. Similarily, the function **close()** will be called when the output is stopped.
Line 29: Line 28:
         local param2_value = self:param_get("param2_name")         local param2_value = self:param_get("param2_name")
         print("My output started. Param 2 value is " .. param2_value)         print("My output started. Param 2 value is " .. param2_value)
-end 
- 
-function my_output_register() 
-        pom.output.register(my_output) 
 end end
  
Line 54: Line 49:
  
 function my_output:open() function my_output:open()
-        self:event_listen_start("my_event", nil, my_output:event_process)+        self:event_listen_start("my_event", nil, self.event_process)
 end end
  
Line 79: Line 74:
         print("New payload of class " .. pload.type["class"])         print("New payload of class " .. pload.type["class"])
         priv.tot_len = 0         priv.tot_len = 0
 +        return true
 end end
  
 function my_output:pload_write(priv, pdata) function my_output:pload_write(priv, pdata)
         priv.tot_len += pdata.len         priv.tot_len += pdata.len
 +        return true
 end end
  
Line 90: Line 87:
  
 function my_output:open() function my_output:open()
-        self:pload_listen_start(my_output:pload_open, my_output:pload_write, my_output:pload_close)+        self:pload_listen_start(self.pload_open, self.pload_write, self.pload_close)
 end end
  
Line 111: Line 108:
 <code lua> <code lua>
  
-function my_output:pload_process(pload_priv, pload)+function my_output:pload_open(pload_priv, pload)
        -- Log the event associated with the payload        -- Log the event associated with the payload
        self.log:event_process(pload.event)        self.log:event_process(pload.event)
Line 118: Line 115:
        local fname = "/tmp/" .. self.file_count .. ".bin"        local fname = "/tmp/" .. self.file_count .. ".bin"
        self.file_count++;        self.file_count++;
 +       
 +       -- Send the payload to the plugin, it will take care of it from now on
        self.file:pload_process(pload, { filename = fname })        self.file:pload_process(pload, { filename = fname })
 +       
 +       -- Return false because there is nothing more to do
 +       return false
 end end
  
Line 134: Line 136:
         self.file_count = 0         self.file_count = 0
                  
-        -- Listen to the http_request event +        -- Listen to the http_request event in order have the payload generated out of it 
-        self:even_listen_start("http_request", nil, self:event_process)+        self:even_listen_start("http_request", nil, nil) 
 +         
 +        -- Listen to payloads -- 
 +        self:pload_listen_start(self.payload_open, nil, nil)
 end end
  
 function my_output:close() function my_output:close()
 +        self:pload_listen_stop()
         self:event_listen_stop("http_request")         self:event_listen_stop("http_request")
         self.file:close()         self.file:close()
Line 164: Line 170:
         local key, value         local key, value
         key, value = data_iter()         key, value = data_iter()
-        it not then break end+        if not key then break end
                  
-        local value_type = type(v)+        local value_type = type(value)
         if value_type == "userdata" then         if value_type == "userdata" then
                 print("Data has key " .. key .. " which value is a data_item object")                 print("Data has key " .. key .. " which value is a data_item object")
Line 182: Line 188:
 == Parameters: == == Parameters: ==
   * //data_item//: A data_item object from a data object.   * //data_item//: A data_item object from a data object.
 +
 +=== pom.dns.forward_lookup(name) ===
 +Perform a forward lookup for a hostname using the offline DNS database.
 +
 +== Parameters: ==
 +  * //name//: A name to lookup
 +
 +=== pom.dns.reverse_lookup(name) ===
 +Perform a reverse lookup for a hostname or IP using the offline DNS database. It will try to find out what was the original query that points to the provided name.
 +
 +== Parameters: ==
 +  * //name//: A name or IP to lookup
  
 === pom.log(level, message) === === pom.log(level, message) ===
Line 199: Line 217:
 == Returns: == == Returns: ==
 An output class. An output class.
- 
-=== pom.output.register(output_class) === 
-Registers a new output. 
- 
-== Parameters: == 
-  * //output_class//: A output class created with pom.output.new(). 
  
 === pom.plugin.new(plugin_name) === === pom.plugin.new(plugin_name) ===
Line 238: Line 250:
 Returns a data object containing all the information related to this event. Returns a data object containing all the information related to this event.
  
 +=== event.timestsamp ===
 +== Returns: ==
 +Returns the timestamp when the event started in micro seconds since epoch.
 ==== output ==== ==== output ====
  
Line 245: Line 260:
 Called when an instance of the output is stopped. This function must be implemented by addon. Called when an instance of the output is stopped. This function must be implemented by addon.
  
-=== output:event_listen_start(event_name, process_begin_function, process_end_function) ===+=== output:event_listen_start(event_name, process_begin_function, process_end_function, filter) ===
 Call this function to start listening to a particular event. You must call output:event_listen_stop(event_name) when you are done listening to that particular event. Call this function to start listening to a particular event. You must call output:event_listen_stop(event_name) when you are done listening to that particular event.
  
 == Parameters: == == Parameters: ==
   * //event_name//: Name of the event you want to listen to. For a list of available events, see [[pom-ng:events|here]].   * //event_name//: Name of the event you want to listen to. For a list of available events, see [[pom-ng:events|here]].
-  * //process_begin_function//: Function that will be called when an event starts. +  * //process_begin_function//: Function that will be called when an event starts. Its prototype is process_function(event)
-  * //process_end_function//: Function that will be called when an event stops.+  * //process_end_function//: Function that will be called when an event stops. Its prototype is process_function(event). 
 +  * //filter//: String containing an event filter, optional.
  
 === output:event_listen_stop(event_name) === === output:event_listen_stop(event_name) ===
Line 262: Line 278:
 Called when an instance of the output is started. This function must be implemented by addon. Called when an instance of the output is started. This function must be implemented by addon.
  
-=== output:pload_listen_start(open_function, write_function, close_function) ===+=== output:pload_listen_start(open_function, write_function, close_function, filter) ===
 Start listening to payloads. Every payload will be processed. It's up to the output to filter them. If you don't need a specific function, you can specify nil instead. Start listening to payloads. Every payload will be processed. It's up to the output to filter them. If you don't need a specific function, you can specify nil instead.
  
 == Parameters: == == Parameters: ==
-  * //open_function//: Function that will be called when a new payload is open. Its prototype is open_function(payload_priv, payload). +  * //open_function//: Function that will be called when a new payload is open. Its prototype is open_function(payload_priv, payload). It must return **true** if it want to continue processing the payload, otherwise **false**
-  * //write_function//: Function that will be called when new data from a payload are available. Its prototype is write_function(payload_priv, payload_data).+  * //write_function//: Function that will be called when new data from a payload are available. Its prototype is write_function(payload_priv, payload_data). It must return **true** to continue processing the payload, other **false**.
   * //close_function//: Function that will be called once a payload has been fully processed. Its prototype is close_function(payload_priv).   * //close_function//: Function that will be called once a payload has been fully processed. Its prototype is close_function(payload_priv).
 +  * //filter//: Pload filter to use, optional.
  
 == Parameters of the above functions: == == Parameters of the above functions: ==
Line 285: Line 302:
  
 ==== pload ==== ==== pload ====
 +
 +=== pload.data ===
 +
 +== Returns: ==
 +Returns the data related to this payload. It contains the data that the analyzer identified. For example, images will contain 'height' and 'width'.
  
 === pload.event === === pload.event ===
Line 291: Line 313:
 Returns the event related to this payload. Returns the event related to this payload.
  
-=== pload.data ===+=== pload.filename ===
  
 == Returns: == == Returns: ==
-Returns the data related to this payloadIt contains the data that the analyzer identified. For example, images will contain 'height' and 'width'.+Returns the pload filename if it has been set, nil otherwise. 
 + 
 +=== pload.parent === 
 + 
 +== Returns: == 
 +Returns the pload that was the parent of the present pload if any.
  
 === pload.type === === pload.type ===
Line 319: Line 346:
  
 ==== plugin ==== ==== plugin ====
 +
 +Plugins are a piece of C code, usually from existing outputs, that perform useful functions. There are two types of plugins : event plugins and payload plugins. As you can guess, event plugins will process events and payload plugins will process payloads.
 +
 +Here is a [[pom-ng:lua:plugins|list of plugins]].
 +
  
 === plugin:close() === === plugin:close() ===
 Close the plugin and releases all the associated data. Close the plugin and releases all the associated data.
  
-=== plugin:event_listen_start(event_name) ===+=== plugin:event_listen_start(event_name, filter) ===
 Have the plugin listens to a specific event and process it. Have the plugin listens to a specific event and process it.
  
 == Parameters: == == Parameters: ==
   * //event_name//: Name of the event to listen to.   * //event_name//: Name of the event to listen to.
 +  * //filter//: String containing an event filter, optional.
  
 === plugin:event_listen_stop(event_name) === === plugin:event_listen_stop(event_name) ===
Line 361: Line 394:
  
 === plugin:pload_process(pload, parameters) === === plugin:pload_process(pload, parameters) ===
-Process a specific payload.+Process a specific payload. **It should only be used in the pload_open callback function of the output !**
  
 == Parameters: == == Parameters: ==
pom-ng/lua.1350893423.txt.gz · Last modified: 2020/05/26 21:59 (external edit)