Tag Stream v1.2 - a Snort detection-plugin!
Created: (2003/07/12 22:32:02) Last Updated: (2004/11/16 13:38:00)

Purpose:

Provide a lightweight detection plugin that allows you to mark a stream4 session with a "tag" that can be inspected ( or "checked") by other/subsequent rules as a test criteria before triggering. (Patch for snort 2.0.x and 2.1.x provided, see INSTALL notes.) v 1.2 provides optional output in a predefined file. TagStream v1.2 now provides a way to check the stream4 client packet count. View the README for more information.

Requirements:

In order for the sp_tag_stream detection-plugin to work with snort ( stream4 in particular ), one change must be made within decode.h.

Snort must include a new 64bit variable in it's _Session struct, session_tag_flags, which is to be modified and checked by sp_tag_stream.c.
This can be accomplished by using the patch. Also, changes are covered in detail in the INSTALL document, for manual integration.

Download the latest:

Get the tagstream v1.3 patch for Snort 2.2.0
http://www.metre.net/files/tagstream-1.3_snort-2.2.0_patch (md5)
Just apply directly to snort-2.2.0 source tree (no tar file needed)
i.e. cd snort-2.2.0; patch -p1 < tagstream-1.2_snort-2.2.0_patch

Download the v1.2 tar file for Snort 2.0 and 2.1 http://www.metre.net/files/tagstream-1.2.tgz (md5)
Tar file contains both the source code and a patch.
You can use the patch method (one for snort-2.0.0-2.0.5 and one for 2.1) or just manually integrate the code using the INSTALL notes.
-The "patch" will attempt yo modify a couple of snort files including decode.h.

Usage:

Once compiled, the TagStream plugin can be activated in a rule by including the detection plugin option "tagstream: s=1;".

Here is an example implementation.

Scenario A: Make an association between two rules such that rule A. will only trigger if rule B has matched on a packet in the same TCP stream.

Rule A: Alert on TCP port 25 streams containing the pattern 'CONFIDENTIAL' which are coming from bill@bigcorporation.com

alert $EXTERNAL_NET any > $HOME_NET 25 ( msg:"Bill's is sending out confidential information again !"; flow:to_server,established; content:"CONFIDENTIAL"; tagstream: c=1; )

Rule B: Tag TCP port 25 streams containing 'mail from bill@bigcorporation.com'

alert $EXTERNAL_NET any > $HOME_NET 25 ( msg:"Check for Bill's outgoing email and tag the stream - but don't alert"; flow:to_server,established; content:"mail from"; nocase; distance:5; content: "bill@bigcorporation.com"; tagstream: s=1 i=1; )

Rule B identifies TCP port 25 streams containing 'mail from bill@bigcorporation.com' and mark it appropriately (s=1). Since we don't need this particular rule to generate an alert, we use the invert tag (i=1) option. We use tag value '1' to identify all streams matching Rule B. Rule A checks whether tag value 1 (c=1) is set on the stream prior to alerting. The invert mode option simply takes a non-zero value (i=1) to enable.

2. The second rule will only trigger when the content contains the expression "CONFIDENTIAL" and the packet is associated with stream tagged as being an email from bill.

Scenario B: Create a set of (content) signatures to define 'normal' TCP traffic. Use tagstream to identify all TCP streams with matching content. Create a final rule that generates one alert for every TCP stream which which has not been tagged within 4 packets (p>4) of the session. Each 'normal content' signature rules would contain 'tagtream: s=1;' The final signature rule would take on the form: alert $EXTERNAL_NET any > $WEB_SERVER 80 ( msg:"Unknown Request !"; flow:to_server,established; tagstream: c!1 p>4; ) Note: We use 63 bits of a 64bit byte to allow up to 63 different tags to be set [associated] with a given TCP stream.

Changes:

        2004-11-16  created tagstream v-1.3 patch for snort-2.2.0 
	   Corrected logic causing 'c!1' to be treated as 'c=1'	
	   Added plugin identification to 'snort -V' output
	
        2004-09-30  created tagstream v-1.2 patch for snort-2.2.0 

	2003-12-28  v-1.2 - Added 'packet' (p) count test (using !,=,<,>). 
	Expanded tag 'check' (c) logic to include !,=,< and >. Both c and p have 
	equal precedence.  You can now write rules that require a (or any 'p>1') 
	tag to have been set by the Nth packet. 


	2003-12-08  v-1.1 - added debug mode output. Checks for presence of 
	tagstream.debug.log in snort CWD at snort startup. If present and 
	writable, it will append a record for each action it takes.
	Nice for debugging stream4 issues.

Old Links:

Please let me know if you experience any problems. Thanks.

Author: John Curry john dot curry at metre dot net      This code is distributed under the "GNU Public License"

Special thanks, again, to both bmc and to madcow