1. Introduction

Generally, MMT-5Greplay takes as input a sequence of message and output alerts. It loads first a set of rules to be verified and be compiled as dynamic libraries. Each time a message coming, it verifies the message against the rules. If some rules are satisfied, it output alerts.

     rules.so ----> --------------
                   |              |
==== messages ===> | MMT-5Greplay | ==== alerts ===>
                   |              |
                    --------------

2. Workflow

The workflow of MMT-5Greplay multi-threading is represented as Figure below. Details of the functions will be introduced subsequently.

Edit

2.1. Initialize

This process need to be done only once before calling any other functions.

2.2.1 Load rules

int mmt_sec_init( const char * excluded_rules_id )

• Description: This function initialises MMT-5Greplay to analyse a set of rules. By defaults, these rules must be compiled and located on the folder ./rules or /opt/mmt/security/rules.

• Input: This function allows to exclude some rules from verification. The ID of excluded rules are set by the parameter excluded_rules_id. The parameter is a null-terminated byte string

  The IDs are separated by comma ,. A continue range of IDs is represented by the smallest and the biggest ID and they are separated by a dash -.

  For example, mmt_sec_init("1-5,7,9"), will exclude rules having id 1,2,3,4,5,7 and 9 from verification.

• Return:

  • 0 if no error
  • 1 if MMT-5Greplay found no rules to verify

2.2.2 Register

// A function to be called when a rule is validated
typedef void (*mmt_sec_callback)(
		const rule_info_t *rule,         //rule being validated
		enum verdict_type verdict,       //DETECTED, NOT_RESPECTED
		uint64_t timestamp,              //moment (by time) the rule is validated
		uint64_t counter,                //moment (by order of packet) the rule is validated
		const mmt_array_t * const trace, //historic of messages that validates the rule
		void *user_data                  //#user-data being given in mmt_sec_register_rules
);
mmt_sec_handler_t* mmt_sec_register( size_t threads_count, const uint32_t *cores_id, 
                         const char *rules_mask, bool verbose, mmt_sec_callback callback, void *args );

• Description: Register some rules to validate.

  After calling this function, depending on number of threads given in threads_count parameter, MMT-5Greplay can create several threads and starts them. The processing of the threads is represented by the loop forever block in Figure above. This block always check the MMT-5Greplay buffer to get out a message to verify. Each time it found a rule being validated, it will call the function given by callback parameter. It is stoped by calling mmt_sec_unregister function.

• Input:

  • threads_count: number of threads
  • core_mask : a string indicating logical cores to be used, e.g., "1-4,11-12,19" => we use cores 1,2,3,4,11,12,19. Core number starts from 1.
  • rule_mask : a string indicating special rules being attributed to special threads e.g., "(1:10-13)(2:50)(4:1007-1010)". The other rules will be attributed equally to the rest of threads.
  • callback : a function to be called when a rules is validated
  • user_data : data will be passed to the callback

• Return:

  • NULL if there are error, e.g., insufficient memory, parameters are incorrect
  • a handler pointer, otherwise

• Note: The function callback can be called from different threads. (Thus if it accesses to a global variable or a static one, the access to these variables must be synchronous)

2.2. Process

This function need to call every time having a message to be verified.

void mmt_sec_process( mmt_sec_handler_t *handler, message_t *msg );

This function simply put the message into a buffer of MMT-5Greplay. If the buffer is not full, the function return immediately, otherwise it will always verify the buffer until having an available place to put the message.

2.3. Finish

This process need to be done once only when finishing.

2.3.1 Unrgister

size_t mmt_sec_unregister( mmt_sec_handler_t* );

• Description: Stop and free every threads used by MMT-5Greplay.
• Input: a pointer points to the handler being created by mmt_sec_register
• Return: Number of alerts generated

2.3.2 Unload rules

The following function will unload rules. This is called only at the end of processing. After this function, no more mmt-security functions can be called.

void mmt_sec_close();