4.2 Required Functions

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

4.2.1 Preprocessors

Each dynamic preprocessor must define the following items. These must be defined in the global scope of a source file (e.g. spp_example.c).

• const int MAJOR_VERSION

  This specifies the major version of the preprocessor.

• const int MINOR_VERSION

  This specifies the minor version of the preprocessor.

• const int BUILD_VERSION

  This specifies the build version of the preprocessor.

• const char *PREPROC_NAME

  This specifies the display name of the preprocessor.

• void DYNAMIC_PREPROC_SETUP(void)

  This function is called to register the preprocessor to be called with packets data.

The preprocessor must be built with the same macros defined as the Snort binary and linked with the dynamic preprocessor library that was created during the Snort build. A package configuration file is exported as part of the Snort build and can be accessed using the following commands with PKG_CONFIG_PATH=$<$snort build prefix/lib/pkgconfig$>$:

• pkg-config -cflags snort_preproc

  Returns the macros and include path needed to compile the dynamic preprocessor.

• pkg-config -libs snort_preproc

  Returns the library and library path needed to link the dynamic preprocessor.

4.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 evaluation 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 parameter.

  • 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 specified 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 your 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.

4.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.