5.2 Required Functions

Each dynamic module must define a set of functions and data objects to work within this framework.

5.2.1 Preprocessors

Each dynamic preprocessor library must define the following functions. These are defined in the file sf_dynamic_preproc_lib.c. The metadata and setup function for the preprocessor should be defined sf_preproc_info.h.

• int LibVersion(DynamicPluginMeta *)

  This function returns the metadata for the shared library.

• int InitializePreprocessor(DynamicPreprocessorData *)

  This function initializes the data structure for use by the preprocessor into a library global variable, _dpd and invokes the setup function.

5.2.2 Detection Engine

Each dynamic detection engine library must define the following functions.

• int LibVersion(DynamicPluginMeta *)

  This function returns the metadata for the shared library.

• int InitializeEngineLib(DynamicEngineData *)

  This function initializes the data structure for use by the engine.

The sample code provided with Snort predefines those functions and defines the following APIs to be used by a dynamic rules library.

• int RegisterRules(Rule **)

  This is the function to iterate through each rule in the list, initialize it to setup content searches, PCRE evalution data, and register flowbits.

• int DumpRules(char *,Rule **)

  This is the function to iterate through each rule in the list and write a rule-stop to be used by snort to control the action of the rule (alert, log, drop, etc).

• int ruleMatch(void *p, Rule *rule)

  This is the function to evaluate a rule if the rule does not have its own Rule Evaluation Function. This uses the individual functions outlined below for each of the rule options and handles repetitive content issues.

  Each of the functions below returns RULE_MATCH if the option matches based on the current criteria (cursor position, etc).

  • int contentMatch(void *p, ContentInfo* content, u_int8_t **cursor)

    This function evaluates a single content for a given packet, checking for the existence of that content as delimited by ContentInfo and cursor. Cursor position is updated and returned in *cursor.

    With a text rule, the with option corresponds to depth, and the distance option corresponds to offset.

  • int checkFlow(void *p, FlowFlags *flowflags)

    This function evaluates the flow for a given packet.

  • int extractValue(void *p, ByteExtract *byteExtract, u_int8_t *cursor)

    This function extracts the bytes from a given packet, as specified by ByteExtract and delimited by cursor. Value extracted is stored in ByteExtract memoryLocation paraneter.

  • int processFlowbits(void *p, FlowBitsInfo *flowbits)

    This function evaluates the flowbits for a given packet, as specified by FlowBitsInfo. It will interact with flowbits used by text-based rules.

  • int setCursor(void *p, CursorInfo *cursorInfo, u_int8_t **cursor)

    This function adjusts the cursor as delimited by CursorInfo. New cursor position is returned in *cursor. It handles bounds checking for the specified buffer and returns RULE_NOMATCH if the cursor is moved out of bounds.

    It is also used by contentMatch, byteJump, and pcreMatch to adjust the cursor position after a successful match.

  • int checkCursor(void *p, CursorInfo *cursorInfo, u_int8_t *cursor)

    This function validates that the cursor is within bounds of the specified buffer.

  • int checkValue(void *p, ByteData *byteData, u_int32_t value, u_int8_t *cursor)

    This function compares the value to the value stored in ByteData.

  • int byteTest(void *p, ByteData *byteData, u_int8_t *cursor)

    This is a wrapper for extractValue() followed by checkValue().

  • int byteJump(void *p, ByteData *byteData, u_int8_t **cursor)

    This is a wrapper for extractValue() followed by setCursor().

  • int pcreMatch(void *p, PCREInfo *pcre, u_int8_t **cursor)

    This function evaluates a single pcre for a given packet, checking for the existence of the expression as delimited by PCREInfo and cursor. Cursor position is updated and returned in *cursor.

  • int detectAsn1(void *p, Asn1Context *asn1, u_int8_t *cursor)

    This function evaluates an ASN.1 check for a given packet, as delimited by Asn1Context and cursor.

  • int checkHdrOpt(void *p, HdrOptCheck *optData)

    This function evaluates the given packet's protocol headers, as specified by HdrOptCheck.

  • int loopEval(void *p, LoopInfo *loop, u_int8_t **cursor)

    This function iterates through the SubRule of LoopInfo, as delimited by LoopInfo and cursor. Cursor position is updated and returned in *cursor.

  • int preprocOptionEval(void *p, PreprocessorOption *preprocOpt, u_int8_t **cursor)

    This function evaluates the preprocessor defined option, as spepcifed by PreprocessorOption. Cursor position is updated and returned in *cursor.

  • void setTempCursor(u_int8_t **temp_cursor, u_int8_t **cursor)

    This function is used to handled repetitive contents to save off a cursor position temporarily to be reset at later point.

  • void revertTempCursor(u_int8_t **temp_cursor, u_int8_t **cursor)

    This function is used to revert to a previously saved temporary cursor position.

  Note:  

  If you decide to write you own rule evaluation function, patterns that occur more than once may result in false negatives. Take extra care to handle this situation and search for the matched pattern again if subsequent rule options fail to match. This should be done for both content and PCRE options.

5.2.3 Rules

Each dynamic rules library must define the following functions. Examples are defined in the file sfnort_dynamic_detection_lib.c. The metadata and setup function for the preprocessor should be defined in sfsnort_dynamic_detection_lib.h.

• int LibVersion(DynamicPluginMeta *)

  This function returns the metadata for the shared library.

• int EngineVersion(DynamicPluginMeta *)

  This function defines the version requirements for the corresponding detection engine library.

• int DumpSkeletonRules()

  This functions writes out the rule-stubs for rules that are loaded.

• int InitializeDetection()

  This function registers each rule in the rules library. It should set up fast pattern-matcher content, register flowbits, etc.

The sample code provided with Snort predefines those functions and uses the following data within the dynamic rules library.

• Rule *rules[]

  A NULL terminated list of Rule structures that this library defines.