295_Snort2e_07.qxd 5/5/04 5:50 PM Page 350 350 Chapter 7 • Implementing Snort Output Plug-Ins the myPluginSetup function.This function’s purpose is to initialize any contextual data (such as file references) necessary for it to function. Second, it must then provide Snort with some additional function pointers: a function for alerts and two shutdown functions.These pointers are provided by a call to AddFuncToOutputList, AddFuncToCleanExitList, and AddFuncToRestartList. myPluginAlert (AlertW3C) The myPluginAlert function is the actual function Snort calls when there is a new alert to process.You should remember that Snort learns of this function by myPluginInit’s call to AddFuncToOutputList. This function takes several parameters: ■ Packet The actual packet that caused the alert. ■ Message Any message generated by the associated rule. ■ Data An arbitrary DWORD value specified in the AddFuncToOutputList function.This is typically a pointer to a structure, allocated on the heap, containing file handles and other configuration information. ■ EventData A structure containing information about the associated Snort rule. myPluginCleanExit (AlertW3CCleanExit) The myPluginCleanExit function is called by Snort when the application is shut- ting down. Remember that Snort learns of this function by myPluginInit’s call to AddFuncToCleanExitList.This function’s purpose is typically to deallocate any contextual information allocated by myPluginInit. myPluginRestart (AlertW3CRestart) The myPluginRestart function is called by Snort when the application is shutting down. Remember that Snort learns of this function by myPluginInit’s call to AddFuncToRestartList.This function’s purpose is typically to deallocate any con- textual information allocated by myPluginInit. Those functions are the “meat” of the plug-in. Next we’ll identify the impor- tant aspects of the W3C output plug-in’s source code and relate it to what we have just learned.The goals in creating the W3C plug-in were to save alert data to a log file in a W3C format.The plug-in operates as we have just learned, and www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 351 Implementing Snort Output Plug-Ins • Chapter 7 351 we will now explore how it is implemented. Note that implementation and cre- ation are two different beasts. The first step was to create two source files, spo_w3c.h and spo_w3c.c, and declare the structure of our plug-in with the following functions: void AlertW3CInit(unsigned char *ConfigOptions); void AlertW3CSetup(); void AlertW3CCleanExit(int signal, PW3C_CONTEXT Context); void AlertW3CRestart(int signal, PW3C_CONTEXT Context); After creating the two source files, we need to modify Snort’s code base so that it knows about our plug-in.This step is critical because Snort was not cre- ated to dynamically notice or identify new plug-in code just because it resides in the same directory structure as the other plug-ins. So, in Snort’s plugbase.h, we added the following line at the top of the file: #include "output-plugins/spo_w3c.h" Again, inside Snort’s plugbase.h file within the InitOutputPlugins function, we added the following function call: AlertW3CSetup(); Those steps were necessary so that Snort could provide the ability to give our function a call when it starts. Snort calls our setup routine, AlertW3CSetup, when it starts. So, from this point, we need to give Snort some additional information about our plug-in. This is done by the following code snippet: RegisterOutputPlugin("alert_W3C", NT_OUTPUT_ALERT, AlertW3CInit); Now Snort knows that our plug-in is named alert_W3C, and it knows how to activate it. Snort decides whether to activate the plug-in by the presence of a reference to it in the snort.conf file. Such a reference should look like the fol- lowing: output alert_W3C: /snort/log/w3clog.txt We are now getting close to the end of the process.The plug-in is activated via the AlertW3CInit function.This function sets up some configuration infor- mation and informs Snort about some additional entry points into our plug-in: AlertW3C, AlertW3CCleanExit, and AlertW3CRestart. www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 352 352 Chapter 7 • Implementing Snort Output Plug-Ins The configuration information is set up by calling the static routine InitializeContext, which returns a pointer to a W3C_CONTEXT structure. Inside this structure exists only one member: a FILE handle to the opened log. Should we need to add any more configuration information, we’d add it to this structure and the InitializeContext function.The AlertW3CInit function makes several calls to the Snort runtime to inform it about its additional entry points: AddFuncToOutputList(AlertW3C, NT_OUTPUT_ALERT, ctx); AddFuncToCleanExitList(AlertW3CCleanExit, ctx); AddFuncToRestartList(AlertW3CRestart, ctx); The real work of the plug-in is done inside the AlertW3C function. Basically, this function takes its several arguments and serializes them into a W3C log string, which it appends to its log file.This is done in the following steps: 1. Call the static routine InitializeOutputParameters, which takes the same arguments of AlertW3C and serializes it into a data structure OUTPUT_PARAMETERS. 2. Take the OUTPUT_PARAMETERS structure and pass it to the func- tion AllocLogEntryFromParameters, which transforms the structure into a character array containing the log message. 3. Write that character array to the log file using the fwrite function. Finally, when Snort shuts down, it will give our plug-in a call via the AlertW3CCleanExit function.The purpose of this function is very simple: release allocated data structures and system handles, such as our context structure and its file handle.This is done by its internal call to ReleaseContext.You are now ready to put the remaining pieces of the puzzle together by analyzing the source of the plug-in in hopes that you can use this guide and example to write your own plug-in if you so desire. The header file is very straightforward, to the point that it prototypes a single function that takes and returns no information and is directly linked to Snort’s code base: //////////////////////////////////////////////////////////////////////////// // // spo_w3c.h // // Purpose: www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 353 Implementing Snort Output Plug-Ins • Chapter 7 353 // - Header file for spo_w3c.c, which is the output plugin for asserting // alerts in w3c log format. // /////////////////////////////////////////////////////////////////////////// #ifndef _SPO_W3C_H #define _SPO_W3C_H void AlertW3CSetup(); #endif The following code is the body of the plug-in for the new Snort W3C output format style.You will notice all the functions that we have already men- tioned and detailed in addition to some of the structures that we have reimple- mented to allow us to get the appropriate data parsed into the program. It is important to remember that this plug-in must be used in conjunction with Snort and must be compiled with Snort.The location of the output file is in the con- figuration file, so you do not need to modify this code to view your logs. Inline documentation is included in most of the file, but as always, if you have any questions on this code, chapter, or book, you should feel free to drop the authors a line at Syngress, or you may contact James C. Foster directly at jamesfoster@safe-mail.net. /////////////////////////////////////////////////////////////////////////// // // spo_w3c.c // // Purpose: // - output plugin for asserting alerts in w3c log format. // // Arguments: // - Log File Name // // Effect: // - Alerts are written to a file using the w3c log format. // /////////////////////////////////////////////////////////////////////////// #ifdef HAVE_CONFIG_H www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 354 354 Chapter 7 • Implementing Snort Output Plug-Ins #include "config.h" #endif #include <sys/types.h> #include <stdio.h> #include <stdlib.h> #ifndef WIN32 #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> #endif /* !WIN32 */ #ifdef HAVE_STRINGS_H #include <strings.h> #endif #include "event.h" #include "decode.h" #include "plugbase.h" #include "spo_plugbase.h" #include "parser.h" #include "debug.h" #include "mstring.h" #include "util.h" #include "log.h" #include "snort.h" #define MESSAGE_MAX_SIZE 40 #define IP_MAX_SIZE 15 // // Array indices for the plugin's configuration options in snort.conf // #define W3C_ARGUMENT_FILENAME 0 www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 355 Implementing Snort Output Plug-Ins • Chapter 7 355 // // Plugin context information used for snort's callback plugin // architecture. // typedef struct _W3C_CONTEXT { FILE *LogFile; } W3C_CONTEXT, *PW3C_CONTEXT; // // Bit flags specifying what members of the OUTPUT_PARAMETERS // structure are valid. // #define ATTRIBUTE_TIMESTAMP 0x00000001 #define ATTRIBUTE_SOURCE_IP 0x00000002 #define ATTRIBUTE_SOURCE_PORT 0x00000004 #define ATTRIBUTE_DESTINATION_IP 0x00000008 #define ATTRIBUTE_DESTINATION_PORT 0x00000010 #define ATTRIBUTE_MESSAGE 0x00000020 #define ATTRIBUTE_SID 0x00000040 // // This structure is serialized from several data structures // and represents the actual output used in each log entry. // // If any change is needed for the output, you need only modify // this structure, InitializeOutputParameters, and AllocLogEntryFromParameters. // typedef struct _OUTPUT_PARAMETERS { char TimeStamp[TIMEBUF_SIZE + 1]; char SourceIP[IP_MAX_SIZE + 1]; char DestinationIP[IP_MAX_SIZE + 1]; u_short SourcePort; u_short DestinationPort; char Message[MESSAGE_MAX_SIZE + 1]; www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 356 356 Chapter 7 • Implementing Snort Output Plug-Ins unsigned long Attributes; int SID; } OUTPUT_PARAMETERS, *POUTPUT_PARAMETERS; // // Forward definitions // void AlertW3CInit(unsigned char *ConfigOptions); void AlertW3C(Packet *, char *, PW3C_CONTEXT, Event *); void AlertW3CCleanExit(int, PW3C_CONTEXT); void AlertW3CRestart(int signal, PW3C_CONTEXT); // // Function: InitializeContext // // Arguments: // - ConfigOptions - Configuration options specificed in snort.conf // // Purpose: // - Process arguments specified in snort.conf and creates // a runtime context datastructure that snort passes // to our callback routines: AlertW3C, AlertW3CCleanExit, // and AlertW3CRestart. // static PW3C_CONTEXT InitializeContext(unsigned char *ConfigOptions) { int tokenCount = 0; char **tokens = 0; PW3C_CONTEXT ctx = 0; // Ready for additional parameters - increment 3rd parameter // as necessary. tokens = mSplit(ConfigOptions, " ", 2, &tokenCount, 0); www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 357 357 Chapter 7 • Implementing Snort Output Plug-Ins ctx = SnortAlloc(sizeof(W3C_CONTEXT)); ctx->LogFile = OpenAlertFile(tokens[W3C_ARGUMENT_FILENAME]); mSplitFree(&tokens, tokenCount); return ctx; } // // Function: ReleaseContext // // Arguments: // - Context - Context structure allocated by InitializeContext // // Purpose: // - Performs any de-initialization necessary on the context structure // which is allocated on plugin initialization. // static void ReleaseContext(PW3C_CONTEXT Context) { fclose(Context->LogFile); free(Context); } // // Function: InitializeOutputParameters // // Arguments: // - OUT OutputParams - Output parameter is initialize by this function. // - IN PacketData - Packet structure representing data off the wire // - IN Message - Message from the applicable snort rule // - IN Context - Context allocated by InitializeContext on plugin initialization // - IN EventData - Data from the applicable snort rule // www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 358 358 Chapter 7 • Implementing Snort Output Plug-Ins // Purpose: // - This function is called from AlertW3C and is used to serialize // several data sources into one common data structure. // static void InitializeOutputParameters( POUTPUT_PARAMETERS OutputParams, Packet *PacketData, char *Message, PW3C_CONTEXT Context, Event *EventData ) { char *ip = 0; // Clear output buffer bzero(OutputParams, sizeof(OUTPUT_PARAMETERS)); // Timestamp if (PacketData && PacketData->pkth) { ts_print(&PacketData->pkth->ts, OutputParams->TimeStamp); OutputParams->Attributes |= ATTRIBUTE_TIMESTAMP; } // SID if (EventData) { OutputParams->SID = EventData->sig_id; OutputParams->Attributes |= ATTRIBUTE_SID; } // Message if (Message) { strncpy(OutputParams->Message, Message, MESSAGE_MAX_SIZE); OutputParams->Attributes |= ATTRIBUTE_MESSAGE; www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 295_Snort2e_07.qxd 5/5/04 5:50 PM Page 359 Implementing Snort Output Plug-Ins • Chapter 7 359 } if (PacketData && PacketData->iph) { // NOTE: inet_ntoa uses thread local storage on NT platforms and // therefore atomicity is irrelevant. However, *NIX* probably // uses a static buffer. There isn't any compenstation // for this issue anywhere else, so it doesn't matter too much here. ip = inet_ntoa(PacketData->iph->ip_dst); strncpy(OutputParams->DestinationIP, ip, IP_MAX_SIZE); ip = inet_ntoa(PacketData->iph->ip_src); strncpy(OutputParams->SourceIP, ip, IP_MAX_SIZE); OutputParams->Attributes |= ATTRIBUTE_SOURCE_IP; OutputParams->Attributes |= ATTRIBUTE_DESTINATION_IP; } if (PacketData && PacketData->tcph) { OutputParams->SourcePort = ntohs(PacketData->tcph->th_sport); OutputParams->DestinationPort = ntohs(PacketData->tcph->th_dport); OutputParams->Attributes |= ATTRIBUTE_SOURCE_PORT; OutputParams->Attributes |= ATTRIBUTE_DESTINATION_PORT; } } // // Function: AllocLogEntryFromParameters // // Arguments: // - OUTPUT_PARAMETERS - Content serialized from several data sources // into a common usable data structure. www.syngress.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com [...]... 04/06- 21: 12:49.87 611 6 382 1 92 .16 8 .1. 102 - 1 92 .16 8 .1. 1 01 - ICMP PING Windows 04/06- 21: 12:50.008543 408 1 92 .16 8 .1. 1 01 - 1 92 .16 8 .1. 102 - ICMP Echo Reply 04/06- 21: 12:50.877603 382 1 92 .16 8 .1. 102 - 1 92 .16 8 .1. 1 01 - ICMP PING Windows 04/06- 21: 12: 51. 008837 408 1 92 .16 8 .1. 1 01 - 1 92 .16 8 .1. 102 - ICMP Echo Reply 04/06- 21: 12: 51. 878793 382 1 92 .16 8 .1. 102 - 1 92 .16 8 .1. 1 01 - ICMP PING Windows 04/06- 21: 12:52. 016 027 408 1 92 .16 8 .1. 1 01. .. 1 92 .16 8 .1. 1 01 - 1 92 .16 8 .1. 102 - ICMP Echo Reply 04/06- 21: 12:52.879979 382 1 92 .16 8 .1. 102 - 1 92 .16 8 .1. 1 01 - ICMP PING Windows 04/06- 21: 12:53.009929 408 1 92 .16 8 .1. 1 01 - 1 92 .16 8 .1. 102 - ICMP Echo Reply 04/06- 21: 13:02.783056 620 1 92 .16 8 .1. 1 8080 1 92 .16 8 .1. 1 01 313 4 SCAN Proxy Port 8080 attempt 04/06- 21: 13:03.234953 620 1 92 .16 8 .1. 1 8080 1 92 .16 8 .1. 1 01 313 4 SCAN Proxy Port 8080 attempt 04/06- 21: 13:03.736479 620 1 92 .16 8 .1. 1... SCAN Proxy Port 8080 attempt 04/06- 21: 13:03.736479 620 1 92 .16 8 .1. 1 8080 1 92 .16 8 .1. 1 01 313 4 SCAN Proxy Port 8080 attempt 04/06- 21: 13 :18 .394430 385 1 92 .16 8 .1. 1 - 1 92 .16 8 .1. 1 01 - ICMP traceroute 04/06- 21: 13 :18 .408880 408 1 92 .16 8 .1. 1 01 - 1 92 .16 8 .1. 1 - ICMP Echo Reply Dealing with Snort Output Sometimes you might find that it is easier to work with what Snort gives you instead of creating a new output plug-in... the event: Example Full Alert Mode alerts: [**] [1: 1 913 :8] RPC STATD UDP stat mon_name format string exploit attempt [**] [Classification: Attempted Administrator Privilege Gain] [Priority: 1] 11 / 01- 04:27 :16 .65 516 6 1 72 .16 .10 .15 1:807 -> 1 72 .16 .10 .200:956 UDP TTL:3 TOS:0x0 ID:0 IpLen:20 DgmLen :11 04 DF Len: 10 76 [Xref => http://www.securityfocus.com/bid /14 80] [Xref => http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2000-0666]... http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2000-0666] Example of the same event Alerting in Fast mode: 11 / 01- 04:27 :16 .65 516 6 [**] [1: 1 913 :8] RPC STATD UDP stat mon_name format string exploit attempt [**] [Classification: Attempted Administrator Privilege Gain] [Priority: 1] {UDP} 1 72 .16 .10 .15 1:807 -> 1 72 .16 .10 .200:956 We see here a vast difference in output coming from Snort. The first output format we are given, Full Alert mode, gives the... DECLARE t inet; BEGIN t = (( $1> >24) & 255::int8) || ''.'' || (( $1> >16 ) & 255::int8) || ''.'' || (( $1> >8) ( $1 & 255::int8) || ''.'' || & 255::int8); RETURN t; END; ' LANGUAGE 'plpgsql'; The following is an example of the custom function int8ip_to_str(): snort_ db=# SELECT ip_src, int8ip_to_str(ip_src) FROM iphdr; ip_src | int8ip_to_str + ­ 213 0706433 | 12 7.0.0 .1 An extremely common database... Information[ External Reference Links ] It is interesting to note that at the beginning of the alert we see [1: 1 913 :8] This tells the analyst that the detection engine fired the event (1) , the SID for this signature is 19 13, and it has been revised 8 times In the Full Alert mode www.syngress.com 3 81 382 Chapter 8 • Dealing with the Data Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com... output log_tcpdump: /logs /snort/ tcpdump/current.log Example: Multiple databases: output mydatabase: mysql, dbname=dmzsnort host =10 .1. 1.7 user=dbadmin password=badidea output mydatabase: oracle, dbname=security host=securitydb.poc2.com user=joe password=badidea Example: Multiple instances of the same database: output mydatabase: oracle, dbname=sensor host=sensor.poc2.com port =10 302 user=admin password=bads... stored on the Snort sensors An excellent new feature in Snort is the ability to store unified or binary data or to provide such data as an input stream to another program using such infor­ mation Using binary data and unified data streams threads processes away from the Snort executable, thus allowing Snort to focus on the more critical processes such as data collection and storage Chapter 11 addresses... now view the packet from Snort s perspective Take the rule that triggered the rpc statd alert: rpc.rules:alert udp $EXTERNAL_NET any -> $HOME_NET any (msg:"RPC STATD UDP stat mon_name format string exploit attempt"; content:"|00 01 86 B8|"; offset :12 ; depth:4; content:"|00 00 00 01| "; distance:4; within:4; byte_jump:4,4,relative,align; byte_jump:4,4,relative,align; byte_test:4,> ,10 0,0,relative; reference:cve,CVE-2000-0666; . 04/06 - 21 : 12 : 52. 016 027 408 1 92. 16 8 .1. 1 01 - 1 92. 16 8 .1. 1 02 - ICMP Echo Reply 04/06 - 21 : 12 : 52. 879979 3 82 1 92. 16 8 .1. 1 02 - 1 92. 16 8 .1. 1 01 - ICMP PING Windows 04/06 - 21 : 12 : 53.009 929 408 1 92. 16 8 .1. 1 01 - 1 92. 16 8 .1. 1 02. 04/06 - 21 : 12 : 49.87 611 6 3 82 1 92. 16 8 .1. 1 02 - 1 92. 16 8 .1. 1 01 - ICMP PING Windows 04/06 - 21 : 12 : 50.008543 408 1 92. 16 8 .1. 1 01 - 1 92. 16 8 .1. 1 02 - ICMP Echo Reply 04/06 - 21 : 12 : 50.877603 3 82 1 92. 16 8 .1. 1 02 - 1 92. 16 8 .1. 1 01. 1 92. 16 8 .1. 1 01 - ICMP PING Windows 04/06 - 21 : 12 : 51. 008837 408 1 92. 16 8 .1. 1 01 - 1 92. 16 8 .1. 1 02 - ICMP Echo Reply 04/06 - 21 : 12 : 51. 878793 3 82 1 92. 16 8 .1. 1 02 - 1 92. 16 8 .1. 1 01 - ICMP PING Windows 04/06 - 21 : 12 : 52. 016 027