$Id: README.templates,v 1.11 2006/01/29 14:50:25 andreas_o Exp $ #


General info
------------
Modifysid templates are nothing more than an easier way to use the
standard modifysid expressions. With a template, you only need to 
define the (often complex) modifysid expression once, and then call the 
template by name every time you want to use it instead of repeating the 
modifysid expression. For more information about modifysid, see the 
default oinkmaster.conf file. Basically, a modifysid expression is 
simply a substitution expression that will be applied on specified 
rules or files after each update, so that you can make some tweaks to 
the rules. Lots of template examples can be found in the 
template-examples.conf file.



Usage syntax
------------
First you use "define_template" to define a template, and then 
"use_template" to use it. You must make sure the template is defined 
before you attempt to use it. You can either define and/or use the 
templates directly in your regular oinkmaster.conf or put them in a 
separate file, e.g. templates.conf. When using a separate file, make 
sure both files are loaded, i.e. either start Oinkmaster with 
"oinkmaster.pl -C templates.conf -C oinkmaster.conf ..." or use the 
"include" directive inside oinkmaster.conf.

The syntax to define a template is:
define_template  "modifythis" | "withthis"

"modifythis" is a Perl regular expression that will match the 
pattern you want to replace with the "withthis" expression.
It is basically passed to a s/modifythis/withthis/ statement in Perl.
This means that you must escape special characters to match them
as strings.

The syntax to use a template is:
use_template   [ "arg1" "arg2" ... ]

As , you can also specify the wildcard ("*"), a comma-separated 
list of SIDs or even one or more filenames, just as with a regular 
modifysid expression. Everything after  is optional, unless you 
require arguments in your template definition (keep reading). The 
arguments must be quoted strings, separated with space.

The "modifythis" | "withthis" stuff in define_template works just like 
in a regular modifysid, but it has one more useful feature. The 
modifysid expression (the substitution string and/or the 
replacement string) can contain the special string %ARGx%, where x is
a number from 1 and up. Before the substitution on the signature
occurs, all the %ARGx% will be replaced with the corresponding
arguments to use_template. So %ARG1% will be replaced with the first
argument, %ARG2% with the second one, and so on.
This is useful when you for example want to add "tag" statements (or 
thresholding/limiting or whatever) to rules using a modifysid template, 
but you want the number of seconds to tag to be different for different
rules. By giving this value as argument when using the template, there
is no need to write a new template for each value for the number of
seconds. This may sound confusing, but have a look at the examples in
template-examples.conf and it will hopefully make sense.

If you use variables in the substitution expression, it is strongly
recommended to always specify them like ${varname} instead of $varname 
(${1} instead of $1 for example) to avoid parsing confusion
in some situations.



Usage hints
-----------
When appending new stuff to rules using templates (or regular modifysid 
expressions) it usually doesn't matter where in the rule you put it 
unless it affects the way Snort parses and optimizes the rules. The 
important thing is to write the substitution expression so that it
will continue to work even if the original rule becomes updated 
somehow. Imagine this rule:

alert tcp any any -> any any (msg: "foo"; flow:established; sid: 123;)

Now if we want to add something to it, we need to find some part of the 
rule to match, and then replace that part with itself + the stuff we 
want to add. A bad example to do this is to match "flow:established;" 
and replace it with "flow:established; newstuff;", because if the rule
is updated and the flow statement is changed to  
"flow:established,to_server;", our substitution expression would no 
longer match. A better approach is to match against something you know 
isn't going to change, like the SID statement or the very end of the 
rule. Also try not to be strict about whitespaces. For example, 
remember that a SID statement can be written as 
"sid:123;" or "sid: 123;" or "sid : 123 ;" and so on.

As use_template statements are simply translated into modifysid 
statements, you can use multiple use_template for the same SID. They 
will be processed in order of appearance in the config file.
Also remember that they apply both on active and inactive (disabled) 
rules. 



Example template definitions
----------------------------
See the template-examples.conf file!