Home page logo
/

snort logo Snort mailing list archives

Re: Issues with the Snort Manual (Patch)
From: Joel Esler <jesler () sourcefire com>
Date: Mon, 29 Nov 2010 19:15:56 -0500

I know some of the answers to these questions, however, I am going to enter your comments into the existing bug for 
clarification in the manual so that all answers are in one place.  I think that makes the most sense. 


Sent from my iPhone

On Nov 29, 2010, at 6:23 PM, <Joshua.Kinard () us-cert gov> wrote:


Thanks for this.  Will the developers be able to provide
guidance/comments on the following items addressed in the documentation
patch?:

- asn1: Are absolute_offset and relative_offset mutually exclusive?

- asn1: What is the purpose or function of the 'print' parameter?

- byte_extract: Is 'offset' supposed to be able to hold a variable name
extracted from a previous byte_extract keyword?

- session: What is the purpose or function of the 'binary' parameter?

- General: Is a space after a colon in a Snort rule option the preferred
format, or is no space preferred?  Snort parses either-or, but as I
mentioned, the main SourceFire product has choked on instances of these
(specifically, importing a text file with a rule whose "sid" parameter
contains such a space).

- General: Are spaces between parameters in a rule option also the
preferred format, or are no spaces preferred?  Similar to the last
question.  I haven't noticed SourceFire mistreating options formatted as
such, but the possibility probably exists.



I had an additional thought over the weekend, that is not addressed in
the manual nor reflected in my patch.  The manual states that HTTP
content modifiers for pcre (U, I, P, H, D, M, C, K, S, & Y) cannot be
used in combination with the 'R' relative modifier (or 'B' rawbytes).
Content, however, disallows use of the 'rawbytes' option with the HTTP
modifiers, but speaks nothing of the two relative modifiers, 'distance'
or 'within'.

Is a rule written as such valid?:
alert tcp $HOME_NET 1024: -> $EXTERNAL_NET 80 (msg:"Bad HTTP URI
/foobar"; flow:established,to_server; content:"GET"; http_method;
content:"/foobar"; http_uri; distance:0; sid:42000001; rev:1; gid:1;
priority:2;)

Since the http_* modifiers affect where the two content matches look, is
"distance:0;" applicable on the second content to force the match to
continue directly after the end of the first?  This wouldn't be valid in
a pcre option (i.e., content:"GET"; http_method; pcre:"/\/foobar/RU";).
What about when using the http_raw_* modifiers with 'distance' and
'within'?

Lastly, are 'distance' and 'within' valid on the 'uricontent' option?
This has never been clearly addressed it seems and has a history of
confusing people.  It also ties in with the previous question, since
uricontent can be rendered as a content/http_uri pair.  Granted, both of
these questions are more suitable for discussion on snort-users, but
since I'm looking at further modifying the documentation if I can get
some concrete explanation on them, I'm inquiring here instead.


Thanks!,

--J


-----Original Message-----
From: Joel Esler [mailto:jesler () sourcefire com] 
Sent: Wednesday, November 24, 2010 8:07 AM
To: Kinard, Joshua A
Cc: snort-devel () lists sourceforge net
Subject: Re: [Snort-devel] Issues with the Snort Manual (Patch)

Joshua,

This is great, thank you very much.  This is exactly the collaboration
with the community that I love to see.  I'll get this filed into a bug
report right away.

Joel

On Nov 23, 2010, at 11:03 PM, <Joshua.Kinard () us-cert gov> wrote:


Hi snort-devel,

Reading through the Snort manual, I am bothered by the large number of

inconsistencies, spelling errors, missing option parameters, etc found

within the manual.  Snort is a complicated piece of software.  How are

we supposed to properly learn it if the documentation doesn't fully 
explain things or even contradicts itself at times?

I've attached a patch to the LaTeX source file from the recent release

of snort-2.9.0.1, found in the doc/ subdir.  The patch corrects a lot 
of problems I've identified in the manual pertaining to rule options.

I did not review or study the other areas of the manual, but I would 
not be surprised if a lot of the minor tweaks in the rule options 
section (mostly inconsistent use of white space) also exist elsewhere.

I am also not able to actually build TeX files into PDF, as I lack the

appropriate tools at present.


Here's a summary of what I changed:

- Removed extraneous spaces between a rule option name and its 
parameter list.  I.e., content: "ABC"; --> content:"ABC";.  I have 
noticed that the main SourceFire product will choke when importing 
text files with rules that contain a space after the colon.  There is 
no guidance in the manual on what it accepted practice.  So, looking 
over VRT and ET rule releases, I adopted the notation that there 
should be no space between a rule option's name and its parameter
list.

- Removed extraneous spaces between rule option parameters.  I.e., 
byte_test:1, !&, 128, 0; --> byte_test:1,!&,128,0;.  Similar to the 
above, this is mostly a style change.  The common notation is no 
whitespacing between parameter options.  I have probably missed a few 
of these in other parts of the manual.

- dce_iface/dce_opnum: Re-wrote the example syntax to line up with the

rest of the manual.

- byte_test/byte_jump in DCERPC2: Ditto.

- sd_pattern: Added missing semi-colon to the end of the syntax.

- reference: Added missing "osvdb" system ID, and updated the "mcafee"
HTTP URL from snort-2.9.0.1.

- content modifiers depth/offset/distance/within: Added notation that 
these four options can take either a number OR a string value 
representing a variable created by the "byte_extract" option.  The 
lack of this mention could lead to confusion and I am surprised that 
it was missed when byte_extract was added.  Also used the \texttt{} 
operator instead of single quotes in the description fields on a few
items.

- depth: All four of the numeric content modifiers invoke a ParseInt()

function to convert the string value into a number.  This ParseInt 
function accepts -65,535 to 65,535 as a valid range of values.  This 
does not align with the change in depth's documentation from 
snort-2.9.0 to 2.9.0.1.  No change was made pursuant to this notation.

However, I changed the documentation to reflect the fact that depth:0;

is invalid, because the source code in 
src/detection-plugins/sp_pattern_match.c,
lines 518 to 523, do an explicit check for depth != 0 and that depth 
is greater-than-or-equal-to the length of the pattern specified in the

matched content option.  Therefore, it is impossible to have a depth 
of 0 because you cannot have a content with no length.

- http_encode: Removed erroneous LaTeX \hline before the row for 
"ascii".

- byte_test: Removed the '!' operator from the table detailing the 
possible operators.  I reported this once, and found it sloppy that 
while one or two edits were made to address the original issue on the 
preceding page, that the table, nor the notation at the bottom, were 
not updated.

- byte_jump: Another case of sloppiness: The example block for 
byte_test was copied to byte_jump and not changed.  So, I am certain a

few people might've scratched their heads at the mentioning of an 
<operator> or <offset> field, neither of which applies to byte_jump.

- byte_extract: The source code does not support the mention that 
byte_extract's "offset" parameter can also hold a value.
src/detection-plugins/sp_byte_extract.c, line 244 to line 251 backs 
this up.  So I removed the table row stating that this was possible.  
If this IS possible, then the source code needs to be changed.

- byte_test/byte_jump/byte_extract: Re-wrote the syntax line to match 
other elements in the manual.  For byte_jump and byte_extract 
specifically, they mimic the way byte_test mentions its "<endian>" and

"string,<number_type>" parameter..

- asn1: Listed out the options in the syntax example.  I made the 
assumption that relative_offset and absolute_offset cannot be used 
together.  Clarification on this would be appreciated.  Also added the

missing "print" option, although, I can find NO documentation 
explaining what it is for.

- ttl: Broke the syntax example up into two pieces, as it's complex 
and reads better with two syntax examples.  Also explicitly spelled 
out that <= and >= are valid operators.

- ipopts: Added missing "lsrre" option.  Referenced CVE-1999-0909, but

that doesn't explain much.

- dsize, icode, itype: Copied the syntax example for urilen and used 
it with these three options, as that is a more clear example.

- flags: Reserved 1 is now CWR, Congestion Window Reduced, and 
Reserved
2 is ECE, ECN-Echo.  This is per the notes on the Wikipedia page for 
TCP.  Flag values still refer to these as "1, and "2".  Also removed
"0"
from the set of allowable values for the optional 'mask' field.

- flowbits: Added missing "isnotset" to the list of parameters in the 
syntax example.  Also added the explanation for "reset" to the 
flowbits table.

- icode: The usage example erroneously referred to it as "code".
Fixed.

- stream_size: Spelled out tht != means "not equal".  It previously 
said "not".

- session: Added the missing "binary" option after reviewing the 
source code.  NO explanation for this option exists, so I assumed that

it writes out data in some unknown binary format.  Clarification on 
this would be appreciated.

- tag: Added optional "0,packets," parameter to the syntax example.
Used to override tagged_packet_limit.

- replace: Double quotes around the string.

- detection_filter/threshold: Shortened the syntax example to one
line.


Please let me know if there are any issues with any elements of this 
patch.  Also, is there a QA team in place to validate changes to the 
manual in new releases?

Thanks!,

--J
<snort-manual_2.9.0.1-fixes.patch>------------------------------------
------------------------------------------
Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
Tap into the largest installed PC base & get more eyes on your game by

optimizing for Intel(R) Graphics Technology. Get started today with 
the
Intel(R) Software Partner Program. Five $500 cash prizes are up for
grabs.
http://p.sf.net/sfu/intelisp-dev2dev__________________________________
_____________
Snort-devel mailing list
Snort-devel () lists sourceforge net
https://lists.sourceforge.net/lists/listinfo/snort-devel


------------------------------------------------------------------------------
Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
Tap into the largest installed PC base & get more eyes on your game by
optimizing for Intel(R) Graphics Technology. Get started today with the
Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs.
http://p.sf.net/sfu/intelisp-dev2dev
_______________________________________________
Snort-devel mailing list
Snort-devel () lists sourceforge net
https://lists.sourceforge.net/lists/listinfo/snort-devel


  By Date           By Thread  

Current thread:
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]