[Snort-devel] Issues with the Snort Manual (Patch)

Joel Esler jesler at ...402...
Mon Nov 29 19:15:56 EST 2010


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 at ...3108...> 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 at ...402...] 
> Sent: Wednesday, November 24, 2010 8:07 AM
> To: Kinard, Joshua A
> Cc: snort-devel at 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 at ...3108...> 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 at lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/snort-devel
> 




More information about the Snort-devel mailing list