Re: Issues with the Snort Manual (Patch)

[Joel Esler <jesler () sourcefire com>]

I don't think it'll make it into 2.9.0.2, but look for it after that. 


Sent from my iPhone

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

> Sounds good to me!  I'll look forward to the next documentation update.
>
>
> -----Original Message-----
> From: Joel Esler [mailto:jesler () sourcefire com] 
> Sent: Monday, November 29, 2010 7:16 PM
> To: Kinard, Joshua A
> Cc: <snort-devel () lists sourceforge net>
> Subject: Re: [Snort-devel] Issues with the Snort Manual (Patch)
>
> 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